Resource Creation

Vulkan supports three primary resource types: buffers, images, and tensors. Resources are views of memory with associated formatting and dimensionality. Buffers provide access to raw arrays of bytes, whereas images can be multidimensional and may have associated metadata. Tensors can be multidimensional, contain format information like images and may have associated metadata.

Other resource types, such as acceleration structures and micromaps use buffers as the backing store for opaque data structures.

Buffers

Buffers represent linear arrays of data which are used for various purposes by binding them to a graphics or compute pipeline via descriptor sets or certain commands, or by directly specifying them as parameters to certain commands.

Buffers are represented by VkBuffer handles:

// Provided by VK_VERSION_1_0
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkBuffer)

To create buffers, call:

// Provided by VK_VERSION_1_0
VkResult vkCreateBuffer(
    VkDevice                                    device,
    const VkBufferCreateInfo*                   pCreateInfo,
    const VkAllocationCallbacks*                pAllocator,
    VkBuffer*                                   pBuffer);

  • device is the logical device that creates the buffer object.

  • pCreateInfo is a pointer to a VkBufferCreateInfo structure containing parameters affecting creation of the buffer.

  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

  • pBuffer is a pointer to a VkBuffer handle in which the resulting buffer object is returned.

Valid Usage

  • VUID-vkCreateBuffer-device-09664
    device must support at least one queue family with one of the VK_QUEUE_VIDEO_ENCODE_BIT_KHR, VK_QUEUE_VIDEO_DECODE_BIT_KHR, VK_QUEUE_SPARSE_BINDING_BIT, VK_QUEUE_TRANSFER_BIT, VK_QUEUE_COMPUTE_BIT, or VK_QUEUE_GRAPHICS_BIT capabilities

  • VUID-vkCreateBuffer-flags-00911
    If the flags member of pCreateInfo includes VK_BUFFER_CREATE_SPARSE_BINDING_BIT, and the extendedSparseAddressSpace feature is not enabled, creating this VkBuffer must not cause the total required sparse memory for all currently valid sparse resources on the device to exceed VkPhysicalDeviceLimits::sparseAddressSpaceSize

  • VUID-vkCreateBuffer-flags-09383
    If the flags member of pCreateInfo includes VK_BUFFER_CREATE_SPARSE_BINDING_BIT, the extendedSparseAddressSpace feature is enabled, and the usage member of pCreateInfo contains bits not in VkPhysicalDeviceExtendedSparseAddressSpacePropertiesNV::extendedSparseBufferUsageFlags, creating this VkBuffer must not cause the total required sparse memory for all currently valid sparse resources on the device, excluding VkBuffer created with usage member of pCreateInfo containing bits in VkPhysicalDeviceExtendedSparseAddressSpacePropertiesNV::extendedSparseBufferUsageFlags and VkImage created with usage member of pCreateInfo containing bits in VkPhysicalDeviceExtendedSparseAddressSpacePropertiesNV::extendedSparseImageUsageFlags, to exceed VkPhysicalDeviceLimits::sparseAddressSpaceSize

  • VUID-vkCreateBuffer-flags-09384
    If the flags member of pCreateInfo includes VK_BUFFER_CREATE_SPARSE_BINDING_BIT and the extendedSparseAddressSpace feature is enabled, creating this VkBuffer must not cause the total required sparse memory for all currently valid sparse resources on the device to exceed VkPhysicalDeviceExtendedSparseAddressSpacePropertiesNV::extendedSparseAddressSpaceSize

Valid Usage (Implicit)

  • VUID-vkCreateBuffer-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkCreateBuffer-pCreateInfo-parameter
    pCreateInfo must be a valid pointer to a valid VkBufferCreateInfo structure

  • VUID-vkCreateBuffer-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkCreateBuffer-pBuffer-parameter
    pBuffer must be a valid pointer to a VkBuffer handle

  • VUID-vkCreateBuffer-device-queuecount
    The device must have been created with at least 1 queue

Return Codes
Success
Failure

The VkBufferCreateInfo structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkBufferCreateInfo {
    VkStructureType        sType;
    const void*            pNext;
    VkBufferCreateFlags    flags;
    VkDeviceSize           size;
    VkBufferUsageFlags     usage;
    VkSharingMode          sharingMode;
    uint32_t               queueFamilyIndexCount;
    const uint32_t*        pQueueFamilyIndices;
} VkBufferCreateInfo;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • flags is a bitmask of VkBufferCreateFlagBits specifying additional parameters of the buffer.

  • size is the size in bytes of the buffer to be created.

  • usage is a bitmask of VkBufferUsageFlagBits specifying allowed usages of the buffer.

  • sharingMode is a VkSharingMode value specifying the sharing mode of the buffer when it will be accessed by multiple queue families.

  • queueFamilyIndexCount is the number of entries in the pQueueFamilyIndices array.

  • pQueueFamilyIndices is a pointer to an array of queue families that will access this buffer. It is ignored if sharingMode is not VK_SHARING_MODE_CONCURRENT.

If the pNext chain includes a VkBufferUsageFlags2CreateInfo structure, VkBufferUsageFlags2CreateInfo::usage from that structure is used instead of usage from this structure.

Valid Usage
Valid Usage (Implicit)

The VkBufferUsageFlags2CreateInfo structure is defined as:

// Provided by VK_VERSION_1_4
typedef struct VkBufferUsageFlags2CreateInfo {
    VkStructureType        sType;
    const void*            pNext;
    VkBufferUsageFlags2    usage;
} VkBufferUsageFlags2CreateInfo;
// Provided by VK_KHR_maintenance5
// Equivalent to VkBufferUsageFlags2CreateInfo
typedef VkBufferUsageFlags2CreateInfo VkBufferUsageFlags2CreateInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • usage is a bitmask of VkBufferUsageFlagBits2 specifying allowed usages of the buffer.

If this structure is included in the pNext chain of a buffer creation structure, usage is used instead of the corresponding usage value passed in that creation structure, allowing additional usage flags to be specified. If this structure is included in the pNext chain of a buffer query structure, the usage flags of the buffer are returned in usage of this structure, and the usage flags representable in usage of the buffer query structure are also returned in that field.

Valid Usage (Implicit)

Bits which can be set in VkBufferUsageFlags2CreateInfo::usage, specifying usage behavior of a buffer, are:

// Provided by VK_VERSION_1_4
// Flag bits for VkBufferUsageFlagBits2
typedef VkFlags64 VkBufferUsageFlagBits2;
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_TRANSFER_SRC_BIT = 0x00000001ULL;
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_TRANSFER_DST_BIT = 0x00000002ULL;
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_UNIFORM_TEXEL_BUFFER_BIT = 0x00000004ULL;
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_STORAGE_TEXEL_BUFFER_BIT = 0x00000008ULL;
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_UNIFORM_BUFFER_BIT = 0x00000010ULL;
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_STORAGE_BUFFER_BIT = 0x00000020ULL;
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_INDEX_BUFFER_BIT = 0x00000040ULL;
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_VERTEX_BUFFER_BIT = 0x00000080ULL;
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_INDIRECT_BUFFER_BIT = 0x00000100ULL;
// Provided by VK_VERSION_1_4
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_SHADER_DEVICE_ADDRESS_BIT = 0x00020000ULL;
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_AMDX_shader_enqueue with VK_KHR_maintenance5 or VK_VERSION_1_4
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_EXECUTION_GRAPH_SCRATCH_BIT_AMDX = 0x02000000ULL;
#endif
// Provided by VK_KHR_maintenance5
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_TRANSFER_SRC_BIT_KHR = 0x00000001ULL;
// Provided by VK_KHR_maintenance5
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_TRANSFER_DST_BIT_KHR = 0x00000002ULL;
// Provided by VK_KHR_maintenance5
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_UNIFORM_TEXEL_BUFFER_BIT_KHR = 0x00000004ULL;
// Provided by VK_KHR_maintenance5
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_STORAGE_TEXEL_BUFFER_BIT_KHR = 0x00000008ULL;
// Provided by VK_KHR_maintenance5
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_UNIFORM_BUFFER_BIT_KHR = 0x00000010ULL;
// Provided by VK_KHR_maintenance5
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_STORAGE_BUFFER_BIT_KHR = 0x00000020ULL;
// Provided by VK_KHR_maintenance5
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_INDEX_BUFFER_BIT_KHR = 0x00000040ULL;
// Provided by VK_KHR_maintenance5
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_VERTEX_BUFFER_BIT_KHR = 0x00000080ULL;
// Provided by VK_KHR_maintenance5
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_INDIRECT_BUFFER_BIT_KHR = 0x00000100ULL;
// Provided by VK_KHR_maintenance5 with VK_EXT_conditional_rendering
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_CONDITIONAL_RENDERING_BIT_EXT = 0x00000200ULL;
// Provided by VK_KHR_maintenance5 with VK_KHR_ray_tracing_pipeline
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_SHADER_BINDING_TABLE_BIT_KHR = 0x00000400ULL;
// Provided by VK_KHR_maintenance5 with VK_NV_ray_tracing
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_RAY_TRACING_BIT_NV = 0x00000400ULL;
// Provided by VK_KHR_maintenance5 with VK_EXT_transform_feedback
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_TRANSFORM_FEEDBACK_BUFFER_BIT_EXT = 0x00000800ULL;
// Provided by VK_KHR_maintenance5 with VK_EXT_transform_feedback
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_TRANSFORM_FEEDBACK_COUNTER_BUFFER_BIT_EXT = 0x00001000ULL;
// Provided by VK_KHR_maintenance5 with VK_KHR_video_decode_queue
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_VIDEO_DECODE_SRC_BIT_KHR = 0x00002000ULL;
// Provided by VK_KHR_maintenance5 with VK_KHR_video_decode_queue
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_VIDEO_DECODE_DST_BIT_KHR = 0x00004000ULL;
// Provided by VK_KHR_maintenance5 with VK_KHR_video_encode_queue
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_VIDEO_ENCODE_DST_BIT_KHR = 0x00008000ULL;
// Provided by VK_KHR_maintenance5 with VK_KHR_video_encode_queue
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_VIDEO_ENCODE_SRC_BIT_KHR = 0x00010000ULL;
// Provided by VK_KHR_maintenance5 with (VK_VERSION_1_2 or VK_KHR_buffer_device_address) or VK_EXT_buffer_device_address
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_SHADER_DEVICE_ADDRESS_BIT_KHR = 0x00020000ULL;
// Provided by VK_KHR_acceleration_structure with VK_KHR_maintenance5
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_ACCELERATION_STRUCTURE_BUILD_INPUT_READ_ONLY_BIT_KHR = 0x00080000ULL;
// Provided by VK_KHR_acceleration_structure with VK_KHR_maintenance5
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_ACCELERATION_STRUCTURE_STORAGE_BIT_KHR = 0x00100000ULL;
// Provided by VK_KHR_maintenance5 with VK_EXT_descriptor_buffer
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_SAMPLER_DESCRIPTOR_BUFFER_BIT_EXT = 0x00200000ULL;
// Provided by VK_KHR_maintenance5 with VK_EXT_descriptor_buffer
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_RESOURCE_DESCRIPTOR_BUFFER_BIT_EXT = 0x00400000ULL;
// Provided by VK_KHR_maintenance5 with VK_EXT_descriptor_buffer
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_PUSH_DESCRIPTORS_DESCRIPTOR_BUFFER_BIT_EXT = 0x04000000ULL;
// Provided by VK_KHR_maintenance5 with VK_EXT_opacity_micromap
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_MICROMAP_BUILD_INPUT_READ_ONLY_BIT_EXT = 0x00800000ULL;
// Provided by VK_KHR_maintenance5 with VK_EXT_opacity_micromap
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_MICROMAP_STORAGE_BIT_EXT = 0x01000000ULL;
#ifdef VK_ENABLE_BETA_EXTENSIONS
// Provided by VK_AMDX_dense_geometry_format
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_COMPRESSED_DATA_DGF1_BIT_AMDX = 0x200000000ULL;
#endif
// Provided by VK_ARM_data_graph
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_DATA_GRAPH_FOREIGN_DESCRIPTOR_BIT_ARM = 0x20000000ULL;
// Provided by VK_QCOM_tile_memory_heap
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_TILE_MEMORY_BIT_QCOM = 0x08000000ULL;
// Provided by VK_EXT_memory_decompression
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_MEMORY_DECOMPRESSION_BIT_EXT = 0x100000000ULL;
// Provided by VK_EXT_device_generated_commands
static const VkBufferUsageFlagBits2 VK_BUFFER_USAGE_2_PREPROCESS_BUFFER_BIT_EXT = 0x80000000ULL;
// Provided by VK_KHR_maintenance5
// Equivalent to VkBufferUsageFlagBits2
typedef VkBufferUsageFlagBits2 VkBufferUsageFlagBits2KHR;
// Provided by VK_VERSION_1_4
typedef VkFlags64 VkBufferUsageFlags2;
// Provided by VK_KHR_maintenance5
// Equivalent to VkBufferUsageFlags2
typedef VkBufferUsageFlags2 VkBufferUsageFlags2KHR;

VkBufferUsageFlags2 is a bitmask type for setting a mask of zero or more VkBufferUsageFlagBits2.

Bits which can be set in VkBufferCreateInfo::usage, specifying usage behavior of a buffer, are:

// Provided by VK_VERSION_1_0
typedef enum VkBufferUsageFlagBits {
    VK_BUFFER_USAGE_TRANSFER_SRC_BIT = 0x00000001,
    VK_BUFFER_USAGE_TRANSFER_DST_BIT = 0x00000002,
    VK_BUFFER_USAGE_UNIFORM_TEXEL_BUFFER_BIT = 0x00000004,
    VK_BUFFER_USAGE_STORAGE_TEXEL_BUFFER_BIT = 0x00000008,
    VK_BUFFER_USAGE_UNIFORM_BUFFER_BIT = 0x00000010,
    VK_BUFFER_USAGE_STORAGE_BUFFER_BIT = 0x00000020,
    VK_BUFFER_USAGE_INDEX_BUFFER_BIT = 0x00000040,
    VK_BUFFER_USAGE_VERTEX_BUFFER_BIT = 0x00000080,
    VK_BUFFER_USAGE_INDIRECT_BUFFER_BIT = 0x00000100,
  // Provided by VK_VERSION_1_2
    VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT = 0x00020000,
  // Provided by VK_KHR_video_decode_queue
    VK_BUFFER_USAGE_VIDEO_DECODE_SRC_BIT_KHR = 0x00002000,
  // Provided by VK_KHR_video_decode_queue
    VK_BUFFER_USAGE_VIDEO_DECODE_DST_BIT_KHR = 0x00004000,
  // Provided by VK_EXT_transform_feedback
    VK_BUFFER_USAGE_TRANSFORM_FEEDBACK_BUFFER_BIT_EXT = 0x00000800,
  // Provided by VK_EXT_transform_feedback
    VK_BUFFER_USAGE_TRANSFORM_FEEDBACK_COUNTER_BUFFER_BIT_EXT = 0x00001000,
  // Provided by VK_EXT_conditional_rendering
    VK_BUFFER_USAGE_CONDITIONAL_RENDERING_BIT_EXT = 0x00000200,
#ifdef VK_ENABLE_BETA_EXTENSIONS
  // Provided by VK_AMDX_shader_enqueue
    VK_BUFFER_USAGE_EXECUTION_GRAPH_SCRATCH_BIT_AMDX = 0x02000000,
#endif
  // Provided by VK_KHR_acceleration_structure
    VK_BUFFER_USAGE_ACCELERATION_STRUCTURE_BUILD_INPUT_READ_ONLY_BIT_KHR = 0x00080000,
  // Provided by VK_KHR_acceleration_structure
    VK_BUFFER_USAGE_ACCELERATION_STRUCTURE_STORAGE_BIT_KHR = 0x00100000,
  // Provided by VK_KHR_ray_tracing_pipeline
    VK_BUFFER_USAGE_SHADER_BINDING_TABLE_BIT_KHR = 0x00000400,
  // Provided by VK_KHR_video_encode_queue
    VK_BUFFER_USAGE_VIDEO_ENCODE_DST_BIT_KHR = 0x00008000,
  // Provided by VK_KHR_video_encode_queue
    VK_BUFFER_USAGE_VIDEO_ENCODE_SRC_BIT_KHR = 0x00010000,
  // Provided by VK_EXT_descriptor_buffer
    VK_BUFFER_USAGE_SAMPLER_DESCRIPTOR_BUFFER_BIT_EXT = 0x00200000,
  // Provided by VK_EXT_descriptor_buffer
    VK_BUFFER_USAGE_RESOURCE_DESCRIPTOR_BUFFER_BIT_EXT = 0x00400000,
  // Provided by VK_EXT_descriptor_buffer
    VK_BUFFER_USAGE_PUSH_DESCRIPTORS_DESCRIPTOR_BUFFER_BIT_EXT = 0x04000000,
  // Provided by VK_EXT_opacity_micromap
    VK_BUFFER_USAGE_MICROMAP_BUILD_INPUT_READ_ONLY_BIT_EXT = 0x00800000,
  // Provided by VK_EXT_opacity_micromap
    VK_BUFFER_USAGE_MICROMAP_STORAGE_BIT_EXT = 0x01000000,
  // Provided by VK_QCOM_tile_memory_heap
    VK_BUFFER_USAGE_TILE_MEMORY_BIT_QCOM = 0x08000000,
  // Provided by VK_NV_ray_tracing
    VK_BUFFER_USAGE_RAY_TRACING_BIT_NV = VK_BUFFER_USAGE_SHADER_BINDING_TABLE_BIT_KHR,
  // Provided by VK_EXT_buffer_device_address
    VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT_EXT = VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT,
  // Provided by VK_KHR_buffer_device_address
    VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT_KHR = VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT,
} VkBufferUsageFlagBits;
// Provided by VK_VERSION_1_0
typedef VkFlags VkBufferUsageFlags;

VkBufferUsageFlags is a bitmask type for setting a mask of zero or more VkBufferUsageFlagBits.

Bits which can be set in VkBufferCreateInfo::flags, specifying additional parameters of a buffer, are:

// Provided by VK_VERSION_1_0
typedef enum VkBufferCreateFlagBits {
    VK_BUFFER_CREATE_SPARSE_BINDING_BIT = 0x00000001,
    VK_BUFFER_CREATE_SPARSE_RESIDENCY_BIT = 0x00000002,
    VK_BUFFER_CREATE_SPARSE_ALIASED_BIT = 0x00000004,
  // Provided by VK_VERSION_1_1
    VK_BUFFER_CREATE_PROTECTED_BIT = 0x00000008,
  // Provided by VK_VERSION_1_2
    VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT = 0x00000010,
  // Provided by VK_EXT_descriptor_buffer
    VK_BUFFER_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXT = 0x00000020,
  // Provided by VK_KHR_video_maintenance1
    VK_BUFFER_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHR = 0x00000040,
  // Provided by VK_EXT_buffer_device_address
    VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT_EXT = VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT,
  // Provided by VK_KHR_buffer_device_address
    VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT_KHR = VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT,
} VkBufferCreateFlagBits;

See Sparse Resource Features and Physical Device Features for details of the sparse memory features supported on a device.

// Provided by VK_VERSION_1_0
typedef VkFlags VkBufferCreateFlags;

VkBufferCreateFlags is a bitmask type for setting a mask of zero or more VkBufferCreateFlagBits.

If the pNext chain includes a VkDedicatedAllocationBufferCreateInfoNV structure, then that structure includes an enable controlling whether the buffer will have a dedicated memory allocation bound to it.

The VkDedicatedAllocationBufferCreateInfoNV structure is defined as:

// Provided by VK_NV_dedicated_allocation
typedef struct VkDedicatedAllocationBufferCreateInfoNV {
    VkStructureType    sType;
    const void*        pNext;
    VkBool32           dedicatedAllocation;
} VkDedicatedAllocationBufferCreateInfoNV;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • dedicatedAllocation specifies whether the buffer will have a dedicated allocation bound to it.

Valid Usage (Implicit)

To define a set of external memory handle types that may be used as backing store for a buffer, add a VkExternalMemoryBufferCreateInfo structure to the pNext chain of the VkBufferCreateInfo structure. The VkExternalMemoryBufferCreateInfo structure is defined as:

// Provided by VK_VERSION_1_1
typedef struct VkExternalMemoryBufferCreateInfo {
    VkStructureType                    sType;
    const void*                        pNext;
    VkExternalMemoryHandleTypeFlags    handleTypes;
} VkExternalMemoryBufferCreateInfo;
// Provided by VK_KHR_external_memory
// Equivalent to VkExternalMemoryBufferCreateInfo
typedef VkExternalMemoryBufferCreateInfo VkExternalMemoryBufferCreateInfoKHR;

A VkExternalMemoryBufferCreateInfo structure with a non-zero handleTypes field must be included in the creation parameters for a buffer that will be bound to memory that is either exported or imported.

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • handleTypes is zero or a bitmask of VkExternalMemoryHandleTypeFlagBits specifying one or more external memory handle types.

Valid Usage (Implicit)

To request a specific device address for a buffer, add a VkBufferOpaqueCaptureAddressCreateInfo structure to the pNext chain of the VkBufferCreateInfo structure. The VkBufferOpaqueCaptureAddressCreateInfo structure is defined as:

// Provided by VK_VERSION_1_2
typedef struct VkBufferOpaqueCaptureAddressCreateInfo {
    VkStructureType    sType;
    const void*        pNext;
    uint64_t           opaqueCaptureAddress;
} VkBufferOpaqueCaptureAddressCreateInfo;
// Provided by VK_KHR_buffer_device_address
// Equivalent to VkBufferOpaqueCaptureAddressCreateInfo
typedef VkBufferOpaqueCaptureAddressCreateInfo VkBufferOpaqueCaptureAddressCreateInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • opaqueCaptureAddress is the opaque capture address requested for the buffer.

If opaqueCaptureAddress is zero, no specific address is requested.

If opaqueCaptureAddress is not zero, then it should be an address retrieved from vkGetBufferOpaqueCaptureAddress for an identically created buffer on the same implementation.

If this structure is not present, it is as if opaqueCaptureAddress is zero.

Applications should avoid creating buffers with application-provided addresses and implementation-provided addresses in the same process, to reduce the likelihood of VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS errors.

The expected usage for this is that a trace capture/replay tool will add the VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT flag to all buffers that use VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT, and during capture will save the queried opaque device addresses in the trace. During replay, the buffers will be created specifying the original address so any address values stored in the trace data will remain valid.

Implementations are expected to separate such buffers in the GPU address space so normal allocations will avoid using these addresses. Applications and tools should avoid mixing application-provided and implementation-provided addresses for buffers created with VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT, to avoid address space allocation conflicts.
Valid Usage (Implicit)

To request a specific device address for a buffer, add a VkBufferDeviceAddressCreateInfoEXT structure to the pNext chain of the VkBufferCreateInfo structure. The VkBufferDeviceAddressCreateInfoEXT structure is defined as:

// Provided by VK_EXT_buffer_device_address
typedef struct VkBufferDeviceAddressCreateInfoEXT {
    VkStructureType    sType;
    const void*        pNext;
    VkDeviceAddress    deviceAddress;
} VkBufferDeviceAddressCreateInfoEXT;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • deviceAddress is the device address requested for the buffer.

If deviceAddress is zero, no specific address is requested.

If deviceAddress is not zero, then it must be an address retrieved from an identically created buffer on the same implementation. The buffer must also be bound to an identically created VkDeviceMemory object.

If this structure is not present, it is as if deviceAddress is zero.

Applications should avoid creating buffers with application-provided addresses and implementation-provided addresses in the same process, to reduce the likelihood of VK_ERROR_INVALID_DEVICE_ADDRESS_EXT errors.

Valid Usage (Implicit)

The VkBufferCollectionBufferCreateInfoFUCHSIA structure is defined as:

// Provided by VK_FUCHSIA_buffer_collection
typedef struct VkBufferCollectionBufferCreateInfoFUCHSIA {
    VkStructureType              sType;
    const void*                  pNext;
    VkBufferCollectionFUCHSIA    collection;
    uint32_t                     index;
} VkBufferCollectionBufferCreateInfoFUCHSIA;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure

  • collection is the VkBufferCollectionFUCHSIA handle

  • index is the index of the buffer in the buffer collection from which the memory will be imported

Valid Usage
Valid Usage (Implicit)

To destroy a buffer, call:

// Provided by VK_VERSION_1_0
void vkDestroyBuffer(
    VkDevice                                    device,
    VkBuffer                                    buffer,
    const VkAllocationCallbacks*                pAllocator);

  • device is the logical device that destroys the buffer.

  • buffer is the buffer to destroy.

  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

Valid Usage

  • VUID-vkDestroyBuffer-buffer-00922
    All submitted commands that refer to buffer, either directly or via a VkBufferView, must have completed execution

  • VUID-vkDestroyBuffer-buffer-00923
    If VkAllocationCallbacks were provided when buffer was created, a compatible set of callbacks must be provided here

  • VUID-vkDestroyBuffer-buffer-00924
    If no VkAllocationCallbacks were provided when buffer was created, pAllocator must be NULL

Valid Usage (Implicit)

  • VUID-vkDestroyBuffer-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkDestroyBuffer-buffer-parameter
    If buffer is not VK_NULL_HANDLE, buffer must be a valid VkBuffer handle

  • VUID-vkDestroyBuffer-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkDestroyBuffer-buffer-parent
    If buffer is a valid handle, it must have been created, allocated, or retrieved from device

Host Synchronization

  • Host access to buffer must be externally synchronized

Buffer Views

A buffer view represents a contiguous range of a buffer and a specific format to be used to interpret the data. Buffer views are used to enable shaders to access buffer contents using image operations. In order to create a valid buffer view, the buffer must have been created with at least one of the following usage flags:

Buffer views are represented by VkBufferView handles:

// Provided by VK_VERSION_1_0
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkBufferView)

To create a buffer view, call:

// Provided by VK_VERSION_1_0
VkResult vkCreateBufferView(
    VkDevice                                    device,
    const VkBufferViewCreateInfo*               pCreateInfo,
    const VkAllocationCallbacks*                pAllocator,
    VkBufferView*                               pView);

  • device is the logical device that creates the buffer view.

  • pCreateInfo is a pointer to a VkBufferViewCreateInfo structure containing parameters to be used to create the buffer view.

  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

  • pView is a pointer to a VkBufferView handle in which the resulting buffer view object is returned.

Valid Usage
Valid Usage (Implicit)

  • VUID-vkCreateBufferView-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkCreateBufferView-pCreateInfo-parameter
    pCreateInfo must be a valid pointer to a valid VkBufferViewCreateInfo structure

  • VUID-vkCreateBufferView-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkCreateBufferView-pView-parameter
    pView must be a valid pointer to a VkBufferView handle

  • VUID-vkCreateBufferView-device-queuecount
    The device must have been created with at least 1 queue

Return Codes
Success
Failure

The VkBufferViewCreateInfo structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkBufferViewCreateInfo {
    VkStructureType            sType;
    const void*                pNext;
    VkBufferViewCreateFlags    flags;
    VkBuffer                   buffer;
    VkFormat                   format;
    VkDeviceSize               offset;
    VkDeviceSize               range;
} VkBufferViewCreateInfo;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • flags is reserved for future use.

  • buffer is a VkBuffer on which the view will be created.

  • format is a VkFormat describing the format of the data elements in the buffer.

  • offset is an offset in bytes from the base address of the buffer. Accesses to the buffer view from shaders use addressing that is relative to this starting offset.

  • range is a size in bytes of the buffer view. If range is equal to VK_WHOLE_SIZE, the range from offset to the end of the buffer is used. If VK_WHOLE_SIZE is used and the remaining size of the buffer is not a multiple of the texel block size of format, the nearest smaller multiple is used.

The buffer view has a buffer view usage identifying which descriptor types can be created from it. This usage can be defined by including the VkBufferUsageFlags2CreateInfo structure in the pNext chain, and specifying the usage value there. If this structure is not included, it is equal to the VkBufferCreateInfo::usage value used to create buffer.

Valid Usage
Valid Usage (Implicit)
// Provided by VK_VERSION_1_0
typedef VkFlags VkBufferViewCreateFlags;

VkBufferViewCreateFlags is a bitmask type for setting a mask, but is currently reserved for future use.

To destroy a buffer view, call:

// Provided by VK_VERSION_1_0
void vkDestroyBufferView(
    VkDevice                                    device,
    VkBufferView                                bufferView,
    const VkAllocationCallbacks*                pAllocator);

  • device is the logical device that destroys the buffer view.

  • bufferView is the buffer view to destroy.

  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

Valid Usage

  • VUID-vkDestroyBufferView-bufferView-00936
    All submitted commands that refer to bufferView must have completed execution

  • VUID-vkDestroyBufferView-bufferView-00937
    If VkAllocationCallbacks were provided when bufferView was created, a compatible set of callbacks must be provided here

  • VUID-vkDestroyBufferView-bufferView-00938
    If no VkAllocationCallbacks were provided when bufferView was created, pAllocator must be NULL

Valid Usage (Implicit)

  • VUID-vkDestroyBufferView-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkDestroyBufferView-bufferView-parameter
    If bufferView is not VK_NULL_HANDLE, bufferView must be a valid VkBufferView handle

  • VUID-vkDestroyBufferView-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkDestroyBufferView-bufferView-parent
    If bufferView is a valid handle, it must have been created, allocated, or retrieved from device

Host Synchronization

  • Host access to bufferView must be externally synchronized

Buffer View Format Features

Valid uses of a VkBufferView may depend on the buffer view’s format features, defined below. Such constraints are documented in the affected valid usage statement.

Buffer Device Addresses

To query a 64-bit buffer device address value which can be used to identify a buffer to API commands or through which buffer memory can be accessed, call:

// Provided by VK_VERSION_1_2
VkDeviceAddress vkGetBufferDeviceAddress(
    VkDevice                                    device,
    const VkBufferDeviceAddressInfo*            pInfo);
// Provided by VK_KHR_buffer_device_address
// Equivalent to vkGetBufferDeviceAddress
VkDeviceAddress vkGetBufferDeviceAddressKHR(
    VkDevice                                    device,
    const VkBufferDeviceAddressInfo*            pInfo);
// Provided by VK_EXT_buffer_device_address
// Equivalent to vkGetBufferDeviceAddress
VkDeviceAddress vkGetBufferDeviceAddressEXT(
    VkDevice                                    device,
    const VkBufferDeviceAddressInfo*            pInfo);

  • device is the logical device that the buffer was created on.

  • pInfo is a pointer to a VkBufferDeviceAddressInfo structure specifying the buffer to retrieve an address for.

The 64-bit return value, bufferBaseAddress, is an address of the start of pInfo->buffer. Addresses in the range [bufferBaseAddress, bufferBaseAddress + VkBufferCreateInfo::size) can be used to access the memory bound to this buffer on the device.

A value of zero is reserved as a “null” pointer and must not be returned as a valid buffer device address.

If the buffer was created with a non-zero value of VkBufferOpaqueCaptureAddressCreateInfo::opaqueCaptureAddress or VkBufferDeviceAddressCreateInfoEXT::deviceAddress, the return value will be the same address that was returned at capture time.

The returned address must satisfy the alignment requirement specified by VkMemoryRequirements::alignment for the buffer in VkBufferDeviceAddressInfo::buffer.

If multiple VkBuffer objects are bound to overlapping ranges of VkDeviceMemory, implementations may return address ranges which overlap. In this case, it is ambiguous which VkBuffer is associated with any given device address. For purposes of valid usage, if multiple VkBuffer objects can be attributed to a device address, a VkBuffer is selected such that valid usage passes, if it exists.

Valid Usage
Valid Usage (Implicit)

  • VUID-vkGetBufferDeviceAddress-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetBufferDeviceAddress-pInfo-parameter
    pInfo must be a valid pointer to a valid VkBufferDeviceAddressInfo structure

The VkBufferDeviceAddressInfo structure is defined as:

// Provided by VK_VERSION_1_2
typedef struct VkBufferDeviceAddressInfo {
    VkStructureType    sType;
    const void*        pNext;
    VkBuffer           buffer;
} VkBufferDeviceAddressInfo;
// Provided by VK_KHR_buffer_device_address
// Equivalent to VkBufferDeviceAddressInfo
typedef VkBufferDeviceAddressInfo VkBufferDeviceAddressInfoKHR;
// Provided by VK_EXT_buffer_device_address
// Equivalent to VkBufferDeviceAddressInfo
typedef VkBufferDeviceAddressInfo VkBufferDeviceAddressInfoEXT;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • buffer specifies the buffer whose address is being queried.

Valid Usage
Valid Usage (Implicit)

To query a 64-bit buffer opaque capture address, call:

// Provided by VK_VERSION_1_2
uint64_t vkGetBufferOpaqueCaptureAddress(
    VkDevice                                    device,
    const VkBufferDeviceAddressInfo*            pInfo);
// Provided by VK_KHR_buffer_device_address
// Equivalent to vkGetBufferOpaqueCaptureAddress
uint64_t vkGetBufferOpaqueCaptureAddressKHR(
    VkDevice                                    device,
    const VkBufferDeviceAddressInfo*            pInfo);

  • device is the logical device that the buffer was created on.

  • pInfo is a pointer to a VkBufferDeviceAddressInfo structure specifying the buffer to retrieve an address for.

The 64-bit return value is an opaque capture address of the start of pInfo->buffer.

If the buffer was created with a non-zero value of VkBufferOpaqueCaptureAddressCreateInfo::opaqueCaptureAddress the return value must be the same address.

Valid Usage
Valid Usage (Implicit)

  • VUID-vkGetBufferOpaqueCaptureAddress-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetBufferOpaqueCaptureAddress-pInfo-parameter
    pInfo must be a valid pointer to a valid VkBufferDeviceAddressInfo structure

The VkStridedDeviceAddressRegionKHR structure is defined as:

// Provided by VK_KHR_ray_tracing_pipeline
typedef struct VkStridedDeviceAddressRegionKHR {
    VkDeviceAddress    deviceAddress;
    VkDeviceSize       stride;
    VkDeviceSize       size;
} VkStridedDeviceAddressRegionKHR;

  • deviceAddress is the device address (as returned by the vkGetBufferDeviceAddress command) at which the region starts, or zero if the region is unused.

  • stride is the byte stride between consecutive elements.

  • size is the size in bytes of the region starting at deviceAddress.

Valid Usage

  • VUID-VkStridedDeviceAddressRegionKHR-size-04631
    If size is not zero, all addresses between deviceAddress and deviceAddress + size - 1 must be in the buffer device address range of the same buffer

  • VUID-VkStridedDeviceAddressRegionKHR-size-04632
    If size is not zero, stride must be less than or equal to the size of the buffer from which deviceAddress was queried

Valid Usage (Implicit)

  • VUID-VkStridedDeviceAddressRegionKHR-deviceAddress-parameter
    If deviceAddress is not 0, deviceAddress must be a valid VkDeviceAddress value

Images

Images are specialized resources that have multi-dimensional access, as outlined in the Images chapter. Images can be used for various purposes, such as rendering attachments, for copy operations, or accessed through shaders via resource descriptors.

Images are represented by VkImage handles:

// Provided by VK_VERSION_1_0
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkImage)

To create images, call:

// Provided by VK_VERSION_1_0
VkResult vkCreateImage(
    VkDevice                                    device,
    const VkImageCreateInfo*                    pCreateInfo,
    const VkAllocationCallbacks*                pAllocator,
    VkImage*                                    pImage);

  • device is the logical device that creates the image.

  • pCreateInfo is a pointer to a VkImageCreateInfo structure containing parameters to be used to create the image.

  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

  • pImage is a pointer to a VkImage handle in which the resulting image object is returned.

Valid Usage

  • VUID-vkCreateImage-device-09666
    device must support at least one queue family with one of the VK_QUEUE_VIDEO_ENCODE_BIT_KHR, VK_QUEUE_VIDEO_DECODE_BIT_KHR, VK_QUEUE_OPTICAL_FLOW_BIT_NV, VK_QUEUE_SPARSE_BINDING_BIT, VK_QUEUE_TRANSFER_BIT, VK_QUEUE_COMPUTE_BIT, or VK_QUEUE_GRAPHICS_BIT capabilities

  • VUID-vkCreateImage-flags-00939
    If the flags member of pCreateInfo includes VK_IMAGE_CREATE_SPARSE_BINDING_BIT, and the extendedSparseAddressSpace feature is not enabled, creating this VkImage must not cause the total required sparse memory for all currently valid sparse resources on the device to exceed VkPhysicalDeviceLimits::sparseAddressSpaceSize

  • VUID-vkCreateImage-flags-09385
    If the flags member of pCreateInfo includes VK_IMAGE_CREATE_SPARSE_BINDING_BIT, the extendedSparseAddressSpace feature is enabled, and the usage member of pCreateInfo contains bits not in VkPhysicalDeviceExtendedSparseAddressSpacePropertiesNV::extendedSparseImageUsageFlags, creating this VkImage must not cause the total required sparse memory for all currently valid sparse resources on the device, excluding VkBuffer created with usage member of pCreateInfo containing bits in VkPhysicalDeviceExtendedSparseAddressSpacePropertiesNV::extendedSparseBufferUsageFlags and VkImage created with usage member of pCreateInfo containing bits in VkPhysicalDeviceExtendedSparseAddressSpacePropertiesNV::extendedSparseImageUsageFlags, to exceed VkPhysicalDeviceLimits::sparseAddressSpaceSize

  • VUID-vkCreateImage-flags-09386
    If the flags member of pCreateInfo includes VK_IMAGE_CREATE_SPARSE_BINDING_BIT and the extendedSparseAddressSpace feature is enabled, creating this VkImage must not cause the total required sparse memory for all currently valid sparse resources on the device to exceed VkPhysicalDeviceExtendedSparseAddressSpacePropertiesNV::extendedSparseAddressSpaceSize

Valid Usage (Implicit)

  • VUID-vkCreateImage-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkCreateImage-pCreateInfo-parameter
    pCreateInfo must be a valid pointer to a valid VkImageCreateInfo structure

  • VUID-vkCreateImage-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkCreateImage-pImage-parameter
    pImage must be a valid pointer to a VkImage handle

  • VUID-vkCreateImage-device-queuecount
    The device must have been created with at least 1 queue

Return Codes
Success
Failure

The VkImageCreateInfo structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkImageCreateInfo {
    VkStructureType          sType;
    const void*              pNext;
    VkImageCreateFlags       flags;
    VkImageType              imageType;
    VkFormat                 format;
    VkExtent3D               extent;
    uint32_t                 mipLevels;
    uint32_t                 arrayLayers;
    VkSampleCountFlagBits    samples;
    VkImageTiling            tiling;
    VkImageUsageFlags        usage;
    VkSharingMode            sharingMode;
    uint32_t                 queueFamilyIndexCount;
    const uint32_t*          pQueueFamilyIndices;
    VkImageLayout            initialLayout;
} VkImageCreateInfo;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • flags is a bitmask of VkImageCreateFlagBits describing additional parameters of the image.

  • imageType is a VkImageType value specifying the basic dimensionality of the image. Layers in array textures do not count as a dimension for the purposes of the image type.

  • format is a VkFormat describing the format and type of the texel blocks that will be contained in the image.

  • extent is a VkExtent3D describing the number of texels/pixels in each dimension of the base level.

  • mipLevels describes the number of levels of detail available for minified sampling of the image.

  • arrayLayers is the number of layers in the image.

  • samples is a VkSampleCountFlagBits value specifying the number of samples per texel.

  • tiling is a VkImageTiling value specifying the tiling arrangement of the texel blocks in memory.

  • usage is a bitmask of VkImageUsageFlagBits describing the intended usage of the image.

  • sharingMode is a VkSharingMode value specifying the sharing mode of the image when it will be accessed by multiple queue families.

  • queueFamilyIndexCount is the number of entries in the pQueueFamilyIndices array.

  • pQueueFamilyIndices is a pointer to an array of queue families that will access this image. It is ignored if sharingMode is not VK_SHARING_MODE_CONCURRENT.

  • initialLayout is a VkImageLayout value specifying the initial VkImageLayout of all image subresources of the image. See Image Layouts.

Images created with tiling equal to VK_IMAGE_TILING_LINEAR have further restrictions on their limits and capabilities compared to images created with tiling equal to VK_IMAGE_TILING_OPTIMAL. Creation of images with tiling VK_IMAGE_TILING_LINEAR may not be supported unless other parameters meet all of the constraints:

Images created with one of the formats that require a sampler Y′CBCR conversion, have further restrictions on their limits and capabilities compared to images created with other formats. Creation of images with a format requiring Y′CBCR conversion may not be supported unless other parameters meet all of the constraints:

Images created with the VK_IMAGE_USAGE_TILE_MEMORY_BIT_QCOM usage flag set have further restrictions on their limits and capabilities compared to images created without this flag. Creation of images with usage including VK_IMAGE_USAGE_TILE_MEMORY_BIT_QCOM may not be supported unless parameters meet all of the constraints:

Implementations may support additional limits and capabilities beyond those listed above.

To determine the set of valid usage bits for a given format, call vkGetPhysicalDeviceFormatProperties.

If the size of the resultant image would exceed maxResourceSize, then vkCreateImage must fail and return VK_ERROR_OUT_OF_DEVICE_MEMORY. This failure may occur even when all image creation parameters satisfy their valid usage requirements.

If the implementation reports VK_TRUE in VkPhysicalDeviceHostImageCopyProperties::identicalMemoryTypeRequirements, usage of VK_IMAGE_USAGE_HOST_TRANSFER_BIT must not affect the memory type requirements of the image as described in Sparse Resource Memory Requirements and Resource Memory Association.

For images created without the VK_IMAGE_CREATE_EXTENDED_USAGE_BIT flag set, a usage bit is valid if it is supported for the format the image is created with.

For images created with VK_IMAGE_CREATE_EXTENDED_USAGE_BIT a usage bit is valid if it is supported for at least one of the formats a VkImageView created from the image can have (see Image Views for more detail).
Image Creation Limits

Valid values for some image creation parameters are limited by a numerical upper bound or by inclusion in a bitset. For example, VkImageCreateInfo::arrayLayers is limited by imageCreateMaxArrayLayers, defined below; and VkImageCreateInfo::samples is limited by imageCreateSampleCounts, also defined below.

Several limiting values are defined below, as well as assisting values from which the limiting values are derived. The limiting values are referenced by the relevant valid usage statements of VkImageCreateInfo.

Valid Usage
Valid Usage (Implicit)

The VkBufferCollectionImageCreateInfoFUCHSIA structure is defined as:

// Provided by VK_FUCHSIA_buffer_collection
typedef struct VkBufferCollectionImageCreateInfoFUCHSIA {
    VkStructureType              sType;
    const void*                  pNext;
    VkBufferCollectionFUCHSIA    collection;
    uint32_t                     index;
} VkBufferCollectionImageCreateInfoFUCHSIA;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure

  • collection is the VkBufferCollectionFUCHSIA handle

  • index is the index of the buffer in the buffer collection from which the memory will be imported

Valid Usage
Valid Usage (Implicit)

The VkImageStencilUsageCreateInfo structure is defined as:

// Provided by VK_VERSION_1_2
typedef struct VkImageStencilUsageCreateInfo {
    VkStructureType      sType;
    const void*          pNext;
    VkImageUsageFlags    stencilUsage;
} VkImageStencilUsageCreateInfo;
// Provided by VK_EXT_separate_stencil_usage
// Equivalent to VkImageStencilUsageCreateInfo
typedef VkImageStencilUsageCreateInfo VkImageStencilUsageCreateInfoEXT;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • stencilUsage is a bitmask of VkImageUsageFlagBits describing the intended usage of the stencil aspect of the image.

If the pNext chain of VkImageCreateInfo includes a VkImageStencilUsageCreateInfo structure, then that structure includes the usage flags specific to the stencil aspect of the image for an image with a depth-stencil format.

This structure specifies image usages which only apply to the stencil aspect of a depth/stencil format image. When this structure is included in the pNext chain of VkImageCreateInfo, the stencil aspect of the image must only be used as specified by stencilUsage. When this structure is not included in the pNext chain of VkImageCreateInfo, the stencil aspect of an image must only be used as specified by VkImageCreateInfo::usage. Use of other aspects of an image are unaffected by this structure.

This structure can also be included in the pNext chain of VkPhysicalDeviceImageFormatInfo2 to query additional capabilities specific to image creation parameter combinations including a separate set of usage flags for the stencil aspect of the image using vkGetPhysicalDeviceImageFormatProperties2. When this structure is not included in the pNext chain of VkPhysicalDeviceImageFormatInfo2 then the implicit value of stencilUsage matches that of VkPhysicalDeviceImageFormatInfo2::usage.

Valid Usage
Valid Usage (Implicit)

If the pNext chain includes a VkDedicatedAllocationImageCreateInfoNV structure, then that structure includes an enable controlling whether the image will have a dedicated memory allocation bound to it.

The VkDedicatedAllocationImageCreateInfoNV structure is defined as:

// Provided by VK_NV_dedicated_allocation
typedef struct VkDedicatedAllocationImageCreateInfoNV {
    VkStructureType    sType;
    const void*        pNext;
    VkBool32           dedicatedAllocation;
} VkDedicatedAllocationImageCreateInfoNV;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • dedicatedAllocation specifies whether the image will have a dedicated allocation bound to it.

Using a dedicated allocation for color and depth/stencil attachments or other large images may improve performance on some devices.
Valid Usage
Valid Usage (Implicit)

To define a set of external memory handle types that may be used as backing store for an image, add a VkExternalMemoryImageCreateInfo structure to the pNext chain of the VkImageCreateInfo structure. The VkExternalMemoryImageCreateInfo structure is defined as:

// Provided by VK_VERSION_1_1
typedef struct VkExternalMemoryImageCreateInfo {
    VkStructureType                    sType;
    const void*                        pNext;
    VkExternalMemoryHandleTypeFlags    handleTypes;
} VkExternalMemoryImageCreateInfo;
// Provided by VK_KHR_external_memory
// Equivalent to VkExternalMemoryImageCreateInfo
typedef VkExternalMemoryImageCreateInfo VkExternalMemoryImageCreateInfoKHR;

A VkExternalMemoryImageCreateInfo structure with a non-zero handleTypes field must be included in the creation parameters for an image that will be bound to memory that is either exported or imported.

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • handleTypes is zero or a bitmask of VkExternalMemoryHandleTypeFlagBits specifying one or more external memory handle types.

Valid Usage (Implicit)

Use External Memory On Open Harmony OS platform

The VkExternalFormatOHOS structure is defined as:

// Provided by VK_OHOS_external_memory
typedef struct VkExternalFormatOHOS {
    VkStructureType    sType;
    void*              pNext;
    uint64_t           externalFormat;
} VkExternalFormatOHOS;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • externalFormat is an implementation-defined identifier for the external format.

To obtain additional format that are not provided by VkFormat for an Open Harmony OS hardware buffer, this structure should be included in the pNext chain of another structure. The return value of externalFormat indicates whether an additional format exists. If zero is returned, then no external format is used and other format information should be used for implementations, and this is also true if this structure is not present.

Valid Usage (Implicit)

To import memory created outside of the current Vulkan instance from an Open Harmony OS native buffer, add a VkImportNativeBufferInfoOHOS structure to the pNext chain of the VkMemoryAllocateInfo structure. The VkImportNativeBufferInfoOHOS structure is defined as:

// Provided by VK_OHOS_external_memory
typedef struct VkImportNativeBufferInfoOHOS {
    VkStructureType            sType;
    const void*                pNext;
    struct OH_NativeBuffer*    buffer;
} VkImportNativeBufferInfoOHOS;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • buffer is a pointer to an OH_NativeBuffer structure.

A reference to the imported native buffer should be acquired by the implementation if the vkAllocateMemory command succeeds. Then the reference must release when the device memory object is freed. If the command fails, the implementation must not retain a reference.

Valid Usage (Implicit)

The OH_NativeBuffer structure is defined as:

// Provided by VK_OHOS_external_memory
struct OH_NativeBuffer;

It is the native buffer structure on Open Harmony OS platform. It is defined in Open Harmony OS NDK headers.

To obtain optimal Open Harmony OS native buffer usage flags for specific image creation parameters, add a VkNativeBufferUsageOHOS structure to the pNext chain of a VkImageFormatProperties2 structure passed to vkGetPhysicalDeviceImageFormatProperties2.

The VkNativeBufferUsageOHOS structure is defined as:

// Provided by VK_OHOS_external_memory
typedef struct VkNativeBufferUsageOHOS {
    VkStructureType    sType;
    void*              pNext;
    uint64_t           OHOSNativeBufferUsage;
} VkNativeBufferUsageOHOS;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • OHOSNativeBufferUsage returns the Open Harmony OS buffer usage flags.

Valid Usage (Implicit)

To determine the memory parameters to use when importing an Open Harmony OS native buffer:

// Provided by VK_OHOS_external_memory
VkResult vkGetNativeBufferPropertiesOHOS(
    VkDevice                                    device,
    const struct OH_NativeBuffer*               buffer,
    VkNativeBufferPropertiesOHOS*               pProperties);

  • device is the logical device that will be importing buffer.

  • buffer is the OH_NativeBuffer object specifies the buffer for which its properties are to be queried.

  • pProperties is a pointer to a VkNativeBufferPropertiesOHOS structure in which the properties of buffer are returned.

Valid Usage (Implicit)

  • VUID-vkGetNativeBufferPropertiesOHOS-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetNativeBufferPropertiesOHOS-buffer-parameter
    buffer must be a valid pointer to a valid OH_NativeBuffer value

  • VUID-vkGetNativeBufferPropertiesOHOS-pProperties-parameter
    pProperties must be a valid pointer to a VkNativeBufferPropertiesOHOS structure

Return Codes
Success
Failure

To obtain an OH_NativeBuffer object, call:

// Provided by VK_OHOS_external_memory
VkResult vkGetMemoryNativeBufferOHOS(
    VkDevice                                    device,
    const VkMemoryGetNativeBufferInfoOHOS*      pInfo,
    struct OH_NativeBuffer**                    pBuffer);

  • device is a valid Vulkan device object.

  • pInfo is a pointer pointing to a VkMemoryGetNativeBufferInfoOHOS structure.

  • pBuffer is a pointer to an OH_NativeBuffer object.

Valid Usage (Implicit)

  • VUID-vkGetMemoryNativeBufferOHOS-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetMemoryNativeBufferOHOS-pInfo-parameter
    pInfo must be a valid pointer to a valid VkMemoryGetNativeBufferInfoOHOS structure

  • VUID-vkGetMemoryNativeBufferOHOS-pBuffer-parameter
    pBuffer must be a valid pointer to a valid pointer to an OH_NativeBuffer value

Return Codes
Success
Failure

The VkNativeBufferPropertiesOHOS structure is defined as:

// Provided by VK_OHOS_external_memory
typedef struct VkNativeBufferPropertiesOHOS {
    VkStructureType    sType;
    void*              pNext;
    VkDeviceSize       allocationSize;
    uint32_t           memoryTypeBits;
} VkNativeBufferPropertiesOHOS;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • allocationSize is the size of the external memory.

  • memoryTypeBits is a bitmask containing one bit set for every memory type which the specified Open Harmony OS native buffer can be imported as.

Valid Usage (Implicit)

To obtain format properties of an Open Harmony OS native buffer, include a VkNativeBufferFormatPropertiesOHOS structure in the pNext chain of the VkNativeBufferPropertiesOHOS structure passed to vkGetNativeBufferPropertiesOHOS. The VkNativeBufferFormatPropertiesOHOS structure is defined as:

// Provided by VK_OHOS_external_memory
typedef struct VkNativeBufferFormatPropertiesOHOS {
    VkStructureType                  sType;
    void*                            pNext;
    VkFormat                         format;
    uint64_t                         externalFormat;
    VkFormatFeatureFlags             formatFeatures;
    VkComponentMapping               samplerYcbcrConversionComponents;
    VkSamplerYcbcrModelConversion    suggestedYcbcrModel;
    VkSamplerYcbcrRange              suggestedYcbcrRange;
    VkChromaLocation                 suggestedXChromaOffset;
    VkChromaLocation                 suggestedYChromaOffset;
} VkNativeBufferFormatPropertiesOHOS;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • format is the Vulkan format corresponding to the Open Harmony OS native buffer’s format, or VK_FORMAT_UNDEFINED if there is not an equivalent Vulkan format.

  • externalFormat is an implementation-defined external format identifier for use with VkExternalFormatOHOS.

  • formatFeatures describes the capabilities of this external format when used with an image bound to memory imported from buffer.

  • samplerYcbcrConversionComponents represents a set of VkComponentSwizzle.

  • suggestedYcbcrModel represents the color model.

  • suggestedYcbcrRange represents the numerical value range.

  • suggestedXChromaOffset represents the X chroma offset.

  • suggestedYChromaOffset represents the Y chroma offset.

Valid Usage (Implicit)

The VkMemoryGetNativeBufferInfoOHOS structure is defined as:

// Provided by VK_OHOS_external_memory
typedef struct VkMemoryGetNativeBufferInfoOHOS {
    VkStructureType    sType;
    const void*        pNext;
    VkDeviceMemory     memory;
} VkMemoryGetNativeBufferInfoOHOS;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • memory is a valid VkDeviceMemory object from which the Open Harmony OS native buffer will be exported.

Valid Usage (Implicit)

If the pNext chain includes a VkExternalMemoryImageCreateInfoNV structure, then that structure defines a set of external memory handle types that may be used as backing store for the image.

The VkExternalMemoryImageCreateInfoNV structure is defined as:

// Provided by VK_NV_external_memory
typedef struct VkExternalMemoryImageCreateInfoNV {
    VkStructureType                      sType;
    const void*                          pNext;
    VkExternalMemoryHandleTypeFlagsNV    handleTypes;
} VkExternalMemoryImageCreateInfoNV;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • handleTypes is zero or a bitmask of VkExternalMemoryHandleTypeFlagBitsNV specifying one or more external memory handle types.

Valid Usage (Implicit)

VkExternalFormatANDROID is defined as:

// Provided by VK_ANDROID_external_memory_android_hardware_buffer
typedef struct VkExternalFormatANDROID {
    VkStructureType    sType;
    void*              pNext;
    uint64_t           externalFormat;
} VkExternalFormatANDROID;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • externalFormat is an implementation-defined identifier for the external format

When included in the pNext chain of another structure, it indicates additional format information beyond what is provided by VkFormat values for an Android hardware buffer. If externalFormat is zero, it indicates that no external format is used, and implementations should rely only on other format information. If this structure is not present, it is equivalent to setting externalFormat to zero.

Valid Usage
Valid Usage (Implicit)

To create an image with an QNX Screen external format, add a VkExternalFormatQNX structure in the pNext chain of VkImageCreateInfo. VkExternalFormatQNX is defined as:

// Provided by VK_QNX_external_memory_screen_buffer
typedef struct VkExternalFormatQNX {
    VkStructureType    sType;
    void*              pNext;
    uint64_t           externalFormat;
} VkExternalFormatQNX;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • externalFormat is an implementation-defined identifier for the external format

If externalFormat is zero, the effect is as if the VkExternalFormatQNX structure was not present. Otherwise, the image will have the specified external format.

Valid Usage
Valid Usage (Implicit)

If the pNext chain of VkImageCreateInfo includes a VkImageSwapchainCreateInfoKHR structure, then that structure includes a swapchain handle indicating that the image will be bound to memory from that swapchain.

The VkImageSwapchainCreateInfoKHR structure is defined as:

// Provided by VK_VERSION_1_1 with VK_KHR_swapchain, VK_KHR_device_group with VK_KHR_swapchain
typedef struct VkImageSwapchainCreateInfoKHR {
    VkStructureType    sType;
    const void*        pNext;
    VkSwapchainKHR     swapchain;
} VkImageSwapchainCreateInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • swapchain is VK_NULL_HANDLE or a handle of a swapchain that the image will be bound to.

Valid Usage
Valid Usage (Implicit)

If the pNext chain of VkImageCreateInfo includes a VkImageFormatListCreateInfo structure, then that structure contains a list of all formats that can be used when creating views of this image.

The VkImageFormatListCreateInfo structure is defined as:

// Provided by VK_VERSION_1_2
typedef struct VkImageFormatListCreateInfo {
    VkStructureType    sType;
    const void*        pNext;
    uint32_t           viewFormatCount;
    const VkFormat*    pViewFormats;
} VkImageFormatListCreateInfo;
// Provided by VK_KHR_image_format_list
// Equivalent to VkImageFormatListCreateInfo
typedef VkImageFormatListCreateInfo VkImageFormatListCreateInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • viewFormatCount is the number of entries in the pViewFormats array.

  • pViewFormats is a pointer to an array of VkFormat values specifying all formats which can be used when creating views of this image.

If viewFormatCount is zero, pViewFormats is ignored and the image is created as if the VkImageFormatListCreateInfo structure were not included in the pNext chain of VkImageCreateInfo.

Valid Usage

  • VUID-VkImageFormatListCreateInfo-viewFormatCount-09540
    If viewFormatCount is not 0, each element of pViewFormats must not be VK_FORMAT_UNDEFINED

Valid Usage (Implicit)

  • VUID-VkImageFormatListCreateInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_IMAGE_FORMAT_LIST_CREATE_INFO

  • VUID-VkImageFormatListCreateInfo-pViewFormats-parameter
    If viewFormatCount is not 0, pViewFormats must be a valid pointer to an array of viewFormatCount valid VkFormat values

If the pNext chain of VkImageCreateInfo includes a VkImageDrmFormatModifierListCreateInfoEXT structure, then the image will be created with one of the Linux DRM format modifiers listed in the structure. The choice of modifier is implementation-dependent.

The VkImageDrmFormatModifierListCreateInfoEXT structure is defined as:

// Provided by VK_EXT_image_drm_format_modifier
typedef struct VkImageDrmFormatModifierListCreateInfoEXT {
    VkStructureType    sType;
    const void*        pNext;
    uint32_t           drmFormatModifierCount;
    const uint64_t*    pDrmFormatModifiers;
} VkImageDrmFormatModifierListCreateInfoEXT;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • drmFormatModifierCount is the length of the pDrmFormatModifiers array.

  • pDrmFormatModifiers is a pointer to an array of Linux DRM format modifiers.

Valid Usage
Valid Usage (Implicit)

  • VUID-VkImageDrmFormatModifierListCreateInfoEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_LIST_CREATE_INFO_EXT

  • VUID-VkImageDrmFormatModifierListCreateInfoEXT-pDrmFormatModifiers-parameter
    pDrmFormatModifiers must be a valid pointer to an array of drmFormatModifierCount uint64_t values

  • VUID-VkImageDrmFormatModifierListCreateInfoEXT-drmFormatModifierCount-arraylength
    drmFormatModifierCount must be greater than 0

If the pNext chain of VkImageCreateInfo includes a VkImageDrmFormatModifierExplicitCreateInfoEXT structure, then the image will be created with the Linux DRM format modifier and memory layout defined by the structure.

The VkImageDrmFormatModifierExplicitCreateInfoEXT structure is defined as:

// Provided by VK_EXT_image_drm_format_modifier
typedef struct VkImageDrmFormatModifierExplicitCreateInfoEXT {
    VkStructureType               sType;
    const void*                   pNext;
    uint64_t                      drmFormatModifier;
    uint32_t                      drmFormatModifierPlaneCount;
    const VkSubresourceLayout*    pPlaneLayouts;
} VkImageDrmFormatModifierExplicitCreateInfoEXT;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • drmFormatModifier is the Linux DRM format modifier with which the image will be created.

  • drmFormatModifierPlaneCount is the number of memory planes in the image (as reported by VkDrmFormatModifierPropertiesEXT) as well as the length of the pPlaneLayouts array.

  • pPlaneLayouts is a pointer to an array of VkSubresourceLayout structures describing the image’s memory planes.

The ith member of pPlaneLayouts describes the layout of the image’s ith memory plane (that is, VK_IMAGE_ASPECT_MEMORY_PLANE_i_BIT_EXT). In each element of pPlaneLayouts, the implementation must ignore size. The implementation calculates the size of each plane, which the application can query with vkGetImageSubresourceLayout.

When creating an image with VkImageDrmFormatModifierExplicitCreateInfoEXT, it is the application’s responsibility to satisfy all valid usage requirements. However, the implementation must validate that the provided pPlaneLayouts, when combined with the provided drmFormatModifier and other creation parameters in VkImageCreateInfo and its pNext chain, produce a valid image. (This validation is necessarily implementation-dependent and outside the scope of Vulkan, and therefore not described by valid usage requirements). If this validation fails, then vkCreateImage returns VK_ERROR_INVALID_DRM_FORMAT_MODIFIER_PLANE_LAYOUT_EXT.

Valid Usage
Valid Usage (Implicit)

  • VUID-VkImageDrmFormatModifierExplicitCreateInfoEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_EXPLICIT_CREATE_INFO_EXT

  • VUID-VkImageDrmFormatModifierExplicitCreateInfoEXT-pPlaneLayouts-parameter
    pPlaneLayouts must be a valid pointer to an array of drmFormatModifierPlaneCount VkSubresourceLayout structures

  • VUID-VkImageDrmFormatModifierExplicitCreateInfoEXT-drmFormatModifierPlaneCount-arraylength
    drmFormatModifierPlaneCount must be greater than 0

If the pNext list of VkImageCreateInfo includes a VkImageCompressionControlEXT structure, then that structure describes compression controls for this image.

The VkImageCompressionControlEXT structure is defined as:

// Provided by VK_EXT_image_compression_control
typedef struct VkImageCompressionControlEXT {
    VkStructureType                         sType;
    const void*                             pNext;
    VkImageCompressionFlagsEXT              flags;
    uint32_t                                compressionControlPlaneCount;
    VkImageCompressionFixedRateFlagsEXT*    pFixedRateFlags;
} VkImageCompressionControlEXT;

If enabled, fixed-rate compression is done in an implementation-defined manner and may be applied at block granularity. In that case, a write to an individual texel may modify the value of other texels in the same block.

Valid Usage
Valid Usage (Implicit)

Some combinations of compression properties may not be supported. For example, some implementations may not support different fixed-rate compression rates per plane of a multi-planar format and will not be able to enable fixed-rate compression for any plane if the requested rates differ.

Possible values of VkImageCompressionControlEXT::flags, specifying compression controls for an image, are:

// Provided by VK_EXT_image_compression_control
typedef enum VkImageCompressionFlagBitsEXT {
    VK_IMAGE_COMPRESSION_DEFAULT_EXT = 0,
    VK_IMAGE_COMPRESSION_FIXED_RATE_DEFAULT_EXT = 0x00000001,
    VK_IMAGE_COMPRESSION_FIXED_RATE_EXPLICIT_EXT = 0x00000002,
    VK_IMAGE_COMPRESSION_DISABLED_EXT = 0x00000004,
} VkImageCompressionFlagBitsEXT;

If VkImageCompressionControlEXT::flags is VK_IMAGE_COMPRESSION_FIXED_RATE_EXPLICIT_EXT, then the ith member of the pFixedRateFlags array specifies the allowed compression rates for the image’s ith plane.

If VK_IMAGE_COMPRESSION_DISABLED_EXT is included in VkImageCompressionControlEXT::flags, both lossless and fixed-rate compression will be disabled. This is likely to have a negative impact on performance and is only intended to be used for debugging purposes.

 
// Provided by VK_EXT_image_compression_control
typedef VkFlags VkImageCompressionFlagsEXT;

VkImageCompressionFlagsEXT is a bitmask type for setting a mask of zero or more VkImageCompressionFlagBitsEXT.

// Provided by VK_EXT_image_compression_control
typedef VkFlags VkImageCompressionFixedRateFlagsEXT;

VkImageCompressionFixedRateFlagsEXT is a bitmask type for setting a mask of zero or more VkImageCompressionFixedRateFlagBitsEXT.

Bits which can be set in VkImageCompressionControlEXT::pFixedRateFlags, specifying allowed compression rates for an image plane, are:

// Provided by VK_EXT_image_compression_control
typedef enum VkImageCompressionFixedRateFlagBitsEXT {
    VK_IMAGE_COMPRESSION_FIXED_RATE_NONE_EXT = 0,
    VK_IMAGE_COMPRESSION_FIXED_RATE_1BPC_BIT_EXT = 0x00000001,
    VK_IMAGE_COMPRESSION_FIXED_RATE_2BPC_BIT_EXT = 0x00000002,
    VK_IMAGE_COMPRESSION_FIXED_RATE_3BPC_BIT_EXT = 0x00000004,
    VK_IMAGE_COMPRESSION_FIXED_RATE_4BPC_BIT_EXT = 0x00000008,
    VK_IMAGE_COMPRESSION_FIXED_RATE_5BPC_BIT_EXT = 0x00000010,
    VK_IMAGE_COMPRESSION_FIXED_RATE_6BPC_BIT_EXT = 0x00000020,
    VK_IMAGE_COMPRESSION_FIXED_RATE_7BPC_BIT_EXT = 0x00000040,
    VK_IMAGE_COMPRESSION_FIXED_RATE_8BPC_BIT_EXT = 0x00000080,
    VK_IMAGE_COMPRESSION_FIXED_RATE_9BPC_BIT_EXT = 0x00000100,
    VK_IMAGE_COMPRESSION_FIXED_RATE_10BPC_BIT_EXT = 0x00000200,
    VK_IMAGE_COMPRESSION_FIXED_RATE_11BPC_BIT_EXT = 0x00000400,
    VK_IMAGE_COMPRESSION_FIXED_RATE_12BPC_BIT_EXT = 0x00000800,
    VK_IMAGE_COMPRESSION_FIXED_RATE_13BPC_BIT_EXT = 0x00001000,
    VK_IMAGE_COMPRESSION_FIXED_RATE_14BPC_BIT_EXT = 0x00002000,
    VK_IMAGE_COMPRESSION_FIXED_RATE_15BPC_BIT_EXT = 0x00004000,
    VK_IMAGE_COMPRESSION_FIXED_RATE_16BPC_BIT_EXT = 0x00008000,
    VK_IMAGE_COMPRESSION_FIXED_RATE_17BPC_BIT_EXT = 0x00010000,
    VK_IMAGE_COMPRESSION_FIXED_RATE_18BPC_BIT_EXT = 0x00020000,
    VK_IMAGE_COMPRESSION_FIXED_RATE_19BPC_BIT_EXT = 0x00040000,
    VK_IMAGE_COMPRESSION_FIXED_RATE_20BPC_BIT_EXT = 0x00080000,
    VK_IMAGE_COMPRESSION_FIXED_RATE_21BPC_BIT_EXT = 0x00100000,
    VK_IMAGE_COMPRESSION_FIXED_RATE_22BPC_BIT_EXT = 0x00200000,
    VK_IMAGE_COMPRESSION_FIXED_RATE_23BPC_BIT_EXT = 0x00400000,
    VK_IMAGE_COMPRESSION_FIXED_RATE_24BPC_BIT_EXT = 0x00800000,
} VkImageCompressionFixedRateFlagBitsEXT;

If the format has a different bit rate for different components, VkImageCompressionControlEXT::pFixedRateFlags describes the rate of the component with the largest number of bits assigned to it, scaled pro rata. For example, to request that a VK_FORMAT_A2R10G10B10_UNORM_PACK32 format be stored at a rate of 8 bits per pixel, use VK_IMAGE_COMPRESSION_FIXED_RATE_2BPC_BIT_EXT (10 bits for the largest component, stored at quarter the original size, 2.5 bits, rounded down).

If flags includes VK_IMAGE_COMPRESSION_FIXED_RATE_EXPLICIT_EXT, and multiple bits are set in VkImageCompressionControlEXT::pFixedRateFlags for a plane, implementations should apply the lowest allowed bitrate that is supported.

The choice of “bits per component” terminology was chosen so that the same compression rate describes the same degree of compression applied to formats that differ only in the number of components. For example, VK_FORMAT_R8G8_UNORM compressed to half its original size is a rate of 4 bits per component, 8 bits per pixel. VK_FORMAT_R8G8B8A8_UNORM compressed to half its original size is 4 bits per component, 16 bits per pixel. Both of these cases can be requested with VK_IMAGE_COMPRESSION_FIXED_RATE_4BPC_BIT_EXT.

To query the compression properties of an image, add a VkImageCompressionPropertiesEXT structure to the pNext chain of the VkSubresourceLayout2 structure in a call to vkGetImageSubresourceLayout2.

To determine the compression rates that are supported for a given image format, add a VkImageCompressionPropertiesEXT structure to the pNext chain of the VkImageFormatProperties2 structure in a call to vkGetPhysicalDeviceImageFormatProperties2.

Since fixed-rate compression is disabled by default, the VkImageCompressionPropertiesEXT structure passed to vkGetPhysicalDeviceImageFormatProperties2 will not indicate any fixed-rate compression support unless a VkImageCompressionControlEXT structure is also included in the pNext chain of the VkPhysicalDeviceImageFormatInfo2 structure passed to the same command.

The VkImageCompressionPropertiesEXT structure is defined as:

// Provided by VK_EXT_image_compression_control
typedef struct VkImageCompressionPropertiesEXT {
    VkStructureType                        sType;
    void*                                  pNext;
    VkImageCompressionFlagsEXT             imageCompressionFlags;
    VkImageCompressionFixedRateFlagsEXT    imageCompressionFixedRateFlags;
} VkImageCompressionPropertiesEXT;
Valid Usage (Implicit)

If the pNext list of VkImageCreateInfo includes a VkImageAlignmentControlCreateInfoMESA structure, then that structure describes desired alignment for this image.

The VkImageAlignmentControlCreateInfoMESA structure is defined as:

// Provided by VK_MESA_image_alignment_control
typedef struct VkImageAlignmentControlCreateInfoMESA {
    VkStructureType    sType;
    const void*        pNext;
    uint32_t           maximumRequestedAlignment;
} VkImageAlignmentControlCreateInfoMESA;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • maximumRequestedAlignment specifies the maximum alignment for the image.

If maximumRequestedAlignment is not 0, the implementation should choose an image memory layout that requires an alignment no larger than maximumRequestedAlignment as reported in VkMemoryRequirements::alignment. If such a layout does not exist for the given image creation parameters, the implementation should return the smallest alignment which is supported in VkMemoryRequirements.

If an implementation needs to disable image compression for maximumRequestedAlignment to be honored - where a larger alignment would enable image compression - the implementation should not use maximumRequestedAlignment, and should return the smallest alignment which does not compromise compression. If the imageCompressionControl feature is enabled, the application can chain a VkImageCompressionControlEXT with VK_IMAGE_COMPRESSION_DISABLED_EXT. In this case, image compression considerations should not apply when implementation decides alignment.

Valid Usage

  • VUID-VkImageAlignmentControlCreateInfoMESA-maximumRequestedAlignment-09655
    If maximumRequestedAlignment is not 0, maximumRequestedAlignment must be a power of two

  • VUID-VkImageAlignmentControlCreateInfoMESA-maximumRequestedAlignment-09656
    If maximumRequestedAlignment is not 0, the bitwise-and of maximumRequestedAlignment and supportedImageAlignmentMask must be non-zero

  • VUID-VkImageAlignmentControlCreateInfoMESA-imageAlignmentControl-09657
    imageAlignmentControl must be enabled

Valid Usage (Implicit)

Bits which can be set in

specify intended usage of an image, and are:

// Provided by VK_VERSION_1_0
typedef enum VkImageUsageFlagBits {
    VK_IMAGE_USAGE_TRANSFER_SRC_BIT = 0x00000001,
    VK_IMAGE_USAGE_TRANSFER_DST_BIT = 0x00000002,
    VK_IMAGE_USAGE_SAMPLED_BIT = 0x00000004,
    VK_IMAGE_USAGE_STORAGE_BIT = 0x00000008,
    VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT = 0x00000010,
    VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT = 0x00000020,
    VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT = 0x00000040,
    VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT = 0x00000080,
  // Provided by VK_VERSION_1_4
    VK_IMAGE_USAGE_HOST_TRANSFER_BIT = 0x00400000,
  // Provided by VK_KHR_video_decode_queue
    VK_IMAGE_USAGE_VIDEO_DECODE_DST_BIT_KHR = 0x00000400,
  // Provided by VK_KHR_video_decode_queue
    VK_IMAGE_USAGE_VIDEO_DECODE_SRC_BIT_KHR = 0x00000800,
  // Provided by VK_KHR_video_decode_queue
    VK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHR = 0x00001000,
  // Provided by VK_EXT_fragment_density_map
    VK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT = 0x00000200,
  // Provided by VK_KHR_fragment_shading_rate
    VK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR = 0x00000100,
  // Provided by VK_KHR_video_encode_queue
    VK_IMAGE_USAGE_VIDEO_ENCODE_DST_BIT_KHR = 0x00002000,
  // Provided by VK_KHR_video_encode_queue
    VK_IMAGE_USAGE_VIDEO_ENCODE_SRC_BIT_KHR = 0x00004000,
  // Provided by VK_KHR_video_encode_queue
    VK_IMAGE_USAGE_VIDEO_ENCODE_DPB_BIT_KHR = 0x00008000,
  // Provided by VK_EXT_attachment_feedback_loop_layout
    VK_IMAGE_USAGE_ATTACHMENT_FEEDBACK_LOOP_BIT_EXT = 0x00080000,
  // Provided by VK_HUAWEI_invocation_mask
    VK_IMAGE_USAGE_INVOCATION_MASK_BIT_HUAWEI = 0x00040000,
  // Provided by VK_QCOM_image_processing
    VK_IMAGE_USAGE_SAMPLE_WEIGHT_BIT_QCOM = 0x00100000,
  // Provided by VK_QCOM_image_processing
    VK_IMAGE_USAGE_SAMPLE_BLOCK_MATCH_BIT_QCOM = 0x00200000,
  // Provided by VK_ARM_tensors
    VK_IMAGE_USAGE_TENSOR_ALIASING_BIT_ARM = 0x00800000,
  // Provided by VK_QCOM_tile_memory_heap
    VK_IMAGE_USAGE_TILE_MEMORY_BIT_QCOM = 0x08000000,
  // Provided by VK_KHR_video_encode_quantization_map
    VK_IMAGE_USAGE_VIDEO_ENCODE_QUANTIZATION_DELTA_MAP_BIT_KHR = 0x02000000,
  // Provided by VK_KHR_video_encode_quantization_map
    VK_IMAGE_USAGE_VIDEO_ENCODE_EMPHASIS_MAP_BIT_KHR = 0x04000000,
  // Provided by VK_NV_shading_rate_image
    VK_IMAGE_USAGE_SHADING_RATE_IMAGE_BIT_NV = VK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR,
  // Provided by VK_EXT_host_image_copy
    VK_IMAGE_USAGE_HOST_TRANSFER_BIT_EXT = VK_IMAGE_USAGE_HOST_TRANSFER_BIT,
} VkImageUsageFlagBits;
// Provided by VK_VERSION_1_0
typedef VkFlags VkImageUsageFlags;

VkImageUsageFlags is a bitmask type for setting a mask of zero or more VkImageUsageFlagBits.

Bits which can be set in VkImageCreateInfo::flags, specifying additional parameters of an image, are:

// Provided by VK_VERSION_1_0
typedef enum VkImageCreateFlagBits {
    VK_IMAGE_CREATE_SPARSE_BINDING_BIT = 0x00000001,
    VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT = 0x00000002,
    VK_IMAGE_CREATE_SPARSE_ALIASED_BIT = 0x00000004,
    VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT = 0x00000008,
    VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT = 0x00000010,
  // Provided by VK_VERSION_1_1
    VK_IMAGE_CREATE_ALIAS_BIT = 0x00000400,
  // Provided by VK_VERSION_1_1
    VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT = 0x00000040,
  // Provided by VK_VERSION_1_1
    VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT = 0x00000020,
  // Provided by VK_VERSION_1_1
    VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT = 0x00000080,
  // Provided by VK_VERSION_1_1
    VK_IMAGE_CREATE_EXTENDED_USAGE_BIT = 0x00000100,
  // Provided by VK_VERSION_1_1
    VK_IMAGE_CREATE_PROTECTED_BIT = 0x00000800,
  // Provided by VK_VERSION_1_1
    VK_IMAGE_CREATE_DISJOINT_BIT = 0x00000200,
  // Provided by VK_NV_corner_sampled_image
    VK_IMAGE_CREATE_CORNER_SAMPLED_BIT_NV = 0x00002000,
  // Provided by VK_EXT_sample_locations
    VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT = 0x00001000,
  // Provided by VK_EXT_fragment_density_map
    VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT = 0x00004000,
  // Provided by VK_EXT_descriptor_buffer
    VK_IMAGE_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXT = 0x00010000,
  // Provided by VK_EXT_multisampled_render_to_single_sampled
    VK_IMAGE_CREATE_MULTISAMPLED_RENDER_TO_SINGLE_SAMPLED_BIT_EXT = 0x00040000,
  // Provided by VK_EXT_image_2d_view_of_3d
    VK_IMAGE_CREATE_2D_VIEW_COMPATIBLE_BIT_EXT = 0x00020000,
  // Provided by VK_KHR_video_maintenance1
    VK_IMAGE_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHR = 0x00100000,
  // Provided by VK_EXT_fragment_density_map_offset
    VK_IMAGE_CREATE_FRAGMENT_DENSITY_MAP_OFFSET_BIT_EXT = 0x00008000,
  // Provided by VK_KHR_bind_memory2 with VK_KHR_device_group
    VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT_KHR = VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT,
  // Provided by VK_KHR_maintenance1
    VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT_KHR = VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT,
  // Provided by VK_KHR_maintenance2
    VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT_KHR = VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT,
  // Provided by VK_KHR_maintenance2
    VK_IMAGE_CREATE_EXTENDED_USAGE_BIT_KHR = VK_IMAGE_CREATE_EXTENDED_USAGE_BIT,
  // Provided by VK_KHR_sampler_ycbcr_conversion
    VK_IMAGE_CREATE_DISJOINT_BIT_KHR = VK_IMAGE_CREATE_DISJOINT_BIT,
  // Provided by VK_KHR_bind_memory2
    VK_IMAGE_CREATE_ALIAS_BIT_KHR = VK_IMAGE_CREATE_ALIAS_BIT,
  // Provided by VK_QCOM_fragment_density_map_offset
    VK_IMAGE_CREATE_FRAGMENT_DENSITY_MAP_OFFSET_BIT_QCOM = VK_IMAGE_CREATE_FRAGMENT_DENSITY_MAP_OFFSET_BIT_EXT,
} VkImageCreateFlagBits;

See Sparse Resource Features and Sparse Physical Device Features for more details.

// Provided by VK_VERSION_1_0
typedef VkFlags VkImageCreateFlags;

VkImageCreateFlags is a bitmask type for setting a mask of zero or more VkImageCreateFlagBits.

Possible values of VkImageCreateInfo::imageType, specifying the basic dimensionality of an image, are:

// Provided by VK_VERSION_1_0
typedef enum VkImageType {
    VK_IMAGE_TYPE_1D = 0,
    VK_IMAGE_TYPE_2D = 1,
    VK_IMAGE_TYPE_3D = 2,
} VkImageType;

Possible values of VkImageCreateInfo::tiling, specifying the tiling arrangement of texel blocks in an image, are:

// Provided by VK_VERSION_1_0
typedef enum VkImageTiling {
    VK_IMAGE_TILING_OPTIMAL = 0,
    VK_IMAGE_TILING_LINEAR = 1,
  // Provided by VK_EXT_image_drm_format_modifier
    VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT = 1000158000,
} VkImageTiling;

To query the memory layout of an image subresource, call:

// Provided by VK_VERSION_1_0
void vkGetImageSubresourceLayout(
    VkDevice                                    device,
    VkImage                                     image,
    const VkImageSubresource*                   pSubresource,
    VkSubresourceLayout*                        pLayout);

  • device is the logical device that owns the image.

  • image is the image whose layout is being queried.

  • pSubresource is a pointer to a VkImageSubresource structure selecting a specific image subresource from the image.

  • pLayout is a pointer to a VkSubresourceLayout structure in which the layout is returned.

If the image is linear, then the returned layout is valid for host access.

If the image’s tiling is VK_IMAGE_TILING_LINEAR and its format is a multi-planar format, then vkGetImageSubresourceLayout describes one format plane of the image. If the image’s tiling is VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then vkGetImageSubresourceLayout describes one memory plane of the image. If the image’s tiling is VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT and the image is non-linear, then the returned layout has an implementation-dependent meaning; the vendor of the image’s DRM format modifier may provide documentation that explains how to interpret the returned layout.

vkGetImageSubresourceLayout is invariant for the lifetime of a single image. However, the subresource layout of images in Android hardware buffer or QNX Screen buffer external memory is not known until the image has been bound to memory, so applications must not call vkGetImageSubresourceLayout for such an image before it has been bound.

Valid Usage
Valid Usage (Implicit)

  • VUID-vkGetImageSubresourceLayout-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetImageSubresourceLayout-image-parameter
    image must be a valid VkImage handle

  • VUID-vkGetImageSubresourceLayout-pSubresource-parameter
    pSubresource must be a valid pointer to a valid VkImageSubresource structure

  • VUID-vkGetImageSubresourceLayout-pLayout-parameter
    pLayout must be a valid pointer to a VkSubresourceLayout structure

  • VUID-vkGetImageSubresourceLayout-image-parent
    image must have been created, allocated, or retrieved from device

The VkImageSubresource structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkImageSubresource {
    VkImageAspectFlags    aspectMask;
    uint32_t              mipLevel;
    uint32_t              arrayLayer;
} VkImageSubresource;

  • aspectMask is a VkImageAspectFlags value selecting the image aspect.

  • mipLevel selects the mipmap level.

  • arrayLayer selects the array layer.

Valid Usage (Implicit)

  • VUID-VkImageSubresource-aspectMask-parameter
    aspectMask must be a valid combination of VkImageAspectFlagBits values

  • VUID-VkImageSubresource-aspectMask-requiredbitmask
    aspectMask must not be 0

Information about the layout of the image subresource is returned in a VkSubresourceLayout structure:

// Provided by VK_VERSION_1_0
typedef struct VkSubresourceLayout {
    VkDeviceSize    offset;
    VkDeviceSize    size;
    VkDeviceSize    rowPitch;
    VkDeviceSize    arrayPitch;
    VkDeviceSize    depthPitch;
} VkSubresourceLayout;

  • offset is the byte offset from the start of the image or the plane where the image subresource begins.

  • size is the size in bytes of the image subresource. size includes any extra memory that is required based on rowPitch.

  • rowPitch describes the number of bytes between each row of texels in an image.

  • arrayPitch describes the number of bytes between each array layer of an image.

  • depthPitch describes the number of bytes between each slice of 3D image.

If the image is linear, then rowPitch, arrayPitch and depthPitch describe the layout of the image subresource in linear memory. For uncompressed formats, rowPitch is the number of bytes between texels with the same x coordinate in adjacent rows (y coordinates differ by one). arrayPitch is the number of bytes between texels with the same x and y coordinate in adjacent array layers of the image (array layer values differ by one). depthPitch is the number of bytes between texels with the same x and y coordinate in adjacent slices of a 3D image (z coordinates differ by one). Expressed as an addressing formula, the starting byte of a texel in the image subresource has address:

// (x,y,z,layer) are in texel coordinates
address(x,y,z,layer) = layer*arrayPitch + z*depthPitch + y*rowPitch + x*elementSize + offset

For compressed formats, the rowPitch is the number of bytes between compressed texel blocks in adjacent rows. arrayPitch is the number of bytes between compressed texel blocks in adjacent array layers. depthPitch is the number of bytes between compressed texel blocks in adjacent slices of a 3D image.

// (x,y,z,layer) are in compressed texel block coordinates
address(x,y,z,layer) = layer*arrayPitch + z*depthPitch + y*rowPitch + x*compressedTexelBlockByteSize + offset;

The value of arrayPitch is undefined for images that were not created as arrays. depthPitch is defined only for 3D images.

If the image has a single-plane color format and its tiling is VK_IMAGE_TILING_LINEAR , then the aspectMask member of VkImageSubresource must be VK_IMAGE_ASPECT_COLOR_BIT.

If the image has a depth/stencil format and its tiling is VK_IMAGE_TILING_LINEAR , then aspectMask must be either VK_IMAGE_ASPECT_DEPTH_BIT or VK_IMAGE_ASPECT_STENCIL_BIT. On implementations that store depth and stencil aspects separately, querying each of these image subresource layouts will return a different offset and size representing the region of memory used for that aspect. On implementations that store depth and stencil aspects interleaved, the same offset and size are returned and represent the interleaved memory allocation.

If the image has a multi-planar format and its tiling is VK_IMAGE_TILING_LINEAR , then the aspectMask member of VkImageSubresource must be VK_IMAGE_ASPECT_PLANE_0_BIT, VK_IMAGE_ASPECT_PLANE_1_BIT, or (for 3-plane formats only) VK_IMAGE_ASPECT_PLANE_2_BIT. Querying each of these image subresource layouts will return a different offset and size representing the region of memory used for that plane. If the image is disjoint, then the offset is relative to the base address of the plane. If the image is non-disjoint, then the offset is relative to the base address of the image.

If the image’s tiling is VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then the aspectMask member of VkImageSubresource must be one of VK_IMAGE_ASPECT_MEMORY_PLANE_i_BIT_EXT, where the maximum allowed plane index i is defined by the VkDrmFormatModifierPropertiesEXT::drmFormatModifierPlaneCount associated with the image’s VkImageCreateInfo::format and modifier. The memory range used by the subresource is described by offset and size. If the image is disjoint, then the offset is relative to the base address of the memory plane. If the image is non-disjoint, then the offset is relative to the base address of the image. If the image is non-linear, then rowPitch, arrayPitch, and depthPitch have an implementation-dependent meaning.

To query the memory layout of an image subresource, call:

// Provided by VK_VERSION_1_4
void vkGetImageSubresourceLayout2(
    VkDevice                                    device,
    VkImage                                     image,
    const VkImageSubresource2*                  pSubresource,
    VkSubresourceLayout2*                       pLayout);
// Provided by VK_KHR_maintenance5
// Equivalent to vkGetImageSubresourceLayout2
void vkGetImageSubresourceLayout2KHR(
    VkDevice                                    device,
    VkImage                                     image,
    const VkImageSubresource2*                  pSubresource,
    VkSubresourceLayout2*                       pLayout);
// Provided by VK_EXT_host_image_copy, VK_EXT_image_compression_control
// Equivalent to vkGetImageSubresourceLayout2
void vkGetImageSubresourceLayout2EXT(
    VkDevice                                    device,
    VkImage                                     image,
    const VkImageSubresource2*                  pSubresource,
    VkSubresourceLayout2*                       pLayout);

  • device is the logical device that owns the image.

  • image is the image whose layout is being queried.

  • pSubresource is a pointer to a VkImageSubresource2 structure selecting a specific image for the image subresource.

  • pLayout is a pointer to a VkSubresourceLayout2 structure in which the layout is returned.

vkGetImageSubresourceLayout2 behaves similarly to vkGetImageSubresourceLayout, with the ability to specify extended inputs via chained input structures, and to return extended information via chained output structures.

It is legal to call vkGetImageSubresourceLayout2 with an image created with tiling equal to VK_IMAGE_TILING_OPTIMAL, but the members of VkSubresourceLayout2::subresourceLayout will have undefined values in this case.

Structures chained from VkImageSubresource2::pNext will also be updated when tiling is equal to VK_IMAGE_TILING_OPTIMAL.
Valid Usage
Valid Usage (Implicit)

  • VUID-vkGetImageSubresourceLayout2-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetImageSubresourceLayout2-image-parameter
    image must be a valid VkImage handle

  • VUID-vkGetImageSubresourceLayout2-pSubresource-parameter
    pSubresource must be a valid pointer to a valid VkImageSubresource2 structure

  • VUID-vkGetImageSubresourceLayout2-pLayout-parameter
    pLayout must be a valid pointer to a VkSubresourceLayout2 structure

  • VUID-vkGetImageSubresourceLayout2-image-parent
    image must have been created, allocated, or retrieved from device

The VkImageSubresource2 structure is defined as:

// Provided by VK_VERSION_1_4
typedef struct VkImageSubresource2 {
    VkStructureType       sType;
    void*                 pNext;
    VkImageSubresource    imageSubresource;
} VkImageSubresource2;
// Provided by VK_KHR_maintenance5
// Equivalent to VkImageSubresource2
typedef VkImageSubresource2 VkImageSubresource2KHR;
// Provided by VK_EXT_host_image_copy, VK_EXT_image_compression_control
// Equivalent to VkImageSubresource2
typedef VkImageSubresource2 VkImageSubresource2EXT;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • imageSubresource is a VkImageSubresource structure.

Valid Usage (Implicit)

Information about the layout of the image subresource is returned in a VkSubresourceLayout2 structure:

// Provided by VK_VERSION_1_4
typedef struct VkSubresourceLayout2 {
    VkStructureType        sType;
    void*                  pNext;
    VkSubresourceLayout    subresourceLayout;
} VkSubresourceLayout2;
// Provided by VK_KHR_maintenance5
// Equivalent to VkSubresourceLayout2
typedef VkSubresourceLayout2 VkSubresourceLayout2KHR;
// Provided by VK_EXT_host_image_copy, VK_EXT_image_compression_control
// Equivalent to VkSubresourceLayout2
typedef VkSubresourceLayout2 VkSubresourceLayout2EXT;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • subresourceLayout is a VkSubresourceLayout structure.

Valid Usage (Implicit)

To query the memory size needed to copy to or from an image using vkCopyMemoryToImage or vkCopyImageToMemory when the VK_HOST_IMAGE_COPY_MEMCPY_BIT flag is specified, add a VkSubresourceHostMemcpySize structure to the pNext chain of the VkSubresourceLayout2 structure in a call to vkGetImageSubresourceLayout2.

The VkSubresourceHostMemcpySize structure is defined as:

// Provided by VK_VERSION_1_4
typedef struct VkSubresourceHostMemcpySize {
    VkStructureType    sType;
    void*              pNext;
    VkDeviceSize       size;
} VkSubresourceHostMemcpySize;
// Provided by VK_EXT_host_image_copy
// Equivalent to VkSubresourceHostMemcpySize
typedef VkSubresourceHostMemcpySize VkSubresourceHostMemcpySizeEXT;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • size is the size in bytes of the image subresource.

Valid Usage (Implicit)

To query the memory layout of an image subresource, without an image object, call:

// Provided by VK_VERSION_1_4
void vkGetDeviceImageSubresourceLayout(
    VkDevice                                    device,
    const VkDeviceImageSubresourceInfo*         pInfo,
    VkSubresourceLayout2*                       pLayout);
// Provided by VK_KHR_maintenance5
// Equivalent to vkGetDeviceImageSubresourceLayout
void vkGetDeviceImageSubresourceLayoutKHR(
    VkDevice                                    device,
    const VkDeviceImageSubresourceInfo*         pInfo,
    VkSubresourceLayout2*                       pLayout);

  • device is the logical device that owns the image.

  • pInfo is a pointer to a VkDeviceImageSubresourceInfo structure containing parameters required for the subresource layout query.

  • pLayout is a pointer to a VkSubresourceLayout2 structure in which the layout is returned.

vkGetDeviceImageSubresourceLayout behaves similarly to vkGetImageSubresourceLayout2, but uses a VkImageCreateInfo structure to specify the image rather than a VkImage object.

Valid Usage (Implicit)

  • VUID-vkGetDeviceImageSubresourceLayout-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetDeviceImageSubresourceLayout-pInfo-parameter
    pInfo must be a valid pointer to a valid VkDeviceImageSubresourceInfo structure

  • VUID-vkGetDeviceImageSubresourceLayout-pLayout-parameter
    pLayout must be a valid pointer to a VkSubresourceLayout2 structure

The VkDeviceImageSubresourceInfo structure is defined as:

// Provided by VK_VERSION_1_4
typedef struct VkDeviceImageSubresourceInfo {
    VkStructureType               sType;
    const void*                   pNext;
    const VkImageCreateInfo*      pCreateInfo;
    const VkImageSubresource2*    pSubresource;
} VkDeviceImageSubresourceInfo;
// Provided by VK_KHR_maintenance5
// Equivalent to VkDeviceImageSubresourceInfo
typedef VkDeviceImageSubresourceInfo VkDeviceImageSubresourceInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • pCreateInfo is a pointer to a VkImageCreateInfo structure containing parameters affecting creation of the image to query.

  • pSubresource is a pointer to a VkImageSubresource2 structure selecting a specific image subresource for the query.

Valid Usage

  • VUID-VkDeviceImageSubresourceInfo-aspectMask-00997
    The aspectMask member of pSubresource must only have a single bit set

  • VUID-VkDeviceImageSubresourceInfo-mipLevel-01716
    The mipLevel member of pSubresource must be less than the mipLevels specified in pCreateInfo

  • VUID-VkDeviceImageSubresourceInfo-arrayLayer-01717
    The arrayLayer member of pSubresource must be less than the arrayLayers specified in pCreateInfo

  • VUID-VkDeviceImageSubresourceInfo-format-08886
    If format of the image is a color format that is not a multi-planar format, and tiling of the pCreateInfo is VK_IMAGE_TILING_LINEAR or VK_IMAGE_TILING_OPTIMAL, the aspectMask member of pSubresource must be VK_IMAGE_ASPECT_COLOR_BIT

  • VUID-VkDeviceImageSubresourceInfo-format-04462
    If format of the pCreateInfo has a depth component, the aspectMask member of pSubresource must contain VK_IMAGE_ASPECT_DEPTH_BIT

  • VUID-VkDeviceImageSubresourceInfo-format-04463
    If format of the pCreateInfo has a stencil component, the aspectMask member of pSubresource must contain VK_IMAGE_ASPECT_STENCIL_BIT

  • VUID-VkDeviceImageSubresourceInfo-format-04464
    If format of the pCreateInfo does not contain a stencil or depth component, the aspectMask member of pSubresource must not contain VK_IMAGE_ASPECT_DEPTH_BIT or VK_IMAGE_ASPECT_STENCIL_BIT

  • VUID-VkDeviceImageSubresourceInfo-tiling-08717
    If the tiling of the pCreateInfo is VK_IMAGE_TILING_LINEAR and has a multi-planar format, then the aspectMask member of pSubresource must be a single valid multi-planar aspect mask bit

Valid Usage (Implicit)

  • VUID-VkDeviceImageSubresourceInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_DEVICE_IMAGE_SUBRESOURCE_INFO

  • VUID-VkDeviceImageSubresourceInfo-pNext-pNext
    pNext must be NULL

  • VUID-VkDeviceImageSubresourceInfo-pCreateInfo-parameter
    pCreateInfo must be a valid pointer to a valid VkImageCreateInfo structure

  • VUID-VkDeviceImageSubresourceInfo-pSubresource-parameter
    pSubresource must be a valid pointer to a valid VkImageSubresource2 structure

If an image was created with VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then the image has a Linux DRM format modifier. To query the modifier, call:

// Provided by VK_EXT_image_drm_format_modifier
VkResult vkGetImageDrmFormatModifierPropertiesEXT(
    VkDevice                                    device,
    VkImage                                     image,
    VkImageDrmFormatModifierPropertiesEXT*      pProperties);

  • device is the logical device that owns the image.

  • image is the queried image.

  • pProperties is a pointer to a VkImageDrmFormatModifierPropertiesEXT structure in which properties of the image’s DRM format modifier are returned.

Valid Usage
Valid Usage (Implicit)

  • VUID-vkGetImageDrmFormatModifierPropertiesEXT-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetImageDrmFormatModifierPropertiesEXT-image-parameter
    image must be a valid VkImage handle

  • VUID-vkGetImageDrmFormatModifierPropertiesEXT-pProperties-parameter
    pProperties must be a valid pointer to a VkImageDrmFormatModifierPropertiesEXT structure

  • VUID-vkGetImageDrmFormatModifierPropertiesEXT-image-parent
    image must have been created, allocated, or retrieved from device

Return Codes
Success
Failure

The VkImageDrmFormatModifierPropertiesEXT structure is defined as:

// Provided by VK_EXT_image_drm_format_modifier
typedef struct VkImageDrmFormatModifierPropertiesEXT {
    VkStructureType    sType;
    void*              pNext;
    uint64_t           drmFormatModifier;
} VkImageDrmFormatModifierPropertiesEXT;

If the image was created with VkImageDrmFormatModifierListCreateInfoEXT, then the returned drmFormatModifier must belong to the list of modifiers provided at time of image creation in VkImageDrmFormatModifierListCreateInfoEXT::pDrmFormatModifiers. If the image was created with VkImageDrmFormatModifierExplicitCreateInfoEXT, then the returned drmFormatModifier must be the modifier provided at time of image creation in VkImageDrmFormatModifierExplicitCreateInfoEXT::drmFormatModifier.

Valid Usage (Implicit)

To destroy an image, call:

// Provided by VK_VERSION_1_0
void vkDestroyImage(
    VkDevice                                    device,
    VkImage                                     image,
    const VkAllocationCallbacks*                pAllocator);

  • device is the logical device that destroys the image.

  • image is the image to destroy.

  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

Valid Usage

  • VUID-vkDestroyImage-image-01000
    All submitted commands that refer to image, either directly or via a VkImageView, must have completed execution

  • VUID-vkDestroyImage-image-01001
    If VkAllocationCallbacks were provided when image was created, a compatible set of callbacks must be provided here

  • VUID-vkDestroyImage-image-01002
    If no VkAllocationCallbacks were provided when image was created, pAllocator must be NULL

  • VUID-vkDestroyImage-image-04882
    image must not have been acquired from vkGetSwapchainImagesKHR

Valid Usage (Implicit)

  • VUID-vkDestroyImage-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkDestroyImage-image-parameter
    If image is not VK_NULL_HANDLE, image must be a valid VkImage handle

  • VUID-vkDestroyImage-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkDestroyImage-image-parent
    If image is a valid handle, it must have been created, allocated, or retrieved from device

Host Synchronization

  • Host access to image must be externally synchronized

Image Format Features

Valid uses of a VkImage may depend on the image’s format features, defined below. Such constraints are documented in the affected valid usage statement.

Corner-Sampled Images

A corner-sampled image is an image where unnormalized texel coordinates are centered on integer values rather than half-integer values.

A corner-sampled image has a number of differences compared to conventional texture image:

Corner-sampling is only supported for 2D and 3D images. When sampling a corner-sampled image, the sampler addressing mode must be VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE. Corner-sampled images are not supported as cube maps or depth/stencil images.

Image Mip Level Sizing

A complete mipmap chain is the full set of mip levels, from the largest mip level provided, down to the minimum mip level size.

Conventional Images

For conventional images, the dimensions of each successive mip level, n+1, are:

widthn+1 = max(⌊widthn/2⌋, 1)

heightn+1 = max(⌊heightn/2⌋, 1)

depthn+1 = max(⌊depthn/2⌋, 1)

where widthn, heightn, and depthn are the dimensions of the next larger mip level, n.

The minimum mip level size is:

  • 1 for one-dimensional images,

  • 1x1 for two-dimensional images, and

  • 1x1x1 for three-dimensional images.

The number of levels in a complete mipmap chain is:

⌊log2(max(width0, height0, depth0))⌋ + 1

where width0, height0, and depth0 are the dimensions of the largest (most detailed) mip level, 0.

Corner-Sampled Images

For corner-sampled images, the dimensions of each successive mip level, n+1, are:

widthn+1 = max(⌈widthn/2⌉, 2)

heightn+1 = max(⌈heightn/2⌉, 2)

depthn+1 = max(⌈depthn/2⌉, 2)

where widthn, heightn, and depthn are the dimensions of the next larger mip level, n.

The minimum mip level size is:

  • 2x2 for two-dimensional images, and

  • 2x2x2 for three-dimensional images.

The number of levels in a complete mipmap chain is:

⌈log2(max(width0, height0, depth0))⌉

where width0, height0, and depth0 are the dimensions of the largest (most detailed) mip level, 0.

Image Layouts

Images are stored in implementation-dependent opaque layouts in memory. Each layout has limitations on what kinds of operations are supported for image subresources using the layout. At any given time, the data representing an image subresource in memory exists in a particular layout which is determined by the most recent layout transition that was performed on that image subresource. Applications have control over which layout each image subresource uses, and can transition an image subresource from one layout to another. Transitions can happen with an image memory barrier, included as part of a vkCmdPipelineBarrier or a vkCmdWaitEvents command buffer command (see Image Memory Barriers), or as part of a subpass dependency within a render pass (see VkSubpassDependency).

Image layout is per-image subresource. Separate image subresources of the same image can be in different layouts at the same time, with the exception that depth and stencil aspects of a given image subresource can only be in different layouts if the separateDepthStencilLayouts feature is enabled. When an VkImageView descriptor is accessed on the device, all image subresources must be in a valid image layout.

Each layout may offer optimal performance for a specific usage of image memory. For example, an image with a layout of VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL may provide optimal performance for use as a color attachment, but be unsupported for use in transfer commands. Applications can transition an image subresource from one layout to another in order to achieve optimal performance when the image subresource is used for multiple kinds of operations. After initialization, applications need not use any layout other than the general layout, though this may produce suboptimal performance on some implementations.

Upon creation, all image subresources of an image are initially in the same layout, where that layout is selected by the VkImageCreateInfo::initialLayout member. The initialLayout must be either VK_IMAGE_LAYOUT_UNDEFINED or VK_IMAGE_LAYOUT_ZERO_INITIALIZED_EXT or VK_IMAGE_LAYOUT_PREINITIALIZED. If it is VK_IMAGE_LAYOUT_PREINITIALIZED, then the image data can be preinitialized by the host while using this layout, and the transition away from this layout will preserve that data. If it is VK_IMAGE_LAYOUT_ZERO_INITIALIZED_EXT, then the image data is interpreted to be zeroed. If the memory bound to this image is not fully zeroed when the image is transitioned to a different layout, the results are undefined. If it is VK_IMAGE_LAYOUT_UNDEFINED, then the contents of the data are considered to be undefined, and the transition away from this layout is not guaranteed to preserve that data. For either of these initial layouts, any image subresources must be transitioned to another layout before they are accessed by the device.

Host access to image memory is only well-defined for linear images and for image subresources of those images which are currently in any of the following layouts:

Calling vkGetImageSubresourceLayout for a linear image returns a subresource layout mapping that is valid for either of those image layouts.

The set of image layouts consists of:

// Provided by VK_VERSION_1_0
typedef enum VkImageLayout {
    VK_IMAGE_LAYOUT_UNDEFINED = 0,
    VK_IMAGE_LAYOUT_GENERAL = 1,
    VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL = 2,
    VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL = 3,
    VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL = 4,
    VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL = 5,
    VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL = 6,
    VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL = 7,
    VK_IMAGE_LAYOUT_PREINITIALIZED = 8,
  // Provided by VK_VERSION_1_1
    VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL = 1000117000,
  // Provided by VK_VERSION_1_1
    VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL = 1000117001,
  // Provided by VK_VERSION_1_2
    VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL = 1000241000,
  // Provided by VK_VERSION_1_2
    VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL = 1000241001,
  // Provided by VK_VERSION_1_2
    VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL = 1000241002,
  // Provided by VK_VERSION_1_2
    VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL = 1000241003,
  // Provided by VK_VERSION_1_3
    VK_IMAGE_LAYOUT_READ_ONLY_OPTIMAL = 1000314000,
  // Provided by VK_VERSION_1_3
    VK_IMAGE_LAYOUT_ATTACHMENT_OPTIMAL = 1000314001,
  // Provided by VK_VERSION_1_4
    VK_IMAGE_LAYOUT_RENDERING_LOCAL_READ = 1000232000,
  // Provided by VK_KHR_swapchain
    VK_IMAGE_LAYOUT_PRESENT_SRC_KHR = 1000001002,
  // Provided by VK_KHR_video_decode_queue
    VK_IMAGE_LAYOUT_VIDEO_DECODE_DST_KHR = 1000024000,
  // Provided by VK_KHR_video_decode_queue
    VK_IMAGE_LAYOUT_VIDEO_DECODE_SRC_KHR = 1000024001,
  // Provided by VK_KHR_video_decode_queue
    VK_IMAGE_LAYOUT_VIDEO_DECODE_DPB_KHR = 1000024002,
  // Provided by VK_KHR_shared_presentable_image
    VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR = 1000111000,
  // Provided by VK_EXT_fragment_density_map
    VK_IMAGE_LAYOUT_FRAGMENT_DENSITY_MAP_OPTIMAL_EXT = 1000218000,
  // Provided by VK_KHR_fragment_shading_rate
    VK_IMAGE_LAYOUT_FRAGMENT_SHADING_RATE_ATTACHMENT_OPTIMAL_KHR = 1000164003,
  // Provided by VK_KHR_video_encode_queue
    VK_IMAGE_LAYOUT_VIDEO_ENCODE_DST_KHR = 1000299000,
  // Provided by VK_KHR_video_encode_queue
    VK_IMAGE_LAYOUT_VIDEO_ENCODE_SRC_KHR = 1000299001,
  // Provided by VK_KHR_video_encode_queue
    VK_IMAGE_LAYOUT_VIDEO_ENCODE_DPB_KHR = 1000299002,
  // Provided by VK_EXT_attachment_feedback_loop_layout
    VK_IMAGE_LAYOUT_ATTACHMENT_FEEDBACK_LOOP_OPTIMAL_EXT = 1000339000,
  // Provided by VK_ARM_tensors
    VK_IMAGE_LAYOUT_TENSOR_ALIASING_ARM = 1000460000,
  // Provided by VK_KHR_video_encode_quantization_map
    VK_IMAGE_LAYOUT_VIDEO_ENCODE_QUANTIZATION_MAP_KHR = 1000553000,
  // Provided by VK_EXT_zero_initialize_device_memory
    VK_IMAGE_LAYOUT_ZERO_INITIALIZED_EXT = 1000620000,
  // Provided by VK_KHR_maintenance2
    VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL_KHR = VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL,
  // Provided by VK_KHR_maintenance2
    VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL_KHR = VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL,
  // Provided by VK_NV_shading_rate_image
    VK_IMAGE_LAYOUT_SHADING_RATE_OPTIMAL_NV = VK_IMAGE_LAYOUT_FRAGMENT_SHADING_RATE_ATTACHMENT_OPTIMAL_KHR,
  // Provided by VK_KHR_dynamic_rendering_local_read
    VK_IMAGE_LAYOUT_RENDERING_LOCAL_READ_KHR = VK_IMAGE_LAYOUT_RENDERING_LOCAL_READ,
  // Provided by VK_KHR_separate_depth_stencil_layouts
    VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL_KHR = VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL,
  // Provided by VK_KHR_separate_depth_stencil_layouts
    VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL_KHR = VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL,
  // Provided by VK_KHR_separate_depth_stencil_layouts
    VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL_KHR = VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL,
  // Provided by VK_KHR_separate_depth_stencil_layouts
    VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL_KHR = VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL,
  // Provided by VK_KHR_synchronization2
    VK_IMAGE_LAYOUT_READ_ONLY_OPTIMAL_KHR = VK_IMAGE_LAYOUT_READ_ONLY_OPTIMAL,
  // Provided by VK_KHR_synchronization2
    VK_IMAGE_LAYOUT_ATTACHMENT_OPTIMAL_KHR = VK_IMAGE_LAYOUT_ATTACHMENT_OPTIMAL,
} VkImageLayout;

The type(s) of device access supported by each layout are:

The layout of each image subresource is not a state of the image subresource itself, but is rather a property of how the data in memory is organized, and thus for each mechanism of accessing an image in the API the application must specify a parameter or structure member that indicates which image layout the image subresource(s) are considered to be in when the image will be accessed. For transfer commands, this is a parameter to the command (see Clear Commands and Copy Commands). For use as a framebuffer attachment, this is a member in the substructures of the VkRenderPassCreateInfo (see Render Pass). For use in a descriptor set, this is a member in the VkDescriptorImageInfo structure (see Descriptor Set Updates).

If the unifiedImageLayouts feature is enabled, the VK_IMAGE_LAYOUT_GENERAL image layout may be used in place of the other layouts where allowed with no loss of performance.

VK_IMAGE_LAYOUT_GENERAL can be a useful catch-all image layout, but there are situations where a dedicated image layout must be used instead. Some examples include:

While VK_IMAGE_LAYOUT_GENERAL suggests that all types of device access is possible, it does not mean that all patterns of memory accesses are safe in all situations. Common Render Pass Data Races outlines some situations where data races are unavoidable. For example, when a subresource is used as both an attachment and a sampled image (i.e., not an input attachment), enabling feedback loop adds extra guarantees which VK_IMAGE_LAYOUT_GENERAL alone does not.

Image Layout Matching Rules

At the time that any command buffer command accessing an image executes on any queue, the layouts of the image subresources that are accessed must all match exactly the layout specified via the API controlling those accesses, except in case of accesses to an image with a depth/stencil format performed through descriptors referring to only a single aspect of the image, where the following relaxed matching rules apply:

When performing a layout transition on an image subresource, the old layout value must either equal the current layout of the image subresource (at the time the transition executes), or else be VK_IMAGE_LAYOUT_UNDEFINED (implying that the contents of the image subresource need not be preserved). The new layout used in a transition must not be any of:

The image layout of each image subresource of a depth/stencil image created with VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT is dependent on the last sample locations used to render to the image subresource as a depth/stencil attachment, thus applications must provide the same sample locations that were last used to render to the given image subresource whenever a layout transition of the image subresource happens, otherwise the contents of the depth aspect of the image subresource become undefined.

In addition, depth reads from a depth/stencil attachment referring to an image subresource range of a depth/stencil image created with VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT using different sample locations than what have been last used to perform depth writes to the image subresources of the same image subresource range return undefined values.

Similarly, depth writes to a depth/stencil attachment referring to an image subresource range of a depth/stencil image created with VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT using different sample locations than what have been last used to perform depth writes to the image subresources of the same image subresource range make the contents of the depth aspect of those image subresources undefined.

Image Views

Image objects are not directly accessed by pipeline shaders for reading or writing image data. Instead, image views representing contiguous ranges of the image subresources and containing additional metadata are used for that purpose. Views must be created on images of compatible types, and must represent a valid subset of image subresources.

Image views are represented by VkImageView handles:

// Provided by VK_VERSION_1_0
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkImageView)

VK_REMAINING_ARRAY_LAYERS is a special constant value used for image views to indicate that all remaining array layers in an image after the base layer should be included in the view.

#define VK_REMAINING_ARRAY_LAYERS         (~0U)

VK_REMAINING_MIP_LEVELS is a special constant value used for image views to indicate that all remaining mipmap levels in an image after the base level should be included in the view.

#define VK_REMAINING_MIP_LEVELS           (~0U)

The types of image views that can be created are:

// Provided by VK_VERSION_1_0
typedef enum VkImageViewType {
    VK_IMAGE_VIEW_TYPE_1D = 0,
    VK_IMAGE_VIEW_TYPE_2D = 1,
    VK_IMAGE_VIEW_TYPE_3D = 2,
    VK_IMAGE_VIEW_TYPE_CUBE = 3,
    VK_IMAGE_VIEW_TYPE_1D_ARRAY = 4,
    VK_IMAGE_VIEW_TYPE_2D_ARRAY = 5,
    VK_IMAGE_VIEW_TYPE_CUBE_ARRAY = 6,
} VkImageViewType;

To create an image view, call:

// Provided by VK_VERSION_1_0
VkResult vkCreateImageView(
    VkDevice                                    device,
    const VkImageViewCreateInfo*                pCreateInfo,
    const VkAllocationCallbacks*                pAllocator,
    VkImageView*                                pView);

  • device is the logical device that creates the image view.

  • pCreateInfo is a pointer to a VkImageViewCreateInfo structure containing parameters to be used to create the image view.

  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

  • pView is a pointer to a VkImageView handle in which the resulting image view object is returned.

Valid Usage
Valid Usage (Implicit)

  • VUID-vkCreateImageView-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkCreateImageView-pCreateInfo-parameter
    pCreateInfo must be a valid pointer to a valid VkImageViewCreateInfo structure

  • VUID-vkCreateImageView-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkCreateImageView-pView-parameter
    pView must be a valid pointer to a VkImageView handle

  • VUID-vkCreateImageView-device-queuecount
    The device must have been created with at least 1 queue

Return Codes
Success
Failure

The VkImageViewCreateInfo structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkImageViewCreateInfo {
    VkStructureType            sType;
    const void*                pNext;
    VkImageViewCreateFlags     flags;
    VkImage                    image;
    VkImageViewType            viewType;
    VkFormat                   format;
    VkComponentMapping         components;
    VkImageSubresourceRange    subresourceRange;
} VkImageViewCreateInfo;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • flags is a bitmask of VkImageViewCreateFlagBits specifying additional parameters of the image view.

  • image is a VkImage on which the view will be created.

  • viewType is a VkImageViewType value specifying the type of the image view.

  • format is a VkFormat specifying the format and type used to interpret texel blocks of the image.

  • components is a VkComponentMapping structure specifying a remapping of color components (or of depth or stencil components after they have been converted into color components).

  • subresourceRange is a VkImageSubresourceRange structure selecting the set of mipmap levels and array layers to be accessible to the view.

Some of the image creation parameters are inherited by the view. In particular, image view creation inherits the implicit parameter usage specifying the allowed usages of the image view that, by default, takes the value of the corresponding usage parameter specified in VkImageCreateInfo at image creation time. The implicit usage can be overridden by adding a VkImageViewUsageCreateInfo structure to the pNext chain, but the view usage must be a subset of the image usage. If image has a depth-stencil format and was created with a VkImageStencilUsageCreateInfo structure included in the pNext chain of VkImageCreateInfo, the usage is calculated based on the subresource.aspectMask provided:

If image is a 3D image, its Z range can be restricted to a subset by adding a VkImageViewSlicedCreateInfoEXT to the pNext chain.

If image was created with the VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT flag, and if the format of the image is not multi-planar format can be different from the image’s format, but if image was created without the VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT flag and they are not equal they must be compatible. Image format compatibility is defined in the Format Compatibility Classes section. Views of compatible formats will have the same mapping between texel coordinates and memory locations irrespective of the format, with only the interpretation of the bit pattern changing.

If image was created with a multi-planar format, and the image view’s aspectMask is one of VK_IMAGE_ASPECT_PLANE_0_BIT, VK_IMAGE_ASPECT_PLANE_1_BIT or VK_IMAGE_ASPECT_PLANE_2_BIT, the view’s aspect mask is considered to be equivalent to VK_IMAGE_ASPECT_COLOR_BIT when used as a framebuffer attachment.

Values intended to be used with one view format may not be exactly preserved when written or read through a different format. For example, an integer value that happens to have the bit pattern of a floating-point denorm or NaN may be flushed or canonicalized when written or read through a view with a floating-point format. Similarly, a value written through a signed normalized format that has a bit pattern exactly equal to -2b may be changed to -2b + 1 as described in Conversion from Normalized Fixed-Point to Floating-Point.

If image was created with the VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT flag, format must be compatible with the image’s format as described above; or must be an uncompressed format, in which case it must be size-compatible with the image’s format. In this case, the resulting image view’s texel dimensions equal the dimensions of the selected mip level divided by the compressed texel block size and rounded up.

The VkComponentMapping components member describes a remapping from components of the image to components of the vector returned by shader image instructions. This remapping must be the identity swizzle for any VkImageView used with a combined image sampler that enables sampler Y′CBCR conversion, input attachment descriptors, framebuffer attachments, and storage image descriptors.

If the image view is to be used with a sampler which supports sampler Y′CBCR conversion, an identically defined object of type VkSamplerYcbcrConversion to that used to create the sampler must be passed to vkCreateImageView in a VkSamplerYcbcrConversionInfo included in the pNext chain of VkImageViewCreateInfo. Conversely, if a VkSamplerYcbcrConversion object is passed to vkCreateImageView, an identically defined VkSamplerYcbcrConversion object must be used when sampling the image.

If the image has a multi-planar format, subresourceRange.aspectMask is VK_IMAGE_ASPECT_COLOR_BIT, and usage includes VK_IMAGE_USAGE_SAMPLED_BIT, then the format must be identical to the image format and the sampler to be used with the image view must enable sampler Y′CBCR conversion.

When such an image is used in a video coding operation, the sampler Y′CBCR conversion has no effect.

If image was created with the VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT and the image has a multi-planar format, and if subresourceRange.aspectMask is VK_IMAGE_ASPECT_PLANE_0_BIT, VK_IMAGE_ASPECT_PLANE_1_BIT, or VK_IMAGE_ASPECT_PLANE_2_BIT, format must be compatible with the corresponding plane of the image, and the sampler to be used with the image view must not enable sampler Y′CBCR conversion. The width and height of the single-plane image view must be derived from the multi-planar image’s dimensions in the manner listed for plane compatibility for the plane.

Any view of an image plane will have the same mapping between texel coordinates and memory locations as used by the components of the color aspect, subject to the formulae relating texel coordinates to lower-resolution planes as described in Chroma Reconstruction. That is, if an R or B plane has a reduced resolution relative to the G plane of the multi-planar image, the image view operates using the (uplane, vplane) unnormalized coordinates of the reduced-resolution plane, and these coordinates access the same memory locations as the (ucolor, vcolor) unnormalized coordinates of the color aspect for which chroma reconstruction operations operate on the same (uplane, vplane) or (iplane, jplane) coordinates.

Table 1. Image Type and Image View Type Compatibility Requirements
Image View Type Compatible Image Types

VK_IMAGE_VIEW_TYPE_1D

VK_IMAGE_TYPE_1D

VK_IMAGE_VIEW_TYPE_1D_ARRAY

VK_IMAGE_TYPE_1D

VK_IMAGE_VIEW_TYPE_2D

VK_IMAGE_TYPE_2D , VK_IMAGE_TYPE_3D

VK_IMAGE_VIEW_TYPE_2D_ARRAY

VK_IMAGE_TYPE_2D , VK_IMAGE_TYPE_3D

VK_IMAGE_VIEW_TYPE_CUBE

VK_IMAGE_TYPE_2D

VK_IMAGE_VIEW_TYPE_CUBE_ARRAY

VK_IMAGE_TYPE_2D

VK_IMAGE_VIEW_TYPE_3D

VK_IMAGE_TYPE_3D
Valid Usage
Valid Usage (Implicit)

Bits which can be set in VkImageViewCreateInfo::flags, specifying additional parameters of an image view, are:

// Provided by VK_VERSION_1_0
typedef enum VkImageViewCreateFlagBits {
  // Provided by VK_EXT_fragment_density_map
    VK_IMAGE_VIEW_CREATE_FRAGMENT_DENSITY_MAP_DYNAMIC_BIT_EXT = 0x00000001,
  // Provided by VK_EXT_descriptor_buffer
    VK_IMAGE_VIEW_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXT = 0x00000004,
  // Provided by VK_EXT_fragment_density_map2
    VK_IMAGE_VIEW_CREATE_FRAGMENT_DENSITY_MAP_DEFERRED_BIT_EXT = 0x00000002,
} VkImageViewCreateFlagBits;
// Provided by VK_VERSION_1_0
typedef VkFlags VkImageViewCreateFlags;

VkImageViewCreateFlags is a bitmask type for setting a mask of zero or more VkImageViewCreateFlagBits.

The set of usages for the created image view can be restricted compared to the parent image’s usage flags by adding a VkImageViewUsageCreateInfo structure to the pNext chain of VkImageViewCreateInfo.

The VkImageViewUsageCreateInfo structure is defined as:

// Provided by VK_VERSION_1_1
typedef struct VkImageViewUsageCreateInfo {
    VkStructureType      sType;
    const void*          pNext;
    VkImageUsageFlags    usage;
} VkImageViewUsageCreateInfo;
// Provided by VK_KHR_maintenance2
// Equivalent to VkImageViewUsageCreateInfo
typedef VkImageViewUsageCreateInfo VkImageViewUsageCreateInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • usage is a bitmask of VkImageUsageFlagBits specifying allowed usages of the image view.

When this structure is chained to VkImageViewCreateInfo the usage field overrides the implicit usage parameter inherited from image creation time and its value is used instead for the purposes of determining the valid usage conditions of VkImageViewCreateInfo.

Valid Usage (Implicit)

The range of 3D slices for the created image view can be restricted to a subset of the parent image’s Z range by adding a VkImageViewSlicedCreateInfoEXT structure to the pNext chain of VkImageViewCreateInfo.

The VkImageViewSlicedCreateInfoEXT structure is defined as:

// Provided by VK_EXT_image_sliced_view_of_3d
typedef struct VkImageViewSlicedCreateInfoEXT {
    VkStructureType    sType;
    const void*        pNext;
    uint32_t           sliceOffset;
    uint32_t           sliceCount;
} VkImageViewSlicedCreateInfoEXT;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • sliceOffset is the Z-offset for the first 3D slice accessible to the image view.

  • sliceCount is the number of 3D slices accessible to the image view.

When this structure is chained to VkImageViewCreateInfo the sliceOffset field is treated as a Z-offset for the sliced view and sliceCount specifies the range. Shader accesses using a Z coordinate of 0 will access the depth slice corresponding to sliceOffset in the image, and in a shader, the maximum in-bounds Z coordinate for the view is sliceCount - 1.

A sliced 3D view must only be used with a single mip level. The slice coordinates are integer coordinates within the subresourceRange.baseMipLevel used to create the image view.

The effective view depth is equal to extent.depth used to create the image for this view adjusted by subresourceRange.baseMipLevel as specified in Image Mip Level Sizing.

Shader access to this image view is only affected by VkImageViewSlicedCreateInfoEXT if it uses a descriptor of type VK_DESCRIPTOR_TYPE_STORAGE_IMAGE. For access using any other descriptor type, the contents of VkImageViewSlicedCreateInfoEXT are ignored; instead, sliceOffset is treated as being equal to 0, and sliceCount is treated as being equal to VK_REMAINING_3D_SLICES_EXT.

Valid Usage

  • VUID-VkImageViewSlicedCreateInfoEXT-sliceOffset-07867
    sliceOffset must be less than the effective view depth as specified in Image Mip Level Sizing

  • VUID-VkImageViewSlicedCreateInfoEXT-sliceCount-07868
    If sliceCount is not VK_REMAINING_3D_SLICES_EXT, it must be non-zero and sliceOffset + sliceCount must be less than or equal to the effective view depth as specified in Image Mip Level Sizing

  • VUID-VkImageViewSlicedCreateInfoEXT-image-07869
    image must have been created with imageType equal to VK_IMAGE_TYPE_3D

  • VUID-VkImageViewSlicedCreateInfoEXT-viewType-07909
    viewType must be VK_IMAGE_VIEW_TYPE_3D

  • VUID-VkImageViewSlicedCreateInfoEXT-None-07870
    The image view must reference exactly 1 mip level

  • VUID-VkImageViewSlicedCreateInfoEXT-None-07871
    The imageSlicedViewOf3D feature must be enabled

Valid Usage (Implicit)

VK_REMAINING_3D_SLICES_EXT is a special constant value used for VkImageViewSlicedCreateInfoEXT::sliceCount to indicate that all remaining 3D slices in an image after the first slice offset specified should be included in the view.

#define VK_REMAINING_3D_SLICES_EXT        (~0U)

The VkImageSubresourceRange structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkImageSubresourceRange {
    VkImageAspectFlags    aspectMask;
    uint32_t              baseMipLevel;
    uint32_t              levelCount;
    uint32_t              baseArrayLayer;
    uint32_t              layerCount;
} VkImageSubresourceRange;

  • aspectMask is a bitmask of VkImageAspectFlagBits specifying which aspect(s) of the image are included in the view.

  • baseMipLevel is the first mipmap level accessible to the view.

  • levelCount is the number of mipmap levels (starting from baseMipLevel) accessible to the view.

  • baseArrayLayer is the first array layer accessible to the view.

  • layerCount is the number of array layers (starting from baseArrayLayer) accessible to the view.

The number of mipmap levels and array layers must be a subset of the image subresources in the image. If an application wants to use all mip levels or layers in an image after the baseMipLevel or baseArrayLayer, it can set levelCount and layerCount to the special values VK_REMAINING_MIP_LEVELS and VK_REMAINING_ARRAY_LAYERS without knowing the exact number of mip levels or layers.

For cube and cube array image views, the layers of the image view starting at baseArrayLayer correspond to faces in the order +X, -X, +Y, -Y, +Z, -Z. For cube arrays, each set of six sequential layers is a single cube, so the number of cube maps in a cube map array view is layerCount / 6, and image array layer (baseArrayLayer + i) is face index (i mod 6) of cube i / 6. If the number of layers in the view, whether set explicitly in layerCount or implied by VK_REMAINING_ARRAY_LAYERS, is not a multiple of 6, the last cube map in the array must not be accessed.

aspectMask must be only VK_IMAGE_ASPECT_COLOR_BIT, VK_IMAGE_ASPECT_DEPTH_BIT or VK_IMAGE_ASPECT_STENCIL_BIT if format is a color, depth-only or stencil-only format, respectively, except if format is a multi-planar format. If using a depth/stencil format with both depth and stencil components, aspectMask must include at least one of VK_IMAGE_ASPECT_DEPTH_BIT and VK_IMAGE_ASPECT_STENCIL_BIT, and can include both.

When the VkImageSubresourceRange structure is used to select a subset of the slices of a 3D image’s mip level in order to create a 2D or 2D array image view of a 3D image created with VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT, baseArrayLayer and layerCount specify the first slice index and the number of slices to include in the created image view. Such an image view can be used as a framebuffer attachment that refers only to the specified range of slices of the selected mip level. If the maintenance9 feature is not enabled, any layout transitions performed on such an attachment view during a render pass instance still apply to the entire subresource referenced which includes all the slices of the selected mip level.

When using an image view of a depth/stencil image to populate a descriptor set (e.g. for sampling in the shader, or for use as an input attachment), the aspectMask must only include one bit, which selects whether the image view is used for depth reads (i.e. using a floating-point sampler or input attachment in the shader) or stencil reads (i.e. using an unsigned integer sampler or input attachment in the shader). When an image view of a depth/stencil image is used as a depth/stencil framebuffer attachment, the aspectMask is ignored and both depth and stencil image subresources are used.

When creating a VkImageView, if sampler Y′CBCR conversion is enabled in the sampler, the aspectMask of a subresourceRange used by the VkImageView must be VK_IMAGE_ASPECT_COLOR_BIT.

When creating a VkImageView, if sampler Y′CBCR conversion is not enabled in the sampler and the image format is multi-planar format, the image must have been created with VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT, and the aspectMask of the VkImageView’s subresourceRange must be VK_IMAGE_ASPECT_PLANE_0_BIT, VK_IMAGE_ASPECT_PLANE_1_BIT or VK_IMAGE_ASPECT_PLANE_2_BIT.

Valid Usage
Valid Usage (Implicit)

  • VUID-VkImageSubresourceRange-aspectMask-parameter
    aspectMask must be a valid combination of VkImageAspectFlagBits values

  • VUID-VkImageSubresourceRange-aspectMask-requiredbitmask
    aspectMask must not be 0

Bits which can be set in an aspect mask to specify aspects of an image for purposes such as identifying a subresource, are:

// Provided by VK_VERSION_1_0
typedef enum VkImageAspectFlagBits {
    VK_IMAGE_ASPECT_COLOR_BIT = 0x00000001,
    VK_IMAGE_ASPECT_DEPTH_BIT = 0x00000002,
    VK_IMAGE_ASPECT_STENCIL_BIT = 0x00000004,
    VK_IMAGE_ASPECT_METADATA_BIT = 0x00000008,
  // Provided by VK_VERSION_1_1
    VK_IMAGE_ASPECT_PLANE_0_BIT = 0x00000010,
  // Provided by VK_VERSION_1_1
    VK_IMAGE_ASPECT_PLANE_1_BIT = 0x00000020,
  // Provided by VK_VERSION_1_1
    VK_IMAGE_ASPECT_PLANE_2_BIT = 0x00000040,
  // Provided by VK_VERSION_1_3
    VK_IMAGE_ASPECT_NONE = 0,
  // Provided by VK_EXT_image_drm_format_modifier
    VK_IMAGE_ASPECT_MEMORY_PLANE_0_BIT_EXT = 0x00000080,
  // Provided by VK_EXT_image_drm_format_modifier
    VK_IMAGE_ASPECT_MEMORY_PLANE_1_BIT_EXT = 0x00000100,
  // Provided by VK_EXT_image_drm_format_modifier
    VK_IMAGE_ASPECT_MEMORY_PLANE_2_BIT_EXT = 0x00000200,
  // Provided by VK_EXT_image_drm_format_modifier
    VK_IMAGE_ASPECT_MEMORY_PLANE_3_BIT_EXT = 0x00000400,
  // Provided by VK_KHR_sampler_ycbcr_conversion
    VK_IMAGE_ASPECT_PLANE_0_BIT_KHR = VK_IMAGE_ASPECT_PLANE_0_BIT,
  // Provided by VK_KHR_sampler_ycbcr_conversion
    VK_IMAGE_ASPECT_PLANE_1_BIT_KHR = VK_IMAGE_ASPECT_PLANE_1_BIT,
  // Provided by VK_KHR_sampler_ycbcr_conversion
    VK_IMAGE_ASPECT_PLANE_2_BIT_KHR = VK_IMAGE_ASPECT_PLANE_2_BIT,
  // Provided by VK_KHR_maintenance4
    VK_IMAGE_ASPECT_NONE_KHR = VK_IMAGE_ASPECT_NONE,
} VkImageAspectFlagBits;
// Provided by VK_VERSION_1_0
typedef VkFlags VkImageAspectFlags;

VkImageAspectFlags is a bitmask type for setting a mask of zero or more VkImageAspectFlagBits.

The VkComponentMapping structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkComponentMapping {
    VkComponentSwizzle    r;
    VkComponentSwizzle    g;
    VkComponentSwizzle    b;
    VkComponentSwizzle    a;
} VkComponentMapping;

  • r is a VkComponentSwizzle specifying the component value placed in the R component of the output vector.

  • g is a VkComponentSwizzle specifying the component value placed in the G component of the output vector.

  • b is a VkComponentSwizzle specifying the component value placed in the B component of the output vector.

  • a is a VkComponentSwizzle specifying the component value placed in the A component of the output vector.

Valid Usage (Implicit)

Possible values of the members of VkComponentMapping, specifying the component values placed in each component of the output vector, are:

// Provided by VK_VERSION_1_0
typedef enum VkComponentSwizzle {
    VK_COMPONENT_SWIZZLE_IDENTITY = 0,
    VK_COMPONENT_SWIZZLE_ZERO = 1,
    VK_COMPONENT_SWIZZLE_ONE = 2,
    VK_COMPONENT_SWIZZLE_R = 3,
    VK_COMPONENT_SWIZZLE_G = 4,
    VK_COMPONENT_SWIZZLE_B = 5,
    VK_COMPONENT_SWIZZLE_A = 6,
} VkComponentSwizzle;

Setting the identity swizzle on a component is equivalent to setting the identity mapping on that component. That is:

Table 2. Component Mappings Equivalent To VK_COMPONENT_SWIZZLE_IDENTITY
Component Identity Mapping

components.r

VK_COMPONENT_SWIZZLE_R

components.g

VK_COMPONENT_SWIZZLE_G

components.b

VK_COMPONENT_SWIZZLE_B

components.a

VK_COMPONENT_SWIZZLE_A

If the pNext chain includes a VkImageViewASTCDecodeModeEXT structure, then that structure includes a parameter specifying the decode mode for image views using ASTC compressed formats.

The VkImageViewASTCDecodeModeEXT structure is defined as:

// Provided by VK_EXT_astc_decode_mode
typedef struct VkImageViewASTCDecodeModeEXT {
    VkStructureType    sType;
    const void*        pNext;
    VkFormat           decodeMode;
} VkImageViewASTCDecodeModeEXT;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • decodeMode is the intermediate format used to decode ASTC compressed formats.

Valid Usage

If format uses sRGB encoding then the decodeMode has no effect.

Valid Usage (Implicit)

If the pNext chain includes a VkImageViewSampleWeightCreateInfoQCOM structure, then that structure includes a parameter specifying the parameters for weight image views used in weight image sampling.

The VkImageViewSampleWeightCreateInfoQCOM structure is defined as:

// Provided by VK_QCOM_image_processing
typedef struct VkImageViewSampleWeightCreateInfoQCOM {
    VkStructureType    sType;
    const void*        pNext;
    VkOffset2D         filterCenter;
    VkExtent2D         filterSize;
    uint32_t           numPhases;
} VkImageViewSampleWeightCreateInfoQCOM;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • filterCenter is a VkOffset2D describing the location of the weight filter origin.

  • filterSize is a VkExtent2D specifying weight filter dimensions.

  • numPhases is the number of sub-pixel filter phases.

The filterCenter specifies the origin or center of the filter kernel, as described in Weight Sampling Operation. The numPhases describes the number of sub-pixel filter phases as described in Weight Sampling Phases.

Valid Usage
Valid Usage (Implicit)

To destroy an image view, call:

// Provided by VK_VERSION_1_0
void vkDestroyImageView(
    VkDevice                                    device,
    VkImageView                                 imageView,
    const VkAllocationCallbacks*                pAllocator);

  • device is the logical device that destroys the image view.

  • imageView is the image view to destroy.

  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

Valid Usage

  • VUID-vkDestroyImageView-imageView-01026
    All submitted commands that refer to imageView must have completed execution

  • VUID-vkDestroyImageView-imageView-01027
    If VkAllocationCallbacks were provided when imageView was created, a compatible set of callbacks must be provided here

  • VUID-vkDestroyImageView-imageView-01028
    If no VkAllocationCallbacks were provided when imageView was created, pAllocator must be NULL

Valid Usage (Implicit)

  • VUID-vkDestroyImageView-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkDestroyImageView-imageView-parameter
    If imageView is not VK_NULL_HANDLE, imageView must be a valid VkImageView handle

  • VUID-vkDestroyImageView-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkDestroyImageView-imageView-parent
    If imageView is a valid handle, it must have been created, allocated, or retrieved from device

Host Synchronization

  • Host access to imageView must be externally synchronized

To get the handle for an image view, call:

// Provided by VK_NVX_image_view_handle
uint32_t vkGetImageViewHandleNVX(
    VkDevice                                    device,
    const VkImageViewHandleInfoNVX*             pInfo);

  • device is the logical device that owns the image view.

  • pInfo describes the image view to query and type of handle.

Valid Usage (Implicit)

  • VUID-vkGetImageViewHandleNVX-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetImageViewHandleNVX-pInfo-parameter
    pInfo must be a valid pointer to a valid VkImageViewHandleInfoNVX structure

To get the 64-bit handle for an image view, call:

// Provided by VK_NVX_image_view_handle
uint64_t vkGetImageViewHandle64NVX(
    VkDevice                                    device,
    const VkImageViewHandleInfoNVX*             pInfo);

  • device is the logical device that owns the image view.

  • pInfo describes the image view to query and type of handle.

Valid Usage (Implicit)

  • VUID-vkGetImageViewHandle64NVX-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetImageViewHandle64NVX-pInfo-parameter
    pInfo must be a valid pointer to a valid VkImageViewHandleInfoNVX structure

The VkImageViewHandleInfoNVX structure is defined as:

// Provided by VK_NVX_image_view_handle
typedef struct VkImageViewHandleInfoNVX {
    VkStructureType     sType;
    const void*         pNext;
    VkImageView         imageView;
    VkDescriptorType    descriptorType;
    VkSampler           sampler;
} VkImageViewHandleInfoNVX;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • imageView is the image view to query.

  • descriptorType is the type of descriptor for which to query a handle.

  • sampler is the sampler to combine with the image view when generating the handle.

Valid Usage
Valid Usage (Implicit)

  • VUID-VkImageViewHandleInfoNVX-sType-sType
    sType must be VK_STRUCTURE_TYPE_IMAGE_VIEW_HANDLE_INFO_NVX

  • VUID-VkImageViewHandleInfoNVX-pNext-pNext
    pNext must be NULL

  • VUID-VkImageViewHandleInfoNVX-imageView-parameter
    imageView must be a valid VkImageView handle

  • VUID-VkImageViewHandleInfoNVX-descriptorType-parameter
    descriptorType must be a valid VkDescriptorType value

  • VUID-VkImageViewHandleInfoNVX-sampler-parameter
    If sampler is not VK_NULL_HANDLE, sampler must be a valid VkSampler handle

  • VUID-VkImageViewHandleInfoNVX-commonparent
    Both of imageView, and sampler that are valid handles of non-ignored parameters must have been created, allocated, or retrieved from the same VkDevice

To get the device address for an image view, call:

// Provided by VK_NVX_image_view_handle
VkResult vkGetImageViewAddressNVX(
    VkDevice                                    device,
    VkImageView                                 imageView,
    VkImageViewAddressPropertiesNVX*            pProperties);

  • device is the logical device that owns the image view.

  • imageView is a handle to the image view.

  • pProperties contains the device address and size when the call returns.

Valid Usage (Implicit)

  • VUID-vkGetImageViewAddressNVX-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetImageViewAddressNVX-imageView-parameter
    imageView must be a valid VkImageView handle

  • VUID-vkGetImageViewAddressNVX-pProperties-parameter
    pProperties must be a valid pointer to a VkImageViewAddressPropertiesNVX structure

  • VUID-vkGetImageViewAddressNVX-imageView-parent
    imageView must have been created, allocated, or retrieved from device

Return Codes
Success
Failure

The VkImageViewAddressPropertiesNVX structure is defined as:

// Provided by VK_NVX_image_view_handle
typedef struct VkImageViewAddressPropertiesNVX {
    VkStructureType    sType;
    void*              pNext;
    VkDeviceAddress    deviceAddress;
    VkDeviceSize       size;
} VkImageViewAddressPropertiesNVX;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • deviceAddress is the device address of the image view.

  • size is the size in bytes of the image view device memory.

Valid Usage (Implicit)

Image View Format Features

Valid uses of a VkImageView may depend on the image view’s format features, defined below. Such constraints are documented in the affected valid usage statement.

The VkImageViewMinLodCreateInfoEXT structure is defined as:

// Provided by VK_EXT_image_view_min_lod
typedef struct VkImageViewMinLodCreateInfoEXT {
    VkStructureType    sType;
    const void*        pNext;
    float              minLod;
} VkImageViewMinLodCreateInfoEXT;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • minLod is the value to clamp the minimum LOD accessible by this VkImageView.

If the pNext chain includes a VkImageViewMinLodCreateInfoEXT structure, then that structure includes a parameter specifying a value to clamp the minimum LOD value during Image Level(s) Selection, Texel Gathering and Integer Texel Coordinate Operations.

If the image view contains VkImageViewMinLodCreateInfoEXT and it is used as part of a sampling operation:

minLodFloatimageView = minLod

otherwise:

minLodFloatimageView = 0.0

An integer variant of this parameter is also defined for sampling operations which access integer mipmap levels:

minLodIntegerimageView = ⌊minLodFloatimageView⌋

Valid Usage

  • VUID-VkImageViewMinLodCreateInfoEXT-minLod-06455
    If the minLod feature is not enabled, minLod must be 0.0

  • VUID-VkImageViewMinLodCreateInfoEXT-minLod-06456
    minLod must be less or equal to the index of the last mipmap level accessible to the view

Valid Usage (Implicit)

Acceleration Structures

Acceleration structures are opaque data structures that are built by the implementation to more efficiently perform spatial queries on the provided geometric data. For these extensions, an acceleration structure is either a top-level acceleration structure containing a set of bottom-level acceleration structures or a bottom-level acceleration structure containing either a set of axis-aligned bounding boxes for custom geometry or a set of triangles.

Each instance in the top-level acceleration structure contains a reference to a bottom-level acceleration structure as well as an instance transform plus information required to index into the shader bindings. The top-level acceleration structure is what is bound to the acceleration descriptor, for example to trace inside the shader in the ray tracing pipeline.

Acceleration structures for the VK_KHR_acceleration_structure extension are represented by VkAccelerationStructureKHR handles:

// Provided by VK_KHR_acceleration_structure
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkAccelerationStructureKHR)

To create an acceleration structure, call:

// Provided by VK_KHR_acceleration_structure
VkResult vkCreateAccelerationStructureKHR(
    VkDevice                                    device,
    const VkAccelerationStructureCreateInfoKHR* pCreateInfo,
    const VkAllocationCallbacks*                pAllocator,
    VkAccelerationStructureKHR*                 pAccelerationStructure);

  • device is the logical device that creates the acceleration structure object.

  • pCreateInfo is a pointer to a VkAccelerationStructureCreateInfoKHR structure containing parameters affecting creation of the acceleration structure.

  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

  • pAccelerationStructure is a pointer to a VkAccelerationStructureKHR handle in which the resulting acceleration structure object is returned.

Similar to other objects in Vulkan, the acceleration structure creation merely creates an object with a specific “shape”. The type and quantity of geometry that can be built into an acceleration structure is determined by the parameters of VkAccelerationStructureCreateInfoKHR.

The acceleration structure data is stored in the object referred to by VkAccelerationStructureCreateInfoKHR::buffer. Once memory has been bound to that buffer, it must be populated by acceleration structure build or acceleration structure copy commands such as vkCmdBuildAccelerationStructuresKHR, vkBuildAccelerationStructuresKHR, vkCmdCopyAccelerationStructureKHR, and vkCopyAccelerationStructureKHR.

The expected usage for a trace capture/replay tool is that it will serialize and later deserialize the acceleration structure data using acceleration structure copy commands. During capture the tool will use vkCopyAccelerationStructureToMemoryKHR or vkCmdCopyAccelerationStructureToMemoryKHR with a mode of VK_COPY_ACCELERATION_STRUCTURE_MODE_SERIALIZE_KHR, and vkCopyMemoryToAccelerationStructureKHR or vkCmdCopyMemoryToAccelerationStructureKHR with a mode of VK_COPY_ACCELERATION_STRUCTURE_MODE_DESERIALIZE_KHR during replay.

Memory does not need to be bound to the underlying buffer when vkCreateAccelerationStructureKHR is called.

The input buffers passed to acceleration structure build commands will be referenced by the implementation for the duration of the command. After the command completes, the acceleration structure may hold a reference to any acceleration structure specified by an active instance contained therein. Apart from this referencing, acceleration structures must be fully self-contained. The application can reuse or free any memory which was used by the command as an input or as scratch without affecting the results of ray traversal.

Valid Usage
Valid Usage (Implicit)

  • VUID-vkCreateAccelerationStructureKHR-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkCreateAccelerationStructureKHR-pCreateInfo-parameter
    pCreateInfo must be a valid pointer to a valid VkAccelerationStructureCreateInfoKHR structure

  • VUID-vkCreateAccelerationStructureKHR-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkCreateAccelerationStructureKHR-pAccelerationStructure-parameter
    pAccelerationStructure must be a valid pointer to a VkAccelerationStructureKHR handle

  • VUID-vkCreateAccelerationStructureKHR-device-queuecount
    The device must have been created with at least 1 queue

Return Codes
Success
Failure

The VkAccelerationStructureCreateInfoKHR structure is defined as:

// Provided by VK_KHR_acceleration_structure
typedef struct VkAccelerationStructureCreateInfoKHR {
    VkStructureType                          sType;
    const void*                              pNext;
    VkAccelerationStructureCreateFlagsKHR    createFlags;
    VkBuffer                                 buffer;
    VkDeviceSize                             offset;
    VkDeviceSize                             size;
    VkAccelerationStructureTypeKHR           type;
    VkDeviceAddress                          deviceAddress;
} VkAccelerationStructureCreateInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • createFlags is a bitmask of VkAccelerationStructureCreateFlagBitsKHR specifying additional creation parameters of the acceleration structure.

  • buffer is the buffer on which the acceleration structure will be stored.

  • offset is an offset in bytes from the base address of the buffer at which the acceleration structure will be stored, and must be a multiple of 256.

  • size is the size required for the acceleration structure.

  • type is a VkAccelerationStructureTypeKHR value specifying the type of acceleration structure that will be created.

  • deviceAddress is the device address requested for the acceleration structure, obtained from vkGetAccelerationStructureDeviceAddressKHR, if the accelerationStructureCaptureReplay feature is being used. If deviceAddress is zero, no specific address is requested.

Applications should avoid creating acceleration structures with application-provided addresses and implementation-provided addresses in the same process, to reduce the likelihood of VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS_KHR errors.

The expected usage for this is that a trace capture/replay tool will add the VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT flag to all buffers that use VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT, and will add VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT to all buffers used as storage for an acceleration structure where deviceAddress is not zero. This also means that the tool will need to add VK_MEMORY_ALLOCATE_DEVICE_ADDRESS_BIT to memory allocations to allow the flag to be set where the application may not have otherwise required it. During capture the tool will save the queried opaque device addresses in the trace. During replay, the buffers will be created specifying the original address so any address values stored in the trace data will remain valid.

Implementations are expected to separate such buffers in the GPU address space so normal allocations will avoid using these addresses. Applications and tools should avoid mixing application-provided and implementation-provided addresses for buffers created with VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT, to avoid address space allocation conflicts.

Applications should create an acceleration structure with a specific VkAccelerationStructureTypeKHR other than VK_ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR.

VK_ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR is intended to be used by API translation layers. This can be used at acceleration structure creation time in cases where the actual acceleration structure type (top or bottom) is not yet known. The actual acceleration structure type must be specified as VK_ACCELERATION_STRUCTURE_TYPE_TOP_LEVEL_KHR or VK_ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_KHR when the build is performed.

If the acceleration structure will be the target of a build operation, the required size for an acceleration structure can be queried with vkGetAccelerationStructureBuildSizesKHR. If the acceleration structure is going to be the target of a compacting copy, vkCmdWriteAccelerationStructuresPropertiesKHR or vkWriteAccelerationStructuresPropertiesKHR can be used to obtain the compacted size required.

If the acceleration structure will be the target of a build operation with VK_BUILD_ACCELERATION_STRUCTURE_MOTION_BIT_NV it must include VK_ACCELERATION_STRUCTURE_CREATE_MOTION_BIT_NV in createFlags and include VkAccelerationStructureMotionInfoNV as an extension structure in pNext with the number of instances as metadata for the object.

Valid Usage
Valid Usage (Implicit)

The VkAccelerationStructureMotionInfoNV structure is defined as:

// Provided by VK_NV_ray_tracing_motion_blur
typedef struct VkAccelerationStructureMotionInfoNV {
    VkStructureType                             sType;
    const void*                                 pNext;
    uint32_t                                    maxInstances;
    VkAccelerationStructureMotionInfoFlagsNV    flags;
} VkAccelerationStructureMotionInfoNV;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • maxInstances is the maximum number of instances that may be used in the motion top-level acceleration structure.

  • flags is 0 and reserved for future use.

Valid Usage (Implicit)
// Provided by VK_NV_ray_tracing_motion_blur
typedef VkFlags VkAccelerationStructureMotionInfoFlagsNV;

VkAccelerationStructureMotionInfoFlagsNV is a bitmask type for setting a mask, but is currently reserved for future use.

To get the build sizes for an acceleration structure, call:

// Provided by VK_KHR_acceleration_structure
void vkGetAccelerationStructureBuildSizesKHR(
    VkDevice                                    device,
    VkAccelerationStructureBuildTypeKHR         buildType,
    const VkAccelerationStructureBuildGeometryInfoKHR* pBuildInfo,
    const uint32_t*                             pMaxPrimitiveCounts,
    VkAccelerationStructureBuildSizesInfoKHR*   pSizeInfo);

  • device is the logical device that will be used for creating the acceleration structure.

  • buildType defines whether host or device operations (or both) are being queried for.

  • pBuildInfo is a pointer to a VkAccelerationStructureBuildGeometryInfoKHR structure describing parameters of a build operation.

  • pMaxPrimitiveCounts is a pointer to an array of pBuildInfo->geometryCount uint32_t values defining the number of primitives built into each geometry.

  • pSizeInfo is a pointer to a VkAccelerationStructureBuildSizesInfoKHR structure which returns the size required for an acceleration structure and the sizes required for the scratch buffers, given the build parameters. The size requirements for a scratch buffer may be zero.

The srcAccelerationStructure, dstAccelerationStructure, and mode members of pBuildInfo are ignored. Any VkDeviceOrHostAddressKHR or VkDeviceOrHostAddressConstKHR members of pBuildInfo are ignored by this command, except that the hostAddress member of VkAccelerationStructureGeometryTrianglesDataKHR::transformData will be examined to check if it is NULL.

An acceleration structure created with the accelerationStructureSize returned by this command supports any build or update with a VkAccelerationStructureBuildGeometryInfoKHR structure and array of VkAccelerationStructureBuildRangeInfoKHR structures subject to the following properties:

Similarly, the updateScratchSize value will support any build command specifying the VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR mode under the above conditions, and the buildScratchSize value will support any build command specifying the VK_BUILD_ACCELERATION_STRUCTURE_MODE_BUILD_KHR mode under the above conditions.

Valid Usage
Valid Usage (Implicit)

  • VUID-vkGetAccelerationStructureBuildSizesKHR-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetAccelerationStructureBuildSizesKHR-buildType-parameter
    buildType must be a valid VkAccelerationStructureBuildTypeKHR value

  • VUID-vkGetAccelerationStructureBuildSizesKHR-pBuildInfo-parameter
    pBuildInfo must be a valid pointer to a valid VkAccelerationStructureBuildGeometryInfoKHR structure

  • VUID-vkGetAccelerationStructureBuildSizesKHR-pMaxPrimitiveCounts-parameter
    If pMaxPrimitiveCounts is not NULL, pMaxPrimitiveCounts must be a valid pointer to an array of pBuildInfo->geometryCount uint32_t values

  • VUID-vkGetAccelerationStructureBuildSizesKHR-pSizeInfo-parameter
    pSizeInfo must be a valid pointer to a VkAccelerationStructureBuildSizesInfoKHR structure

The VkAccelerationStructureBuildSizesInfoKHR structure describes the required build sizes for an acceleration structure and scratch buffers and is defined as:

// Provided by VK_KHR_acceleration_structure
typedef struct VkAccelerationStructureBuildSizesInfoKHR {
    VkStructureType    sType;
    void*              pNext;
    VkDeviceSize       accelerationStructureSize;
    VkDeviceSize       updateScratchSize;
    VkDeviceSize       buildScratchSize;
} VkAccelerationStructureBuildSizesInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • accelerationStructureSize is the size in bytes required in a VkAccelerationStructureKHR for a build or update operation.

  • updateScratchSize is the size in bytes required in a scratch buffer for an update operation.

  • buildScratchSize is the size in bytes required in a scratch buffer for a build operation.

Valid Usage (Implicit)

Acceleration structures for the VK_NV_ray_tracing extension are represented by the similar VkAccelerationStructureNV handles:

// Provided by VK_NV_ray_tracing
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkAccelerationStructureNV)

To create acceleration structures, call:

// Provided by VK_NV_ray_tracing
VkResult vkCreateAccelerationStructureNV(
    VkDevice                                    device,
    const VkAccelerationStructureCreateInfoNV*  pCreateInfo,
    const VkAllocationCallbacks*                pAllocator,
    VkAccelerationStructureNV*                  pAccelerationStructure);

  • device is the logical device that creates the buffer object.

  • pCreateInfo is a pointer to a VkAccelerationStructureCreateInfoNV structure containing parameters affecting creation of the acceleration structure.

  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

  • pAccelerationStructure is a pointer to a VkAccelerationStructureNV handle in which the resulting acceleration structure object is returned.

Similarly to other objects in Vulkan, the acceleration structure creation merely creates an object with a specific “shape” as specified by the information in VkAccelerationStructureInfoNV and compactedSize in pCreateInfo.

Once memory has been bound to the acceleration structure using vkBindAccelerationStructureMemoryNV, that memory is populated by calls to vkCmdBuildAccelerationStructureNV and vkCmdCopyAccelerationStructureNV.

Acceleration structure creation uses the count and type information from the geometries, but does not use the data references in the structures.

Valid Usage (Implicit)

  • VUID-vkCreateAccelerationStructureNV-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkCreateAccelerationStructureNV-pCreateInfo-parameter
    pCreateInfo must be a valid pointer to a valid VkAccelerationStructureCreateInfoNV structure

  • VUID-vkCreateAccelerationStructureNV-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkCreateAccelerationStructureNV-pAccelerationStructure-parameter
    pAccelerationStructure must be a valid pointer to a VkAccelerationStructureNV handle

  • VUID-vkCreateAccelerationStructureNV-device-queuecount
    The device must have been created with at least 1 queue

Return Codes
Success
Failure

The VkAccelerationStructureCreateInfoNV structure is defined as:

// Provided by VK_NV_ray_tracing
typedef struct VkAccelerationStructureCreateInfoNV {
    VkStructureType                  sType;
    const void*                      pNext;
    VkDeviceSize                     compactedSize;
    VkAccelerationStructureInfoNV    info;
} VkAccelerationStructureCreateInfoNV;
Valid Usage

  • VUID-VkAccelerationStructureCreateInfoNV-compactedSize-02421
    If compactedSize is not 0 then both info.geometryCount and info.instanceCount must be 0

Valid Usage (Implicit)

The VkAccelerationStructureInfoNV structure is defined as:

// Provided by VK_NV_ray_tracing
typedef struct VkAccelerationStructureInfoNV {
    VkStructureType                        sType;
    const void*                            pNext;
    VkAccelerationStructureTypeNV          type;
    VkBuildAccelerationStructureFlagsNV    flags;
    uint32_t                               instanceCount;
    uint32_t                               geometryCount;
    const VkGeometryNV*                    pGeometries;
} VkAccelerationStructureInfoNV;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • type is a VkAccelerationStructureTypeNV value specifying the type of acceleration structure that will be created.

  • flags is a bitmask of VkBuildAccelerationStructureFlagBitsNV specifying additional parameters of the acceleration structure.

  • instanceCount specifies the number of instances that will be in the new acceleration structure.

  • geometryCount specifies the number of geometries that will be in the new acceleration structure.

  • pGeometries is a pointer to an array of geometryCount VkGeometryNV structures containing the scene data being passed into the acceleration structure.

VkAccelerationStructureInfoNV contains information that is used both for acceleration structure creation with vkCreateAccelerationStructureNV and in combination with the actual geometric data to build the acceleration structure with vkCmdBuildAccelerationStructureNV.

Valid Usage
Valid Usage (Implicit)

Values which can be set in VkAccelerationStructureCreateInfoKHR::type or VkAccelerationStructureInfoNV::type specifying the type of acceleration structure, are:

// Provided by VK_KHR_acceleration_structure
typedef enum VkAccelerationStructureTypeKHR {
    VK_ACCELERATION_STRUCTURE_TYPE_TOP_LEVEL_KHR = 0,
    VK_ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_KHR = 1,
    VK_ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR = 2,
  // Provided by VK_NV_ray_tracing
    VK_ACCELERATION_STRUCTURE_TYPE_TOP_LEVEL_NV = VK_ACCELERATION_STRUCTURE_TYPE_TOP_LEVEL_KHR,
  // Provided by VK_NV_ray_tracing
    VK_ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_NV = VK_ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_KHR,
} VkAccelerationStructureTypeKHR;
// Provided by VK_NV_ray_tracing
// Equivalent to VkAccelerationStructureTypeKHR
typedef VkAccelerationStructureTypeKHR VkAccelerationStructureTypeNV;

Bits which can be set in VkAccelerationStructureCreateInfoKHR::createFlags, specifying additional creation parameters for acceleration structures, are:

// Provided by VK_KHR_acceleration_structure
typedef enum VkAccelerationStructureCreateFlagBitsKHR {
    VK_ACCELERATION_STRUCTURE_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT_KHR = 0x00000001,
  // Provided by VK_EXT_descriptor_buffer
    VK_ACCELERATION_STRUCTURE_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXT = 0x00000008,
  // Provided by VK_NV_ray_tracing_motion_blur
    VK_ACCELERATION_STRUCTURE_CREATE_MOTION_BIT_NV = 0x00000004,
} VkAccelerationStructureCreateFlagBitsKHR;
// Provided by VK_KHR_acceleration_structure
typedef VkFlags VkAccelerationStructureCreateFlagsKHR;

VkAccelerationStructureCreateFlagsKHR is a bitmask type for setting a mask of zero or more VkAccelerationStructureCreateFlagBitsKHR.

Bits which can be set in VkAccelerationStructureBuildGeometryInfoKHR::flags or VkAccelerationStructureInfoNV::flags specifying additional parameters for acceleration structure builds, are:

// Provided by VK_KHR_acceleration_structure
typedef enum VkBuildAccelerationStructureFlagBitsKHR {
    VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_UPDATE_BIT_KHR = 0x00000001,
    VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_COMPACTION_BIT_KHR = 0x00000002,
    VK_BUILD_ACCELERATION_STRUCTURE_PREFER_FAST_TRACE_BIT_KHR = 0x00000004,
    VK_BUILD_ACCELERATION_STRUCTURE_PREFER_FAST_BUILD_BIT_KHR = 0x00000008,
    VK_BUILD_ACCELERATION_STRUCTURE_LOW_MEMORY_BIT_KHR = 0x00000010,
  // Provided by VK_NV_ray_tracing_motion_blur
    VK_BUILD_ACCELERATION_STRUCTURE_MOTION_BIT_NV = 0x00000020,
  // Provided by VK_EXT_opacity_micromap
    VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_OPACITY_MICROMAP_UPDATE_BIT_EXT = 0x00000040,
  // Provided by VK_EXT_opacity_micromap
    VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_DISABLE_OPACITY_MICROMAPS_BIT_EXT = 0x00000080,
  // Provided by VK_EXT_opacity_micromap
    VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_OPACITY_MICROMAP_DATA_UPDATE_BIT_EXT = 0x00000100,
#ifdef VK_ENABLE_BETA_EXTENSIONS
  // Provided by VK_NV_displacement_micromap
    VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_DISPLACEMENT_MICROMAP_UPDATE_BIT_NV = 0x00000200,
#endif
  // Provided by VK_KHR_ray_tracing_position_fetch
    VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_DATA_ACCESS_BIT_KHR = 0x00000800,
  // Provided by VK_NV_cluster_acceleration_structure
    VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_CLUSTER_OPACITY_MICROMAPS_BIT_NV = 0x00001000,
  // Provided by VK_NV_ray_tracing
    VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_UPDATE_BIT_NV = VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_UPDATE_BIT_KHR,
  // Provided by VK_NV_ray_tracing
    VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_COMPACTION_BIT_NV = VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_COMPACTION_BIT_KHR,
  // Provided by VK_NV_ray_tracing
    VK_BUILD_ACCELERATION_STRUCTURE_PREFER_FAST_TRACE_BIT_NV = VK_BUILD_ACCELERATION_STRUCTURE_PREFER_FAST_TRACE_BIT_KHR,
  // Provided by VK_NV_ray_tracing
    VK_BUILD_ACCELERATION_STRUCTURE_PREFER_FAST_BUILD_BIT_NV = VK_BUILD_ACCELERATION_STRUCTURE_PREFER_FAST_BUILD_BIT_KHR,
  // Provided by VK_NV_ray_tracing
    VK_BUILD_ACCELERATION_STRUCTURE_LOW_MEMORY_BIT_NV = VK_BUILD_ACCELERATION_STRUCTURE_LOW_MEMORY_BIT_KHR,
  // Provided by VK_EXT_opacity_micromap
  // VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_OPACITY_MICROMAP_UPDATE_EXT is a legacy alias
    VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_OPACITY_MICROMAP_UPDATE_EXT = VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_OPACITY_MICROMAP_UPDATE_BIT_EXT,
  // Provided by VK_EXT_opacity_micromap
  // VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_DISABLE_OPACITY_MICROMAPS_EXT is a legacy alias
    VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_DISABLE_OPACITY_MICROMAPS_EXT = VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_DISABLE_OPACITY_MICROMAPS_BIT_EXT,
  // Provided by VK_EXT_opacity_micromap
  // VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_OPACITY_MICROMAP_DATA_UPDATE_EXT is a legacy alias
    VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_OPACITY_MICROMAP_DATA_UPDATE_EXT = VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_OPACITY_MICROMAP_DATA_UPDATE_BIT_EXT,
#ifdef VK_ENABLE_BETA_EXTENSIONS
  // Provided by VK_NV_displacement_micromap
  // VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_DISPLACEMENT_MICROMAP_UPDATE_NV is a legacy alias
    VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_DISPLACEMENT_MICROMAP_UPDATE_NV = VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_DISPLACEMENT_MICROMAP_UPDATE_BIT_NV,
#endif
  // Provided by VK_KHR_ray_tracing_position_fetch
  // VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_DATA_ACCESS_KHR is a legacy alias
    VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_DATA_ACCESS_KHR = VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_DATA_ACCESS_BIT_KHR,
} VkBuildAccelerationStructureFlagBitsKHR;
// Provided by VK_NV_ray_tracing
// Equivalent to VkBuildAccelerationStructureFlagBitsKHR
typedef VkBuildAccelerationStructureFlagBitsKHR VkBuildAccelerationStructureFlagBitsNV;

VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_UPDATE_BIT_KHR and VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_COMPACTION_BIT_KHR may take more time and memory than a normal build, and so should only be used when those features are needed.

VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_UPDATE_BIT_KHR and VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_COMPACTION_BIT_KHR are allowed to be used together. In that case, the result of the compaction copy is used as the source of a build with mode of VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR to perform the compacted update.

 
// Provided by VK_KHR_acceleration_structure
typedef VkFlags VkBuildAccelerationStructureFlagsKHR;
// Provided by VK_NV_ray_tracing
// Equivalent to VkBuildAccelerationStructureFlagsKHR
typedef VkBuildAccelerationStructureFlagsKHR VkBuildAccelerationStructureFlagsNV;

VkBuildAccelerationStructureFlagsKHR is a bitmask type for setting a mask of zero or more VkBuildAccelerationStructureFlagBitsKHR.

The VkGeometryNV structure describes geometry in a bottom-level acceleration structure and is defined as:

// Provided by VK_NV_ray_tracing
typedef struct VkGeometryNV {
    VkStructureType       sType;
    const void*           pNext;
    VkGeometryTypeKHR     geometryType;
    VkGeometryDataNV      geometry;
    VkGeometryFlagsKHR    flags;
} VkGeometryNV;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • geometryType specifies the VkGeometryTypeKHR which this geometry refers to.

  • geometry contains the geometry data as described in VkGeometryDataNV.

  • flags has VkGeometryFlagBitsKHR describing options for this geometry.

Valid Usage
Valid Usage (Implicit)

Geometry types are specified by VkGeometryTypeKHR, which takes values:

// Provided by VK_KHR_acceleration_structure
typedef enum VkGeometryTypeKHR {
    VK_GEOMETRY_TYPE_TRIANGLES_KHR = 0,
    VK_GEOMETRY_TYPE_AABBS_KHR = 1,
    VK_GEOMETRY_TYPE_INSTANCES_KHR = 2,
  // Provided by VK_NV_ray_tracing_linear_swept_spheres
    VK_GEOMETRY_TYPE_SPHERES_NV = 1000429004,
  // Provided by VK_NV_ray_tracing_linear_swept_spheres
    VK_GEOMETRY_TYPE_LINEAR_SWEPT_SPHERES_NV = 1000429005,
#ifdef VK_ENABLE_BETA_EXTENSIONS
  // Provided by VK_AMDX_dense_geometry_format
    VK_GEOMETRY_TYPE_DENSE_GEOMETRY_FORMAT_TRIANGLES_AMDX = 1000478000,
#endif
  // Provided by VK_NV_ray_tracing
    VK_GEOMETRY_TYPE_TRIANGLES_NV = VK_GEOMETRY_TYPE_TRIANGLES_KHR,
  // Provided by VK_NV_ray_tracing
    VK_GEOMETRY_TYPE_AABBS_NV = VK_GEOMETRY_TYPE_AABBS_KHR,
} VkGeometryTypeKHR;
// Provided by VK_NV_ray_tracing
// Equivalent to VkGeometryTypeKHR
typedef VkGeometryTypeKHR VkGeometryTypeNV;

Bits specifying additional parameters for geometries in acceleration structure builds, are:

// Provided by VK_KHR_acceleration_structure
typedef enum VkGeometryFlagBitsKHR {
    VK_GEOMETRY_OPAQUE_BIT_KHR = 0x00000001,
    VK_GEOMETRY_NO_DUPLICATE_ANY_HIT_INVOCATION_BIT_KHR = 0x00000002,
  // Provided by VK_NV_ray_tracing
    VK_GEOMETRY_OPAQUE_BIT_NV = VK_GEOMETRY_OPAQUE_BIT_KHR,
  // Provided by VK_NV_ray_tracing
    VK_GEOMETRY_NO_DUPLICATE_ANY_HIT_INVOCATION_BIT_NV = VK_GEOMETRY_NO_DUPLICATE_ANY_HIT_INVOCATION_BIT_KHR,
} VkGeometryFlagBitsKHR;
// Provided by VK_NV_ray_tracing
// Equivalent to VkGeometryFlagBitsKHR
typedef VkGeometryFlagBitsKHR VkGeometryFlagBitsNV;

  • VK_GEOMETRY_OPAQUE_BIT_KHR specifies that this geometry does not invoke the any-hit shaders even if present in a hit group.

  • VK_GEOMETRY_NO_DUPLICATE_ANY_HIT_INVOCATION_BIT_KHR specifies that the implementation must only call the any-hit shader a single time for each primitive in this geometry. If this bit is absent an implementation may invoke the any-hit shader more than once for this geometry.

// Provided by VK_KHR_acceleration_structure
typedef VkFlags VkGeometryFlagsKHR;
// Provided by VK_NV_ray_tracing
// Equivalent to VkGeometryFlagsKHR
typedef VkGeometryFlagsKHR VkGeometryFlagsNV;

VkGeometryFlagsKHR is a bitmask type for setting a mask of zero or more VkGeometryFlagBitsKHR.

The VkGeometryDataNV structure specifies geometry in a bottom-level acceleration structure and is defined as:

// Provided by VK_NV_ray_tracing
typedef struct VkGeometryDataNV {
    VkGeometryTrianglesNV    triangles;
    VkGeometryAABBNV         aabbs;
} VkGeometryDataNV;
Valid Usage (Implicit)

  • VUID-VkGeometryDataNV-triangles-parameter
    triangles must be a valid VkGeometryTrianglesNV structure

  • VUID-VkGeometryDataNV-aabbs-parameter
    aabbs must be a valid VkGeometryAABBNV structure

The VkGeometryTrianglesNV structure specifies triangle geometry in a bottom-level acceleration structure and is defined as:

// Provided by VK_NV_ray_tracing
typedef struct VkGeometryTrianglesNV {
    VkStructureType    sType;
    const void*        pNext;
    VkBuffer           vertexData;
    VkDeviceSize       vertexOffset;
    uint32_t           vertexCount;
    VkDeviceSize       vertexStride;
    VkFormat           vertexFormat;
    VkBuffer           indexData;
    VkDeviceSize       indexOffset;
    uint32_t           indexCount;
    VkIndexType        indexType;
    VkBuffer           transformData;
    VkDeviceSize       transformOffset;
} VkGeometryTrianglesNV;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • vertexData is the buffer containing vertex data for this geometry.

  • vertexOffset is the offset in bytes within vertexData containing vertex data for this geometry.

  • vertexCount is the number of valid vertices.

  • vertexStride is the stride in bytes between each vertex.

  • vertexFormat is a VkFormat describing the format of each vertex element.

  • indexData is the buffer containing index data for this geometry.

  • indexOffset is the offset in bytes within indexData containing index data for this geometry.

  • indexCount is the number of indices to include in this geometry.

  • indexType is a VkIndexType describing the format of each index.

  • transformData is an optional buffer containing an VkTransformMatrixNV structure defining a transformation to be applied to this geometry.

  • transformOffset is the offset in bytes in transformData of the transform information described above.

If indexType is VK_INDEX_TYPE_NONE_NV, then this structure describes a set of triangles determined by vertexCount. Otherwise, this structure describes a set of indexed triangles determined by indexCount.

Valid Usage

  • VUID-VkGeometryTrianglesNV-vertexOffset-02428
    vertexOffset must be less than the size of vertexData

  • VUID-VkGeometryTrianglesNV-vertexOffset-02429
    vertexOffset must be a multiple of the component size of vertexFormat

  • VUID-VkGeometryTrianglesNV-vertexFormat-02430
    vertexFormat must be one of VK_FORMAT_R32G32B32_SFLOAT, VK_FORMAT_R32G32_SFLOAT, VK_FORMAT_R16G16B16_SFLOAT, VK_FORMAT_R16G16_SFLOAT, VK_FORMAT_R16G16_SNORM, or VK_FORMAT_R16G16B16_SNORM

  • VUID-VkGeometryTrianglesNV-vertexStride-03818
    vertexStride must be less than or equal to 232-1

  • VUID-VkGeometryTrianglesNV-indexOffset-02431
    indexOffset must be less than the size of indexData

  • VUID-VkGeometryTrianglesNV-indexOffset-02432
    indexOffset must be a multiple of the element size of indexType

  • VUID-VkGeometryTrianglesNV-indexType-02433
    indexType must be VK_INDEX_TYPE_UINT16, VK_INDEX_TYPE_UINT32, or VK_INDEX_TYPE_NONE_NV

  • VUID-VkGeometryTrianglesNV-indexData-02434
    indexData must be VK_NULL_HANDLE if indexType is VK_INDEX_TYPE_NONE_NV

  • VUID-VkGeometryTrianglesNV-indexData-02435
    indexData must be a valid VkBuffer handle if indexType is not VK_INDEX_TYPE_NONE_NV

  • VUID-VkGeometryTrianglesNV-indexCount-02436
    indexCount must be 0 if indexType is VK_INDEX_TYPE_NONE_NV

  • VUID-VkGeometryTrianglesNV-transformOffset-02437
    transformOffset must be less than the size of transformData

  • VUID-VkGeometryTrianglesNV-transformOffset-02438
    transformOffset must be a multiple of 16

Valid Usage (Implicit)

  • VUID-VkGeometryTrianglesNV-sType-sType
    sType must be VK_STRUCTURE_TYPE_GEOMETRY_TRIANGLES_NV

  • VUID-VkGeometryTrianglesNV-pNext-pNext
    pNext must be NULL

  • VUID-VkGeometryTrianglesNV-vertexData-parameter
    If vertexData is not VK_NULL_HANDLE, vertexData must be a valid VkBuffer handle

  • VUID-VkGeometryTrianglesNV-vertexFormat-parameter
    vertexFormat must be a valid VkFormat value

  • VUID-VkGeometryTrianglesNV-indexData-parameter
    If indexData is not VK_NULL_HANDLE, indexData must be a valid VkBuffer handle

  • VUID-VkGeometryTrianglesNV-indexType-parameter
    indexType must be a valid VkIndexType value

  • VUID-VkGeometryTrianglesNV-transformData-parameter
    If transformData is not VK_NULL_HANDLE, transformData must be a valid VkBuffer handle

  • VUID-VkGeometryTrianglesNV-commonparent
    Each of indexData, transformData, and vertexData that are valid handles of non-ignored parameters must have been created, allocated, or retrieved from the same VkDevice

The VkGeometryAABBNV structure specifies axis-aligned bounding box geometry in a bottom-level acceleration structure, and is defined as:

// Provided by VK_NV_ray_tracing
typedef struct VkGeometryAABBNV {
    VkStructureType    sType;
    const void*        pNext;
    VkBuffer           aabbData;
    uint32_t           numAABBs;
    uint32_t           stride;
    VkDeviceSize       offset;
} VkGeometryAABBNV;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • aabbData is the buffer containing axis-aligned bounding box data.

  • numAABBs is the number of AABBs in this geometry.

  • stride is the stride in bytes between AABBs in aabbData.

  • offset is the offset in bytes of the first AABB in aabbData.

The AABB data in memory is six 32-bit floats consisting of the minimum x, y, and z values followed by the maximum x, y, and z values.

Valid Usage

  • VUID-VkGeometryAABBNV-offset-02439
    offset must be less than the size of aabbData

  • VUID-VkGeometryAABBNV-offset-02440
    offset must be a multiple of 8

  • VUID-VkGeometryAABBNV-stride-02441
    stride must be a multiple of 8

Valid Usage (Implicit)

To destroy an acceleration structure, call:

// Provided by VK_KHR_acceleration_structure
void vkDestroyAccelerationStructureKHR(
    VkDevice                                    device,
    VkAccelerationStructureKHR                  accelerationStructure,
    const VkAllocationCallbacks*                pAllocator);

  • device is the logical device that destroys the acceleration structure.

  • accelerationStructure is the acceleration structure to destroy.

  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

Valid Usage

  • VUID-vkDestroyAccelerationStructureKHR-accelerationStructure-08934
    The VkPhysicalDeviceAccelerationStructureFeaturesKHR::accelerationStructure feature must be enabled

  • VUID-vkDestroyAccelerationStructureKHR-accelerationStructure-02442
    All submitted commands that refer to accelerationStructure must have completed execution

  • VUID-vkDestroyAccelerationStructureKHR-accelerationStructure-02443
    If VkAllocationCallbacks were provided when accelerationStructure was created, a compatible set of callbacks must be provided here

  • VUID-vkDestroyAccelerationStructureKHR-accelerationStructure-02444
    If no VkAllocationCallbacks were provided when accelerationStructure was created, pAllocator must be NULL

Valid Usage (Implicit)

  • VUID-vkDestroyAccelerationStructureKHR-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkDestroyAccelerationStructureKHR-accelerationStructure-parameter
    If accelerationStructure is not VK_NULL_HANDLE, accelerationStructure must be a valid VkAccelerationStructureKHR handle

  • VUID-vkDestroyAccelerationStructureKHR-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkDestroyAccelerationStructureKHR-accelerationStructure-parent
    If accelerationStructure is a valid handle, it must have been created, allocated, or retrieved from device

Host Synchronization

  • Host access to accelerationStructure must be externally synchronized

To destroy an acceleration structure, call:

// Provided by VK_NV_ray_tracing
void vkDestroyAccelerationStructureNV(
    VkDevice                                    device,
    VkAccelerationStructureNV                   accelerationStructure,
    const VkAllocationCallbacks*                pAllocator);

  • device is the logical device that destroys the buffer.

  • accelerationStructure is the acceleration structure to destroy.

  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

Valid Usage

  • VUID-vkDestroyAccelerationStructureNV-accelerationStructure-03752
    All submitted commands that refer to accelerationStructure must have completed execution

  • VUID-vkDestroyAccelerationStructureNV-accelerationStructure-03753
    If VkAllocationCallbacks were provided when accelerationStructure was created, a compatible set of callbacks must be provided here

  • VUID-vkDestroyAccelerationStructureNV-accelerationStructure-03754
    If no VkAllocationCallbacks were provided when accelerationStructure was created, pAllocator must be NULL

Valid Usage (Implicit)

  • VUID-vkDestroyAccelerationStructureNV-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkDestroyAccelerationStructureNV-accelerationStructure-parameter
    If accelerationStructure is not VK_NULL_HANDLE, accelerationStructure must be a valid VkAccelerationStructureNV handle

  • VUID-vkDestroyAccelerationStructureNV-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkDestroyAccelerationStructureNV-accelerationStructure-parent
    If accelerationStructure is a valid handle, it must have been created, allocated, or retrieved from device

Host Synchronization

  • Host access to accelerationStructure must be externally synchronized

An acceleration structure has memory requirements for the structure object itself, scratch space for the build, and scratch space for the update.

Scratch space is allocated as a VkBuffer, so for VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_BUILD_SCRATCH_NV and VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_UPDATE_SCRATCH_NV the pMemoryRequirements->alignment and pMemoryRequirements->memoryTypeBits values returned by this call must be filled with zero, and should be ignored by the application.

To query the memory requirements, call:

// Provided by VK_NV_ray_tracing
void vkGetAccelerationStructureMemoryRequirementsNV(
    VkDevice                                    device,
    const VkAccelerationStructureMemoryRequirementsInfoNV* pInfo,
    VkMemoryRequirements2KHR*                   pMemoryRequirements);

  • device is the logical device on which the acceleration structure was created.

  • pInfo is a pointer to a VkAccelerationStructureMemoryRequirementsInfoNV structure specifying the acceleration structure to get memory requirements for.

  • pMemoryRequirements is a pointer to a VkMemoryRequirements2KHR structure in which the requested acceleration structure memory requirements are returned.

Valid Usage (Implicit)

  • VUID-vkGetAccelerationStructureMemoryRequirementsNV-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetAccelerationStructureMemoryRequirementsNV-pInfo-parameter
    pInfo must be a valid pointer to a valid VkAccelerationStructureMemoryRequirementsInfoNV structure

  • VUID-vkGetAccelerationStructureMemoryRequirementsNV-pMemoryRequirements-parameter
    pMemoryRequirements must be a valid pointer to a VkMemoryRequirements2KHR structure

The VkAccelerationStructureMemoryRequirementsInfoNV structure is defined as:

// Provided by VK_NV_ray_tracing
typedef struct VkAccelerationStructureMemoryRequirementsInfoNV {
    VkStructureType                                    sType;
    const void*                                        pNext;
    VkAccelerationStructureMemoryRequirementsTypeNV    type;
    VkAccelerationStructureNV                          accelerationStructure;
} VkAccelerationStructureMemoryRequirementsInfoNV;
Valid Usage (Implicit)

Possible values of type in VkAccelerationStructureMemoryRequirementsInfoNV are:,

// Provided by VK_NV_ray_tracing
typedef enum VkAccelerationStructureMemoryRequirementsTypeNV {
    VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_OBJECT_NV = 0,
    VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_BUILD_SCRATCH_NV = 1,
    VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_UPDATE_SCRATCH_NV = 2,
} VkAccelerationStructureMemoryRequirementsTypeNV;

Possible values of buildType in vkGetAccelerationStructureBuildSizesKHR are:

// Provided by VK_KHR_acceleration_structure
typedef enum VkAccelerationStructureBuildTypeKHR {
    VK_ACCELERATION_STRUCTURE_BUILD_TYPE_HOST_KHR = 0,
    VK_ACCELERATION_STRUCTURE_BUILD_TYPE_DEVICE_KHR = 1,
    VK_ACCELERATION_STRUCTURE_BUILD_TYPE_HOST_OR_DEVICE_KHR = 2,
} VkAccelerationStructureBuildTypeKHR;

To attach memory to one or more acceleration structures at a time, call:

// Provided by VK_NV_ray_tracing
VkResult vkBindAccelerationStructureMemoryNV(
    VkDevice                                    device,
    uint32_t                                    bindInfoCount,
    const VkBindAccelerationStructureMemoryInfoNV* pBindInfos);

  • device is the logical device that owns the acceleration structures and memory.

  • bindInfoCount is the number of elements in pBindInfos.

  • pBindInfos is a pointer to an array of VkBindAccelerationStructureMemoryInfoNV structures describing acceleration structures and memory to bind.

Valid Usage (Implicit)

  • VUID-vkBindAccelerationStructureMemoryNV-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkBindAccelerationStructureMemoryNV-pBindInfos-parameter
    pBindInfos must be a valid pointer to an array of bindInfoCount valid VkBindAccelerationStructureMemoryInfoNV structures

  • VUID-vkBindAccelerationStructureMemoryNV-bindInfoCount-arraylength
    bindInfoCount must be greater than 0

Return Codes
Success
Failure

The VkBindAccelerationStructureMemoryInfoNV structure is defined as:

// Provided by VK_NV_ray_tracing
typedef struct VkBindAccelerationStructureMemoryInfoNV {
    VkStructureType              sType;
    const void*                  pNext;
    VkAccelerationStructureNV    accelerationStructure;
    VkDeviceMemory               memory;
    VkDeviceSize                 memoryOffset;
    uint32_t                     deviceIndexCount;
    const uint32_t*              pDeviceIndices;
} VkBindAccelerationStructureMemoryInfoNV;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • accelerationStructure is the acceleration structure to be attached to memory.

  • memory is a VkDeviceMemory object describing the device memory to attach.

  • memoryOffset is the start offset of the region of memory that is to be bound to the acceleration structure. The number of bytes returned in the VkMemoryRequirements::size member in memory, starting from memoryOffset bytes, will be bound to the specified acceleration structure.

  • deviceIndexCount is the number of elements in pDeviceIndices.

  • pDeviceIndices is a pointer to an array of device indices.

Valid Usage
Valid Usage (Implicit)

  • VUID-VkBindAccelerationStructureMemoryInfoNV-sType-sType
    sType must be VK_STRUCTURE_TYPE_BIND_ACCELERATION_STRUCTURE_MEMORY_INFO_NV

  • VUID-VkBindAccelerationStructureMemoryInfoNV-pNext-pNext
    pNext must be NULL

  • VUID-VkBindAccelerationStructureMemoryInfoNV-accelerationStructure-parameter
    accelerationStructure must be a valid VkAccelerationStructureNV handle

  • VUID-VkBindAccelerationStructureMemoryInfoNV-memory-parameter
    memory must be a valid VkDeviceMemory handle

  • VUID-VkBindAccelerationStructureMemoryInfoNV-pDeviceIndices-parameter
    If deviceIndexCount is not 0, pDeviceIndices must be a valid pointer to an array of deviceIndexCount uint32_t values

  • VUID-VkBindAccelerationStructureMemoryInfoNV-commonparent
    Both of accelerationStructure, and memory must have been created, allocated, or retrieved from the same VkDevice

To allow constructing geometry instances with device code if desired, we need to be able to query an opaque handle for an acceleration structure. This handle is a value of 8 bytes. To get this handle, call:

// Provided by VK_NV_ray_tracing
VkResult vkGetAccelerationStructureHandleNV(
    VkDevice                                    device,
    VkAccelerationStructureNV                   accelerationStructure,
    size_t                                      dataSize,
    void*                                       pData);

  • device is the logical device that owns the acceleration structures.

  • accelerationStructure is the acceleration structure.

  • dataSize is the size in bytes of the buffer pointed to by pData.

  • pData is a pointer to an application-allocated buffer where the results will be written.

Valid Usage

  • VUID-vkGetAccelerationStructureHandleNV-dataSize-02240
    dataSize must be large enough to contain the result of the query, as described above

  • VUID-vkGetAccelerationStructureHandleNV-accelerationStructure-02787
    accelerationStructure must be bound completely and contiguously to a single VkDeviceMemory object via vkBindAccelerationStructureMemoryNV

Valid Usage (Implicit)

  • VUID-vkGetAccelerationStructureHandleNV-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetAccelerationStructureHandleNV-accelerationStructure-parameter
    accelerationStructure must be a valid VkAccelerationStructureNV handle

  • VUID-vkGetAccelerationStructureHandleNV-pData-parameter
    pData must be a valid pointer to an array of dataSize bytes

  • VUID-vkGetAccelerationStructureHandleNV-dataSize-arraylength
    dataSize must be greater than 0

  • VUID-vkGetAccelerationStructureHandleNV-accelerationStructure-parent
    accelerationStructure must have been created, allocated, or retrieved from device

Return Codes
Success
Failure

To query the 64-bit device address for an acceleration structure, call:

// Provided by VK_KHR_acceleration_structure
VkDeviceAddress vkGetAccelerationStructureDeviceAddressKHR(
    VkDevice                                    device,
    const VkAccelerationStructureDeviceAddressInfoKHR* pInfo);

  • device is the logical device that the acceleration structure was created on.

  • pInfo is a pointer to a VkAccelerationStructureDeviceAddressInfoKHR structure specifying the acceleration structure to retrieve an address for.

The 64-bit return value is an address of the acceleration structure, which can be used for device and shader operations that involve acceleration structures, such as ray traversal and acceleration structure building.

If the acceleration structure was created with a non-zero value of VkAccelerationStructureCreateInfoKHR::deviceAddress, the return value will be the same address.

If the acceleration structure was created with a type of VK_ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR, the returned address must be consistent with the relative offset to other acceleration structures with type VK_ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR allocated with the same VkBuffer. That is, the difference in returned addresses between the two must be the same as the difference in offsets provided at acceleration structure creation.

The returned address must be aligned to 256 bytes.

The acceleration structure device address may be different from the buffer device address corresponding to the acceleration structure’s start offset in its storage buffer for acceleration structure types other than VK_ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR.
Valid Usage

  • VUID-vkGetAccelerationStructureDeviceAddressKHR-accelerationStructure-08935
    The VkPhysicalDeviceAccelerationStructureFeaturesKHR::accelerationStructure feature must be enabled

  • VUID-vkGetAccelerationStructureDeviceAddressKHR-device-03504
    If device was created with multiple physical devices, then the bufferDeviceAddressMultiDevice feature must be enabled

  • VUID-vkGetAccelerationStructureDeviceAddressKHR-pInfo-09541
    If the buffer on which pInfo->accelerationStructure was placed is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-vkGetAccelerationStructureDeviceAddressKHR-pInfo-09542
    The buffer on which pInfo->accelerationStructure was placed must have been created with the VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT usage flag set

Valid Usage (Implicit)

  • VUID-vkGetAccelerationStructureDeviceAddressKHR-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetAccelerationStructureDeviceAddressKHR-pInfo-parameter
    pInfo must be a valid pointer to a valid VkAccelerationStructureDeviceAddressInfoKHR structure

The VkAccelerationStructureDeviceAddressInfoKHR structure is defined as:

// Provided by VK_KHR_acceleration_structure
typedef struct VkAccelerationStructureDeviceAddressInfoKHR {
    VkStructureType               sType;
    const void*                   pNext;
    VkAccelerationStructureKHR    accelerationStructure;
} VkAccelerationStructureDeviceAddressInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • accelerationStructure specifies the acceleration structure whose address is being queried.

Valid Usage (Implicit)

Micromaps

Micromaps are opaque data structures that are built by the implementation to encode sub-triangle data to be included in an acceleration structure.

Micromaps are represented by VkMicromapEXT handles:

// Provided by VK_EXT_opacity_micromap
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkMicromapEXT)

To create a micromap, call:

// Provided by VK_EXT_opacity_micromap
VkResult vkCreateMicromapEXT(
    VkDevice                                    device,
    const VkMicromapCreateInfoEXT*              pCreateInfo,
    const VkAllocationCallbacks*                pAllocator,
    VkMicromapEXT*                              pMicromap);

  • device is the logical device that creates the micromap object.

  • pCreateInfo is a pointer to a VkMicromapCreateInfoEXT structure containing parameters affecting creation of the micromap.

  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

  • pMicromap is a pointer to a VkMicromapEXT handle in which the resulting micromap object is returned.

Similar to other objects in Vulkan, the micromap creation merely creates an object with a specific “shape”. The type and quantity of geometry that can be built into a micromap is determined by the parameters of VkMicromapCreateInfoEXT.

The micromap data is stored in the object referred to by VkMicromapCreateInfoEXT::buffer. Once memory has been bound to that buffer, it must be populated by micromap build or micromap copy commands such as vkCmdBuildMicromapsEXT, vkBuildMicromapsEXT, vkCmdCopyMicromapEXT, and vkCopyMicromapEXT.

The expected usage for a trace capture/replay tool is that it will serialize and later deserialize the micromap data using micromap copy commands. During capture the tool will use vkCopyMicromapToMemoryEXT or vkCmdCopyMicromapToMemoryEXT with a mode of VK_COPY_MICROMAP_MODE_SERIALIZE_EXT, and vkCopyMemoryToMicromapEXT or vkCmdCopyMemoryToMicromapEXT with a mode of VK_COPY_MICROMAP_MODE_DESERIALIZE_EXT during replay.

The input buffers passed to micromap build commands will be referenced by the implementation for the duration of the command. Micromaps must be fully self-contained. The application can reuse or free any memory which was used by the command as an input or as scratch without affecting the results of a subsequent acceleration structure build using the micromap or traversal of that acceleration structure.

Valid Usage
Valid Usage (Implicit)

  • VUID-vkCreateMicromapEXT-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkCreateMicromapEXT-pCreateInfo-parameter
    pCreateInfo must be a valid pointer to a valid VkMicromapCreateInfoEXT structure

  • VUID-vkCreateMicromapEXT-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkCreateMicromapEXT-pMicromap-parameter
    pMicromap must be a valid pointer to a VkMicromapEXT handle

  • VUID-vkCreateMicromapEXT-device-queuecount
    The device must have been created with at least 1 queue

Return Codes
Success
Failure

The VkMicromapCreateInfoEXT structure is defined as:

// Provided by VK_EXT_opacity_micromap
typedef struct VkMicromapCreateInfoEXT {
    VkStructureType             sType;
    const void*                 pNext;
    VkMicromapCreateFlagsEXT    createFlags;
    VkBuffer                    buffer;
    VkDeviceSize                offset;
    VkDeviceSize                size;
    VkMicromapTypeEXT           type;
    VkDeviceAddress             deviceAddress;
} VkMicromapCreateInfoEXT;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • createFlags is a bitmask of VkMicromapCreateFlagBitsEXT specifying additional creation parameters of the micromap.

  • buffer is the buffer on which the micromap will be stored.

  • offset is an offset in bytes from the base address of the buffer at which the micromap will be stored, and must be a multiple of 256.

  • size is the size required for the micromap.

  • type is a VkMicromapTypeEXT value specifying the type of micromap that will be created.

  • deviceAddress is the device address requested for the micromap if the micromapCaptureReplay feature is being used.

If deviceAddress is zero, no specific address is requested.

If deviceAddress is not zero, deviceAddress must be an address retrieved from an identically created micromap on the same implementation. The micromap must also be placed on an identically created buffer and at the same offset.

Applications should avoid creating micromaps with application-provided addresses and implementation-provided addresses in the same process, to reduce the likelihood of VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS_KHR errors.

The expected usage for this is that a trace capture/replay tool will add the VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT flag to all buffers that use VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT, and will add VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT to all buffers used as storage for a micromap where deviceAddress is not zero. This also means that the tool will need to add VK_MEMORY_ALLOCATE_DEVICE_ADDRESS_BIT to memory allocations to allow the flag to be set where the application may not have otherwise required it. During capture the tool will save the queried opaque device addresses in the trace. During replay, the buffers will be created specifying the original address so any address values stored in the trace data will remain valid.

Implementations are expected to separate such buffers in the GPU address space so normal allocations will avoid using these addresses. Applications and tools should avoid mixing application-provided and implementation-provided addresses for buffers created with VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT, to avoid address space allocation conflicts.

If the micromap will be the target of a build operation, the required size for a micromap can be queried with vkGetMicromapBuildSizesEXT.

Valid Usage
Valid Usage (Implicit)

  • VUID-VkMicromapCreateInfoEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_MICROMAP_CREATE_INFO_EXT

  • VUID-VkMicromapCreateInfoEXT-pNext-pNext
    pNext must be NULL

  • VUID-VkMicromapCreateInfoEXT-createFlags-parameter
    createFlags must be a valid combination of VkMicromapCreateFlagBitsEXT values

  • VUID-VkMicromapCreateInfoEXT-buffer-parameter
    buffer must be a valid VkBuffer handle

  • VUID-VkMicromapCreateInfoEXT-type-parameter
    type must be a valid VkMicromapTypeEXT value

  • VUID-VkMicromapCreateInfoEXT-deviceAddress-parameter
    If deviceAddress is not 0, deviceAddress must be a valid VkDeviceAddress value

To get the build sizes for a micromap, call:

// Provided by VK_EXT_opacity_micromap
void vkGetMicromapBuildSizesEXT(
    VkDevice                                    device,
    VkAccelerationStructureBuildTypeKHR         buildType,
    const VkMicromapBuildInfoEXT*               pBuildInfo,
    VkMicromapBuildSizesInfoEXT*                pSizeInfo);

  • device is the logical device that will be used for creating the micromap.

  • buildType defines whether host or device operations (or both) are being queried for.

  • pBuildInfo is a pointer to a VkMicromapBuildInfoEXT structure describing parameters of a build operation.

  • pSizeInfo is a pointer to a VkMicromapBuildSizesInfoEXT structure which returns the size required for a micromap and the sizes required for the scratch buffers, given the build parameters. The size requirements for a scratch buffer may be zero.

The dstMicromap and mode members of pBuildInfo are ignored. Any VkDeviceOrHostAddressKHR members of pBuildInfo are ignored by this command.

A micromap created with the micromapSize returned by this command supports any build with a VkMicromapBuildInfoEXT structure subject to the following properties:

Similarly, the buildScratchSize value will support any build command specifying the VK_BUILD_MICROMAP_MODE_BUILD_EXT mode under the above conditions.

Valid Usage

  • VUID-vkGetMicromapBuildSizesEXT-dstMicromap-09180
    VkMicromapBuildInfoEXT::dstMicromap must have been created from device

  • VUID-vkGetMicromapBuildSizesEXT-micromap-07439
    The micromap feature must be enabled

  • VUID-vkGetMicromapBuildSizesEXT-device-07440
    If device was created with multiple physical devices, then the bufferDeviceAddressMultiDevice feature must be enabled

Valid Usage (Implicit)

  • VUID-vkGetMicromapBuildSizesEXT-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetMicromapBuildSizesEXT-buildType-parameter
    buildType must be a valid VkAccelerationStructureBuildTypeKHR value

  • VUID-vkGetMicromapBuildSizesEXT-pBuildInfo-parameter
    pBuildInfo must be a valid pointer to a valid VkMicromapBuildInfoEXT structure

  • VUID-vkGetMicromapBuildSizesEXT-pSizeInfo-parameter
    pSizeInfo must be a valid pointer to a VkMicromapBuildSizesInfoEXT structure

The VkMicromapBuildSizesInfoEXT structure describes the required build sizes for a micromap and scratch buffers and is defined as:

// Provided by VK_EXT_opacity_micromap
typedef struct VkMicromapBuildSizesInfoEXT {
    VkStructureType    sType;
    const void*        pNext;
    VkDeviceSize       micromapSize;
    VkDeviceSize       buildScratchSize;
    VkBool32           discardable;
} VkMicromapBuildSizesInfoEXT;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • micromapSize is the size in bytes required in a VkMicromapEXT for a build or update operation.

  • buildScratchSize is the size in bytes required in a scratch buffer for a build operation.

  • discardable indicates whether or not the micromap object may be destroyed after an acceleration structure build or update. A false value means that acceleration structures built with this micromap may contain references to the data contained therein, and the application must not destroy the micromap until ray traversal has concluded. A true value means that the information in the micromap will be copied by value into the acceleration structure, and the micromap may be destroyed after the acceleration structure build concludes.

Valid Usage (Implicit)

Values which can be set in VkMicromapCreateInfoEXT::type specifying the type of micromap, are:

// Provided by VK_EXT_opacity_micromap
typedef enum VkMicromapTypeEXT {
    VK_MICROMAP_TYPE_OPACITY_MICROMAP_EXT = 0,
#ifdef VK_ENABLE_BETA_EXTENSIONS
  // Provided by VK_NV_displacement_micromap
    VK_MICROMAP_TYPE_DISPLACEMENT_MICROMAP_NV = 1000397000,
#endif
} VkMicromapTypeEXT;

Bits which can be set in VkMicromapCreateInfoEXT::createFlags, specifying additional creation parameters for micromaps, are:

// Provided by VK_EXT_opacity_micromap
typedef enum VkMicromapCreateFlagBitsEXT {
    VK_MICROMAP_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT_EXT = 0x00000001,
} VkMicromapCreateFlagBitsEXT;
// Provided by VK_EXT_opacity_micromap
typedef VkFlags VkMicromapCreateFlagsEXT;

VkMicromapCreateFlagsEXT is a bitmask type for setting a mask of zero or more VkMicromapCreateFlagBitsEXT.

Bits which can be set in VkMicromapBuildInfoEXT::flags specifying additional parameters for micromap builds, are:

// Provided by VK_EXT_opacity_micromap
typedef enum VkBuildMicromapFlagBitsEXT {
    VK_BUILD_MICROMAP_PREFER_FAST_TRACE_BIT_EXT = 0x00000001,
    VK_BUILD_MICROMAP_PREFER_FAST_BUILD_BIT_EXT = 0x00000002,
    VK_BUILD_MICROMAP_ALLOW_COMPACTION_BIT_EXT = 0x00000004,
} VkBuildMicromapFlagBitsEXT;
// Provided by VK_EXT_opacity_micromap
typedef VkFlags VkBuildMicromapFlagsEXT;

VkBuildMicromapFlagsEXT is a bitmask type for setting a mask of zero or more VkBuildMicromapFlagBitsEXT.

To destroy a micromap, call:

// Provided by VK_EXT_opacity_micromap
void vkDestroyMicromapEXT(
    VkDevice                                    device,
    VkMicromapEXT                               micromap,
    const VkAllocationCallbacks*                pAllocator);

  • device is the logical device that destroys the micromap.

  • micromap is the micromap to destroy.

  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

Valid Usage

  • VUID-vkDestroyMicromapEXT-micromap-10382
    The micromap feature must be enabled

  • VUID-vkDestroyMicromapEXT-micromap-07441
    All submitted commands that refer to micromap must have completed execution

  • VUID-vkDestroyMicromapEXT-micromap-07442
    If VkAllocationCallbacks were provided when micromap was created, a compatible set of callbacks must be provided here

  • VUID-vkDestroyMicromapEXT-micromap-07443
    If no VkAllocationCallbacks were provided when micromap was created, pAllocator must be NULL

Valid Usage (Implicit)

  • VUID-vkDestroyMicromapEXT-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkDestroyMicromapEXT-micromap-parameter
    If micromap is not VK_NULL_HANDLE, micromap must be a valid VkMicromapEXT handle

  • VUID-vkDestroyMicromapEXT-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkDestroyMicromapEXT-micromap-parent
    If micromap is a valid handle, it must have been created, allocated, or retrieved from device

Host Synchronization

  • Host access to micromap must be externally synchronized

Resource Memory Association

Resources are initially created as virtual allocations with no backing memory. Device memory is allocated separately (see Device Memory) and then associated with the resource. This association is done differently for sparse and non-sparse resources.

Resources created with any of the sparse creation flags are considered sparse resources. Resources created without these flags are non-sparse. The details on resource memory association for sparse resources is described in Sparse Resources.

Non-sparse resources must be bound completely and contiguously to a single VkDeviceMemory object before the resource is passed as a parameter to any of the following operations:

  • creating buffer, image, or tensor views

  • updating descriptor sets

  • recording commands in a command buffer

Once bound, the memory binding is immutable for the lifetime of the resource.

In a logical device representing more than one physical device, buffer and image resources exist on all physical devices but can be bound to memory differently on each. Each such replicated resource is an instance of the resource. For sparse resources, each instance can be bound to memory arbitrarily differently. For non-sparse resources, each instance can either be bound to the local or a peer instance of the memory, or for images can be bound to rectangular regions from the local and/or peer instances. When a resource is used in a descriptor set, each physical device interprets the descriptor according to its own instance’s binding to memory.

There are no new copy commands to transfer data between physical devices. Instead, an application can create a resource with a peer mapping and use it as the source or destination of a transfer command executed by a single physical device to copy the data from one physical device to another.

To determine the memory requirements for a buffer resource, call:

// Provided by VK_VERSION_1_0
void vkGetBufferMemoryRequirements(
    VkDevice                                    device,
    VkBuffer                                    buffer,
    VkMemoryRequirements*                       pMemoryRequirements);

  • device is the logical device that owns the buffer.

  • buffer is the buffer to query.

  • pMemoryRequirements is a pointer to a VkMemoryRequirements structure in which the memory requirements of the buffer object are returned.

Valid Usage (Implicit)

  • VUID-vkGetBufferMemoryRequirements-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetBufferMemoryRequirements-buffer-parameter
    buffer must be a valid VkBuffer handle

  • VUID-vkGetBufferMemoryRequirements-pMemoryRequirements-parameter
    pMemoryRequirements must be a valid pointer to a VkMemoryRequirements structure

  • VUID-vkGetBufferMemoryRequirements-buffer-parent
    buffer must have been created, allocated, or retrieved from device

To determine the memory requirements for an image resource which is not created with the VK_IMAGE_CREATE_DISJOINT_BIT flag set, call:

// Provided by VK_VERSION_1_0
void vkGetImageMemoryRequirements(
    VkDevice                                    device,
    VkImage                                     image,
    VkMemoryRequirements*                       pMemoryRequirements);

  • device is the logical device that owns the image.

  • image is the image to query.

  • pMemoryRequirements is a pointer to a VkMemoryRequirements structure in which the memory requirements of the image object are returned.

Valid Usage
Valid Usage (Implicit)

  • VUID-vkGetImageMemoryRequirements-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetImageMemoryRequirements-image-parameter
    image must be a valid VkImage handle

  • VUID-vkGetImageMemoryRequirements-pMemoryRequirements-parameter
    pMemoryRequirements must be a valid pointer to a VkMemoryRequirements structure

  • VUID-vkGetImageMemoryRequirements-image-parent
    image must have been created, allocated, or retrieved from device

To determine the memory requirements for a tensor resource, call:

// Provided by VK_ARM_tensors
void vkGetTensorMemoryRequirementsARM(
    VkDevice                                    device,
    const VkTensorMemoryRequirementsInfoARM*    pInfo,
    VkMemoryRequirements2*                      pMemoryRequirements);

  • device is the logical device that owns the tensor.

  • pInfo is a pointer to a VkTensorMemoryRequirementsInfoARM structure containing parameters required for the memory requirements query.

  • pMemoryRequirements is a pointer to a VkMemoryRequirements2 structure in which the memory requirements of the tensor object are returned.

Valid Usage (Implicit)

  • VUID-vkGetTensorMemoryRequirementsARM-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetTensorMemoryRequirementsARM-pInfo-parameter
    pInfo must be a valid pointer to a valid VkTensorMemoryRequirementsInfoARM structure

  • VUID-vkGetTensorMemoryRequirementsARM-pMemoryRequirements-parameter
    pMemoryRequirements must be a valid pointer to a VkMemoryRequirements2 structure

The VkTensorMemoryRequirementsInfoARM structure is defined as:

// Provided by VK_ARM_tensors
typedef struct VkTensorMemoryRequirementsInfoARM {
    VkStructureType    sType;
    const void*        pNext;
    VkTensorARM        tensor;
} VkTensorMemoryRequirementsInfoARM;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • tensor is the tensor to query.

Valid Usage (Implicit)

To determine the memory requirements for a tensor resource without creating an object, call:

// Provided by VK_ARM_tensors
void vkGetDeviceTensorMemoryRequirementsARM(
    VkDevice                                    device,
    const VkDeviceTensorMemoryRequirementsARM*  pInfo,
    VkMemoryRequirements2*                      pMemoryRequirements);

  • device is the logical device intended to own the tensor.

  • pInfo is a pointer to a VkDeviceTensorMemoryRequirementsARM structure containing parameters required for the memory requirements query.

  • pMemoryRequirements is a pointer to a VkMemoryRequirements2 structure in which the memory requirements of the tensor object are returned.

Valid Usage

  • VUID-vkGetDeviceTensorMemoryRequirementsARM-tensors-09831
    The tensors feature must be enabled

Valid Usage (Implicit)

  • VUID-vkGetDeviceTensorMemoryRequirementsARM-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetDeviceTensorMemoryRequirementsARM-pInfo-parameter
    pInfo must be a valid pointer to a valid VkDeviceTensorMemoryRequirementsARM structure

  • VUID-vkGetDeviceTensorMemoryRequirementsARM-pMemoryRequirements-parameter
    pMemoryRequirements must be a valid pointer to a VkMemoryRequirements2 structure

The VkDeviceTensorMemoryRequirementsARM structure is defined as:

// Provided by VK_ARM_tensors
typedef struct VkDeviceTensorMemoryRequirementsARM {
    VkStructureType                 sType;
    const void*                     pNext;
    const VkTensorCreateInfoARM*    pCreateInfo;
} VkDeviceTensorMemoryRequirementsARM;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • pCreateInfo is a pointer to a VkTensorCreateInfoARM structure containing parameters affecting the creation of the tensor to query.

Valid Usage (Implicit)

The VkMemoryRequirements structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkMemoryRequirements {
    VkDeviceSize    size;
    VkDeviceSize    alignment;
    uint32_t        memoryTypeBits;
} VkMemoryRequirements;

  • size is the size, in bytes, of the memory allocation required for the resource.

  • alignment is the alignment, in bytes, of the offset within the allocation required for the resource.

  • memoryTypeBits is a bitmask and contains one bit set for every supported memory type for the resource. Bit i is set if and only if the memory type i in the VkPhysicalDeviceMemoryProperties structure for the physical device is supported for the resource.

The precise size of images that will be bound to external Android hardware buffer memory is unknown until the memory has been imported or allocated, so applications must not call vkGetImageMemoryRequirements or vkGetImageMemoryRequirements2 with such a VkImage before it has been bound to memory. For this reason, applications also must not call vkGetDeviceImageMemoryRequirements with a VkImageCreateInfo describing an external Android hardware buffer. When importing Android hardware buffer memory, the allocationSize can be determined by calling vkGetAndroidHardwareBufferPropertiesANDROID. When allocating new memory for a VkImage that can be exported to an Android hardware buffer, the memory’s allocationSize must be zero; the actual size will be determined by the dedicated image’s parameters. After the memory has been allocated, the amount of space allocated from the memory’s heap can be obtained by getting the image’s memory requirements or by calling vkGetAndroidHardwareBufferPropertiesANDROID with the Android hardware buffer exported from the memory.

When allocating new memory for a VkBuffer that can be exported to an Android hardware buffer an application may still call vkGetBufferMemoryRequirements or vkGetBufferMemoryRequirements2 with VkBuffer before it has been bound to memory.

The value of size has no meaning and should be ignored if the resource being queried was created with any of the following external memory handle types:

The implementation guarantees certain properties about the memory requirements returned by vkGetBufferMemoryRequirements2, vkGetImageMemoryRequirements2, vkGetDeviceBufferMemoryRequirements, vkGetDeviceImageMemoryRequirements, vkGetDeviceTensorMemoryRequirementsARM, vkGetTensorMemoryRequirementsARM, vkGetBufferMemoryRequirements and vkGetImageMemoryRequirements:

To determine the memory requirements for a buffer resource, call:

// Provided by VK_VERSION_1_1
void vkGetBufferMemoryRequirements2(
    VkDevice                                    device,
    const VkBufferMemoryRequirementsInfo2*      pInfo,
    VkMemoryRequirements2*                      pMemoryRequirements);
// Provided by VK_KHR_get_memory_requirements2
// Equivalent to vkGetBufferMemoryRequirements2
void vkGetBufferMemoryRequirements2KHR(
    VkDevice                                    device,
    const VkBufferMemoryRequirementsInfo2*      pInfo,
    VkMemoryRequirements2*                      pMemoryRequirements);

  • device is the logical device that owns the buffer.

  • pInfo is a pointer to a VkBufferMemoryRequirementsInfo2 structure containing parameters required for the memory requirements query.

  • pMemoryRequirements is a pointer to a VkMemoryRequirements2 structure in which the memory requirements of the buffer object are returned.

Valid Usage (Implicit)

  • VUID-vkGetBufferMemoryRequirements2-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetBufferMemoryRequirements2-pInfo-parameter
    pInfo must be a valid pointer to a valid VkBufferMemoryRequirementsInfo2 structure

  • VUID-vkGetBufferMemoryRequirements2-pMemoryRequirements-parameter
    pMemoryRequirements must be a valid pointer to a VkMemoryRequirements2 structure

To determine the memory requirements for a buffer resource without creating an object, call:

// Provided by VK_VERSION_1_3
void vkGetDeviceBufferMemoryRequirements(
    VkDevice                                    device,
    const VkDeviceBufferMemoryRequirements*     pInfo,
    VkMemoryRequirements2*                      pMemoryRequirements);
// Provided by VK_KHR_maintenance4
// Equivalent to vkGetDeviceBufferMemoryRequirements
void vkGetDeviceBufferMemoryRequirementsKHR(
    VkDevice                                    device,
    const VkDeviceBufferMemoryRequirements*     pInfo,
    VkMemoryRequirements2*                      pMemoryRequirements);

  • device is the logical device intended to own the buffer.

  • pInfo is a pointer to a VkDeviceBufferMemoryRequirements structure containing parameters required for the memory requirements query.

  • pMemoryRequirements is a pointer to a VkMemoryRequirements2 structure in which the memory requirements of the buffer object are returned.

Valid Usage (Implicit)

  • VUID-vkGetDeviceBufferMemoryRequirements-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetDeviceBufferMemoryRequirements-pInfo-parameter
    pInfo must be a valid pointer to a valid VkDeviceBufferMemoryRequirements structure

  • VUID-vkGetDeviceBufferMemoryRequirements-pMemoryRequirements-parameter
    pMemoryRequirements must be a valid pointer to a VkMemoryRequirements2 structure

The VkBufferMemoryRequirementsInfo2 structure is defined as:

// Provided by VK_VERSION_1_1
typedef struct VkBufferMemoryRequirementsInfo2 {
    VkStructureType    sType;
    const void*        pNext;
    VkBuffer           buffer;
} VkBufferMemoryRequirementsInfo2;
// Provided by VK_KHR_get_memory_requirements2
// Equivalent to VkBufferMemoryRequirementsInfo2
typedef VkBufferMemoryRequirementsInfo2 VkBufferMemoryRequirementsInfo2KHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • buffer is the buffer to query.

Valid Usage (Implicit)

The VkDeviceBufferMemoryRequirements structure is defined as:

// Provided by VK_VERSION_1_3
typedef struct VkDeviceBufferMemoryRequirements {
    VkStructureType              sType;
    const void*                  pNext;
    const VkBufferCreateInfo*    pCreateInfo;
} VkDeviceBufferMemoryRequirements;
// Provided by VK_KHR_maintenance4
// Equivalent to VkDeviceBufferMemoryRequirements
typedef VkDeviceBufferMemoryRequirements VkDeviceBufferMemoryRequirementsKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • pCreateInfo is a pointer to a VkBufferCreateInfo structure containing parameters affecting creation of the buffer to query.

Valid Usage (Implicit)

To determine the memory requirements for an image resource, call:

// Provided by VK_VERSION_1_1
void vkGetImageMemoryRequirements2(
    VkDevice                                    device,
    const VkImageMemoryRequirementsInfo2*       pInfo,
    VkMemoryRequirements2*                      pMemoryRequirements);
// Provided by VK_KHR_get_memory_requirements2
// Equivalent to vkGetImageMemoryRequirements2
void vkGetImageMemoryRequirements2KHR(
    VkDevice                                    device,
    const VkImageMemoryRequirementsInfo2*       pInfo,
    VkMemoryRequirements2*                      pMemoryRequirements);

  • device is the logical device that owns the image.

  • pInfo is a pointer to a VkImageMemoryRequirementsInfo2 structure containing parameters required for the memory requirements query.

  • pMemoryRequirements is a pointer to a VkMemoryRequirements2 structure in which the memory requirements of the image object are returned.

Valid Usage (Implicit)

  • VUID-vkGetImageMemoryRequirements2-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetImageMemoryRequirements2-pInfo-parameter
    pInfo must be a valid pointer to a valid VkImageMemoryRequirementsInfo2 structure

  • VUID-vkGetImageMemoryRequirements2-pMemoryRequirements-parameter
    pMemoryRequirements must be a valid pointer to a VkMemoryRequirements2 structure

To determine the memory requirements for an image resource without creating an object, call:

// Provided by VK_VERSION_1_3
void vkGetDeviceImageMemoryRequirements(
    VkDevice                                    device,
    const VkDeviceImageMemoryRequirements*      pInfo,
    VkMemoryRequirements2*                      pMemoryRequirements);
// Provided by VK_KHR_maintenance4
// Equivalent to vkGetDeviceImageMemoryRequirements
void vkGetDeviceImageMemoryRequirementsKHR(
    VkDevice                                    device,
    const VkDeviceImageMemoryRequirements*      pInfo,
    VkMemoryRequirements2*                      pMemoryRequirements);

  • device is the logical device intended to own the image.

  • pInfo is a pointer to a VkDeviceImageMemoryRequirements structure containing parameters required for the memory requirements query.

  • pMemoryRequirements is a pointer to a VkMemoryRequirements2 structure in which the memory requirements of the image object are returned.

Valid Usage (Implicit)

  • VUID-vkGetDeviceImageMemoryRequirements-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetDeviceImageMemoryRequirements-pInfo-parameter
    pInfo must be a valid pointer to a valid VkDeviceImageMemoryRequirements structure

  • VUID-vkGetDeviceImageMemoryRequirements-pMemoryRequirements-parameter
    pMemoryRequirements must be a valid pointer to a VkMemoryRequirements2 structure

The VkImageMemoryRequirementsInfo2 structure is defined as:

// Provided by VK_VERSION_1_1
typedef struct VkImageMemoryRequirementsInfo2 {
    VkStructureType    sType;
    const void*        pNext;
    VkImage            image;
} VkImageMemoryRequirementsInfo2;
// Provided by VK_KHR_get_memory_requirements2
// Equivalent to VkImageMemoryRequirementsInfo2
typedef VkImageMemoryRequirementsInfo2 VkImageMemoryRequirementsInfo2KHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • image is the image to query.

Valid Usage
Valid Usage (Implicit)

  • VUID-VkImageMemoryRequirementsInfo2-sType-sType
    sType must be VK_STRUCTURE_TYPE_IMAGE_MEMORY_REQUIREMENTS_INFO_2

  • VUID-VkImageMemoryRequirementsInfo2-pNext-pNext
    pNext must be NULL or a pointer to a valid instance of VkImagePlaneMemoryRequirementsInfo

  • VUID-VkImageMemoryRequirementsInfo2-sType-unique
    The sType value of each structure in the pNext chain must be unique

  • VUID-VkImageMemoryRequirementsInfo2-image-parameter
    image must be a valid VkImage handle

The VkDeviceImageMemoryRequirements structure is defined as:

// Provided by VK_VERSION_1_3
typedef struct VkDeviceImageMemoryRequirements {
    VkStructureType             sType;
    const void*                 pNext;
    const VkImageCreateInfo*    pCreateInfo;
    VkImageAspectFlagBits       planeAspect;
} VkDeviceImageMemoryRequirements;
// Provided by VK_KHR_maintenance4
// Equivalent to VkDeviceImageMemoryRequirements
typedef VkDeviceImageMemoryRequirements VkDeviceImageMemoryRequirementsKHR;
Valid Usage
Valid Usage (Implicit)

  • VUID-VkDeviceImageMemoryRequirements-sType-sType
    sType must be VK_STRUCTURE_TYPE_DEVICE_IMAGE_MEMORY_REQUIREMENTS

  • VUID-VkDeviceImageMemoryRequirements-pNext-pNext
    pNext must be NULL

  • VUID-VkDeviceImageMemoryRequirements-pCreateInfo-parameter
    pCreateInfo must be a valid pointer to a valid VkImageCreateInfo structure

  • VUID-VkDeviceImageMemoryRequirements-planeAspect-parameter
    If planeAspect is not 0, planeAspect must be a valid VkImageAspectFlagBits value

To determine the memory requirements for a plane of a disjoint image, add a VkImagePlaneMemoryRequirementsInfo structure to the pNext chain of the VkImageMemoryRequirementsInfo2 structure.

The VkImagePlaneMemoryRequirementsInfo structure is defined as:

// Provided by VK_VERSION_1_1
typedef struct VkImagePlaneMemoryRequirementsInfo {
    VkStructureType          sType;
    const void*              pNext;
    VkImageAspectFlagBits    planeAspect;
} VkImagePlaneMemoryRequirementsInfo;
// Provided by VK_KHR_sampler_ycbcr_conversion
// Equivalent to VkImagePlaneMemoryRequirementsInfo
typedef VkImagePlaneMemoryRequirementsInfo VkImagePlaneMemoryRequirementsInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • planeAspect is a VkImageAspectFlagBits value specifying the aspect corresponding to the image plane to query.

Valid Usage
Valid Usage (Implicit)

To determine the tile memory allocation requirements of a buffer or image resource, add a VkTileMemoryRequirementsQCOM structure to the pNext chain of the VkMemoryRequirements2 structure passed as the pMemoryRequirements parameter of vkGetBufferMemoryRequirements2 or vkGetImageMemoryRequirements2, respectively. The VkTileMemoryRequirementsQCOM structure is defined as:

// Provided by VK_QCOM_tile_memory_heap
typedef struct VkTileMemoryRequirementsQCOM {
    VkStructureType    sType;
    void*              pNext;
    VkDeviceSize       size;
    VkDeviceSize       alignment;
} VkTileMemoryRequirementsQCOM;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • size is the size, in bytes, of the tile memory allocation required for the resource.

  • alignment is the alignment, in bytes, of the offset within the tile memory allocation required for the resource.

The size and alignment must be used when the resource is bound to a VkDeviceMemory object that was allocated from a VkMemoryType that has a heapIndex that corresponds to a VkMemoryHeap with the VK_MEMORY_HEAP_TILE_MEMORY_BIT_QCOM property.

If the resource cannot be bound to tile memory, then size and alignment is filled with zero by the implementation.

Valid Usage (Implicit)

The VkMemoryRequirements2 structure is defined as:

// Provided by VK_VERSION_1_1
typedef struct VkMemoryRequirements2 {
    VkStructureType         sType;
    void*                   pNext;
    VkMemoryRequirements    memoryRequirements;
} VkMemoryRequirements2;
// Provided by VK_KHR_get_memory_requirements2, VK_NV_ray_tracing with VK_KHR_get_memory_requirements2 or VK_VERSION_1_1
// Equivalent to VkMemoryRequirements2
typedef VkMemoryRequirements2 VkMemoryRequirements2KHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • memoryRequirements is a VkMemoryRequirements structure describing the memory requirements of the resource.

Valid Usage (Implicit)

The VkMemoryDedicatedRequirements structure is defined as:

// Provided by VK_VERSION_1_1
typedef struct VkMemoryDedicatedRequirements {
    VkStructureType    sType;
    void*              pNext;
    VkBool32           prefersDedicatedAllocation;
    VkBool32           requiresDedicatedAllocation;
} VkMemoryDedicatedRequirements;
// Provided by VK_KHR_dedicated_allocation
// Equivalent to VkMemoryDedicatedRequirements
typedef VkMemoryDedicatedRequirements VkMemoryDedicatedRequirementsKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • prefersDedicatedAllocation specifies that the implementation would prefer a dedicated allocation for this resource. The application is still free to suballocate the resource but it may get better performance if a dedicated allocation is used.

  • requiresDedicatedAllocation specifies that a dedicated allocation is required for this resource.

To determine the dedicated allocation requirements of a buffer or image or tensor resource, add a VkMemoryDedicatedRequirements structure to the pNext chain of the VkMemoryRequirements2 structure passed as the pMemoryRequirements parameter of vkGetBufferMemoryRequirements2, vkGetTensorMemoryRequirementsARM, vkGetDeviceBufferMemoryRequirements, vkGetDeviceImageMemoryRequirements, or vkGetImageMemoryRequirements2 respectively.

Constraints on the values returned for buffer resources are:

Constraints on the values returned for image resources are:

Constraints on the values returned for tensor resources are:

Valid Usage (Implicit)

To attach memory to a buffer object, call:

// Provided by VK_VERSION_1_0
VkResult vkBindBufferMemory(
    VkDevice                                    device,
    VkBuffer                                    buffer,
    VkDeviceMemory                              memory,
    VkDeviceSize                                memoryOffset);

  • device is the logical device that owns the buffer and memory.

  • buffer is the buffer to be attached to memory.

  • memory is a VkDeviceMemory object describing the device memory to attach.

  • memoryOffset is the start offset of the region of memory which is to be bound to the buffer. The number of bytes returned in the VkMemoryRequirements::size member in memory, starting from memoryOffset bytes, will be bound to the specified buffer.

vkBindBufferMemory is equivalent to passing the same parameters through VkBindBufferMemoryInfo to vkBindBufferMemory2.

Valid Usage
Valid Usage (Implicit)

  • VUID-vkBindBufferMemory-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkBindBufferMemory-buffer-parameter
    buffer must be a valid VkBuffer handle

  • VUID-vkBindBufferMemory-memory-parameter
    memory must be a valid VkDeviceMemory handle

  • VUID-vkBindBufferMemory-buffer-parent
    buffer must have been created, allocated, or retrieved from device

  • VUID-vkBindBufferMemory-memory-parent
    memory must have been created, allocated, or retrieved from device

Host Synchronization

  • Host access to buffer must be externally synchronized

Return Codes
Success
Failure

To attach memory to buffer objects for one or more buffers at a time, call:

// Provided by VK_VERSION_1_1
VkResult vkBindBufferMemory2(
    VkDevice                                    device,
    uint32_t                                    bindInfoCount,
    const VkBindBufferMemoryInfo*               pBindInfos);
// Provided by VK_KHR_bind_memory2
// Equivalent to vkBindBufferMemory2
VkResult vkBindBufferMemory2KHR(
    VkDevice                                    device,
    uint32_t                                    bindInfoCount,
    const VkBindBufferMemoryInfo*               pBindInfos);

  • device is the logical device that owns the buffers and memory.

  • bindInfoCount is the number of elements in pBindInfos.

  • pBindInfos is a pointer to an array of bindInfoCount VkBindBufferMemoryInfo structures describing buffers and memory to bind.

On some implementations, it may be more efficient to batch memory bindings into a single command.

If the maintenance6 feature is enabled, this command must attempt to perform all of the memory binding operations described by pBindInfos, and must not early exit on the first failure.

If any of the memory binding operations described by pBindInfos fail, the VkResult returned by this command must be the return value of any one of the memory binding operations which did not return VK_SUCCESS.

If the vkBindBufferMemory2 command failed, VkBindMemoryStatus structures were not included in the pNext chains of each element of pBindInfos, and bindInfoCount was greater than one, then the buffers referenced by pBindInfos will be in an indeterminate state, and must not be used.

Applications should destroy these buffers.
Valid Usage (Implicit)

  • VUID-vkBindBufferMemory2-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkBindBufferMemory2-pBindInfos-parameter
    pBindInfos must be a valid pointer to an array of bindInfoCount valid VkBindBufferMemoryInfo structures

  • VUID-vkBindBufferMemory2-bindInfoCount-arraylength
    bindInfoCount must be greater than 0

Return Codes
Success
Failure

VkBindBufferMemoryInfo contains members corresponding to the parameters of vkBindBufferMemory.

The VkBindBufferMemoryInfo structure is defined as:

// Provided by VK_VERSION_1_1
typedef struct VkBindBufferMemoryInfo {
    VkStructureType    sType;
    const void*        pNext;
    VkBuffer           buffer;
    VkDeviceMemory     memory;
    VkDeviceSize       memoryOffset;
} VkBindBufferMemoryInfo;
// Provided by VK_KHR_bind_memory2
// Equivalent to VkBindBufferMemoryInfo
typedef VkBindBufferMemoryInfo VkBindBufferMemoryInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • buffer is the buffer to be attached to memory.

  • memory is a VkDeviceMemory object describing the device memory to attach.

  • memoryOffset is the start offset of the region of memory which is to be bound to the buffer. The number of bytes returned in the VkMemoryRequirements::size member in memory, starting from memoryOffset bytes, will be bound to the specified buffer.

Valid Usage
Valid Usage (Implicit)

  • VUID-VkBindBufferMemoryInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_BIND_BUFFER_MEMORY_INFO

  • VUID-VkBindBufferMemoryInfo-pNext-pNext
    Each pNext member of any structure (including this one) in the pNext chain must be either NULL or a pointer to a valid instance of VkBindBufferMemoryDeviceGroupInfo or VkBindMemoryStatus

  • VUID-VkBindBufferMemoryInfo-sType-unique
    The sType value of each structure in the pNext chain must be unique

  • VUID-VkBindBufferMemoryInfo-buffer-parameter
    buffer must be a valid VkBuffer handle

  • VUID-VkBindBufferMemoryInfo-memory-parameter
    memory must be a valid VkDeviceMemory handle

  • VUID-VkBindBufferMemoryInfo-commonparent
    Both of buffer, and memory must have been created, allocated, or retrieved from the same VkDevice

Host Synchronization

  • Host access to buffer must be externally synchronized

The VkBindBufferMemoryDeviceGroupInfo structure is defined as:

// Provided by VK_VERSION_1_1
typedef struct VkBindBufferMemoryDeviceGroupInfo {
    VkStructureType    sType;
    const void*        pNext;
    uint32_t           deviceIndexCount;
    const uint32_t*    pDeviceIndices;
} VkBindBufferMemoryDeviceGroupInfo;
// Provided by VK_KHR_bind_memory2 with VK_KHR_device_group
// Equivalent to VkBindBufferMemoryDeviceGroupInfo
typedef VkBindBufferMemoryDeviceGroupInfo VkBindBufferMemoryDeviceGroupInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • deviceIndexCount is the number of elements in pDeviceIndices.

  • pDeviceIndices is a pointer to an array of device indices.

If the pNext chain of VkBindBufferMemoryInfo includes a VkBindBufferMemoryDeviceGroupInfo structure, then that structure determines how memory is bound to buffers across multiple devices in a device group.

If deviceIndexCount is greater than zero, then on device index i the buffer is attached to the instance of memory on the physical device with device index pDeviceIndices[i].

If deviceIndexCount is zero and memory comes from a memory heap with the VK_MEMORY_HEAP_MULTI_INSTANCE_BIT bit set, then it is as if pDeviceIndices contains consecutive indices from zero to the number of physical devices in the logical device, minus one. In other words, by default each physical device attaches to its own instance of memory.

If deviceIndexCount is zero and memory comes from a memory heap without the VK_MEMORY_HEAP_MULTI_INSTANCE_BIT bit set, then it is as if pDeviceIndices contains an array of zeros. In other words, by default each physical device attaches to instance zero.

Valid Usage

  • VUID-VkBindBufferMemoryDeviceGroupInfo-deviceIndexCount-01606
    deviceIndexCount must either be zero or equal to the number of physical devices in the logical device

  • VUID-VkBindBufferMemoryDeviceGroupInfo-pDeviceIndices-01607
    All elements of pDeviceIndices must be valid device indices

Valid Usage (Implicit)

  • VUID-VkBindBufferMemoryDeviceGroupInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_BIND_BUFFER_MEMORY_DEVICE_GROUP_INFO

  • VUID-VkBindBufferMemoryDeviceGroupInfo-pDeviceIndices-parameter
    If deviceIndexCount is not 0, pDeviceIndices must be a valid pointer to an array of deviceIndexCount uint32_t values

The VkBindMemoryStatus structure is defined as:

// Provided by VK_VERSION_1_4
typedef struct VkBindMemoryStatus {
    VkStructureType    sType;
    const void*        pNext;
    VkResult*          pResult;
} VkBindMemoryStatus;
// Provided by VK_KHR_maintenance6
// Equivalent to VkBindMemoryStatus
typedef VkBindMemoryStatus VkBindMemoryStatusKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • pResult is a pointer to a VkResult value.

If the pNext chain of VkBindBufferMemoryInfo or VkBindImageMemoryInfo includes a VkBindMemoryStatus structure, then the VkBindMemoryStatus::pResult will be populated with a value describing the result of the corresponding memory binding operation.

Valid Usage (Implicit)

To attach memory to a VkImage object created without the VK_IMAGE_CREATE_DISJOINT_BIT set, call:

// Provided by VK_VERSION_1_0
VkResult vkBindImageMemory(
    VkDevice                                    device,
    VkImage                                     image,
    VkDeviceMemory                              memory,
    VkDeviceSize                                memoryOffset);

  • device is the logical device that owns the image and memory.

  • image is the image.

  • memory is the VkDeviceMemory object describing the device memory to attach.

  • memoryOffset is the start offset of the region of memory which is to be bound to the image. The number of bytes returned in the VkMemoryRequirements::size member in memory, starting from memoryOffset bytes, will be bound to the specified image.

vkBindImageMemory is equivalent to passing the same parameters through VkBindImageMemoryInfo to vkBindImageMemory2.

Valid Usage
Valid Usage (Implicit)

  • VUID-vkBindImageMemory-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkBindImageMemory-image-parameter
    image must be a valid VkImage handle

  • VUID-vkBindImageMemory-memory-parameter
    memory must be a valid VkDeviceMemory handle

  • VUID-vkBindImageMemory-image-parent
    image must have been created, allocated, or retrieved from device

  • VUID-vkBindImageMemory-memory-parent
    memory must have been created, allocated, or retrieved from device

Host Synchronization

  • Host access to image must be externally synchronized

Return Codes
Success
Failure

To attach memory to image objects for one or more images at a time, call:

// Provided by VK_VERSION_1_1
VkResult vkBindImageMemory2(
    VkDevice                                    device,
    uint32_t                                    bindInfoCount,
    const VkBindImageMemoryInfo*                pBindInfos);
// Provided by VK_KHR_bind_memory2
// Equivalent to vkBindImageMemory2
VkResult vkBindImageMemory2KHR(
    VkDevice                                    device,
    uint32_t                                    bindInfoCount,
    const VkBindImageMemoryInfo*                pBindInfos);

  • device is the logical device that owns the images and memory.

  • bindInfoCount is the number of elements in pBindInfos.

  • pBindInfos is a pointer to an array of VkBindImageMemoryInfo structures, describing images and memory to bind.

On some implementations, it may be more efficient to batch memory bindings into a single command.

If the maintenance6 feature is enabled, this command must attempt to perform all of the memory binding operations described by pBindInfos, and must not early exit on the first failure.

If any of the memory binding operations described by pBindInfos fail, the VkResult returned by this command must be the return value of any one of the memory binding operations which did not return VK_SUCCESS.

If the vkBindImageMemory2 command failed, VkBindMemoryStatus structures were not included in the pNext chains of each element of pBindInfos, and bindInfoCount was greater than one, then the images referenced by pBindInfos will be in an indeterminate state, and must not be used.

Applications should destroy these images.
Valid Usage
Valid Usage (Implicit)

  • VUID-vkBindImageMemory2-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkBindImageMemory2-pBindInfos-parameter
    pBindInfos must be a valid pointer to an array of bindInfoCount valid VkBindImageMemoryInfo structures

  • VUID-vkBindImageMemory2-bindInfoCount-arraylength
    bindInfoCount must be greater than 0

Return Codes
Success
Failure

VkBindImageMemoryInfo contains members corresponding to the parameters of vkBindImageMemory.

The VkBindImageMemoryInfo structure is defined as:

// Provided by VK_VERSION_1_1
typedef struct VkBindImageMemoryInfo {
    VkStructureType    sType;
    const void*        pNext;
    VkImage            image;
    VkDeviceMemory     memory;
    VkDeviceSize       memoryOffset;
} VkBindImageMemoryInfo;
// Provided by VK_KHR_bind_memory2
// Equivalent to VkBindImageMemoryInfo
typedef VkBindImageMemoryInfo VkBindImageMemoryInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • image is the image to be attached to memory.

  • memory is a VkDeviceMemory object describing the device memory to attach.

  • memoryOffset is the start offset of the region of memory which is to be bound to the image. The number of bytes returned in the VkMemoryRequirements::size member in memory, starting from memoryOffset bytes, will be bound to the specified image.

Valid Usage
Valid Usage (Implicit)
Host Synchronization

  • Host access to image must be externally synchronized

The VkBindImageMemoryDeviceGroupInfo structure is defined as:

// Provided by VK_VERSION_1_1
typedef struct VkBindImageMemoryDeviceGroupInfo {
    VkStructureType    sType;
    const void*        pNext;
    uint32_t           deviceIndexCount;
    const uint32_t*    pDeviceIndices;
    uint32_t           splitInstanceBindRegionCount;
    const VkRect2D*    pSplitInstanceBindRegions;
} VkBindImageMemoryDeviceGroupInfo;
// Provided by VK_KHR_bind_memory2 with VK_KHR_device_group
// Equivalent to VkBindImageMemoryDeviceGroupInfo
typedef VkBindImageMemoryDeviceGroupInfo VkBindImageMemoryDeviceGroupInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • deviceIndexCount is the number of elements in pDeviceIndices.

  • pDeviceIndices is a pointer to an array of device indices.

  • splitInstanceBindRegionCount is the number of elements in pSplitInstanceBindRegions.

  • pSplitInstanceBindRegions is a pointer to an array of VkRect2D structures describing which regions of the image are attached to each instance of memory.

If the pNext chain of VkBindImageMemoryInfo includes a VkBindImageMemoryDeviceGroupInfo structure, then that structure determines how memory is bound to images across multiple devices in a device group.

If deviceIndexCount is greater than zero, then on device index i image is attached to the instance of the memory on the physical device with device index pDeviceIndices[i].

Let N be the number of physical devices in the logical device. If splitInstanceBindRegionCount is greater than zero, then pSplitInstanceBindRegions is a pointer to an array of N2 rectangles, where the image region specified by the rectangle at element i*N+j in resource instance i is bound to the memory instance j. The blocks of the memory that are bound to each sparse image block region use an offset in memory, relative to memoryOffset, computed as if the whole image was being bound to a contiguous range of memory. In other words, horizontally adjacent image blocks use consecutive blocks of memory, vertically adjacent image blocks are separated by the number of bytes per block multiplied by the width in blocks of image, and the block at (0,0) corresponds to memory starting at memoryOffset.

If splitInstanceBindRegionCount and deviceIndexCount are zero and the memory comes from a memory heap with the VK_MEMORY_HEAP_MULTI_INSTANCE_BIT bit set, then it is as if pDeviceIndices contains consecutive indices from zero to the number of physical devices in the logical device, minus one. In other words, by default each physical device attaches to its own instance of the memory.

If splitInstanceBindRegionCount and deviceIndexCount are zero and the memory comes from a memory heap without the VK_MEMORY_HEAP_MULTI_INSTANCE_BIT bit set, then it is as if pDeviceIndices contains an array of zeros. In other words, by default each physical device attaches to instance zero.

Valid Usage

  • VUID-VkBindImageMemoryDeviceGroupInfo-deviceIndexCount-01633
    At least one of deviceIndexCount and splitInstanceBindRegionCount must be zero

  • VUID-VkBindImageMemoryDeviceGroupInfo-deviceIndexCount-01634
    deviceIndexCount must either be zero or equal to the number of physical devices in the logical device

  • VUID-VkBindImageMemoryDeviceGroupInfo-pDeviceIndices-01635
    All elements of pDeviceIndices must be valid device indices

  • VUID-VkBindImageMemoryDeviceGroupInfo-splitInstanceBindRegionCount-01636
    splitInstanceBindRegionCount must either be zero or equal to the number of physical devices in the logical device squared

  • VUID-VkBindImageMemoryDeviceGroupInfo-pSplitInstanceBindRegions-01637
    Elements of pSplitInstanceBindRegions that correspond to the same instance of an image must not overlap

  • VUID-VkBindImageMemoryDeviceGroupInfo-offset-01638
    The offset.x member of any element of pSplitInstanceBindRegions must be a multiple of the sparse image block width (VkSparseImageFormatProperties::imageGranularity.width) of all non-metadata aspects of the image

  • VUID-VkBindImageMemoryDeviceGroupInfo-offset-01639
    The offset.y member of any element of pSplitInstanceBindRegions must be a multiple of the sparse image block height (VkSparseImageFormatProperties::imageGranularity.height) of all non-metadata aspects of the image

  • VUID-VkBindImageMemoryDeviceGroupInfo-extent-01640
    The extent.width member of any element of pSplitInstanceBindRegions must either be a multiple of the sparse image block width of all non-metadata aspects of the image, or else extent.width + offset.x must equal the width of the image subresource

  • VUID-VkBindImageMemoryDeviceGroupInfo-extent-01641
    The extent.height member of any element of pSplitInstanceBindRegions must either be a multiple of the sparse image block height of all non-metadata aspects of the image, or else extent.height + offset.y must equal the height of the image subresource

Valid Usage (Implicit)

  • VUID-VkBindImageMemoryDeviceGroupInfo-sType-sType
    sType must be VK_STRUCTURE_TYPE_BIND_IMAGE_MEMORY_DEVICE_GROUP_INFO

  • VUID-VkBindImageMemoryDeviceGroupInfo-pDeviceIndices-parameter
    If deviceIndexCount is not 0, pDeviceIndices must be a valid pointer to an array of deviceIndexCount uint32_t values

  • VUID-VkBindImageMemoryDeviceGroupInfo-pSplitInstanceBindRegions-parameter
    If splitInstanceBindRegionCount is not 0, pSplitInstanceBindRegions must be a valid pointer to an array of splitInstanceBindRegionCount VkRect2D structures

If the pNext chain of VkBindImageMemoryInfo includes a VkBindImageMemorySwapchainInfoKHR structure, then that structure includes a swapchain handle and image index indicating that the image will be bound to memory from that swapchain.

The VkBindImageMemorySwapchainInfoKHR structure is defined as:

// Provided by VK_VERSION_1_1 with VK_KHR_swapchain, VK_KHR_device_group with VK_KHR_swapchain
typedef struct VkBindImageMemorySwapchainInfoKHR {
    VkStructureType    sType;
    const void*        pNext;
    VkSwapchainKHR     swapchain;
    uint32_t           imageIndex;
} VkBindImageMemorySwapchainInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • swapchain is VK_NULL_HANDLE or a swapchain handle.

  • imageIndex is an image index within swapchain.

If swapchain is not NULL, the swapchain and imageIndex are used to determine the memory that the image is bound to, instead of memory and memoryOffset.

Memory can be bound to a swapchain and use the pDeviceIndices or pSplitInstanceBindRegions members of VkBindImageMemoryDeviceGroupInfo.

Valid Usage
Valid Usage (Implicit)
Host Synchronization

  • Host access to swapchain must be externally synchronized

In order to bind planes of a disjoint image, add a VkBindImagePlaneMemoryInfo structure to the pNext chain of VkBindImageMemoryInfo.

The VkBindImagePlaneMemoryInfo structure is defined as:

// Provided by VK_VERSION_1_1
typedef struct VkBindImagePlaneMemoryInfo {
    VkStructureType          sType;
    const void*              pNext;
    VkImageAspectFlagBits    planeAspect;
} VkBindImagePlaneMemoryInfo;
// Provided by VK_KHR_sampler_ycbcr_conversion
// Equivalent to VkBindImagePlaneMemoryInfo
typedef VkBindImagePlaneMemoryInfo VkBindImagePlaneMemoryInfoKHR;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • planeAspect is a VkImageAspectFlagBits value specifying the aspect of the disjoint image plane to bind.

Valid Usage
Valid Usage (Implicit)

To attach memory to tensor objects call:

// Provided by VK_ARM_tensors
VkResult vkBindTensorMemoryARM(
    VkDevice                                    device,
    uint32_t                                    bindInfoCount,
    const VkBindTensorMemoryInfoARM*            pBindInfos);

  • device is the logical device that owns the buffers and memory.

  • bindInfoCount is the number of elements in pBindInfos.

  • pBindInfos is a pointer to an array of structures of type VkBindTensorMemoryInfoARM, describing tensors and memory to bind.

On some implementations, it may be more efficient to batch memory bindings into a single command.

Valid Usage (Implicit)

  • VUID-vkBindTensorMemoryARM-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkBindTensorMemoryARM-pBindInfos-parameter
    pBindInfos must be a valid pointer to an array of bindInfoCount valid VkBindTensorMemoryInfoARM structures

  • VUID-vkBindTensorMemoryARM-bindInfoCount-arraylength
    bindInfoCount must be greater than 0

Return Codes
Success
Failure

The VkBindTensorMemoryInfoARM structure is defined as:

// Provided by VK_ARM_tensors
typedef struct VkBindTensorMemoryInfoARM {
    VkStructureType    sType;
    const void*        pNext;
    VkTensorARM        tensor;
    VkDeviceMemory     memory;
    VkDeviceSize       memoryOffset;
} VkBindTensorMemoryInfoARM;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • tensor is the tensor to be attached to memory.

  • memory is a VkDeviceMemory object describing the device memory to attach.

  • memoryOffset is the start offset of the region of memory which is to be bound to the tensor. The number of bytes returned in the VkMemoryRequirements::size member in memory, starting from memoryOffset bytes, will be bound to the specified tensor.

Valid Usage
Valid Usage (Implicit)

  • VUID-VkBindTensorMemoryInfoARM-sType-sType
    sType must be VK_STRUCTURE_TYPE_BIND_TENSOR_MEMORY_INFO_ARM

  • VUID-VkBindTensorMemoryInfoARM-pNext-pNext
    pNext must be NULL

  • VUID-VkBindTensorMemoryInfoARM-tensor-parameter
    tensor must be a valid VkTensorARM handle

  • VUID-VkBindTensorMemoryInfoARM-memory-parameter
    memory must be a valid VkDeviceMemory handle

  • VUID-VkBindTensorMemoryInfoARM-commonparent
    Both of memory, and tensor must have been created, allocated, or retrieved from the same VkDevice

Host Synchronization

  • Host access to tensor must be externally synchronized

Buffer-Image Granularity

The implementation-dependent limit bufferImageGranularity specifies a page-like granularity at which linear and non-linear resources must be placed in adjacent memory locations to avoid aliasing. Two resources which do not satisfy this granularity requirement are said to alias. bufferImageGranularity is specified in bytes, and must be a power of two. Implementations which do not impose a granularity restriction may report a bufferImageGranularity value of one.

Despite its name, bufferImageGranularity is really a granularity between “linear” and “non-linear” resources. The limit bufferImageGranularity also applies to tensor resources.

Given resourceA at the lower memory offset and resourceB at the higher memory offset in the same VkDeviceMemory object, where one resource is linear and the other is non-linear (as defined in the Glossary), and the following:

resourceA.end       = resourceA.memoryOffset + resourceA.size - 1
resourceA.endPage   = resourceA.end & ~(bufferImageGranularity-1)
resourceB.start     = resourceB.memoryOffset
resourceB.startPage = resourceB.start & ~(bufferImageGranularity-1)

The following property must hold:

resourceA.endPage < resourceB.startPage

That is, the end of the first resource (A) and the beginning of the second resource (B) must be on separate “pages” of size bufferImageGranularity. bufferImageGranularity may be different than the physical page size of the memory heap. This restriction is only needed when a linear resource and a non-linear resource are adjacent in memory and will be used simultaneously. The memory ranges of adjacent resources can be closer than bufferImageGranularity, provided they meet the alignment requirement for the objects in question.

Sparse block size in bytes and sparse image and buffer memory alignments must all be multiples of the bufferImageGranularity. Therefore, memory bound to sparse resources naturally satisfies the bufferImageGranularity.

The implementation-dependent limit, bufferImageGranularity also applies to tensor resources.

Resource Sharing Mode

Buffer and image objects are created with a sharing mode controlling how they can be accessed from queues. The supported sharing modes are:

// Provided by VK_VERSION_1_0
typedef enum VkSharingMode {
    VK_SHARING_MODE_EXCLUSIVE = 0,
    VK_SHARING_MODE_CONCURRENT = 1,
} VkSharingMode;

  • VK_SHARING_MODE_EXCLUSIVE specifies that access to any range or image subresource of the object will be exclusive to a single queue family at a time.

  • VK_SHARING_MODE_CONCURRENT specifies that concurrent access to any range or image subresource of the object from multiple queue families is supported.

VK_SHARING_MODE_CONCURRENT may result in lower performance access to the buffer or image than VK_SHARING_MODE_EXCLUSIVE.

Ranges of buffers and image subresources of image objects created using VK_SHARING_MODE_EXCLUSIVE must only be accessed by queues in the queue family that has ownership of the resource. Upon creation, such resources are not owned by any queue family; ownership is implicitly acquired upon first use within a queue. Once a resource using VK_SHARING_MODE_EXCLUSIVE is owned by some queue family, unless the maintenance9 feature is enabled, the application must perform a queue family ownership transfer if it wishes to make the memory contents of a range or image subresource accessible to a different queue family. VK_SHARING_MODE_EXCLUSIVE resources that are already owned by a queue family may be acquired by a different queue family without a queue family ownership transfer, but unless the maintenance9 feature is enabled, their contents become undefined.

If the maintenance9 feature is enabled, the contents of buffer resources, and of linear image resources (i.e., those created with tiling set to VK_IMAGE_TILING_LINEAR) are always preserved when they are implicitly acquired by a different queue family on the same logical device (i.e., neither queue family is VK_QUEUE_FAMILY_FOREIGN_EXT or VK_QUEUE_FAMILY_EXTERNAL). This means that whenever the maintenance9 feature is enabled, explicit queue family ownership transfers of buffer and linear image resources between different queue families on the same logical device are optional.

Additionally, if the maintenance9 feature is enabled, the contents of some optimal image resources (i.e., those created with VK_IMAGE_TILING_OPTIMAL) are always preserved when they are implicitly acquired by a different queue family on the same logical device (i.e., neither queue family is VK_QUEUE_FAMILY_FOREIGN_EXT or VK_QUEUE_FAMILY_EXTERNAL). This applies only to optimal images that are being implicitly acquired by a queue family whose index bit is set in the current queue family’s VkQueueFamilyOwnershipTransferPropertiesKHR::optimalImageTransferToQueueFamilies, and that were created without any of the following bits set in usage:

This means that whenever the maintenance9 feature is enabled, explicit queue family ownership transfers of such image resources between such combinations of queue families are optional. For all other optimal images and/or combinations of queue families, the application must still perform an explicit queue family ownership transfer if it wishes to make the memory contents of an optimal image subresource already owned by a queue family accessible to a different queue family.

Applications are allowed to perform explicit queue family ownership transfers in circumstances where they are not required, but there is no functional nor performance advantage in doing so. Performing explicit transfers in such cases remains supported for backward compatibility and is not recommended for new applications.

Before being used on the first queue, images still require a layout transition from these layouts:

A queue family can take ownership of an image subresource, tensor subresource, or buffer range of a resource created with VK_SHARING_MODE_EXCLUSIVE, without an ownership transfer, in the same way as for a resource that was just created; however, taking ownership in this way has the effect that the contents of the image subresource or buffer range are undefined.

Ranges of buffers, tensor subresources of tensor objects, and image subresources of image objects created using VK_SHARING_MODE_CONCURRENT must only be accessed by queues from the queue families specified through the queueFamilyIndexCount and pQueueFamilyIndices members of the corresponding create info structures.

External Resource Sharing

Resources should only be accessed in the Vulkan instance that has exclusive ownership of their underlying memory. Only one Vulkan instance has exclusive ownership of a resource’s underlying memory at a given time, regardless of whether the resource was created using VK_SHARING_MODE_EXCLUSIVE or VK_SHARING_MODE_CONCURRENT. Applications can transfer ownership of a resource’s underlying memory only if the memory has been imported from or exported to another instance or external API using external memory handles. The semantics for transferring ownership outside of the instance are similar to those used for transferring ownership of VK_SHARING_MODE_EXCLUSIVE resources between queues, and is also accomplished using VkBufferMemoryBarrier or VkImageMemoryBarrier operations. To make the contents of the underlying memory accessible in the destination instance or API, applications must

  1. Release exclusive ownership from the source instance or API.

  2. Ensure the release operation has completed using semaphores or fences.

  3. Acquire exclusive ownership in the destination instance or API

Unlike queue family ownership transfers, the destination instance or API is not specified explicitly when releasing ownership, nor is the source instance or API specified when acquiring ownership. Instead, the image or memory barrier’s dstQueueFamilyIndex or srcQueueFamilyIndex parameters are set to the reserved queue family index VK_QUEUE_FAMILY_EXTERNAL or VK_QUEUE_FAMILY_FOREIGN_EXT to represent the external destination or source respectively.

Binding a resource to a memory object shared between multiple Vulkan instances or other APIs does not change the ownership of the underlying memory. The first entity to access the resource implicitly acquires ownership. An entity can also implicitly take ownership from another entity in the same way without an explicit ownership transfer. However, taking ownership in this way has the effect that the contents of the underlying memory are undefined.

Accessing a resource backed by memory that is owned by a particular instance or API has the same semantics as accessing a VK_SHARING_MODE_EXCLUSIVE resource, with one exception: Implementations must ensure layout transitions performed on one member of a set of identical subresources of identical images that alias the same range of an underlying memory object affect the layout of all the subresources in the set.

As a corollary, writes to any image subresources in such a set must not make the contents of memory used by other subresources in the set undefined. An application can define the content of a subresource of one image by performing device writes to an identical subresource of another image provided both images are bound to the same region of external memory. Applications may also add resources to such a set after the content of the existing set members has been defined without making the content undefined by creating a new image with the initial layout VK_IMAGE_LAYOUT_UNDEFINED and binding it to the same region of external memory as the existing images.

Because layout transitions apply to all identical images aliasing the same region of external memory, the actual layout of the memory backing a new image as well as an existing image with defined content will not be undefined. Such an image is not usable until it acquires ownership of its memory from the existing owner. Therefore, the layout specified as part of this transition will be the true initial layout of the image. The undefined layout specified when creating it is a placeholder to simplify valid usage requirements.

Memory Aliasing

A range of a VkDeviceMemory allocation is aliased if it is bound to multiple resources simultaneously, as described below, via vkBindImageMemory, vkBindBufferMemory, vkBindAccelerationStructureMemoryNV, vkBindTensorMemoryARM, via sparse memory bindings, or by binding the memory to resources in multiple Vulkan instances or external APIs using external memory handle export and import mechanisms.

Consider two resources, resourceA and resourceB, bound respectively to memory rangeA and rangeB. Let paddedRangeA and paddedRangeB be, respectively, rangeA and rangeB aligned to bufferImageGranularity. If the resources are both linear or both non-linear (as defined in the Glossary), then the resources alias the memory in the intersection of rangeA and rangeB. If one resource is linear and the other is non-linear, then the resources alias the memory in the intersection of paddedRangeA and paddedRangeB.

Applications can alias memory, but use of multiple aliases is subject to several constraints.

The implementation-dependent limit bufferImageGranularity also applies to tensor resources.

Memory aliasing can be useful to reduce the total device memory footprint of an application, if some large resources are used for disjoint periods of time.

When a non-linear, non-VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT image is bound to an aliased range, all image subresources of the image overlap the range. When a linear image is bound to an aliased range, the image subresources that (according to the image’s advertised layout) include bytes from the aliased range overlap the range. When a VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT image has sparse image blocks bound to an aliased range, only image subresources including those sparse image blocks overlap the range, and when the memory bound to the image’s mip tail overlaps an aliased range all image subresources in the mip tail overlap the range.

Buffers, linear tensors, and linear image subresources are considered host-accessible subresources when they are in any of these layouts:

That is, the host has a well-defined addressing scheme to interpret the contents, and thus the layout of the data in memory can be consistently interpreted across aliases if each of those aliases is a host-accessible subresource. Non-linear images, non-linear tensors, and linear image subresources in other layouts, are not host-accessible.

If two aliases are both host-accessible, then they interpret the contents of the memory in consistent ways, and data written to one alias can be read by the other alias.

For an acceleration structure AS_2 that is an alias of another acceleration structure AS_1, AS_2 can be used in place of AS_1 for operations acting on acceleration structures if the following conditions are met:

After an acceleration structure object is destroyed, aliased acceleration structures may continue being used to refer to that acceleration structure for operations acting on acceleration structures.

If two aliases are both images that were created with identical creation parameters, both were created with the VK_IMAGE_CREATE_ALIAS_BIT flag set, and both are bound identically to memory except for VkBindImageMemoryDeviceGroupInfo::pDeviceIndices and VkBindImageMemoryDeviceGroupInfo::pSplitInstanceBindRegions, then they interpret the contents of the memory in consistent ways, and data written to one alias can be read by the other alias.

Additionally, if an individual plane of a multi-planar image and a single-plane image alias the same memory, then they also interpret the contents of the memory in consistent ways under the same conditions, but with the following modifications:

Aliases created by binding the same memory to resources in multiple Vulkan instances or external APIs using external memory handle export and import mechanisms interpret the contents of the memory in consistent ways, and data written to one alias can be read by the other alias.

Aliases created by binding the same memory to a tensor and an image subresource interpret the contents of the memory in consistent ways if and only if:

Otherwise, the aliases interpret the contents of the memory differently, and writes via one alias make the contents of memory partially or completely undefined to the other alias. If the first alias is a host-accessible subresource, then the bytes affected are those written by the memory operations according to its addressing scheme. If the first alias is not host-accessible, then the bytes affected are those overlapped by the image subresources that were written. If the second alias is a host-accessible subresource, the affected bytes become undefined. If the second alias is not host-accessible, all sparse image blocks (for sparse partially-resident images) or all image subresources (for non-sparse image and fully resident sparse images) that overlap the affected bytes become undefined.

If any image subresources are made undefined due to writes to an alias, then each of those image subresources must have its layout transitioned from VK_IMAGE_LAYOUT_UNDEFINED to a valid layout before it is used, from VK_IMAGE_LAYOUT_ZERO_INITIALIZED_EXT if it is zeroed, or from VK_IMAGE_LAYOUT_PREINITIALIZED if the memory has been written by the host. If any sparse blocks of a sparse image have been made undefined, then only the image subresources containing them must be transitioned.

Use of an overlapping range by two aliases must be separated by a memory dependency using the appropriate access types if at least one of those uses performs writes, whether the aliases interpret memory consistently or not. If buffer or image memory barriers are used, the scope of the barrier must contain the entire range and/or set of image subresources that overlap.

If two aliasing image views are used in the same framebuffer, then the render pass must declare the attachments using the VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT, and follow the other rules listed in that section.

Memory recycled via an application suballocator (i.e. without freeing and reallocating the memory objects) is not substantially different from memory aliasing. However, a suballocator usually waits on a fence before recycling a region of memory, and signaling a fence involves sufficient implicit dependencies to satisfy all the above requirements.

Resource Memory Overlap

Applications can safely access resources concurrently via separate device and host operations as long as the accessed memory locations are guaranteed to not overlap, as defined in Memory Location, and the operation, resource, and access are otherwise independently valid.

Some operations have alignment requirements or access ambiguous memory locations, so the semantics of a particular operation should be considered when determining the overlap. Such requirements will be described alongside the operation. Operations between host and device when using non-coherent memory are aligned to nonCoherentAtomSize, as defined by vkFlushMappedMemoryRanges and vkInvalidateMappedMemoryRanges.

The intent is that buffers (or linear images) can be accessed concurrently, even when they share cache lines, but otherwise do not access the same memory range. The concept of a device cache line size is not exposed in the memory model.

Buffer Collections

Fuchsia’s FIDL-based Sysmem service interoperates with Vulkan via the VK_FUCHSIA_buffer_collection extension.

A buffer collection is a set of one or more buffers which were allocated together as a group and which all have the same properties. These properties describe the buffers' internal representation, such as its dimensions and memory layout. This ensures that all of the buffers can be used interchangeably by tasks that require swapping among multiple buffers, such as double-buffered graphics rendering.

On Fuchsia, the Sysmem service uses buffer collections as a core construct in its design.

Buffer collections are represented by VkBufferCollectionFUCHSIA handles:

// Provided by VK_FUCHSIA_buffer_collection
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkBufferCollectionFUCHSIA)

Definitions

  • FIDL - Fuchsia Interface Definition Language. The declarative language used to define FIDL interprocess communication interfaces on Fuchsia. FIDL files use the fidl extension. FIDL is also used to refer to the services defined by interfaces declared in the FIDL language

  • Sysmem - The FIDL service that facilitates optimal buffer sharing and reuse on Fuchsia

  • client - Any participant of the buffer collection e.g. the Vulkan application

  • token - A zx_handle_t Zircon channel object that allows participation in the buffer collection

Platform Initialization for Buffer Collections

To initialize a buffer collection on Fuchsia:

  • Connect to the Sysmem service to initialize a Sysmem allocator

  • Create an initial buffer collection token using the Sysmem allocator

  • Duplicate the token for each participant beyond the initiator

  • See the Sysmem Overview and fuchsia.sysmem FIDL documentation on fuchsia.dev for more detailed information

Create the Buffer Collection

To create a VkBufferCollectionFUCHSIA for Vulkan to participate in the buffer collection:

// Provided by VK_FUCHSIA_buffer_collection
VkResult vkCreateBufferCollectionFUCHSIA(
    VkDevice                                    device,
    const VkBufferCollectionCreateInfoFUCHSIA*  pCreateInfo,
    const VkAllocationCallbacks*                pAllocator,
    VkBufferCollectionFUCHSIA*                  pCollection);
Valid Usage (Implicit)

  • VUID-vkCreateBufferCollectionFUCHSIA-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkCreateBufferCollectionFUCHSIA-pCreateInfo-parameter
    pCreateInfo must be a valid pointer to a valid VkBufferCollectionCreateInfoFUCHSIA structure

  • VUID-vkCreateBufferCollectionFUCHSIA-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkCreateBufferCollectionFUCHSIA-pCollection-parameter
    pCollection must be a valid pointer to a VkBufferCollectionFUCHSIA handle

  • VUID-vkCreateBufferCollectionFUCHSIA-device-queuecount
    The device must have been created with at least 1 queue

Return Codes
Success
Failure
Host Access

All functions referencing a VkBufferCollectionFUCHSIA must be externally synchronized with the exception of vkCreateBufferCollectionFUCHSIA.

The VkBufferCollectionCreateInfoFUCHSIA structure is defined as:

// Provided by VK_FUCHSIA_buffer_collection
typedef struct VkBufferCollectionCreateInfoFUCHSIA {
    VkStructureType    sType;
    const void*        pNext;
    zx_handle_t        collectionToken;
} VkBufferCollectionCreateInfoFUCHSIA;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure

  • collectionToken is a zx_handle_t containing the Sysmem client’s buffer collection token

Valid Usage

  • VUID-VkBufferCollectionCreateInfoFUCHSIA-collectionToken-06393
    collectionToken must be a valid zx_handle_t to a Zircon channel allocated from Sysmem (fuchsia.sysmem.Allocator/AllocateSharedCollection) with ZX_DEFAULT_CHANNEL_RIGHTS rights

Valid Usage (Implicit)

Set the Constraints

Buffer collections can be established for VkImage allocations or VkBuffer allocations.

Set Image-Based Buffer Collection Constraints

Setting the constraints on the buffer collection initiates the format negotiation and allocation of the buffer collection. To set the constraints on a VkImage buffer collection, call:

// Provided by VK_FUCHSIA_buffer_collection
VkResult vkSetBufferCollectionImageConstraintsFUCHSIA(
    VkDevice                                    device,
    VkBufferCollectionFUCHSIA                   collection,
    const VkImageConstraintsInfoFUCHSIA*        pImageConstraintsInfo);

vkSetBufferCollectionImageConstraintsFUCHSIA may fail if pImageConstraintsInfo->formatConstraintsCount is larger than the implementation-defined limit. If that occurs, vkSetBufferCollectionImageConstraintsFUCHSIA will return VK_ERROR_INITIALIZATION_FAILED.

vkSetBufferCollectionImageConstraintsFUCHSIA may fail if the implementation does not support any of the formats described by the pImageConstraintsInfo structure. If that occurs, vkSetBufferCollectionImageConstraintsFUCHSIA will return VK_ERROR_FORMAT_NOT_SUPPORTED.

Valid Usage

  • VUID-vkSetBufferCollectionImageConstraintsFUCHSIA-collection-06394
    vkSetBufferCollectionImageConstraintsFUCHSIA or vkSetBufferCollectionBufferConstraintsFUCHSIA must not have already been called on collection

Valid Usage (Implicit)

  • VUID-vkSetBufferCollectionImageConstraintsFUCHSIA-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkSetBufferCollectionImageConstraintsFUCHSIA-collection-parameter
    collection must be a valid VkBufferCollectionFUCHSIA handle

  • VUID-vkSetBufferCollectionImageConstraintsFUCHSIA-pImageConstraintsInfo-parameter
    pImageConstraintsInfo must be a valid pointer to a valid VkImageConstraintsInfoFUCHSIA structure

  • VUID-vkSetBufferCollectionImageConstraintsFUCHSIA-collection-parent
    collection must have been created, allocated, or retrieved from device

Return Codes
Success
Failure

The VkImageConstraintsInfoFUCHSIA structure is defined as:

// Provided by VK_FUCHSIA_buffer_collection
typedef struct VkImageConstraintsInfoFUCHSIA {
    VkStructureType                               sType;
    const void*                                   pNext;
    uint32_t                                      formatConstraintsCount;
    const VkImageFormatConstraintsInfoFUCHSIA*    pFormatConstraints;
    VkBufferCollectionConstraintsInfoFUCHSIA      bufferCollectionConstraints;
    VkImageConstraintsInfoFlagsFUCHSIA            flags;
} VkImageConstraintsInfoFUCHSIA;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • formatConstraintsCount is the number of elements in pFormatConstraints.

  • pFormatConstraints is a pointer to an array of VkImageFormatConstraintsInfoFUCHSIA structures of size formatConstraintsCount that is used to further constrain buffer collection format selection for image-based buffer collections.

  • bufferCollectionConstraints is a VkBufferCollectionConstraintsInfoFUCHSIA structure used to supply parameters for the negotiation and allocation for buffer-based buffer collections.

  • flags is a VkImageConstraintsInfoFlagBitsFUCHSIA value specifying hints about the type of memory Sysmem should allocate for the buffer collection.

Valid Usage
Valid Usage (Implicit)
// Provided by VK_FUCHSIA_buffer_collection
typedef VkFlags VkImageConstraintsInfoFlagsFUCHSIA;

VkImageConstraintsInfoFlagsFUCHSIA is a bitmask type for setting a mask of zero or more VkImageConstraintsInfoFlagBitsFUCHSIA bits.

Bits which can be set in VkImageConstraintsInfoFlagBitsFUCHSIA::flags include:

// Provided by VK_FUCHSIA_buffer_collection
typedef enum VkImageConstraintsInfoFlagBitsFUCHSIA {
    VK_IMAGE_CONSTRAINTS_INFO_CPU_READ_RARELY_FUCHSIA = 0x00000001,
    VK_IMAGE_CONSTRAINTS_INFO_CPU_READ_OFTEN_FUCHSIA = 0x00000002,
    VK_IMAGE_CONSTRAINTS_INFO_CPU_WRITE_RARELY_FUCHSIA = 0x00000004,
    VK_IMAGE_CONSTRAINTS_INFO_CPU_WRITE_OFTEN_FUCHSIA = 0x00000008,
    VK_IMAGE_CONSTRAINTS_INFO_PROTECTED_OPTIONAL_FUCHSIA = 0x00000010,
} VkImageConstraintsInfoFlagBitsFUCHSIA;

General hints about the type of memory that should be allocated by Sysmem based on the expected usage of the images in the buffer collection include:

For protected memory:

Note that if all participants in the buffer collection (Vulkan or otherwise) specify that protected memory is optional, Sysmem will not allocate protected memory.

The VkImageFormatConstraintsInfoFUCHSIA structure is defined as:

// Provided by VK_FUCHSIA_buffer_collection
typedef struct VkImageFormatConstraintsInfoFUCHSIA {
    VkStructureType                         sType;
    const void*                             pNext;
    VkImageCreateInfo                       imageCreateInfo;
    VkFormatFeatureFlags                    requiredFormatFeatures;
    VkImageFormatConstraintsFlagsFUCHSIA    flags;
    uint64_t                                sysmemPixelFormat;
    uint32_t                                colorSpaceCount;
    const VkSysmemColorSpaceFUCHSIA*        pColorSpaces;
} VkImageFormatConstraintsInfoFUCHSIA;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure

  • imageCreateInfo is the VkImageCreateInfo used to create a VkImage that is to use memory from the VkBufferCollectionFUCHSIA

  • requiredFormatFeatures is a bitmask of VkFormatFeatureFlagBits specifying required features of the buffers in the buffer collection

  • flags is reserved for future use

  • sysmemPixelFormat is a PixelFormatType value from the fuchsia.sysmem/image_formats.fidl FIDL interface

  • colorSpaceCount is the element count of pColorSpaces

  • pColorSpaces is a pointer to an array of VkSysmemColorSpaceFUCHSIA structs of size colorSpaceCount

Valid Usage (Implicit)

  • VUID-VkImageFormatConstraintsInfoFUCHSIA-sType-sType
    sType must be VK_STRUCTURE_TYPE_IMAGE_FORMAT_CONSTRAINTS_INFO_FUCHSIA

  • VUID-VkImageFormatConstraintsInfoFUCHSIA-pNext-pNext
    pNext must be NULL

  • VUID-VkImageFormatConstraintsInfoFUCHSIA-imageCreateInfo-parameter
    imageCreateInfo must be a valid VkImageCreateInfo structure

  • VUID-VkImageFormatConstraintsInfoFUCHSIA-requiredFormatFeatures-parameter
    requiredFormatFeatures must be a valid combination of VkFormatFeatureFlagBits values

  • VUID-VkImageFormatConstraintsInfoFUCHSIA-requiredFormatFeatures-requiredbitmask
    requiredFormatFeatures must not be 0

  • VUID-VkImageFormatConstraintsInfoFUCHSIA-flags-zerobitmask
    flags must be 0

  • VUID-VkImageFormatConstraintsInfoFUCHSIA-pColorSpaces-parameter
    pColorSpaces must be a valid pointer to an array of colorSpaceCount valid VkSysmemColorSpaceFUCHSIA structures

  • VUID-VkImageFormatConstraintsInfoFUCHSIA-colorSpaceCount-arraylength
    colorSpaceCount must be greater than 0

// Provided by VK_FUCHSIA_buffer_collection
typedef VkFlags VkImageFormatConstraintsFlagsFUCHSIA;

VkImageFormatConstraintsFlagsFUCHSIA is a bitmask type for setting a mask, but is currently reserved for future use.

The VkBufferCollectionConstraintsInfoFUCHSIA structure is defined as:

// Provided by VK_FUCHSIA_buffer_collection
typedef struct VkBufferCollectionConstraintsInfoFUCHSIA {
    VkStructureType    sType;
    const void*        pNext;
    uint32_t           minBufferCount;
    uint32_t           maxBufferCount;
    uint32_t           minBufferCountForCamping;
    uint32_t           minBufferCountForDedicatedSlack;
    uint32_t           minBufferCountForSharedSlack;
} VkBufferCollectionConstraintsInfoFUCHSIA;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure

  • minBufferCount is the minimum number of buffers available in the collection

  • maxBufferCount is the maximum number of buffers allowed in the collection

  • minBufferCountForCamping is the per-participant minimum buffers for camping

  • minBufferCountForDedicatedSlack is the per-participant minimum buffers for dedicated slack

  • minBufferCountForSharedSlack is the per-participant minimum buffers for shared slack

Sysmem uses all buffer count parameters in combination to determine the number of buffers it will allocate. Sysmem defines buffer count constraints in fuchsia.sysmem/constraints.fidl.

Camping as referred to by minBufferCountForCamping, is the number of buffers that should be available for the participant that are not for transient use. This number of buffers is required for the participant to logically operate.

Slack as referred to by minBufferCountForDedicatedSlack and minBufferCountForSharedSlack, refers to the number of buffers desired by participants for optimal performance. minBufferCountForDedicatedSlack refers to the current participant. minBufferCountForSharedSlack refers to buffer slack for all participants in the collection.

Valid Usage (Implicit)

The VkSysmemColorSpaceFUCHSIA structure is defined as:

// Provided by VK_FUCHSIA_buffer_collection
typedef struct VkSysmemColorSpaceFUCHSIA {
    VkStructureType    sType;
    const void*        pNext;
    uint32_t           colorSpace;
} VkSysmemColorSpaceFUCHSIA;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure

  • colorSpace value of the Sysmem ColorSpaceType

Valid Usage

  • VUID-VkSysmemColorSpaceFUCHSIA-colorSpace-06402
    colorSpace must be a ColorSpaceType as defined in fuchsia.sysmem/image_formats.fidl

Valid Usage (Implicit)

Set Buffer-Based Buffer Collection Constraints

To set the constraints on a VkBuffer buffer collection, call:

// Provided by VK_FUCHSIA_buffer_collection
VkResult vkSetBufferCollectionBufferConstraintsFUCHSIA(
    VkDevice                                    device,
    VkBufferCollectionFUCHSIA                   collection,
    const VkBufferConstraintsInfoFUCHSIA*       pBufferConstraintsInfo);

vkSetBufferCollectionBufferConstraintsFUCHSIA may fail if the implementation does not support the constraints specified in the bufferCollectionConstraints structure. If that occurs, vkSetBufferCollectionBufferConstraintsFUCHSIA will return VK_ERROR_FORMAT_NOT_SUPPORTED.

Valid Usage

  • VUID-vkSetBufferCollectionBufferConstraintsFUCHSIA-collection-06403
    vkSetBufferCollectionImageConstraintsFUCHSIA or vkSetBufferCollectionBufferConstraintsFUCHSIA must not have already been called on collection

Valid Usage (Implicit)

  • VUID-vkSetBufferCollectionBufferConstraintsFUCHSIA-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkSetBufferCollectionBufferConstraintsFUCHSIA-collection-parameter
    collection must be a valid VkBufferCollectionFUCHSIA handle

  • VUID-vkSetBufferCollectionBufferConstraintsFUCHSIA-pBufferConstraintsInfo-parameter
    pBufferConstraintsInfo must be a valid pointer to a valid VkBufferConstraintsInfoFUCHSIA structure

  • VUID-vkSetBufferCollectionBufferConstraintsFUCHSIA-collection-parent
    collection must have been created, allocated, or retrieved from device

Return Codes
Success
Failure

The VkBufferConstraintsInfoFUCHSIA structure is defined as:

// Provided by VK_FUCHSIA_buffer_collection
typedef struct VkBufferConstraintsInfoFUCHSIA {
    VkStructureType                             sType;
    const void*                                 pNext;
    VkBufferCreateInfo                          createInfo;
    VkFormatFeatureFlags                        requiredFormatFeatures;
    VkBufferCollectionConstraintsInfoFUCHSIA    bufferCollectionConstraints;
} VkBufferConstraintsInfoFUCHSIA;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure

  • createInfo is a pointer to a VkBufferCreateInfo struct describing the buffer attributes for the buffer collection

  • requiredFormatFeatures is a bitmask of VkFormatFeatureFlagBits required features of the buffers in the buffer collection

  • bufferCollectionConstraints is used to supply parameters for the negotiation and allocation of the buffer collection

Valid Usage
Valid Usage (Implicit)

Retrieve Buffer Collection Properties

After constraints have been set on the buffer collection by calling vkSetBufferCollectionImageConstraintsFUCHSIA or vkSetBufferCollectionBufferConstraintsFUCHSIA, call vkGetBufferCollectionPropertiesFUCHSIA to retrieve the negotiated and finalized properties of the buffer collection.

The call to vkGetBufferCollectionPropertiesFUCHSIA is synchronous. It waits for the Sysmem format negotiation and buffer collection allocation to complete before returning.

// Provided by VK_FUCHSIA_buffer_collection
VkResult vkGetBufferCollectionPropertiesFUCHSIA(
    VkDevice                                    device,
    VkBufferCollectionFUCHSIA                   collection,
    VkBufferCollectionPropertiesFUCHSIA*        pProperties);

For image-based buffer collections, upon calling vkGetBufferCollectionPropertiesFUCHSIA, Sysmem will choose an element of the VkImageConstraintsInfoFUCHSIA::pImageCreateInfos established by the preceding call to vkSetBufferCollectionImageConstraintsFUCHSIA. The index of the element chosen is stored in and can be retrieved from VkBufferCollectionPropertiesFUCHSIA::createInfoIndex.

For buffer-based buffer collections, a single VkBufferCreateInfo is specified as VkBufferConstraintsInfoFUCHSIA::createInfo. VkBufferCollectionPropertiesFUCHSIA::createInfoIndex will therefore always be zero.

vkGetBufferCollectionPropertiesFUCHSIA may fail if Sysmem is unable to resolve the constraints of all of the participants in the buffer collection. If that occurs, vkGetBufferCollectionPropertiesFUCHSIA will return VK_ERROR_INITIALIZATION_FAILED.

Valid Usage
Valid Usage (Implicit)

  • VUID-vkGetBufferCollectionPropertiesFUCHSIA-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetBufferCollectionPropertiesFUCHSIA-collection-parameter
    collection must be a valid VkBufferCollectionFUCHSIA handle

  • VUID-vkGetBufferCollectionPropertiesFUCHSIA-pProperties-parameter
    pProperties must be a valid pointer to a VkBufferCollectionPropertiesFUCHSIA structure

  • VUID-vkGetBufferCollectionPropertiesFUCHSIA-collection-parent
    collection must have been created, allocated, or retrieved from device

Return Codes
Success
Failure

The VkBufferCollectionPropertiesFUCHSIA structure is defined as:

// Provided by VK_FUCHSIA_buffer_collection
typedef struct VkBufferCollectionPropertiesFUCHSIA {
    VkStructureType                  sType;
    void*                            pNext;
    uint32_t                         memoryTypeBits;
    uint32_t                         bufferCount;
    uint32_t                         createInfoIndex;
    uint64_t                         sysmemPixelFormat;
    VkFormatFeatureFlags             formatFeatures;
    VkSysmemColorSpaceFUCHSIA        sysmemColorSpaceIndex;
    VkComponentMapping               samplerYcbcrConversionComponents;
    VkSamplerYcbcrModelConversion    suggestedYcbcrModel;
    VkSamplerYcbcrRange              suggestedYcbcrRange;
    VkChromaLocation                 suggestedXChromaOffset;
    VkChromaLocation                 suggestedYChromaOffset;
} VkBufferCollectionPropertiesFUCHSIA;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure

  • memoryTypeBits is a bitmask containing one bit set for every memory type which the buffer collection can be imported as buffer collection

  • bufferCount is the number of buffers in the collection

  • createInfoIndex as described in Sysmem chosen create infos

  • sysmemPixelFormat is the Sysmem PixelFormatType as defined in fuchsia.sysmem/image_formats.fidl

  • formatFeatures is a bitmask of VkFormatFeatureFlagBits shared by the buffer collection

  • sysmemColorSpaceIndex is a VkSysmemColorSpaceFUCHSIA struct specifying the color space

  • samplerYcbcrConversionComponents is a VkComponentMapping structure specifying the component mapping

  • suggestedYcbcrModel is a VkSamplerYcbcrModelConversion value specifying the suggested Y′CBCR model

  • suggestedYcbcrRange is a VkSamplerYcbcrRange value specifying the suggested Y′CBCR range

  • suggestedXChromaOffset is a VkChromaLocation value specifying the suggested X chroma offset

  • suggestedYChromaOffset is a VkChromaLocation value specifying the suggested Y chroma offset

sysmemColorSpace is only set for image-based buffer collections where the constraints were specified using VkImageConstraintsInfoFUCHSIA in a call to vkSetBufferCollectionImageConstraintsFUCHSIA.

For image-based buffer collections, createInfoIndex will identify both the VkImageConstraintsInfoFUCHSIA::pImageCreateInfos element and the VkImageConstraintsInfoFUCHSIA::pFormatConstraints element chosen by Sysmem when vkSetBufferCollectionImageConstraintsFUCHSIA was called. The value of sysmemColorSpaceIndex will be an index to one of the color spaces provided in the VkImageFormatConstraintsInfoFUCHSIA::pColorSpaces array.

The implementation must have formatFeatures with all bits set that were set in VkImageFormatConstraintsInfoFUCHSIA::requiredFormatFeatures, by the call to vkSetBufferCollectionImageConstraintsFUCHSIA, at createInfoIndex (other bits could be set as well).

Valid Usage (Implicit)

Memory Allocation

To import memory from a buffer collection into a VkImage or a VkBuffer, chain a VkImportMemoryBufferCollectionFUCHSIA structure to the pNext member of the VkMemoryAllocateInfo in the call to vkAllocateMemory.

The VkImportMemoryBufferCollectionFUCHSIA structure is defined as:

// Provided by VK_FUCHSIA_buffer_collection
typedef struct VkImportMemoryBufferCollectionFUCHSIA {
    VkStructureType              sType;
    const void*                  pNext;
    VkBufferCollectionFUCHSIA    collection;
    uint32_t                     index;
} VkImportMemoryBufferCollectionFUCHSIA;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure

  • collection is the VkBufferCollectionFUCHSIA handle

  • index is the index of the buffer to import from collection

Valid Usage
Valid Usage (Implicit)

To release a VkBufferCollectionFUCHSIA:

// Provided by VK_FUCHSIA_buffer_collection
void vkDestroyBufferCollectionFUCHSIA(
    VkDevice                                    device,
    VkBufferCollectionFUCHSIA                   collection,
    const VkAllocationCallbacks*                pAllocator);
Valid Usage
Valid Usage (Implicit)

  • VUID-vkDestroyBufferCollectionFUCHSIA-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkDestroyBufferCollectionFUCHSIA-collection-parameter
    collection must be a valid VkBufferCollectionFUCHSIA handle

  • VUID-vkDestroyBufferCollectionFUCHSIA-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkDestroyBufferCollectionFUCHSIA-collection-parent
    collection must have been created, allocated, or retrieved from device

Tensors

Tensors are similar to images, in that they have multi-dimensional access as documented in the Tensor Operations chapter, but a tensor’s dimensions are not predefined. A tensor can have an arbitrary number of dimensions, up to maxTensorDimensionCount, with one index per dimension used to access the tensor.

Tensors can be used by binding them to pipelines via descriptor sets, or by directly specifying them as parameters to certain commands.

Tensors are represented by VkTensorARM handles:

// Provided by VK_ARM_tensors
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkTensorARM)

To create tensors, call:

// Provided by VK_ARM_tensors
VkResult vkCreateTensorARM(
    VkDevice                                    device,
    const VkTensorCreateInfoARM*                pCreateInfo,
    const VkAllocationCallbacks*                pAllocator,
    VkTensorARM*                                pTensor);

  • device is the logical device that creates the tensor.

  • pCreateInfo is a pointer to a VkTensorCreateInfoARM structure containing parameters to be used to create the tensor.

  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

  • pTensor is a pointer to a VkTensorARM handle in which the resulting tensor object is returned.

Valid Usage

  • VUID-vkCreateTensorARM-tensors-09832
    The tensors feature must be enabled

Valid Usage (Implicit)

  • VUID-vkCreateTensorARM-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkCreateTensorARM-pCreateInfo-parameter
    pCreateInfo must be a valid pointer to a valid VkTensorCreateInfoARM structure

  • VUID-vkCreateTensorARM-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkCreateTensorARM-pTensor-parameter
    pTensor must be a valid pointer to a VkTensorARM handle

  • VUID-vkCreateTensorARM-device-queuecount
    The device must have been created with at least 1 queue

Return Codes
Success
Failure

The VkTensorCreateInfoARM structure is defined as:

// Provided by VK_ARM_tensors
typedef struct VkTensorCreateInfoARM {
    VkStructureType                  sType;
    const void*                      pNext;
    VkTensorCreateFlagsARM           flags;
    const VkTensorDescriptionARM*    pDescription;
    VkSharingMode                    sharingMode;
    uint32_t                         queueFamilyIndexCount;
    const uint32_t*                  pQueueFamilyIndices;
} VkTensorCreateInfoARM;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • flags is a bitmask of VkTensorCreateFlagBitsARM describing additional parameters of the tensor.

  • pDescription is a pointer to an instance of VkTensorDescriptionARM describing the tensor.

  • sharingMode is a VkSharingMode value specifying the sharing mode of the tensor when it will be accessed by multiple queue families.

  • queueFamilyIndexCount is the number of entries in the pQueueFamilyIndices array.

  • pQueueFamilyIndices is a list of queue families that will access this tensor (ignored if sharingMode is not VK_SHARING_MODE_CONCURRENT).

To determine the set of valid usage bits for a given tensor format, call vkGetPhysicalDeviceFormatProperties2 with VkTensorFormatPropertiesARM in the pNext chain.

Tensor Creation Limits

Valid values for some tensor creation parameters are limited by a numerical upper bound or by inclusion in a bitset.

Several limiting values are defined below. The limiting values are referenced by the relevant valid usage statements of VkTensorCreateInfoARM.

  • Let the uint64_t tensorElements define the number of data elements in the tensor computed as the product of all VkTensorCreateInfoARM::pDescription->pDimensions[i] for i between 0 and VkTensorCreateInfoARM::pDescription->dimensionCount - 1.

Valid Usage
Valid Usage (Implicit)

Bits which can be set in VkTensorCreateInfoARM::flags, specifying additional parameters of a tensor, are:

// Provided by VK_ARM_tensors
// Flag bits for VkTensorCreateFlagBitsARM
typedef VkFlags64 VkTensorCreateFlagBitsARM;
static const VkTensorCreateFlagBitsARM VK_TENSOR_CREATE_MUTABLE_FORMAT_BIT_ARM = 0x00000001ULL;
static const VkTensorCreateFlagBitsARM VK_TENSOR_CREATE_PROTECTED_BIT_ARM = 0x00000002ULL;
// Provided by VK_EXT_descriptor_buffer with VK_ARM_tensors
static const VkTensorCreateFlagBitsARM VK_TENSOR_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_ARM = 0x00000004ULL;
// Provided by VK_ARM_tensors
typedef VkFlags64 VkTensorCreateFlagsARM;

VkTensorCreateFlagsARM is a bitmask type for setting a mask of zero or more VkTensorCreateFlagBitsARM.

To define a set of external memory handle types that may be used as backing store for a tensor, add a VkExternalMemoryTensorCreateInfoARM structure to the pNext chain of the VkTensorCreateInfoARM structure.

The VkExternalMemoryTensorCreateInfoARM structure is defined as:

// Provided by VK_ARM_tensors
typedef struct VkExternalMemoryTensorCreateInfoARM {
    VkStructureType                    sType;
    const void*                        pNext;
    VkExternalMemoryHandleTypeFlags    handleTypes;
} VkExternalMemoryTensorCreateInfoARM;

A VkExternalMemoryTensorCreateInfoARM structure with a non-zero handleTypes field must be included in the creation parameters for a tensor that will be bound to memory that is either exported or imported.

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • handleTypes is zero or a bitmask of VkExternalMemoryHandleTypeFlagBits specifying one or more external memory handle types.

Valid Usage (Implicit)

To destroy a tensor, call:

// Provided by VK_ARM_tensors
void vkDestroyTensorARM(
    VkDevice                                    device,
    VkTensorARM                                 tensor,
    const VkAllocationCallbacks*                pAllocator);

  • device is the logical device that destroys the tensor.

  • tensor is the tensor to destroy.

  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

Valid Usage

  • VUID-vkDestroyTensorARM-tensor-09730
    All submitted commands that refer to tensor, either directly or via a VkTensorViewARM, must have completed execution

  • VUID-vkDestroyTensorARM-tensor-09731
    If VkAllocationCallbacks were provided when tensor was created, a compatible set of callbacks must be provided here

  • VUID-vkDestroyTensorARM-tensor-09732
    If no VkAllocationCallbacks were provided when tensor was created, pAllocator must be NULL

Valid Usage (Implicit)

  • VUID-vkDestroyTensorARM-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkDestroyTensorARM-tensor-parameter
    If tensor is not VK_NULL_HANDLE, tensor must be a valid VkTensorARM handle

  • VUID-vkDestroyTensorARM-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkDestroyTensorARM-tensor-parent
    If tensor is a valid handle, it must have been created, allocated, or retrieved from device

Host Synchronization

  • Host access to tensor must be externally synchronized

Tensor Description

The VkTensorDescriptionARM structure is defined as:

// Provided by VK_ARM_tensors
typedef struct VkTensorDescriptionARM {
    VkStructureType          sType;
    const void*              pNext;
    VkTensorTilingARM        tiling;
    VkFormat                 format;
    uint32_t                 dimensionCount;
    const int64_t*           pDimensions;
    const int64_t*           pStrides;
    VkTensorUsageFlagsARM    usage;
} VkTensorDescriptionARM;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • tiling is a VkTensorTilingARM value specifying the tiling of the tensor

  • format is a one component VkFormat describing the format and type of the data elements that will be contained in the tensor.

  • dimensionCount is the number of dimensions for the tensor.

  • pDimensions is a pointer to an array of integers of size dimensionCount providing the number of data elements in each dimension.

  • pStrides is either NULL or is an array of size dimensionCount providing the strides in bytes for the tensor in each dimension.

  • usage is a bitmask of VkTensorUsageFlagBitsARM specifying the usage of the tensor.

When describing a tensor created with VK_TENSOR_TILING_OPTIMAL_ARM, pStrides must be equal to NULL. When describing a tensor created with VK_TENSOR_TILING_LINEAR_ARM, pStrides is either an array of size dimensionCount or NULL.

The formats that must be supported for format are documented in Mandatory tensor format support.

Each element in the pStrides array describes the offset in bytes between increments of the given dimension. For example, pStrides[0] describes the offset between element [x0,x1,x2,x3] and element [x0+1,x1,x2,x3]. The pStrides array can be used to determine whether a tensor is packed or not. If pStrides[dimensionCount-1] is equal to the size of a tensor element and for each dimension n greater than 0 and less than dimensionCount, pStrides[n-1] is equal to pStrides[n] * pDimensions[n], then the tensor is a packed tensor. If the tensorNonPacked feature is not enabled, the tensor must be a packed tensor.

When a tensor is created with VK_TENSOR_TILING_LINEAR_ARM and pStrides equal to NULL the tensor strides are calculated by the vulkan implementation such that the resulting tensor is a packed tensor.

Expressed as an addressing formula, the starting byte of an element in a 4-dimensional, for example, linear tensor has address:

// Assume (x0,x1,x2,x3) are in units of elements.

address(x0,x1,x2,x3) = x0*pStrides[0] + x1*pStrides[1] + x2*pStrides[2] + x3*pStrides[3]
Valid Usage

  • VUID-VkTensorDescriptionARM-dimensionCount-09733
    dimensionCount must be less than or equal to VkPhysicalDeviceTensorPropertiesARM::maxTensorDimensionCount

  • VUID-VkTensorDescriptionARM-pDimensions-09734
    For each i where i ≤ dimensionCount-1, pDimensions[i] must be greater than 0

  • VUID-VkTensorDescriptionARM-pDimensions-09883
    For each i where i ≤ dimensionCount-1, pDimensions[i] must be less than or equal to VkPhysicalDeviceTensorPropertiesARM::maxPerDimensionTensorElements

  • VUID-VkTensorDescriptionARM-format-09735
    format must not be VK_FORMAT_UNDEFINED and must be a one-component VkFormat

  • VUID-VkTensorDescriptionARM-pStrides-09736
    pStrides[dimensionCount-1] must equal the size in bytes of a tensor element

  • VUID-VkTensorDescriptionARM-pStrides-09737
    For each i, pStrides[i] must be a multiple of the element size

  • VUID-VkTensorDescriptionARM-pStrides-09738
    For each i, pStrides[i] must be greater than 0 and less than or equal to VkPhysicalDeviceTensorPropertiesARM::maxTensorStride

  • VUID-VkTensorDescriptionARM-pStrides-09884
    pStrides[0] × pDimensions[0] must be less than or equal to VkPhysicalDeviceTensorPropertiesARM::maxTensorSize

  • VUID-VkTensorDescriptionARM-pStrides-09739
    For each i greater than 0, pStrides[i-1] must be greater than or equal to pStrides[i] × pDimensions[i] so that no two elements of the tensor reference the same memory address

  • VUID-VkTensorDescriptionARM-None-09740
    If the tensorNonPacked feature is not enabled, then the members of VkTensorDescriptionARM must describe a packed tensor

  • VUID-VkTensorDescriptionARM-tiling-09741
    If tiling is VK_TENSOR_TILING_OPTIMAL_ARM and usage is VK_TENSOR_USAGE_IMAGE_ALIASING_BIT_ARM then the size of the tensor along its innermost dimension, i.e. pDimensions[dimensionCount - 1], must be less than or equal to 4

  • VUID-VkTensorDescriptionARM-tiling-09742
    If tiling is VK_TENSOR_TILING_LINEAR_ARM then VK_TENSOR_USAGE_IMAGE_ALIASING_BIT_ARM must not be set in usage

Valid Usage (Implicit)

  • VUID-VkTensorDescriptionARM-sType-sType
    sType must be VK_STRUCTURE_TYPE_TENSOR_DESCRIPTION_ARM

  • VUID-VkTensorDescriptionARM-tiling-parameter
    tiling must be a valid VkTensorTilingARM value

  • VUID-VkTensorDescriptionARM-format-parameter
    format must be a valid VkFormat value

  • VUID-VkTensorDescriptionARM-pDimensions-parameter
    pDimensions must be a valid pointer to an array of dimensionCount int64_t values

  • VUID-VkTensorDescriptionARM-pStrides-parameter
    If pStrides is not NULL, pStrides must be a valid pointer to an array of dimensionCount int64_t values

  • VUID-VkTensorDescriptionARM-usage-parameter
    usage must be a valid combination of VkTensorUsageFlagBitsARM values

  • VUID-VkTensorDescriptionARM-usage-requiredbitmask
    usage must not be 0

  • VUID-VkTensorDescriptionARM-dimensionCount-arraylength
    dimensionCount must be greater than 0

Bits which can be set in VkTensorDescriptionARM::usage, specifying usage behavior of a tensor, are:

// Provided by VK_ARM_tensors
// Flag bits for VkTensorUsageFlagBitsARM
typedef VkFlags64 VkTensorUsageFlagBitsARM;
static const VkTensorUsageFlagBitsARM VK_TENSOR_USAGE_SHADER_BIT_ARM = 0x00000002ULL;
static const VkTensorUsageFlagBitsARM VK_TENSOR_USAGE_TRANSFER_SRC_BIT_ARM = 0x00000004ULL;
static const VkTensorUsageFlagBitsARM VK_TENSOR_USAGE_TRANSFER_DST_BIT_ARM = 0x00000008ULL;
static const VkTensorUsageFlagBitsARM VK_TENSOR_USAGE_IMAGE_ALIASING_BIT_ARM = 0x00000010ULL;
// Provided by VK_ARM_data_graph
static const VkTensorUsageFlagBitsARM VK_TENSOR_USAGE_DATA_GRAPH_BIT_ARM = 0x00000020ULL;
// Provided by VK_ARM_tensors
typedef VkFlags64 VkTensorUsageFlagsARM;

VkTensorUsageFlags is a bitmask type for setting a mask of zero or more VkTensorUsageFlagBitsARM.

Possible values of VkTensorCreateInfoARM::tiling, specifying the tiling arrangement of elements in the tensor, are:

// Provided by VK_ARM_tensors
typedef enum VkTensorTilingARM {
    VK_TENSOR_TILING_OPTIMAL_ARM = 0,
    VK_TENSOR_TILING_LINEAR_ARM = 1,
} VkTensorTilingARM;

  • VK_TENSOR_TILING_OPTIMAL_ARM specifies optimal tiling (elements are laid out in an implementation-dependent arrangement, for more efficient memory access).

  • VK_TENSOR_TILING_LINEAR_ARM specifies linear tiling (elements are laid out linearly and the offset between each element is determined by the strides of the tensor).

Tensor Views

Tensor objects are not directly accessed by pipelines for reading or writing tensor data. Instead, tensor views representing the tensor subresources and containing additional metadata are used for that purpose. Views must be created on tensors of compatible types.

Tensor views are represented by VkTensorViewARM handles:

// Provided by VK_ARM_tensors
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkTensorViewARM)

To create a tensor view, call:

// Provided by VK_ARM_tensors
VkResult vkCreateTensorViewARM(
    VkDevice                                    device,
    const VkTensorViewCreateInfoARM*            pCreateInfo,
    const VkAllocationCallbacks*                pAllocator,
    VkTensorViewARM*                            pView);

  • device is the logical device that creates the tensor view.

  • pCreateInfo is a pointer to an instance of the VkTensorViewCreateInfoARM structure containing parameters to be used to create the tensor view.

  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

  • pView is a pointer to a VkTensorViewARM handle in which the resulting tensor view object is returned.

Some of the tensor creation parameters are inherited by the view. In particular, other than format, the tensor view creation inherits all other parameters from the tensor.

The remaining parameters are contained in pCreateInfo.

Valid Usage (Implicit)

  • VUID-vkCreateTensorViewARM-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkCreateTensorViewARM-pCreateInfo-parameter
    pCreateInfo must be a valid pointer to a valid VkTensorViewCreateInfoARM structure

  • VUID-vkCreateTensorViewARM-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkCreateTensorViewARM-pView-parameter
    pView must be a valid pointer to a VkTensorViewARM handle

  • VUID-vkCreateTensorViewARM-device-queuecount
    The device must have been created with at least 1 queue

Return Codes
Success
Failure

The VkTensorViewCreateInfoARM structure is defined as:

// Provided by VK_ARM_tensors
typedef struct VkTensorViewCreateInfoARM {
    VkStructureType               sType;
    const void*                   pNext;
    VkTensorViewCreateFlagsARM    flags;
    VkTensorARM                   tensor;
    VkFormat                      format;
} VkTensorViewCreateInfoARM;

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • flags is reserved for future use.

  • tensor is a VkTensorARM on which the view will be created.

  • format is a VkFormat describing the format and type used to interpret elements in the tensor.

If tensor was created with the VK_TENSOR_CREATE_MUTABLE_FORMAT_BIT_ARM flag, format can be different from the tensor’s format, but if they are not equal they must be compatible. Tensor format compatibility is defined in the Format Compatibility Classes section. Views of compatible formats will have the same mapping between element locations irrespective of the format, with only the interpretation of the bit pattern changing.

Values intended to be used with one view format may not be exactly preserved when written or read through a different format. For example, an integer value that happens to have the bit pattern of a floating-point denorm or NaN may be flushed or canonicalized when written or read through a view with a floating-point format. Similarly, a value written through a signed normalized format that has a bit pattern exactly equal to -2b may be changed to -2b + 1 as described in Conversion from Normalized Fixed-Point to Floating-Point.
Valid Usage
Valid Usage (Implicit)

Bits which can be set in VkTensorViewCreateInfoARM::flags, specifying additional parameters of an tensor, are:

// Provided by VK_ARM_tensors
// Flag bits for VkTensorViewCreateFlagBitsARM
typedef VkFlags64 VkTensorViewCreateFlagBitsARM;
// Provided by VK_EXT_descriptor_buffer with VK_ARM_tensors
static const VkTensorViewCreateFlagBitsARM VK_TENSOR_VIEW_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_ARM = 0x00000001ULL;
// Provided by VK_ARM_tensors
typedef VkFlags64 VkTensorViewCreateFlagsARM;

VkTensorViewCreateFlagsARM is a bitmask type for setting a mask of zero or more VkTensorViewCreateFlagBitsARM.

To destroy a tensor view, call:

// Provided by VK_ARM_tensors
void vkDestroyTensorViewARM(
    VkDevice                                    device,
    VkTensorViewARM                             tensorView,
    const VkAllocationCallbacks*                pAllocator);

  • device is the logical device that destroys the tensor view.

  • tensorView is the tensor view to destroy.

  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

Valid Usage

  • VUID-vkDestroyTensorViewARM-tensorView-09750
    All submitted commands that refer to tensorView must have completed execution

  • VUID-vkDestroyTensorViewARM-tensorView-09751
    If VkAllocationCallbacks were provided when tensorView was created, a compatible set of callbacks must be provided here

  • VUID-vkDestroyTensorViewARM-tensorView-09752
    If no VkAllocationCallbacks were provided when tensorView was created, pAllocator must be NULL

Valid Usage (Implicit)

  • VUID-vkDestroyTensorViewARM-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkDestroyTensorViewARM-tensorView-parameter
    If tensorView is not VK_NULL_HANDLE, tensorView must be a valid VkTensorViewARM handle

  • VUID-vkDestroyTensorViewARM-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkDestroyTensorViewARM-tensorView-parent
    If tensorView is a valid handle, it must have been created, allocated, or retrieved from device

Host Synchronization

  • Host access to tensorView must be externally synchronized

Tensor View Format Features

Valid usage of a VkTensorViewARM may be constrained by the tensor view’s format features, defined below. Such constraints are documented in the affected valid usage statement.