Vulkan® 1.3.283 - A Specification (with all ratified extensions)

12. Resource Creation

Vulkan supports two primary resource types: buffers and images. 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.

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

12.1. 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-flags-00911
If the flags member of pCreateInfo includes VK_BUFFER_CREATE_SPARSE_BINDING_BIT, creating this VkBuffer must not cause the total required sparse memory for all currently valid sparse resources on the device to exceed VkPhysicalDeviceLimits::sparseAddressSpaceSize

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

Return Codes

Success

VK_SUCCESS

Failure

VK_ERROR_OUT_OF_HOST_MEMORY
VK_ERROR_OUT_OF_DEVICE_MEMORY
VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS_KHR

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 a VkBufferUsageFlags2CreateInfoKHR structure is present in the pNext chain, VkBufferUsageFlags2CreateInfoKHR::usage from that structure is used instead of usage from this structure.

Valid Usage

VUID-VkBufferCreateInfo-None-09499
If the pNext chain does not include a VkBufferUsageFlags2CreateInfoKHR structure, usage must be a valid combination of VkBufferUsageFlagBits values
VUID-VkBufferCreateInfo-None-09500
If the pNext chain does not include a VkBufferUsageFlags2CreateInfoKHR structure, usage must not be 0
VUID-VkBufferCreateInfo-size-00912
size must be greater than 0
VUID-VkBufferCreateInfo-sharingMode-00913
If sharingMode is VK_SHARING_MODE_CONCURRENT, pQueueFamilyIndices must be a valid pointer to an array of queueFamilyIndexCount uint32_t values
VUID-VkBufferCreateInfo-sharingMode-00914
If sharingMode is VK_SHARING_MODE_CONCURRENT, queueFamilyIndexCount must be greater than 1
VUID-VkBufferCreateInfo-sharingMode-01419
If sharingMode is VK_SHARING_MODE_CONCURRENT, each element of pQueueFamilyIndices must be unique and must be less than pQueueFamilyPropertyCount returned by either vkGetPhysicalDeviceQueueFamilyProperties2 or vkGetPhysicalDeviceQueueFamilyProperties for the physicalDevice that was used to create device
VUID-VkBufferCreateInfo-flags-00915
If the sparseBinding feature is not enabled, flags must not contain VK_BUFFER_CREATE_SPARSE_BINDING_BIT
VUID-VkBufferCreateInfo-flags-00916
If the sparseResidencyBuffer feature is not enabled, flags must not contain VK_BUFFER_CREATE_SPARSE_RESIDENCY_BIT
VUID-VkBufferCreateInfo-flags-00917
If the sparseResidencyAliased feature is not enabled, flags must not contain VK_BUFFER_CREATE_SPARSE_ALIASED_BIT
VUID-VkBufferCreateInfo-flags-00918
If flags contains VK_BUFFER_CREATE_SPARSE_RESIDENCY_BIT or VK_BUFFER_CREATE_SPARSE_ALIASED_BIT, it must also contain VK_BUFFER_CREATE_SPARSE_BINDING_BIT
VUID-VkBufferCreateInfo-pNext-00920
If the pNext chain includes a VkExternalMemoryBufferCreateInfo structure, its handleTypes member must only contain bits that are also in VkExternalBufferProperties::externalMemoryProperties.compatibleHandleTypes, as returned by vkGetPhysicalDeviceExternalBufferProperties with pExternalBufferInfo->handleType equal to any one of the handle types specified in VkExternalMemoryBufferCreateInfo::handleTypes
VUID-VkBufferCreateInfo-flags-01887
If the protectedMemory feature is not enabled, flags must not contain VK_BUFFER_CREATE_PROTECTED_BIT
VUID-VkBufferCreateInfo-None-01888
If any of the bits VK_BUFFER_CREATE_SPARSE_BINDING_BIT, VK_BUFFER_CREATE_SPARSE_RESIDENCY_BIT, or VK_BUFFER_CREATE_SPARSE_ALIASED_BIT are set, VK_BUFFER_CREATE_PROTECTED_BIT must not also be set
VUID-VkBufferCreateInfo-opaqueCaptureAddress-03337
If VkBufferOpaqueCaptureAddressCreateInfo::opaqueCaptureAddress is not zero, flags must include VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT
VUID-VkBufferCreateInfo-flags-03338
If flags includes VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT, the bufferDeviceAddressCaptureReplay feature must be enabled
VUID-VkBufferCreateInfo-usage-04813
If usage includes VK_BUFFER_USAGE_VIDEO_DECODE_SRC_BIT_KHR or VK_BUFFER_USAGE_VIDEO_DECODE_DST_BIT_KHR, and flags does not include VK_BUFFER_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHR, then the pNext chain must include a VkVideoProfileListInfoKHR structure with profileCount greater than 0 and pProfiles including at least one VkVideoProfileInfoKHR structure with a videoCodecOperation member specifying a decode operation
VUID-VkBufferCreateInfo-usage-04814
If usage includes VK_BUFFER_USAGE_VIDEO_ENCODE_SRC_BIT_KHR or VK_BUFFER_USAGE_VIDEO_ENCODE_DST_BIT_KHR, and flags does not include VK_BUFFER_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHR, then the pNext chain must include a VkVideoProfileListInfoKHR structure with profileCount greater than 0 and pProfiles including at least one VkVideoProfileInfoKHR structure with a videoCodecOperation member specifying an encode operation
VUID-VkBufferCreateInfo-flags-08325
If flags includes VK_BUFFER_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHR, then videoMaintenance1 must be enabled
VUID-VkBufferCreateInfo-size-06409
size must be less than or equal to VkPhysicalDeviceMaintenance4Properties::maxBufferSize
VUID-VkBufferCreateInfo-flags-09641
If flags includes VK_BUFFER_CREATE_PROTECTED_BIT, then usage must not contain any of the following bits
- VK_BUFFER_USAGE_TRANSFORM_FEEDBACK_BUFFER_BIT_EXT
- VK_BUFFER_USAGE_TRANSFORM_FEEDBACK_COUNTER_BUFFER_BIT_EXT
- VK_BUFFER_USAGE_ACCELERATION_STRUCTURE_BUILD_INPUT_READ_ONLY_BIT_KHR
- VK_BUFFER_USAGE_ACCELERATION_STRUCTURE_STORAGE_BIT_KHR
- VK_BUFFER_USAGE_SHADER_BINDING_TABLE_BIT_KHR
- VK_BUFFER_USAGE_MICROMAP_BUILD_INPUT_READ_ONLY_BIT_EXT
- VK_BUFFER_USAGE_MICROMAP_STORAGE_BIT_EXT

Valid Usage (Implicit)

VUID-VkBufferCreateInfo-sType-sType
sType must be VK_STRUCTURE_TYPE_BUFFER_CREATE_INFO
VUID-VkBufferCreateInfo-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 VkBufferOpaqueCaptureAddressCreateInfo, VkBufferUsageFlags2CreateInfoKHR, VkExternalMemoryBufferCreateInfo, or VkVideoProfileListInfoKHR
VUID-VkBufferCreateInfo-sType-unique
The sType value of each struct in the pNext chain must be unique
VUID-VkBufferCreateInfo-flags-parameter
flags must be a valid combination of VkBufferCreateFlagBits values
VUID-VkBufferCreateInfo-sharingMode-parameter
sharingMode must be a valid VkSharingMode value

The VkBufferUsageFlags2CreateInfoKHR structure is defined as:

// Provided by VK_KHR_maintenance5
typedef struct VkBufferUsageFlags2CreateInfoKHR {
    VkStructureType           sType;
    const void*               pNext;
    VkBufferUsageFlags2KHR    usage;
} 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 VkBufferUsageFlagBits2KHR 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)

VUID-VkBufferUsageFlags2CreateInfoKHR-sType-sType
sType must be VK_STRUCTURE_TYPE_BUFFER_USAGE_FLAGS_2_CREATE_INFO_KHR
VUID-VkBufferUsageFlags2CreateInfoKHR-usage-parameter
usage must be a valid combination of VkBufferUsageFlagBits2KHR values
VUID-VkBufferUsageFlags2CreateInfoKHR-usage-requiredbitmask
usage must not be 0

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

// Provided by VK_KHR_maintenance5
// Flag bits for VkBufferUsageFlagBits2KHR
typedef VkFlags64 VkBufferUsageFlagBits2KHR;
static const VkBufferUsageFlagBits2KHR VK_BUFFER_USAGE_2_TRANSFER_SRC_BIT_KHR = 0x00000001ULL;
static const VkBufferUsageFlagBits2KHR VK_BUFFER_USAGE_2_TRANSFER_DST_BIT_KHR = 0x00000002ULL;
static const VkBufferUsageFlagBits2KHR VK_BUFFER_USAGE_2_UNIFORM_TEXEL_BUFFER_BIT_KHR = 0x00000004ULL;
static const VkBufferUsageFlagBits2KHR VK_BUFFER_USAGE_2_STORAGE_TEXEL_BUFFER_BIT_KHR = 0x00000008ULL;
static const VkBufferUsageFlagBits2KHR VK_BUFFER_USAGE_2_UNIFORM_BUFFER_BIT_KHR = 0x00000010ULL;
static const VkBufferUsageFlagBits2KHR VK_BUFFER_USAGE_2_STORAGE_BUFFER_BIT_KHR = 0x00000020ULL;
static const VkBufferUsageFlagBits2KHR VK_BUFFER_USAGE_2_INDEX_BUFFER_BIT_KHR = 0x00000040ULL;
static const VkBufferUsageFlagBits2KHR VK_BUFFER_USAGE_2_VERTEX_BUFFER_BIT_KHR = 0x00000080ULL;
static const VkBufferUsageFlagBits2KHR VK_BUFFER_USAGE_2_INDIRECT_BUFFER_BIT_KHR = 0x00000100ULL;
// Provided by VK_KHR_maintenance5 with VK_EXT_conditional_rendering
static const VkBufferUsageFlagBits2KHR VK_BUFFER_USAGE_2_CONDITIONAL_RENDERING_BIT_EXT = 0x00000200ULL;
// Provided by VK_KHR_maintenance5 with VK_KHR_ray_tracing_pipeline
static const VkBufferUsageFlagBits2KHR VK_BUFFER_USAGE_2_SHADER_BINDING_TABLE_BIT_KHR = 0x00000400ULL;
// Provided by VK_KHR_maintenance5 with VK_NV_ray_tracing
static const VkBufferUsageFlagBits2KHR VK_BUFFER_USAGE_2_RAY_TRACING_BIT_NV = 0x00000400ULL;
// Provided by VK_KHR_maintenance5 with VK_EXT_transform_feedback
static const VkBufferUsageFlagBits2KHR VK_BUFFER_USAGE_2_TRANSFORM_FEEDBACK_BUFFER_BIT_EXT = 0x00000800ULL;
// Provided by VK_KHR_maintenance5 with VK_EXT_transform_feedback
static const VkBufferUsageFlagBits2KHR VK_BUFFER_USAGE_2_TRANSFORM_FEEDBACK_COUNTER_BUFFER_BIT_EXT = 0x00001000ULL;
// Provided by VK_KHR_maintenance5 with VK_KHR_video_decode_queue
static const VkBufferUsageFlagBits2KHR VK_BUFFER_USAGE_2_VIDEO_DECODE_SRC_BIT_KHR = 0x00002000ULL;
// Provided by VK_KHR_maintenance5 with VK_KHR_video_decode_queue
static const VkBufferUsageFlagBits2KHR VK_BUFFER_USAGE_2_VIDEO_DECODE_DST_BIT_KHR = 0x00004000ULL;
// Provided by VK_KHR_maintenance5 with VK_KHR_video_encode_queue
static const VkBufferUsageFlagBits2KHR VK_BUFFER_USAGE_2_VIDEO_ENCODE_DST_BIT_KHR = 0x00008000ULL;
// Provided by VK_KHR_maintenance5 with VK_KHR_video_encode_queue
static const VkBufferUsageFlagBits2KHR 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 VkBufferUsageFlagBits2KHR VK_BUFFER_USAGE_2_SHADER_DEVICE_ADDRESS_BIT_KHR = 0x00020000ULL;
// Provided by VK_KHR_acceleration_structure with VK_KHR_maintenance5
static const VkBufferUsageFlagBits2KHR 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 VkBufferUsageFlagBits2KHR VK_BUFFER_USAGE_2_ACCELERATION_STRUCTURE_STORAGE_BIT_KHR = 0x00100000ULL;
// Provided by VK_KHR_maintenance5 with VK_EXT_descriptor_buffer
static const VkBufferUsageFlagBits2KHR VK_BUFFER_USAGE_2_SAMPLER_DESCRIPTOR_BUFFER_BIT_EXT = 0x00200000ULL;
// Provided by VK_KHR_maintenance5 with VK_EXT_descriptor_buffer
static const VkBufferUsageFlagBits2KHR VK_BUFFER_USAGE_2_RESOURCE_DESCRIPTOR_BUFFER_BIT_EXT = 0x00400000ULL;
// Provided by VK_KHR_maintenance5 with VK_EXT_descriptor_buffer
static const VkBufferUsageFlagBits2KHR VK_BUFFER_USAGE_2_PUSH_DESCRIPTORS_DESCRIPTOR_BUFFER_BIT_EXT = 0x04000000ULL;
// Provided by VK_KHR_maintenance5 with VK_EXT_opacity_micromap
static const VkBufferUsageFlagBits2KHR VK_BUFFER_USAGE_2_MICROMAP_BUILD_INPUT_READ_ONLY_BIT_EXT = 0x00800000ULL;
// Provided by VK_KHR_maintenance5 with VK_EXT_opacity_micromap
static const VkBufferUsageFlagBits2KHR VK_BUFFER_USAGE_2_MICROMAP_STORAGE_BIT_EXT = 0x01000000ULL;

VK_BUFFER_USAGE_2_TRANSFER_SRC_BIT_KHR specifies that the buffer can be used as the source of a transfer command (see the definition of VK_PIPELINE_STAGE_TRANSFER_BIT).
VK_BUFFER_USAGE_2_TRANSFER_DST_BIT_KHR specifies that the buffer can be used as the destination of a transfer command.
VK_BUFFER_USAGE_2_UNIFORM_TEXEL_BUFFER_BIT_KHR specifies that the buffer can be used to create a VkBufferView suitable for occupying a VkDescriptorSet slot of type VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER.
VK_BUFFER_USAGE_2_STORAGE_TEXEL_BUFFER_BIT_KHR specifies that the buffer can be used to create a VkBufferView suitable for occupying a VkDescriptorSet slot of type VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER.
VK_BUFFER_USAGE_2_UNIFORM_BUFFER_BIT_KHR specifies that the buffer can be used in a VkDescriptorBufferInfo suitable for occupying a VkDescriptorSet slot either of type VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER or VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC.
VK_BUFFER_USAGE_2_STORAGE_BUFFER_BIT_KHR specifies that the buffer can be used in a VkDescriptorBufferInfo suitable for occupying a VkDescriptorSet slot either of type VK_DESCRIPTOR_TYPE_STORAGE_BUFFER or VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC.
VK_BUFFER_USAGE_2_INDEX_BUFFER_BIT_KHR specifies that the buffer is suitable for passing as the buffer parameter to vkCmdBindIndexBuffer2KHR and vkCmdBindIndexBuffer.
VK_BUFFER_USAGE_2_VERTEX_BUFFER_BIT_KHR specifies that the buffer is suitable for passing as an element of the pBuffers array to vkCmdBindVertexBuffers.
VK_BUFFER_USAGE_2_INDIRECT_BUFFER_BIT_KHR specifies that the buffer is suitable for passing as the buffer parameter to vkCmdDrawIndirect, vkCmdDrawIndexedIndirect, or vkCmdDispatchIndirect.
VK_BUFFER_USAGE_2_TRANSFORM_FEEDBACK_BUFFER_BIT_EXT specifies that the buffer is suitable for using for binding as a transform feedback buffer with vkCmdBindTransformFeedbackBuffersEXT.
VK_BUFFER_USAGE_2_TRANSFORM_FEEDBACK_COUNTER_BUFFER_BIT_EXT specifies that the buffer is suitable for using as a counter buffer with vkCmdBeginTransformFeedbackEXT and vkCmdEndTransformFeedbackEXT.
VK_BUFFER_USAGE_2_SHADER_BINDING_TABLE_BIT_KHR specifies that the buffer is suitable for use as a Shader Binding Table.
VK_BUFFER_USAGE_2_ACCELERATION_STRUCTURE_BUILD_INPUT_READ_ONLY_BIT_KHR specifies that the buffer is suitable for use as a read-only input to an acceleration structure build.
VK_BUFFER_USAGE_2_ACCELERATION_STRUCTURE_STORAGE_BIT_KHR specifies that the buffer is suitable for storage space for a VkAccelerationStructureKHR.
VK_BUFFER_USAGE_2_SHADER_DEVICE_ADDRESS_BIT_KHR specifies that the buffer can be used to retrieve a buffer device address via vkGetBufferDeviceAddress and use that address to access the buffer’s memory from a shader.
VK_BUFFER_USAGE_2_VIDEO_DECODE_SRC_BIT_KHR specifies that the buffer can be used as the source video bitstream buffer in a video decode operation.
VK_BUFFER_USAGE_2_VIDEO_DECODE_DST_BIT_KHR is reserved for future use.
VK_BUFFER_USAGE_2_VIDEO_ENCODE_DST_BIT_KHR specifies that the buffer can be used as the destination video bitstream buffer in a video encode operation.
VK_BUFFER_USAGE_2_VIDEO_ENCODE_SRC_BIT_KHR is reserved for future use.

// Provided by VK_KHR_maintenance5
typedef VkFlags64 VkBufferUsageFlags2KHR;

VkBufferUsageFlags2KHR is a bitmask type for setting a mask of zero or more VkBufferUsageFlagBits2KHR.

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_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_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_KHR_buffer_device_address
    VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT_KHR = VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT,
} VkBufferUsageFlagBits;

VK_BUFFER_USAGE_TRANSFER_SRC_BIT specifies that the buffer can be used as the source of a transfer command (see the definition of VK_PIPELINE_STAGE_TRANSFER_BIT).
VK_BUFFER_USAGE_TRANSFER_DST_BIT specifies that the buffer can be used as the destination of a transfer command.
VK_BUFFER_USAGE_UNIFORM_TEXEL_BUFFER_BIT specifies that the buffer can be used to create a VkBufferView suitable for occupying a VkDescriptorSet slot of type VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER.
VK_BUFFER_USAGE_STORAGE_TEXEL_BUFFER_BIT specifies that the buffer can be used to create a VkBufferView suitable for occupying a VkDescriptorSet slot of type VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER.
VK_BUFFER_USAGE_UNIFORM_BUFFER_BIT specifies that the buffer can be used in a VkDescriptorBufferInfo suitable for occupying a VkDescriptorSet slot either of type VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER or VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC.
VK_BUFFER_USAGE_STORAGE_BUFFER_BIT specifies that the buffer can be used in a VkDescriptorBufferInfo suitable for occupying a VkDescriptorSet slot either of type VK_DESCRIPTOR_TYPE_STORAGE_BUFFER or VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC.
VK_BUFFER_USAGE_INDEX_BUFFER_BIT specifies that the buffer is suitable for passing as the buffer parameter to vkCmdBindIndexBuffer2KHR and vkCmdBindIndexBuffer.
VK_BUFFER_USAGE_VERTEX_BUFFER_BIT specifies that the buffer is suitable for passing as an element of the pBuffers array to vkCmdBindVertexBuffers.
VK_BUFFER_USAGE_INDIRECT_BUFFER_BIT specifies that the buffer is suitable for passing as the buffer parameter to vkCmdDrawIndirect, vkCmdDrawIndexedIndirect, or vkCmdDispatchIndirect.
VK_BUFFER_USAGE_TRANSFORM_FEEDBACK_BUFFER_BIT_EXT specifies that the buffer is suitable for using for binding as a transform feedback buffer with vkCmdBindTransformFeedbackBuffersEXT.
VK_BUFFER_USAGE_TRANSFORM_FEEDBACK_COUNTER_BUFFER_BIT_EXT specifies that the buffer is suitable for using as a counter buffer with vkCmdBeginTransformFeedbackEXT and vkCmdEndTransformFeedbackEXT.
VK_BUFFER_USAGE_SHADER_BINDING_TABLE_BIT_KHR specifies that the buffer is suitable for use as a Shader Binding Table.
VK_BUFFER_USAGE_ACCELERATION_STRUCTURE_BUILD_INPUT_READ_ONLY_BIT_KHR specifies that the buffer is suitable for use as a read-only input to an acceleration structure build.
VK_BUFFER_USAGE_ACCELERATION_STRUCTURE_STORAGE_BIT_KHR specifies that the buffer is suitable for storage space for a VkAccelerationStructureKHR.
VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT specifies that the buffer can be used to retrieve a buffer device address via vkGetBufferDeviceAddress and use that address to access the buffer’s memory from a shader.
VK_BUFFER_USAGE_VIDEO_DECODE_SRC_BIT_KHR specifies that the buffer can be used as the source video bitstream buffer in a video decode operation.
VK_BUFFER_USAGE_VIDEO_DECODE_DST_BIT_KHR is reserved for future use.
VK_BUFFER_USAGE_VIDEO_ENCODE_DST_BIT_KHR specifies that the buffer can be used as the destination video bitstream buffer in a video encode operation.
VK_BUFFER_USAGE_VIDEO_ENCODE_SRC_BIT_KHR is reserved for future use.

// 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_KHR_video_maintenance1
    VK_BUFFER_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHR = 0x00000040,
  // 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;

VK_BUFFER_CREATE_SPARSE_BINDING_BIT specifies that the buffer will be backed using sparse memory binding.
VK_BUFFER_CREATE_SPARSE_RESIDENCY_BIT specifies that the buffer can be partially backed using sparse memory binding. Buffers created with this flag must also be created with the VK_BUFFER_CREATE_SPARSE_BINDING_BIT flag.
VK_BUFFER_CREATE_SPARSE_ALIASED_BIT specifies that the buffer will be backed using sparse memory binding with memory ranges that might also simultaneously be backing another buffer (or another portion of the same buffer). Buffers created with this flag must also be created with the VK_BUFFER_CREATE_SPARSE_BINDING_BIT flag.
VK_BUFFER_CREATE_PROTECTED_BIT specifies that the buffer is a protected buffer.
VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT specifies that the buffer’s address can be saved and reused on a subsequent run (e.g. for trace capture and replay), see VkBufferOpaqueCaptureAddressCreateInfo for more detail.
VK_BUFFER_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHR specifies that the buffer can be used in video coding operations without having to specify at buffer creation time the set of video profiles the buffer will be used with.

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.

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;

or the equivalent

// Provided by VK_KHR_external_memory
typedef VkExternalMemoryBufferCreateInfo VkExternalMemoryBufferCreateInfoKHR;

Note

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)

VUID-VkExternalMemoryBufferCreateInfo-sType-sType
sType must be VK_STRUCTURE_TYPE_EXTERNAL_MEMORY_BUFFER_CREATE_INFO
VUID-VkExternalMemoryBufferCreateInfo-handleTypes-parameter
handleTypes must be a valid combination of VkExternalMemoryHandleTypeFlagBits values

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;

or the equivalent

// Provided by VK_KHR_buffer_device_address
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.

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

Note

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. Apps/tools should avoid mixing app-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)

VUID-VkBufferOpaqueCaptureAddressCreateInfo-sType-sType
sType must be VK_STRUCTURE_TYPE_BUFFER_OPAQUE_CAPTURE_ADDRESS_CREATE_INFO

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

12.2. 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:

VK_BUFFER_USAGE_UNIFORM_TEXEL_BUFFER_BIT
VK_BUFFER_USAGE_STORAGE_TEXEL_BUFFER_BIT

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 (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

Return Codes

Success

VK_SUCCESS

Failure

VK_ERROR_OUT_OF_HOST_MEMORY
VK_ERROR_OUT_OF_DEVICE_MEMORY

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 VkBufferUsageFlags2CreateInfoKHR 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

VUID-VkBufferViewCreateInfo-offset-00925
offset must be less than the size of buffer
VUID-VkBufferViewCreateInfo-range-00928
If range is not equal to VK_WHOLE_SIZE, range must be greater than 0
VUID-VkBufferViewCreateInfo-range-00929
If range is not equal to VK_WHOLE_SIZE, range must be an integer multiple of the texel block size of format
VUID-VkBufferViewCreateInfo-range-00930
If range is not equal to VK_WHOLE_SIZE, the number of texel buffer elements given by (⌊range / (texel block size)⌋ × (texels per block)) where texel block size and texels per block are as defined in the Compatible Formats table for format, must be less than or equal to VkPhysicalDeviceLimits::maxTexelBufferElements
VUID-VkBufferViewCreateInfo-offset-00931
If range is not equal to VK_WHOLE_SIZE, the sum of offset and range must be less than or equal to the size of buffer
VUID-VkBufferViewCreateInfo-range-04059
If range is equal to VK_WHOLE_SIZE, the number of texel buffer elements given by (⌊(size - offset) / (texel block size)⌋ × (texels per block)) where size is the size of buffer, and texel block size and texels per block are as defined in the Compatible Formats table for format, must be less than or equal to VkPhysicalDeviceLimits::maxTexelBufferElements
VUID-VkBufferViewCreateInfo-buffer-00932
buffer must have been created with a usage value containing at least one of VK_BUFFER_USAGE_UNIFORM_TEXEL_BUFFER_BIT or VK_BUFFER_USAGE_STORAGE_TEXEL_BUFFER_BIT
VUID-VkBufferViewCreateInfo-format-08778
If the buffer view usage contains VK_BUFFER_USAGE_UNIFORM_TEXEL_BUFFER_BIT, then format features of format must contain VK_FORMAT_FEATURE_UNIFORM_TEXEL_BUFFER_BIT
VUID-VkBufferViewCreateInfo-format-08779
If the buffer view usage contains VK_BUFFER_USAGE_STORAGE_TEXEL_BUFFER_BIT, then format features of format must contain VK_FORMAT_FEATURE_STORAGE_TEXEL_BUFFER_BIT
VUID-VkBufferViewCreateInfo-buffer-00935
If buffer is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object
VUID-VkBufferViewCreateInfo-offset-02749
If the texelBufferAlignment feature is not enabled, offset must be a multiple of VkPhysicalDeviceLimits::minTexelBufferOffsetAlignment
VUID-VkBufferViewCreateInfo-buffer-02750
If the texelBufferAlignment feature is enabled and if buffer was created with usage containing VK_BUFFER_USAGE_STORAGE_TEXEL_BUFFER_BIT, offset must be a multiple of the lesser of VkPhysicalDeviceTexelBufferAlignmentProperties::storageTexelBufferOffsetAlignmentBytes or, if VkPhysicalDeviceTexelBufferAlignmentProperties::storageTexelBufferOffsetSingleTexelAlignment is VK_TRUE, the size of a texel of the requested format. If the size of a texel is a multiple of three bytes, then the size of a single component of format is used instead
VUID-VkBufferViewCreateInfo-buffer-02751
If the texelBufferAlignment feature is enabled and if buffer was created with usage containing VK_BUFFER_USAGE_UNIFORM_TEXEL_BUFFER_BIT, offset must be a multiple of the lesser of VkPhysicalDeviceTexelBufferAlignmentProperties::uniformTexelBufferOffsetAlignmentBytes or, if VkPhysicalDeviceTexelBufferAlignmentProperties::uniformTexelBufferOffsetSingleTexelAlignment is VK_TRUE, the size of a texel of the requested format. If the size of a texel is a multiple of three bytes, then the size of a single component of format is used instead
VUID-VkBufferViewCreateInfo-pNext-08780
If the pNext chain includes a VkBufferUsageFlags2CreateInfoKHR, its usage must not contain any other bit than VK_BUFFER_USAGE_2_UNIFORM_TEXEL_BUFFER_BIT_KHR or VK_BUFFER_USAGE_2_STORAGE_TEXEL_BUFFER_BIT_KHR
VUID-VkBufferViewCreateInfo-pNext-08781
If the pNext chain includes a VkBufferUsageFlags2CreateInfoKHR, its usage must be a subset of the VkBufferCreateInfo::usage specified or VkBufferUsageFlags2CreateInfoKHR::usage from VkBufferCreateInfo::pNext when creating buffer

Valid Usage (Implicit)

VUID-VkBufferViewCreateInfo-sType-sType
sType must be VK_STRUCTURE_TYPE_BUFFER_VIEW_CREATE_INFO
VUID-VkBufferViewCreateInfo-pNext-pNext
pNext must be NULL or a pointer to a valid instance of VkBufferUsageFlags2CreateInfoKHR
VUID-VkBufferViewCreateInfo-sType-unique
The sType value of each struct in the pNext chain must be unique
VUID-VkBufferViewCreateInfo-flags-zerobitmask
flags must be 0
VUID-VkBufferViewCreateInfo-buffer-parameter
buffer must be a valid VkBuffer handle
VUID-VkBufferViewCreateInfo-format-parameter
format must be a valid VkFormat value

// 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

12.2.1. 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.

If Vulkan 1.3 is supported or the VK_KHR_format_feature_flags2 extension is supported, then the buffer view’s set of format features is the value of VkFormatProperties3::bufferFeatures found by calling vkGetPhysicalDeviceFormatProperties2 on the same format as VkBufferViewCreateInfo::format.

12.3. Images

Images represent multidimensional - up to 3 - arrays of data which can be used for various purposes (e.g. attachments, textures), by binding them to a graphics or compute pipeline via descriptor sets, or by directly specifying them as parameters to certain commands.

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-flags-00939
If the flags member of pCreateInfo includes VK_IMAGE_CREATE_SPARSE_BINDING_BIT, creating this VkImage must not cause the total required sparse memory for all currently valid sparse resources on the device to exceed VkPhysicalDeviceLimits::sparseAddressSpaceSize

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

Return Codes

Success

VK_SUCCESS

Failure

VK_ERROR_OUT_OF_HOST_MEMORY
VK_ERROR_OUT_OF_DEVICE_MEMORY
VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS_KHR

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 data elements 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:

imageType is VK_IMAGE_TYPE_2D
format is not a depth/stencil format
mipLevels is 1
arrayLayers is 1
samples is VK_SAMPLE_COUNT_1_BIT
usage only includes VK_IMAGE_USAGE_TRANSFER_SRC_BIT and/or VK_IMAGE_USAGE_TRANSFER_DST_BIT

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

imageType is VK_IMAGE_TYPE_2D
mipLevels is 1
arrayLayers is 1, unless otherwise indicated by VkImageFormatProperties::maxArrayLayers, as returned by vkGetPhysicalDeviceImageFormatProperties
samples is VK_SAMPLE_COUNT_1_BIT

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 VkPhysicalDeviceHostImageCopyPropertiesEXT::identicalMemoryTypeRequirements, usage of VK_IMAGE_USAGE_HOST_TRANSFER_BIT_EXT must not affect the memory type requirements of the image as described in Sparse Resource Memory Requirements and Resource Memory Association.

Note

For images created without VK_IMAGE_CREATE_EXTENDED_USAGE_BIT 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.

Let VkBool32 imageCreateMaybeLinear indicate if the resultant image may be linear. (The definition below is trivial because certain extensions are disabled in this build of the specification).
- If tiling is VK_IMAGE_TILING_LINEAR, then imageCreateMaybeLinear is VK_TRUE.
- If tiling is VK_IMAGE_TILING_OPTIMAL, then imageCreateMaybeLinear is VK_FALSE.
Let VkFormatFeatureFlags imageCreateFormatFeatures be the set of valid format features available during image creation.
- If tiling is VK_IMAGE_TILING_LINEAR, then imageCreateFormatFeatures is the value of VkFormatProperties::linearTilingFeatures found by calling vkGetPhysicalDeviceFormatProperties with parameter format equal to VkImageCreateInfo::format.
- If tiling is VK_IMAGE_TILING_OPTIMAL, then imageCreateFormatFeatures is the value of VkFormatProperties::optimalTilingFeatures found by calling vkGetPhysicalDeviceFormatProperties with parameter format equal to VkImageCreateInfo::format.
Let VkImageFormatProperties2 imageCreateImageFormatPropertiesList[] be the list of structures obtained by calling vkGetPhysicalDeviceImageFormatProperties2, possibly multiple times, as follows:
- The parameters VkPhysicalDeviceImageFormatInfo2::format, imageType, tiling, usage, and flags must be equal to those in VkImageCreateInfo.
- If VkImageCreateInfo::pNext contains a VkExternalMemoryImageCreateInfo structure whose handleTypes is not 0, then VkPhysicalDeviceImageFormatInfo2::pNext must contain a VkPhysicalDeviceExternalImageFormatInfo structure whose handleType is not 0; and vkGetPhysicalDeviceImageFormatProperties2 must be called for each handle type in VkExternalMemoryImageCreateInfo::handleTypes, successively setting VkPhysicalDeviceExternalImageFormatInfo::handleType on each call.
- If VkImageCreateInfo::pNext contains no VkExternalMemoryImageCreateInfo structure, or contains a structure whose handleTypes is 0, then VkPhysicalDeviceImageFormatInfo2::pNext must either contain no VkPhysicalDeviceExternalImageFormatInfo structure, or contain a structure whose handleType is 0.
- If VkImageCreateInfo::pNext contains a VkVideoProfileListInfoKHR structure then VkPhysicalDeviceImageFormatInfo2::pNext must also contain the same VkVideoProfileListInfoKHR structure on each call.
- If any call to vkGetPhysicalDeviceImageFormatProperties2 returns an error, then imageCreateImageFormatPropertiesList is defined to be the empty list.
Let uint32_t imageCreateMaxMipLevels be the minimum value of VkImageFormatProperties::maxMipLevels in imageCreateImageFormatPropertiesList. The value is undefined if imageCreateImageFormatPropertiesList is empty.
Let uint32_t imageCreateMaxArrayLayers be the minimum value of VkImageFormatProperties::maxArrayLayers in imageCreateImageFormatPropertiesList. The value is undefined if imageCreateImageFormatPropertiesList is empty.
Let VkExtent3D imageCreateMaxExtent be the component-wise minimum over all VkImageFormatProperties::maxExtent values in imageCreateImageFormatPropertiesList. The value is undefined if imageCreateImageFormatPropertiesList is empty.
Let VkSampleCountFlags imageCreateSampleCounts be the intersection of each VkImageFormatProperties::sampleCounts in imageCreateImageFormatPropertiesList. The value is undefined if imageCreateImageFormatPropertiesList is empty.
Let VkVideoFormatPropertiesKHR videoFormatProperties[] be defined as follows.
- If VkImageCreateInfo::pNext contains a VkVideoProfileListInfoKHR structure, then videoFormatProperties is the list of structures obtained by calling vkGetPhysicalDeviceVideoFormatPropertiesKHR with VkPhysicalDeviceVideoFormatInfoKHR::imageUsage equal to the usage member of VkImageCreateInfo and VkPhysicalDeviceVideoFormatInfoKHR::pNext containing the same VkVideoProfileListInfoKHR structure chained to VkImageCreateInfo.
- If VkImageCreateInfo::pNext contains no VkVideoProfileListInfoKHR structure, then videoFormatProperties is an empty list.
Let VkBool32 supportedVideoFormat indicate if the image parameters are supported by the specified video profiles.
- supportedVideoFormat is VK_TRUE if there exists an element in the videoFormatProperties list for which all of the following conditions are true:
  - VkImageCreateInfo::format equals VkVideoFormatPropertiesKHR::format.
  - VkImageCreateInfo::flags only contains bits also set in VkVideoFormatPropertiesKHR::imageCreateFlags.
  - VkImageCreateInfo::imageType equals VkVideoFormatPropertiesKHR::imageType.
  - VkImageCreateInfo::tiling equals VkVideoFormatPropertiesKHR::imageTiling.
  - VkImageCreateInfo::usage only contains bits also set in VkVideoFormatPropertiesKHR::imageUsageFlags, or VkImageCreateInfo::flags includes VK_IMAGE_CREATE_EXTENDED_USAGE_BIT.
- Otherwise supportedVideoFormat is VK_FALSE.

Valid Usage

VUID-VkImageCreateInfo-imageCreateMaxMipLevels-02251
Each of the following values (as described in Image Creation Limits) must not be undefined : imageCreateMaxMipLevels, imageCreateMaxArrayLayers, imageCreateMaxExtent, and imageCreateSampleCounts
VUID-VkImageCreateInfo-sharingMode-00941
If sharingMode is VK_SHARING_MODE_CONCURRENT, pQueueFamilyIndices must be a valid pointer to an array of queueFamilyIndexCount uint32_t values
VUID-VkImageCreateInfo-sharingMode-00942
If sharingMode is VK_SHARING_MODE_CONCURRENT, queueFamilyIndexCount must be greater than 1
VUID-VkImageCreateInfo-sharingMode-01420
If sharingMode is VK_SHARING_MODE_CONCURRENT, each element of pQueueFamilyIndices must be unique and must be less than pQueueFamilyPropertyCount returned by either vkGetPhysicalDeviceQueueFamilyProperties or vkGetPhysicalDeviceQueueFamilyProperties2 for the physicalDevice that was used to create device
VUID-VkImageCreateInfo-format-00943
format must not be VK_FORMAT_UNDEFINED
VUID-VkImageCreateInfo-extent-00944
extent.width must be greater than 0
VUID-VkImageCreateInfo-extent-00945
extent.height must be greater than 0
VUID-VkImageCreateInfo-extent-00946
extent.depth must be greater than 0
VUID-VkImageCreateInfo-mipLevels-00947
mipLevels must be greater than 0
VUID-VkImageCreateInfo-arrayLayers-00948
arrayLayers must be greater than 0
VUID-VkImageCreateInfo-flags-00949
If flags contains VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT, imageType must be VK_IMAGE_TYPE_2D
VUID-VkImageCreateInfo-flags-08865
If flags contains VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT, extent.width and extent.height must be equal
VUID-VkImageCreateInfo-flags-08866
If flags contains VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT, arrayLayers must be greater than or equal to 6
VUID-VkImageCreateInfo-flags-00950
If flags contains VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT, imageType must be VK_IMAGE_TYPE_3D
VUID-VkImageCreateInfo-flags-09403
If flags contains VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT, flags must not include VK_IMAGE_CREATE_SPARSE_ALIASED_BIT, VK_IMAGE_CREATE_SPARSE_BINDING_BIT, or VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT
VUID-VkImageCreateInfo-extent-02252
extent.width must be less than or equal to imageCreateMaxExtent.width (as defined in Image Creation Limits)
VUID-VkImageCreateInfo-extent-02253
extent.height must be less than or equal to imageCreateMaxExtent.height (as defined in Image Creation Limits)
VUID-VkImageCreateInfo-extent-02254
extent.depth must be less than or equal to imageCreateMaxExtent.depth (as defined in Image Creation Limits)
VUID-VkImageCreateInfo-imageType-00956
If imageType is VK_IMAGE_TYPE_1D, both extent.height and extent.depth must be 1
VUID-VkImageCreateInfo-imageType-00957
If imageType is VK_IMAGE_TYPE_2D, extent.depth must be 1
VUID-VkImageCreateInfo-mipLevels-00958
mipLevels must be less than or equal to the number of levels in the complete mipmap chain based on extent.width, extent.height, and extent.depth
VUID-VkImageCreateInfo-mipLevels-02255
mipLevels must be less than or equal to imageCreateMaxMipLevels (as defined in Image Creation Limits)
VUID-VkImageCreateInfo-arrayLayers-02256
arrayLayers must be less than or equal to imageCreateMaxArrayLayers (as defined in Image Creation Limits)
VUID-VkImageCreateInfo-imageType-00961
If imageType is VK_IMAGE_TYPE_3D, arrayLayers must be 1
VUID-VkImageCreateInfo-samples-02257
If samples is not VK_SAMPLE_COUNT_1_BIT, then imageType must be VK_IMAGE_TYPE_2D, flags must not contain VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT, mipLevels must be equal to 1, and imageCreateMaybeLinear (as defined in Image Creation Limits) must be VK_FALSE,
VUID-VkImageCreateInfo-usage-00963
If usage includes VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT, then bits other than VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT, VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, and VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT must not be set
VUID-VkImageCreateInfo-usage-00964
If usage includes VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT, VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT, or VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT, extent.width must be less than or equal to VkPhysicalDeviceLimits::maxFramebufferWidth
VUID-VkImageCreateInfo-usage-00965
If usage includes VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT, VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT, or VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT, extent.height must be less than or equal to VkPhysicalDeviceLimits::maxFramebufferHeight
VUID-VkImageCreateInfo-usage-00966
If usage includes VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT, usage must also contain at least one of VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT, VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, or VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT
VUID-VkImageCreateInfo-samples-02258
samples must be a valid VkSampleCountFlagBits value that is set in imageCreateSampleCounts (as defined in Image Creation Limits)
VUID-VkImageCreateInfo-usage-00968
If the shaderStorageImageMultisample feature is not enabled, and usage contains VK_IMAGE_USAGE_STORAGE_BIT, samples must be VK_SAMPLE_COUNT_1_BIT
VUID-VkImageCreateInfo-flags-00969
If the sparseBinding feature is not enabled, flags must not contain VK_IMAGE_CREATE_SPARSE_BINDING_BIT
VUID-VkImageCreateInfo-flags-01924
If the sparseResidencyAliased feature is not enabled, flags must not contain VK_IMAGE_CREATE_SPARSE_ALIASED_BIT
VUID-VkImageCreateInfo-tiling-04121
If tiling is VK_IMAGE_TILING_LINEAR, flags must not contain VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT
VUID-VkImageCreateInfo-imageType-00970
If imageType is VK_IMAGE_TYPE_1D, flags must not contain VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT
VUID-VkImageCreateInfo-imageType-00971
If the sparseResidencyImage2D feature is not enabled, and imageType is VK_IMAGE_TYPE_2D, flags must not contain VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT
VUID-VkImageCreateInfo-imageType-00972
If the sparseResidencyImage3D feature is not enabled, and imageType is VK_IMAGE_TYPE_3D, flags must not contain VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT
VUID-VkImageCreateInfo-imageType-00973
If the sparseResidency2Samples feature is not enabled, imageType is VK_IMAGE_TYPE_2D, and samples is VK_SAMPLE_COUNT_2_BIT, flags must not contain VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT
VUID-VkImageCreateInfo-imageType-00974
If the sparseResidency4Samples feature is not enabled, imageType is VK_IMAGE_TYPE_2D, and samples is VK_SAMPLE_COUNT_4_BIT, flags must not contain VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT
VUID-VkImageCreateInfo-imageType-00975
If the sparseResidency8Samples feature is not enabled, imageType is VK_IMAGE_TYPE_2D, and samples is VK_SAMPLE_COUNT_8_BIT, flags must not contain VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT
VUID-VkImageCreateInfo-imageType-00976
If the sparseResidency16Samples feature is not enabled, imageType is VK_IMAGE_TYPE_2D, and samples is VK_SAMPLE_COUNT_16_BIT, flags must not contain VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT
VUID-VkImageCreateInfo-flags-00987
If flags contains VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT or VK_IMAGE_CREATE_SPARSE_ALIASED_BIT, it must also contain VK_IMAGE_CREATE_SPARSE_BINDING_BIT
VUID-VkImageCreateInfo-None-01925
If any of the bits VK_IMAGE_CREATE_SPARSE_BINDING_BIT, VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT, or VK_IMAGE_CREATE_SPARSE_ALIASED_BIT are set, VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT must not also be set
VUID-VkImageCreateInfo-flags-01890
If the protectedMemory feature is not enabled, flags must not contain VK_IMAGE_CREATE_PROTECTED_BIT
VUID-VkImageCreateInfo-None-01891
If any of the bits VK_IMAGE_CREATE_SPARSE_BINDING_BIT, VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT, or VK_IMAGE_CREATE_SPARSE_ALIASED_BIT are set, VK_IMAGE_CREATE_PROTECTED_BIT must not also be set
VUID-VkImageCreateInfo-pNext-00990
If the pNext chain includes a VkExternalMemoryImageCreateInfo structure, its handleTypes member must only contain bits that are also in VkExternalImageFormatProperties::externalMemoryProperties.compatibleHandleTypes, as returned by vkGetPhysicalDeviceImageFormatProperties2 with format, imageType, tiling, usage, and flags equal to those in this structure, and with a VkPhysicalDeviceExternalImageFormatInfo structure included in the pNext chain, with a handleType equal to any one of the handle types specified in VkExternalMemoryImageCreateInfo::handleTypes
VUID-VkImageCreateInfo-physicalDeviceCount-01421
If the logical device was created with VkDeviceGroupDeviceCreateInfo::physicalDeviceCount equal to 1, flags must not contain VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT
VUID-VkImageCreateInfo-flags-02259
If flags contains VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT, then mipLevels must be one, arrayLayers must be one, imageType must be VK_IMAGE_TYPE_2D. and imageCreateMaybeLinear (as defined in Image Creation Limits) must be VK_FALSE
VUID-VkImageCreateInfo-flags-01572
If flags contains VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT, then format must be a compressed image format
VUID-VkImageCreateInfo-flags-01573
If flags contains VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT, then flags must also contain VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT
VUID-VkImageCreateInfo-initialLayout-00993
initialLayout must be VK_IMAGE_LAYOUT_UNDEFINED or VK_IMAGE_LAYOUT_PREINITIALIZED
VUID-VkImageCreateInfo-pNext-01443
If the pNext chain includes a VkExternalMemoryImageCreateInfo or VkExternalMemoryImageCreateInfoNV structure whose handleTypes member is not 0, initialLayout must be VK_IMAGE_LAYOUT_UNDEFINED
VUID-VkImageCreateInfo-format-06410
If the image format is one of the formats that require a sampler Y′C_BC_R conversion, mipLevels must be 1
VUID-VkImageCreateInfo-format-06411
If the image format is one of the formats that require a sampler Y′C_BC_R conversion, samples must be VK_SAMPLE_COUNT_1_BIT
VUID-VkImageCreateInfo-format-06412
If the image format is one of the formats that require a sampler Y′C_BC_R conversion, imageType must be VK_IMAGE_TYPE_2D
VUID-VkImageCreateInfo-imageCreateFormatFeatures-02260
If format is a multi-planar format, and if imageCreateFormatFeatures (as defined in Image Creation Limits) does not contain VK_FORMAT_FEATURE_DISJOINT_BIT, then flags must not contain VK_IMAGE_CREATE_DISJOINT_BIT
VUID-VkImageCreateInfo-format-01577
If format is not a multi-planar format, and flags does not include VK_IMAGE_CREATE_ALIAS_BIT, flags must not contain VK_IMAGE_CREATE_DISJOINT_BIT
VUID-VkImageCreateInfo-format-04712
If format has a _422 or _420 suffix, extent.width must be a multiple of 2
VUID-VkImageCreateInfo-format-04713
If format has a _420 suffix, extent.height must be a multiple of 2
VUID-VkImageCreateInfo-format-02795
If format is a depth-stencil format, usage includes VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, and the pNext chain includes a VkImageStencilUsageCreateInfo structure, then its VkImageStencilUsageCreateInfo::stencilUsage member must also include VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT
VUID-VkImageCreateInfo-format-02796
If format is a depth-stencil format, usage does not include VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, and the pNext chain includes a VkImageStencilUsageCreateInfo structure, then its VkImageStencilUsageCreateInfo::stencilUsage member must also not include VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT
VUID-VkImageCreateInfo-format-02797
If format is a depth-stencil format, usage includes VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT, and the pNext chain includes a VkImageStencilUsageCreateInfo structure, then its VkImageStencilUsageCreateInfo::stencilUsage member must also include VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT
VUID-VkImageCreateInfo-format-02798
If format is a depth-stencil format, usage does not include VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT, and the pNext chain includes a VkImageStencilUsageCreateInfo structure, then its VkImageStencilUsageCreateInfo::stencilUsage member must also not include VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT
VUID-VkImageCreateInfo-Format-02536
If Format is a depth-stencil format and the pNext chain includes a VkImageStencilUsageCreateInfo structure with its stencilUsage member including VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT, extent.width must be less than or equal to VkPhysicalDeviceLimits::maxFramebufferWidth
VUID-VkImageCreateInfo-format-02537
If format is a depth-stencil format and the pNext chain includes a VkImageStencilUsageCreateInfo structure with its stencilUsage member including VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT, extent.height must be less than or equal to VkPhysicalDeviceLimits::maxFramebufferHeight
VUID-VkImageCreateInfo-format-02538
If the shaderStorageImageMultisample feature is not enabled, format is a depth-stencil format and the pNext chain includes a VkImageStencilUsageCreateInfo structure with its stencilUsage including VK_IMAGE_USAGE_STORAGE_BIT, samples must be VK_SAMPLE_COUNT_1_BIT
VUID-VkImageCreateInfo-imageType-02082
If usage includes VK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR, imageType must be VK_IMAGE_TYPE_2D
VUID-VkImageCreateInfo-samples-02083
If usage includes VK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR, samples must be VK_SAMPLE_COUNT_1_BIT
VUID-VkImageCreateInfo-imageView2DOn3DImage-04459
If the VK_KHR_portability_subset extension is enabled, and VkPhysicalDevicePortabilitySubsetFeaturesKHR::imageView2DOn3DImage is VK_FALSE, flags must not contain VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT
VUID-VkImageCreateInfo-multisampleArrayImage-04460
If the VK_KHR_portability_subset extension is enabled, and VkPhysicalDevicePortabilitySubsetFeaturesKHR::multisampleArrayImage is VK_FALSE, and samples is not VK_SAMPLE_COUNT_1_BIT, then arrayLayers must be 1
VUID-VkImageCreateInfo-pNext-06722
If a VkImageFormatListCreateInfo structure was included in the pNext chain and VkImageFormatListCreateInfo::viewFormatCount is not zero, then each format in VkImageFormatListCreateInfo::pViewFormats must either be compatible with the format as described in the compatibility table or, if flags contains VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT, be an uncompressed format that is size-compatible with format
VUID-VkImageCreateInfo-flags-04738
If flags does not contain VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT and the pNext chain includes a VkImageFormatListCreateInfo structure, then VkImageFormatListCreateInfo::viewFormatCount must be 0 or 1
VUID-VkImageCreateInfo-usage-04815
If usage includes VK_IMAGE_USAGE_VIDEO_DECODE_SRC_BIT_KHR, VK_IMAGE_USAGE_VIDEO_DECODE_DST_BIT_KHR, or VK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHR, and flags does not include VK_IMAGE_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHR, then the pNext chain must include a VkVideoProfileListInfoKHR structure with profileCount greater than 0 and pProfiles including at least one VkVideoProfileInfoKHR structure with a videoCodecOperation member specifying a decode operation
VUID-VkImageCreateInfo-usage-04816
If usage includes VK_IMAGE_USAGE_VIDEO_ENCODE_SRC_BIT_KHR, VK_IMAGE_USAGE_VIDEO_ENCODE_DST_BIT_KHR, or VK_IMAGE_USAGE_VIDEO_ENCODE_DPB_BIT_KHR, and flags does not include VK_IMAGE_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHR, then the pNext chain must include a VkVideoProfileListInfoKHR structure with profileCount greater than 0 and pProfiles including at least one VkVideoProfileInfoKHR structure with a videoCodecOperation member specifying an encode operation
VUID-VkImageCreateInfo-flags-08328
If flags includes VK_IMAGE_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHR, then videoMaintenance1 must be enabled
VUID-VkImageCreateInfo-flags-08329
If flags includes VK_IMAGE_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHR and usage does not include VK_IMAGE_USAGE_VIDEO_DECODE_DST_BIT_KHR, then usage must not include VK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHR
VUID-VkImageCreateInfo-flags-08331
If flags includes VK_IMAGE_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHR, then usage must not include VK_IMAGE_USAGE_VIDEO_ENCODE_DPB_BIT_KHR
VUID-VkImageCreateInfo-pNext-06811
If the pNext chain includes a VkVideoProfileListInfoKHR structure with profileCount greater than 0, then supportedVideoFormat must be VK_TRUE
VUID-VkImageCreateInfo-imageCreateFormatFeatures-09048
If imageCreateFormatFeatures (as defined in Image Creation Limits) does not contain VK_FORMAT_FEATURE_2_HOST_IMAGE_TRANSFER_BIT_EXT, then usage must not contain VK_IMAGE_USAGE_HOST_TRANSFER_BIT_EXT

Valid Usage (Implicit)

VUID-VkImageCreateInfo-sType-sType
sType must be VK_STRUCTURE_TYPE_IMAGE_CREATE_INFO
VUID-VkImageCreateInfo-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 VkExternalMemoryImageCreateInfo, VkImageFormatListCreateInfo, VkImageStencilUsageCreateInfo, VkImageSwapchainCreateInfoKHR, or VkVideoProfileListInfoKHR
VUID-VkImageCreateInfo-sType-unique
The sType value of each struct in the pNext chain must be unique
VUID-VkImageCreateInfo-flags-parameter
flags must be a valid combination of VkImageCreateFlagBits values
VUID-VkImageCreateInfo-imageType-parameter
imageType must be a valid VkImageType value
VUID-VkImageCreateInfo-format-parameter
format must be a valid VkFormat value
VUID-VkImageCreateInfo-samples-parameter
samples must be a valid VkSampleCountFlagBits value
VUID-VkImageCreateInfo-tiling-parameter
tiling must be a valid VkImageTiling value
VUID-VkImageCreateInfo-usage-parameter
usage must be a valid combination of VkImageUsageFlagBits values
VUID-VkImageCreateInfo-usage-requiredbitmask
usage must not be 0
VUID-VkImageCreateInfo-sharingMode-parameter
sharingMode must be a valid VkSharingMode value
VUID-VkImageCreateInfo-initialLayout-parameter
initialLayout must be a valid VkImageLayout value

The VkImageStencilUsageCreateInfo structure is defined as:

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

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

VUID-VkImageStencilUsageCreateInfo-stencilUsage-02539
If stencilUsage includes VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT, it must not include bits other than VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT or VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT

Valid Usage (Implicit)

VUID-VkImageStencilUsageCreateInfo-sType-sType
sType must be VK_STRUCTURE_TYPE_IMAGE_STENCIL_USAGE_CREATE_INFO
VUID-VkImageStencilUsageCreateInfo-stencilUsage-parameter
stencilUsage must be a valid combination of VkImageUsageFlagBits values
VUID-VkImageStencilUsageCreateInfo-stencilUsage-requiredbitmask
stencilUsage must not be 0

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;

or the equivalent

// Provided by VK_KHR_external_memory
typedef VkExternalMemoryImageCreateInfo VkExternalMemoryImageCreateInfoKHR;

Note

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)

VUID-VkExternalMemoryImageCreateInfo-sType-sType
sType must be VK_STRUCTURE_TYPE_EXTERNAL_MEMORY_IMAGE_CREATE_INFO
VUID-VkExternalMemoryImageCreateInfo-handleTypes-parameter
handleTypes must be a valid combination of VkExternalMemoryHandleTypeFlagBits values

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

VUID-VkImageSwapchainCreateInfoKHR-swapchain-00995
If swapchain is not VK_NULL_HANDLE, the fields of VkImageCreateInfo must match the implied image creation parameters of the swapchain

Valid Usage (Implicit)

VUID-VkImageSwapchainCreateInfoKHR-sType-sType
sType must be VK_STRUCTURE_TYPE_IMAGE_SWAPCHAIN_CREATE_INFO_KHR
VUID-VkImageSwapchainCreateInfoKHR-swapchain-parameter
If swapchain is not VK_NULL_HANDLE, swapchain must be a valid VkSwapchainKHR handle

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;

or the equivalent

// Provided by VK_KHR_image_format_list
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

Bits which can be set in

VkImageViewUsageCreateInfo::usage
VkImageStencilUsageCreateInfo::stencilUsage
VkImageCreateInfo::usage

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_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_KHR_fragment_shading_rate
    VK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR = 0x00000100,
  // Provided by VK_EXT_host_image_copy
    VK_IMAGE_USAGE_HOST_TRANSFER_BIT_EXT = 0x00400000,
  // 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,
} VkImageUsageFlagBits;

VK_IMAGE_USAGE_TRANSFER_SRC_BIT specifies that the image can be used as the source of a transfer command.
VK_IMAGE_USAGE_TRANSFER_DST_BIT specifies that the image can be used as the destination of a transfer command.
VK_IMAGE_USAGE_SAMPLED_BIT specifies that the image can be used to create a VkImageView suitable for occupying a VkDescriptorSet slot either of type VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE or VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, and be sampled by a shader.
VK_IMAGE_USAGE_STORAGE_BIT specifies that the image can be used to create a VkImageView suitable for occupying a VkDescriptorSet slot of type VK_DESCRIPTOR_TYPE_STORAGE_IMAGE.
VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT specifies that the image can be used to create a VkImageView suitable for use as a color or resolve attachment in a VkFramebuffer.
VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT specifies that the image can be used to create a VkImageView suitable for use as a depth/stencil or depth/stencil resolve attachment in a VkFramebuffer.
VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT specifies that implementations may support using memory allocations with the VK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT to back an image with this usage. This bit can be set for any image that can be used to create a VkImageView suitable for use as a color, resolve, depth/stencil, or input attachment.
VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT specifies that the image can be used to create a VkImageView suitable for occupying VkDescriptorSet slot of type VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT; be read from a shader as an input attachment; and be used as an input attachment in a framebuffer.
VK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR specifies that the image can be used to create a VkImageView suitable for use as a fragment shading rate attachment
VK_IMAGE_USAGE_VIDEO_DECODE_DST_BIT_KHR specifies that the image can be used as a decode output picture in a video decode operation.
VK_IMAGE_USAGE_VIDEO_DECODE_SRC_BIT_KHR is reserved for future use.
VK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHR specifies that the image can be used as an output reconstructed picture or an input reference picture in a video decode operation.
VK_IMAGE_USAGE_VIDEO_ENCODE_DST_BIT_KHR is reserved for future use.
VK_IMAGE_USAGE_VIDEO_ENCODE_SRC_BIT_KHR specifies that the image can be used as an encode input picture in a video encode operation.
VK_IMAGE_USAGE_VIDEO_ENCODE_DPB_BIT_KHR specifies that the image can be used as an output reconstructed picture or an input reference picture in a video encode operation.
VK_IMAGE_USAGE_ATTACHMENT_FEEDBACK_LOOP_BIT_EXT specifies that the image can be transitioned to the VK_IMAGE_LAYOUT_ATTACHMENT_FEEDBACK_LOOP_OPTIMAL_EXT layout to be used as a color or depth/stencil attachment in a VkFramebuffer and/or as a read-only input resource in a shader (sampled image, combined image sampler or input attachment) in the same render pass.
VK_IMAGE_USAGE_HOST_TRANSFER_BIT_EXT specifies that the image can be used with host copy commands and host layout transitions.

// Provided by VK_VERSION_1_0
typedef VkFlags VkImageUsageFlags;

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

When creating a VkImageView one of the following VkImageUsageFlagBits must be set:

VK_IMAGE_USAGE_SAMPLED_BIT
VK_IMAGE_USAGE_STORAGE_BIT
VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT
VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT
VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT
VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT
VK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR
VK_IMAGE_USAGE_VIDEO_DECODE_DST_BIT_KHR
VK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHR
VK_IMAGE_USAGE_VIDEO_ENCODE_SRC_BIT_KHR
VK_IMAGE_USAGE_VIDEO_ENCODE_DPB_BIT_KHR

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_KHR_video_maintenance1
    VK_IMAGE_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHR = 0x00100000,
  // 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,
} VkImageCreateFlagBits;

VK_IMAGE_CREATE_SPARSE_BINDING_BIT specifies that the image will be backed using sparse memory binding.
VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT specifies that the image can be partially backed using sparse memory binding. Images created with this flag must also be created with the VK_IMAGE_CREATE_SPARSE_BINDING_BIT flag.
VK_IMAGE_CREATE_SPARSE_ALIASED_BIT specifies that the image will be backed using sparse memory binding with memory ranges that might also simultaneously be backing another image (or another portion of the same image). Images created with this flag must also be created with the VK_IMAGE_CREATE_SPARSE_BINDING_BIT flag.
VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT specifies that the image can be used to create a VkImageView with a different format from the image. For multi-planar formats, VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT specifies that a VkImageView can be created of a plane of the image.
VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT specifies that the image can be used to create a VkImageView of type VK_IMAGE_VIEW_TYPE_CUBE or VK_IMAGE_VIEW_TYPE_CUBE_ARRAY.
VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT specifies that the image can be used to create a VkImageView of type VK_IMAGE_VIEW_TYPE_2D or VK_IMAGE_VIEW_TYPE_2D_ARRAY.
VK_IMAGE_CREATE_PROTECTED_BIT specifies that the image is a protected image.
VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT specifies that the image can be used with a non-zero value of the splitInstanceBindRegionCount member of a VkBindImageMemoryDeviceGroupInfo structure passed into vkBindImageMemory2. This flag also has the effect of making the image use the standard sparse image block dimensions.
VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT specifies that the image having a compressed format can be used to create a VkImageView with an uncompressed format where each texel in the image view corresponds to a compressed texel block of the image.
VK_IMAGE_CREATE_EXTENDED_USAGE_BIT specifies that the image can be created with usage flags that are not supported for the format the image is created with but are supported for at least one format a VkImageView created from the image can have.
VK_IMAGE_CREATE_DISJOINT_BIT specifies that an image with a multi-planar format must have each plane separately bound to memory, rather than having a single memory binding for the whole image; the presence of this bit distinguishes a disjoint image from an image without this bit set.
VK_IMAGE_CREATE_ALIAS_BIT specifies that two images created with the same creation parameters and aliased to the same memory can interpret the contents of the memory consistently with each other, subject to the rules described in the Memory Aliasing section. This flag further specifies that each plane of a disjoint image can share an in-memory non-linear representation with single-plane images, and that a single-plane image can share an in-memory non-linear representation with a plane of a multi-planar disjoint image, according to the rules in Compatible Formats of Planes of Multi-Planar Formats. If the pNext chain includes a VkExternalMemoryImageCreateInfo structure whose handleTypes member is not 0, it is as if VK_IMAGE_CREATE_ALIAS_BIT is set.

VK_IMAGE_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHR specifies that the image can be used in video coding operations without having to specify at image creation time the set of video profiles the image will be used with, except for images used only as DPB pictures, as long as the image is otherwise compatible with the video profile in question.

Note

This enables exchanging video picture data without additional copies or conversions when used as:

Decode output pictures, indifferent of the video profile used to produce them.
Encode input pictures, indifferent of the video profile used to consume them.

This includes images created with both VK_IMAGE_USAGE_VIDEO_DECODE_DST_BIT_KHR and VK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHR, which is necessary to use the same video picture as the reconstructed picture and decode output picture in a video decode operation on implementations supporting VK_VIDEO_DECODE_CAPABILITY_DPB_AND_OUTPUT_COINCIDE_BIT_KHR.

However, images with only DPB usage remain tied to the video profiles the image was created with, as the data layout of such DPB-only images may be implementation- and codec-dependent.

If an application would like to share or reuse the device memory backing such images (e.g. for the purposes of temporal aliasing), then it should create separate image objects for each video profile and bind them to the same underlying device memory range, similar to how memory resources can be shared across separate video sessions or any other memory-backed resource.

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;

VK_IMAGE_TYPE_1D specifies a one-dimensional image.
VK_IMAGE_TYPE_2D specifies a two-dimensional image.
VK_IMAGE_TYPE_3D specifies a three-dimensional image.

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,
} VkImageTiling;

VK_IMAGE_TILING_OPTIMAL specifies optimal tiling (texels are laid out in an implementation-dependent arrangement, for more efficient memory access).
VK_IMAGE_TILING_LINEAR specifies linear tiling (texels are laid out in memory in row-major order, possibly with some padding on each row).

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.

The image must be linear. The returned layout is valid for host access.

If the image’s format is a multi-planar format, then vkGetImageSubresourceLayout describes one plane of the image.

vkGetImageSubresourceLayout is invariant for the lifetime of a single image.

Valid Usage

VUID-vkGetImageSubresourceLayout-image-07789
image must have been created with tiling equal to VK_IMAGE_TILING_LINEAR

VUID-vkGetImageSubresourceLayout-aspectMask-00997
The aspectMask member of pSubresource must only have a single bit set
VUID-vkGetImageSubresourceLayout-mipLevel-01716
The mipLevel member of pSubresource must be less than the mipLevels specified in image
VUID-vkGetImageSubresourceLayout-arrayLayer-01717
The arrayLayer member of pSubresource must be less than the arrayLayers specified in image
VUID-vkGetImageSubresourceLayout-format-08886
If format of the image is a color format that is not a multi-planar image format, and tiling of the image is VK_IMAGE_TILING_LINEAR or VK_IMAGE_TILING_OPTIMAL, the aspectMask member of pSubresource must be VK_IMAGE_ASPECT_COLOR_BIT
VUID-vkGetImageSubresourceLayout-format-04462
If format of the image has a depth component, the aspectMask member of pSubresource must contain VK_IMAGE_ASPECT_DEPTH_BIT
VUID-vkGetImageSubresourceLayout-format-04463
If format of the image has a stencil component, the aspectMask member of pSubresource must contain VK_IMAGE_ASPECT_STENCIL_BIT
VUID-vkGetImageSubresourceLayout-format-04464
If format of the image 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-vkGetImageSubresourceLayout-tiling-08717
If the tiling of the image is VK_IMAGE_TILING_LINEAR and has a multi-planar image format, then the aspectMask member of pSubresource must be a single valid multi-planar aspect mask bit

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 , then the aspectMask member of VkImageSubresource must be VK_IMAGE_ASPECT_COLOR_BIT.

If the image has a depth/stencil format , 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 , 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.

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

// Provided by VK_KHR_maintenance5
void vkGetImageSubresourceLayout2KHR(
    VkDevice                                    device,
    VkImage                                     image,
    const VkImageSubresource2KHR*               pSubresource,
    VkSubresourceLayout2KHR*                    pLayout);

or the equivalent command

// Provided by VK_EXT_host_image_copy
void vkGetImageSubresourceLayout2EXT(
    VkDevice                                    device,
    VkImage                                     image,
    const VkImageSubresource2KHR*               pSubresource,
    VkSubresourceLayout2KHR*                    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 VkImageSubresource2KHR structure selecting a specific image for the image subresource.
pLayout is a pointer to a VkSubresourceLayout2KHR structure in which the layout is returned.

vkGetImageSubresourceLayout2KHR 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 vkGetImageSubresourceLayout2KHR with an image created with tiling equal to VK_IMAGE_TILING_OPTIMAL, but the members of VkSubresourceLayout2KHR::subresourceLayout will have undefined values in this case.

Note

Structures chained from VkImageSubresource2KHR::pNext will also be updated when tiling is equal to VK_IMAGE_TILING_OPTIMAL.

Valid Usage

VUID-vkGetImageSubresourceLayout2KHR-aspectMask-00997
The aspectMask member of pSubresource must only have a single bit set
VUID-vkGetImageSubresourceLayout2KHR-mipLevel-01716
The mipLevel member of pSubresource must be less than the mipLevels specified in image
VUID-vkGetImageSubresourceLayout2KHR-arrayLayer-01717
The arrayLayer member of pSubresource must be less than the arrayLayers specified in image
VUID-vkGetImageSubresourceLayout2KHR-format-08886
If format of the image is a color format that is not a multi-planar image format, and tiling of the image is VK_IMAGE_TILING_LINEAR or VK_IMAGE_TILING_OPTIMAL, the aspectMask member of pSubresource must be VK_IMAGE_ASPECT_COLOR_BIT
VUID-vkGetImageSubresourceLayout2KHR-format-04462
If format of the image has a depth component, the aspectMask member of pSubresource must contain VK_IMAGE_ASPECT_DEPTH_BIT
VUID-vkGetImageSubresourceLayout2KHR-format-04463
If format of the image has a stencil component, the aspectMask member of pSubresource must contain VK_IMAGE_ASPECT_STENCIL_BIT
VUID-vkGetImageSubresourceLayout2KHR-format-04464
If format of the image 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-vkGetImageSubresourceLayout2KHR-tiling-08717
If the tiling of the image is VK_IMAGE_TILING_LINEAR and has a multi-planar image format, then the aspectMask member of pSubresource must be a single valid multi-planar aspect mask bit

Valid Usage (Implicit)

VUID-vkGetImageSubresourceLayout2KHR-device-parameter
device must be a valid VkDevice handle
VUID-vkGetImageSubresourceLayout2KHR-image-parameter
image must be a valid VkImage handle
VUID-vkGetImageSubresourceLayout2KHR-pSubresource-parameter
pSubresource must be a valid pointer to a valid VkImageSubresource2KHR structure
VUID-vkGetImageSubresourceLayout2KHR-pLayout-parameter
pLayout must be a valid pointer to a VkSubresourceLayout2KHR structure
VUID-vkGetImageSubresourceLayout2KHR-image-parent
image must have been created, allocated, or retrieved from device

The VkImageSubresource2KHR structure is defined as:

// Provided by VK_KHR_maintenance5
typedef struct VkImageSubresource2KHR {
    VkStructureType       sType;
    void*                 pNext;
    VkImageSubresource    imageSubresource;
} VkImageSubresource2KHR;

or the equivalent

// Provided by VK_EXT_host_image_copy
typedef VkImageSubresource2KHR 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)

VUID-VkImageSubresource2KHR-sType-sType
sType must be VK_STRUCTURE_TYPE_IMAGE_SUBRESOURCE_2_KHR
VUID-VkImageSubresource2KHR-pNext-pNext
pNext must be NULL
VUID-VkImageSubresource2KHR-imageSubresource-parameter
imageSubresource must be a valid VkImageSubresource structure

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

// Provided by VK_KHR_maintenance5
typedef struct VkSubresourceLayout2KHR {
    VkStructureType        sType;
    void*                  pNext;
    VkSubresourceLayout    subresourceLayout;
} VkSubresourceLayout2KHR;

or the equivalent

// Provided by VK_EXT_host_image_copy
typedef VkSubresourceLayout2KHR 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)

VUID-VkSubresourceLayout2KHR-sType-sType
sType must be VK_STRUCTURE_TYPE_SUBRESOURCE_LAYOUT_2_KHR
VUID-VkSubresourceLayout2KHR-pNext-pNext
pNext must be NULL or a pointer to a valid instance of VkSubresourceHostMemcpySizeEXT
VUID-VkSubresourceLayout2KHR-sType-unique
The sType value of each struct in the pNext chain must be unique

To query the memory size needed to copy to or from an image using vkCopyMemoryToImageEXT or vkCopyImageToMemoryEXT when the VK_HOST_IMAGE_COPY_MEMCPY_EXT flag is specified, add a VkSubresourceHostMemcpySizeEXT structure to the pNext chain of the VkSubresourceLayout2EXT structure in a call to vkGetImageSubresourceLayout2EXT.

The VkSubresourceHostMemcpySizeEXT structure is defined as:

// Provided by VK_EXT_host_image_copy
typedef struct VkSubresourceHostMemcpySizeEXT {
    VkStructureType    sType;
    void*              pNext;
    VkDeviceSize       size;
} 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)

VUID-VkSubresourceHostMemcpySizeEXT-sType-sType
sType must be VK_STRUCTURE_TYPE_SUBRESOURCE_HOST_MEMCPY_SIZE_EXT

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

// Provided by VK_KHR_maintenance5
void vkGetDeviceImageSubresourceLayoutKHR(
    VkDevice                                    device,
    const VkDeviceImageSubresourceInfoKHR*      pInfo,
    VkSubresourceLayout2KHR*                    pLayout);

device is the logical device that owns the image.
pInfo is a pointer to a VkDeviceImageSubresourceInfoKHR structure containing parameters required for the subresource layout query.
pLayout is a pointer to a VkSubresourceLayout2KHR structure in which the layout is returned.

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

Valid Usage (Implicit)

VUID-vkGetDeviceImageSubresourceLayoutKHR-device-parameter
device must be a valid VkDevice handle
VUID-vkGetDeviceImageSubresourceLayoutKHR-pInfo-parameter
pInfo must be a valid pointer to a valid VkDeviceImageSubresourceInfoKHR structure
VUID-vkGetDeviceImageSubresourceLayoutKHR-pLayout-parameter
pLayout must be a valid pointer to a VkSubresourceLayout2KHR structure

The VkDeviceImageSubresourceInfoKHR structure is defined as:

// Provided by VK_KHR_maintenance5
typedef struct VkDeviceImageSubresourceInfoKHR {
    VkStructureType                  sType;
    const void*                      pNext;
    const VkImageCreateInfo*         pCreateInfo;
    const VkImageSubresource2KHR*    pSubresource;
} 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 pSubresource is a pointer to a VkImageSubresource2KHR structure selecting a specific image subresource for the query.

Valid Usage

VUID-VkDeviceImageSubresourceInfoKHR-aspectMask-00997
The aspectMask member of pSubresource must only have a single bit set
VUID-VkDeviceImageSubresourceInfoKHR-mipLevel-01716
The mipLevel member of pSubresource must be less than the mipLevels specified in pCreateInfo
VUID-VkDeviceImageSubresourceInfoKHR-arrayLayer-01717
The arrayLayer member of pSubresource must be less than the arrayLayers specified in pCreateInfo
VUID-VkDeviceImageSubresourceInfoKHR-format-08886
If format of the image is a color format that is not a multi-planar image 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-VkDeviceImageSubresourceInfoKHR-format-04462
If format of the pCreateInfo has a depth component, the aspectMask member of pSubresource must contain VK_IMAGE_ASPECT_DEPTH_BIT
VUID-VkDeviceImageSubresourceInfoKHR-format-04463
If format of the pCreateInfo has a stencil component, the aspectMask member of pSubresource must contain VK_IMAGE_ASPECT_STENCIL_BIT
VUID-VkDeviceImageSubresourceInfoKHR-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-VkDeviceImageSubresourceInfoKHR-tiling-08717
If the tiling of the pCreateInfo is VK_IMAGE_TILING_LINEAR and has a multi-planar image format, then the aspectMask member of pSubresource must be a single valid multi-planar aspect mask bit

Valid Usage (Implicit)

VUID-VkDeviceImageSubresourceInfoKHR-sType-sType
sType must be VK_STRUCTURE_TYPE_DEVICE_IMAGE_SUBRESOURCE_INFO_KHR
VUID-VkDeviceImageSubresourceInfoKHR-pNext-pNext
pNext must be NULL
VUID-VkDeviceImageSubresourceInfoKHR-pCreateInfo-parameter
pCreateInfo must be a valid pointer to a valid VkImageCreateInfo structure
VUID-VkDeviceImageSubresourceInfoKHR-pSubresource-parameter
pSubresource must be a valid pointer to a valid VkImageSubresource2KHR structure

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

12.3.1. 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.

If the image was created with VK_IMAGE_TILING_LINEAR, then its set of format features is the value of VkFormatProperties::linearTilingFeatures found by calling vkGetPhysicalDeviceFormatProperties on the same format as VkImageCreateInfo::format.
If the image was created with VK_IMAGE_TILING_OPTIMAL, then its set of format features is the value of VkFormatProperties::optimalTilingFeatures found by calling vkGetPhysicalDeviceFormatProperties on the same format as VkImageCreateInfo::format.

12.3.2. 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:

: width_n+1 = max(⌊width_n/2⌋, 1)
: height_n+1 = max(⌊height_n/2⌋, 1)
: depth_n+1 = max(⌊depth_n/2⌋, 1)

where width_n, height_n, and depth_n 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:

: ⌊log₂(max(width₀, height₀, depth₀))⌋ + 1

where width₀, height₀, and depth₀ are the dimensions of the largest (most detailed) mip level, 0.

12.4. 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.

Note

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_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_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 either the VK_IMAGE_LAYOUT_PREINITIALIZED or VK_IMAGE_LAYOUT_GENERAL layout. 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_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_KHR_fragment_shading_rate
    VK_IMAGE_LAYOUT_FRAGMENT_SHADING_RATE_ATTACHMENT_OPTIMAL_KHR = 1000164003,
  // Provided by VK_KHR_dynamic_rendering_local_read
    VK_IMAGE_LAYOUT_RENDERING_LOCAL_READ_KHR = 1000232000,
  // 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_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_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:

VK_IMAGE_LAYOUT_UNDEFINED specifies that the layout is unknown. Image memory cannot be transitioned into this layout. This layout can be used as the initialLayout member of VkImageCreateInfo. This layout can be used in place of the current image layout in a layout transition, but doing so will cause the contents of the image’s memory to be undefined.
VK_IMAGE_LAYOUT_PREINITIALIZED specifies that an image’s memory is in a defined layout and can be populated by data, but that it has not yet been initialized by the driver. Image memory cannot be transitioned into this layout. This layout can be used as the initialLayout member of VkImageCreateInfo. This layout is intended to be used as the initial layout for an image whose contents are written by the host, and hence the data can be written to memory immediately, without first executing a layout transition. Currently, VK_IMAGE_LAYOUT_PREINITIALIZED is only useful with linear images because there is not a standard layout defined for VK_IMAGE_TILING_OPTIMAL images.
VK_IMAGE_LAYOUT_GENERAL supports all types of device access.
VK_IMAGE_LAYOUT_ATTACHMENT_OPTIMAL specifies a layout that must only be used with attachment accesses in the graphics pipeline.
VK_IMAGE_LAYOUT_READ_ONLY_OPTIMAL specifies a layout allowing read only access as an attachment, or in shaders as a sampled image, combined image/sampler, or input attachment.
VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL must only be used as a color or resolve attachment in a VkFramebuffer. This layout is valid only for image subresources of images created with the VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT usage bit enabled.
VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL specifies a layout for both the depth and stencil aspects of a depth/stencil format image allowing read and write access as a depth/stencil attachment. It is equivalent to VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL and VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL.
VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL specifies a layout for both the depth and stencil aspects of a depth/stencil format image allowing read only access as a depth/stencil attachment or in shaders as a sampled image, combined image/sampler, or input attachment. It is equivalent to VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL and VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL.
VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL specifies a layout for depth/stencil format images allowing read and write access to the stencil aspect as a stencil attachment, and read only access to the depth aspect as a depth attachment or in shaders as a sampled image, combined image/sampler, or input attachment. It is equivalent to VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL and VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL.
VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL specifies a layout for depth/stencil format images allowing read and write access to the depth aspect as a depth attachment, and read only access to the stencil aspect as a stencil attachment or in shaders as a sampled image, combined image/sampler, or input attachment. It is equivalent to VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL and VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL.
VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL specifies a layout for the depth aspect of a depth/stencil format image allowing read and write access as a depth attachment.
VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL specifies a layout for the depth aspect of a depth/stencil format image allowing read-only access as a depth attachment or in shaders as a sampled image, combined image/sampler, or input attachment.
VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL specifies a layout for the stencil aspect of a depth/stencil format image allowing read and write access as a stencil attachment.
VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL specifies a layout for the stencil aspect of a depth/stencil format image allowing read-only access as a stencil attachment or in shaders as a sampled image, combined image/sampler, or input attachment.
VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL specifies a layout allowing read-only access in a shader as a sampled image, combined image/sampler, or input attachment. This layout is valid only for image subresources of images created with the VK_IMAGE_USAGE_SAMPLED_BIT or VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT usage bits enabled.
VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL must only be used as a source image of a transfer command (see the definition of VK_PIPELINE_STAGE_TRANSFER_BIT). This layout is valid only for image subresources of images created with the VK_IMAGE_USAGE_TRANSFER_SRC_BIT usage bit enabled.
VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL must only be used as a destination image of a transfer command. This layout is valid only for image subresources of images created with the VK_IMAGE_USAGE_TRANSFER_DST_BIT usage bit enabled.
VK_IMAGE_LAYOUT_PRESENT_SRC_KHR must only be used for presenting a presentable image for display.
VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR is valid only for shared presentable images, and must be used for any usage the image supports.
VK_IMAGE_LAYOUT_FRAGMENT_SHADING_RATE_ATTACHMENT_OPTIMAL_KHR must only be used as a fragment shading rate attachment or This layout is valid only for image subresources of images created with the VK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR usage bit enabled.
VK_IMAGE_LAYOUT_VIDEO_DECODE_DST_KHR must only be used as a decode output picture in a video decode operation. This layout is valid only for image subresources of images created with the VK_IMAGE_USAGE_VIDEO_DECODE_DST_BIT_KHR usage bit enabled.
VK_IMAGE_LAYOUT_VIDEO_DECODE_SRC_KHR is reserved for future use.
VK_IMAGE_LAYOUT_VIDEO_DECODE_DPB_KHR must only be used as an output reconstructed picture or an input reference picture in a video decode operation. This layout is valid only for image subresources of images created with the VK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHR usage bit enabled.
VK_IMAGE_LAYOUT_VIDEO_ENCODE_DST_KHR is reserved for future use.
VK_IMAGE_LAYOUT_VIDEO_ENCODE_SRC_KHR must only be used as an encode input picture in a video encode operation. This layout is valid only for image subresources of images created with the VK_IMAGE_USAGE_VIDEO_ENCODE_SRC_BIT_KHR usage bit enabled.
VK_IMAGE_LAYOUT_VIDEO_ENCODE_DPB_KHR must only be used as an output reconstructed picture or an input reference picture in a video encode operation. This layout is valid only for image subresources of images created with the VK_IMAGE_USAGE_VIDEO_ENCODE_DPB_BIT_KHR usage bit enabled.
VK_IMAGE_LAYOUT_ATTACHMENT_FEEDBACK_LOOP_OPTIMAL_EXT must only be used as either a color attachment or depth/stencil attachment in a VkFramebuffer and/or read-only access in a shader as a sampled image, combined image/sampler, or input attachment. This layout is valid only for image subresources of images created with the VK_IMAGE_USAGE_ATTACHMENT_FEEDBACK_LOOP_BIT_EXT usage bit enabled and either the VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT or VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT and either the VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT or VK_IMAGE_USAGE_SAMPLED_BIT usage bits enabled.
VK_IMAGE_LAYOUT_RENDERING_LOCAL_READ_KHR must only be used as either a storage image, or a color or depth/stencil attachment and an input attachment. This layout is valid only for image subresources of images created with either VK_IMAGE_USAGE_STORAGE_BIT, or both VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT and either of VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT or VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT.

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).

12.4.1. 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:

Descriptors referring just to the depth aspect of a depth/stencil image only need to match in the image layout of the depth aspect, thus VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL and VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL are considered to match.
Descriptors referring just to the stencil aspect of a depth/stencil image only need to match in the image layout of the stencil aspect, thus VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL and VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL are considered to match.

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 VK_IMAGE_LAYOUT_UNDEFINED or VK_IMAGE_LAYOUT_PREINITIALIZED.

12.5. 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

VUID-vkCreateImageView-image-09179
VkImageViewCreateInfo::image must have been created from device

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

Return Codes

Success

VK_SUCCESS

Failure

VK_ERROR_OUT_OF_HOST_MEMORY
VK_ERROR_OUT_OF_DEVICE_MEMORY
VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS_KHR

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 aspectMask includes only VK_IMAGE_ASPECT_STENCIL_BIT, the implicit usage is equal to VkImageStencilUsageCreateInfo::stencilUsage.
If aspectMask includes only VK_IMAGE_ASPECT_DEPTH_BIT, the implicit usage is equal to VkImageCreateInfo::usage.
If both aspects are included in aspectMask, the implicit usage is equal to the intersection of VkImageCreateInfo::usage and VkImageStencilUsageCreateInfo::stencilUsage.

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.

Note

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 -2^b may be changed to -2^b + 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 storage image descriptors, input attachment descriptors, framebuffer attachments, and any VkImageView used with a combined image sampler that enables sampler Y′C_BC_R conversion.

If the image view is to be used with a sampler which supports sampler Y′C_BC_R 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′C_BC_R conversion.

When such an image is used in a video coding operation, the sampler Y′C_BC_R 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′C_BC_R 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 (u_plane, v_plane) unnormalized coordinates of the reduced-resolution plane, and these coordinates access the same memory locations as the (u_color, v_color) unnormalized coordinates of the color aspect for which chroma reconstruction operations operate on the same (u_plane, v_plane) or (i_plane, j_plane) coordinates.

Table 11. 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

VUID-VkImageViewCreateInfo-image-01003
If image was not created with VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT then viewType must not be VK_IMAGE_VIEW_TYPE_CUBE or VK_IMAGE_VIEW_TYPE_CUBE_ARRAY
VUID-VkImageViewCreateInfo-viewType-01004
If the imageCubeArray feature is not enabled, viewType must not be VK_IMAGE_VIEW_TYPE_CUBE_ARRAY
VUID-VkImageViewCreateInfo-image-06723
If image was created with VK_IMAGE_TYPE_3D but without VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT set then viewType must not be VK_IMAGE_VIEW_TYPE_2D_ARRAY
VUID-VkImageViewCreateInfo-image-06727
If image was created with VK_IMAGE_TYPE_3D but without VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT set then viewType must not be VK_IMAGE_VIEW_TYPE_2D
VUID-VkImageViewCreateInfo-image-04970
If image was created with VK_IMAGE_TYPE_3D and viewType is VK_IMAGE_VIEW_TYPE_2D or VK_IMAGE_VIEW_TYPE_2D_ARRAY then subresourceRange.levelCount must be 1
VUID-VkImageViewCreateInfo-image-04971
If image was created with VK_IMAGE_TYPE_3D and viewType is VK_IMAGE_VIEW_TYPE_2D or VK_IMAGE_VIEW_TYPE_2D_ARRAY then VkImageCreateInfo::flags must not contain any of VK_IMAGE_CREATE_SPARSE_BINDING_BIT, VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT, and VK_IMAGE_CREATE_SPARSE_ALIASED_BIT
VUID-VkImageViewCreateInfo-image-04972
If image was created with a samples value not equal to VK_SAMPLE_COUNT_1_BIT then viewType must be either VK_IMAGE_VIEW_TYPE_2D or VK_IMAGE_VIEW_TYPE_2D_ARRAY
VUID-VkImageViewCreateInfo-image-04441
image must have been created with a usage value containing at least one of the usages defined in the valid image usage list for image views
VUID-VkImageViewCreateInfo-None-02273
The format features of the resultant image view must contain at least one bit
VUID-VkImageViewCreateInfo-usage-02274
If usage contains VK_IMAGE_USAGE_SAMPLED_BIT, then the format features of the resultant image view must contain VK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT
VUID-VkImageViewCreateInfo-usage-02275
If usage contains VK_IMAGE_USAGE_STORAGE_BIT, then the image view’s format features must contain VK_FORMAT_FEATURE_STORAGE_IMAGE_BIT
VUID-VkImageViewCreateInfo-usage-02276
If usage contains VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT, then the image view’s format features must contain VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT
VUID-VkImageViewCreateInfo-usage-02277
If usage contains VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, then the image view’s format features must contain VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT
VUID-VkImageViewCreateInfo-image-08333
If image was created with VK_IMAGE_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHR and usage contains VK_IMAGE_USAGE_VIDEO_DECODE_DST_BIT_KHR, then the image view’s format features must contain VK_FORMAT_FEATURE_VIDEO_DECODE_OUTPUT_BIT_KHR
VUID-VkImageViewCreateInfo-image-08334
If image was created with VK_IMAGE_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHR and usage contains VK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHR, then the image view’s format features must contain VK_FORMAT_FEATURE_VIDEO_DECODE_DPB_BIT_KHR
VUID-VkImageViewCreateInfo-image-08335
If image was created with VK_IMAGE_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHR, then usage must not include VK_IMAGE_USAGE_VIDEO_DECODE_SRC_BIT_KHR
VUID-VkImageViewCreateInfo-image-08336
If image was created with VK_IMAGE_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHR and usage contains VK_IMAGE_USAGE_VIDEO_ENCODE_SRC_BIT_KHR, then the image view’s format features must contain VK_FORMAT_FEATURE_VIDEO_ENCODE_INPUT_BIT_KHR
VUID-VkImageViewCreateInfo-image-08337
If image was created with VK_IMAGE_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHR and usage contains VK_IMAGE_USAGE_VIDEO_ENCODE_DPB_BIT_KHR, then the image view’s format features must contain VK_FORMAT_FEATURE_VIDEO_ENCODE_DPB_BIT_KHR
VUID-VkImageViewCreateInfo-image-08338
If image was created with VK_IMAGE_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHR, then usage must not include VK_IMAGE_USAGE_VIDEO_ENCODE_DST_BIT_KHR
VUID-VkImageViewCreateInfo-usage-08932
If usage contains VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT,

then the image view’s format features must contain at least one of VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT or VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT
VUID-VkImageViewCreateInfo-subresourceRange-01478
subresourceRange.baseMipLevel must be less than the mipLevels specified in VkImageCreateInfo when image was created
VUID-VkImageViewCreateInfo-subresourceRange-01718
If subresourceRange.levelCount is not VK_REMAINING_MIP_LEVELS, subresourceRange.baseMipLevel + subresourceRange.levelCount must be less than or equal to the mipLevels specified in VkImageCreateInfo when image was created
VUID-VkImageViewCreateInfo-image-01482
If image is not a 3D image created with VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT set, or viewType is not VK_IMAGE_VIEW_TYPE_2D or VK_IMAGE_VIEW_TYPE_2D_ARRAY, subresourceRange.baseArrayLayer must be less than the arrayLayers specified in VkImageCreateInfo when image was created
VUID-VkImageViewCreateInfo-subresourceRange-01483
If subresourceRange.layerCount is not VK_REMAINING_ARRAY_LAYERS, image is not a 3D image created with VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT set, or viewType is not VK_IMAGE_VIEW_TYPE_2D or VK_IMAGE_VIEW_TYPE_2D_ARRAY, subresourceRange.layerCount must be non-zero and subresourceRange.baseArrayLayer + subresourceRange.layerCount must be less than or equal to the arrayLayers specified in VkImageCreateInfo when image was created
VUID-VkImageViewCreateInfo-image-02724
If image is a 3D image created with VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT set, and viewType is VK_IMAGE_VIEW_TYPE_2D or VK_IMAGE_VIEW_TYPE_2D_ARRAY, subresourceRange.baseArrayLayer must be less than the depth computed from baseMipLevel and extent.depth specified in VkImageCreateInfo when image was created, according to the formula defined in Image Mip Level Sizing
VUID-VkImageViewCreateInfo-subresourceRange-02725
If subresourceRange.layerCount is not VK_REMAINING_ARRAY_LAYERS, image is a 3D image created with VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT set, and viewType is VK_IMAGE_VIEW_TYPE_2D or VK_IMAGE_VIEW_TYPE_2D_ARRAY, subresourceRange.layerCount must be non-zero and subresourceRange.baseArrayLayer + subresourceRange.layerCount must be less than or equal to the depth computed from baseMipLevel and extent.depth specified in VkImageCreateInfo when image was created, according to the formula defined in Image Mip Level Sizing
VUID-VkImageViewCreateInfo-image-01761
If image was created with the VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT flag, but without the VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT flag, and if the format of the image is not a multi-planar format, format must be compatible with the format used to create image, as defined in Format Compatibility Classes
VUID-VkImageViewCreateInfo-image-01583
If image was created with the VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT flag, format must be compatible with, or must be an uncompressed format that is size-compatible with, the format used to create image
VUID-VkImageViewCreateInfo-image-07072
If image was created with the VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT flag and format is a non-compressed format, the levelCount member of subresourceRange must be 1
VUID-VkImageViewCreateInfo-image-09487
If image was created with the VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT flag, the VkPhysicalDeviceMaintenance6PropertiesKHR::blockTexelViewCompatibleMultipleLayers property is not set to VK_TRUE, and format is a non-compressed format, then the layerCount member of subresourceRange must be 1
VUID-VkImageViewCreateInfo-pNext-01585
If a VkImageFormatListCreateInfo structure was included in the pNext chain of the VkImageCreateInfo structure used when creating image and VkImageFormatListCreateInfo::viewFormatCount is not zero then format must be one of the formats in VkImageFormatListCreateInfo::pViewFormats
VUID-VkImageViewCreateInfo-image-01586
If image was created with the VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT flag, if the format of the image is a multi-planar format, and if subresourceRange.aspectMask is one of the multi-planar aspect mask bits, then format must be compatible with the VkFormat for the plane of the image format indicated by subresourceRange.aspectMask, as defined in Compatible Formats of Planes of Multi-Planar Formats
VUID-VkImageViewCreateInfo-subresourceRange-07818
subresourceRange.aspectMask must only have at most 1 valid multi-planar aspect mask bit
VUID-VkImageViewCreateInfo-image-01762
If image was not created with the VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT flag, or if the format of the image is a multi-planar format and if subresourceRange.aspectMask is VK_IMAGE_ASPECT_COLOR_BIT, format must be identical to the format used to create image
VUID-VkImageViewCreateInfo-format-06415
If the image view requires a sampler Y′C_BC_R conversion and usage contains VK_IMAGE_USAGE_SAMPLED_BIT, then the pNext chain must include a VkSamplerYcbcrConversionInfo structure with a conversion value other than VK_NULL_HANDLE
VUID-VkImageViewCreateInfo-format-04714
If format has a _422 or _420 suffix then image must have been created with a width that is a multiple of 2
VUID-VkImageViewCreateInfo-format-04715
If format has a _420 suffix then image must have been created with a height that is a multiple of 2
VUID-VkImageViewCreateInfo-pNext-01970
If the pNext chain includes a VkSamplerYcbcrConversionInfo structure with a conversion value other than VK_NULL_HANDLE, all members of components must have the identity swizzle
VUID-VkImageViewCreateInfo-pNext-06658
If the pNext chain includes a VkSamplerYcbcrConversionInfo structure with a conversion value other than VK_NULL_HANDLE, format must be the same used in VkSamplerYcbcrConversionCreateInfo::format
VUID-VkImageViewCreateInfo-image-01020
If image is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object
VUID-VkImageViewCreateInfo-subResourceRange-01021
viewType must be compatible with the type of image as shown in the view type compatibility table
VUID-VkImageViewCreateInfo-image-02086
If image was created with usage containing VK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR, viewType must be VK_IMAGE_VIEW_TYPE_2D or VK_IMAGE_VIEW_TYPE_2D_ARRAY
VUID-VkImageViewCreateInfo-usage-04550
If the attachmentFragmentShadingRate feature is enabled, and the usage for the image view includes VK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR, then the image view’s format features must contain VK_FORMAT_FEATURE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR
VUID-VkImageViewCreateInfo-usage-04551
If the attachmentFragmentShadingRate feature is enabled, the usage for the image view includes VK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR, and layeredShadingRateAttachments is VK_FALSE, subresourceRange.layerCount must be 1
VUID-VkImageViewCreateInfo-pNext-02662
If the pNext chain includes a VkImageViewUsageCreateInfo structure, and image was not created with a VkImageStencilUsageCreateInfo structure included in the pNext chain of VkImageCreateInfo, its usage member must not include any bits that were not set in the usage member of the VkImageCreateInfo structure used to create image
VUID-VkImageViewCreateInfo-pNext-02663
If the pNext chain includes a VkImageViewUsageCreateInfo structure, image was created with a VkImageStencilUsageCreateInfo structure included in the pNext chain of VkImageCreateInfo, and subresourceRange.aspectMask includes VK_IMAGE_ASPECT_STENCIL_BIT, the usage member of the VkImageViewUsageCreateInfo structure must not include any bits that were not set in the usage member of the VkImageStencilUsageCreateInfo structure used to create image
VUID-VkImageViewCreateInfo-pNext-02664
If the pNext chain includes a VkImageViewUsageCreateInfo structure, image was created with a VkImageStencilUsageCreateInfo structure included in the pNext chain of VkImageCreateInfo, and subresourceRange.aspectMask includes bits other than VK_IMAGE_ASPECT_STENCIL_BIT, the usage member of the VkImageViewUsageCreateInfo structure must not include any bits that were not set in the usage member of the VkImageCreateInfo structure used to create image
VUID-VkImageViewCreateInfo-imageViewType-04973
If viewType is VK_IMAGE_VIEW_TYPE_1D, VK_IMAGE_VIEW_TYPE_2D, or VK_IMAGE_VIEW_TYPE_3D; and subresourceRange.layerCount is not VK_REMAINING_ARRAY_LAYERS, then subresourceRange.layerCount must be 1
VUID-VkImageViewCreateInfo-imageViewType-04974
If viewType is VK_IMAGE_VIEW_TYPE_1D, VK_IMAGE_VIEW_TYPE_2D, or VK_IMAGE_VIEW_TYPE_3D; and subresourceRange.layerCount is VK_REMAINING_ARRAY_LAYERS, then the remaining number of layers must be 1
VUID-VkImageViewCreateInfo-viewType-02960
If viewType is VK_IMAGE_VIEW_TYPE_CUBE and subresourceRange.layerCount is not VK_REMAINING_ARRAY_LAYERS, subresourceRange.layerCount must be 6
VUID-VkImageViewCreateInfo-viewType-02961
If viewType is VK_IMAGE_VIEW_TYPE_CUBE_ARRAY and subresourceRange.layerCount is not VK_REMAINING_ARRAY_LAYERS, subresourceRange.layerCount must be a multiple of 6
VUID-VkImageViewCreateInfo-viewType-02962
If viewType is VK_IMAGE_VIEW_TYPE_CUBE and subresourceRange.layerCount is VK_REMAINING_ARRAY_LAYERS, the remaining number of layers must be 6
VUID-VkImageViewCreateInfo-viewType-02963
If viewType is VK_IMAGE_VIEW_TYPE_CUBE_ARRAY and subresourceRange.layerCount is VK_REMAINING_ARRAY_LAYERS, the remaining number of layers must be a multiple of 6
VUID-VkImageViewCreateInfo-imageViewFormatSwizzle-04465
If the VK_KHR_portability_subset extension is enabled, and VkPhysicalDevicePortabilitySubsetFeaturesKHR::imageViewFormatSwizzle is VK_FALSE, all elements of components must have the identity swizzle
VUID-VkImageViewCreateInfo-imageViewFormatReinterpretation-04466
If the VK_KHR_portability_subset extension is enabled, and VkPhysicalDevicePortabilitySubsetFeaturesKHR::imageViewFormatReinterpretation is VK_FALSE, the VkFormat in format must not contain a different number of components, or a different number of bits in each component, than the format of the VkImage in image
VUID-VkImageViewCreateInfo-image-04817
If image was created with usage containing VK_IMAGE_USAGE_VIDEO_DECODE_DST_BIT_KHR, VK_IMAGE_USAGE_VIDEO_DECODE_SRC_BIT_KHR, or VK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHR, then the viewType must be VK_IMAGE_VIEW_TYPE_2D or VK_IMAGE_VIEW_TYPE_2D_ARRAY
VUID-VkImageViewCreateInfo-image-04818
If image was created with usage containing VK_IMAGE_USAGE_VIDEO_ENCODE_DST_BIT_KHR, VK_IMAGE_USAGE_VIDEO_ENCODE_SRC_BIT_KHR, or VK_IMAGE_USAGE_VIDEO_ENCODE_DPB_BIT_KHR, then the viewType must be VK_IMAGE_VIEW_TYPE_2D or VK_IMAGE_VIEW_TYPE_2D_ARRAY
VUID-VkImageViewCreateInfo-subresourceRange-09594
subresourceRange.aspectMask must be valid for the format the image was created with

Valid Usage (Implicit)

VUID-VkImageViewCreateInfo-sType-sType
sType must be VK_STRUCTURE_TYPE_IMAGE_VIEW_CREATE_INFO
VUID-VkImageViewCreateInfo-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 VkImageViewUsageCreateInfo or VkSamplerYcbcrConversionInfo
VUID-VkImageViewCreateInfo-sType-unique
The sType value of each struct in the pNext chain must be unique
VUID-VkImageViewCreateInfo-flags-zerobitmask
flags must be 0
VUID-VkImageViewCreateInfo-image-parameter
image must be a valid VkImage handle
VUID-VkImageViewCreateInfo-viewType-parameter
viewType must be a valid VkImageViewType value
VUID-VkImageViewCreateInfo-format-parameter
format must be a valid VkFormat value
VUID-VkImageViewCreateInfo-components-parameter
components must be a valid VkComponentMapping structure
VUID-VkImageViewCreateInfo-subresourceRange-parameter
subresourceRange must be a valid VkImageSubresourceRange structure

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 {
} 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;

or the equivalent

// Provided by VK_KHR_maintenance2
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)

VUID-VkImageViewUsageCreateInfo-sType-sType
sType must be VK_STRUCTURE_TYPE_IMAGE_VIEW_USAGE_CREATE_INFO
VUID-VkImageViewUsageCreateInfo-usage-parameter
usage must be a valid combination of VkImageUsageFlagBits values
VUID-VkImageViewUsageCreateInfo-usage-requiredbitmask
usage must not be 0

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. However, 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′C_BC_R 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′C_BC_R conversion is not enabled in the sampler and the image format is multi-planar, 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

VUID-VkImageSubresourceRange-levelCount-01720
If levelCount is not VK_REMAINING_MIP_LEVELS, it must be greater than 0
VUID-VkImageSubresourceRange-layerCount-01721
If layerCount is not VK_REMAINING_ARRAY_LAYERS, it must be greater than 0
VUID-VkImageSubresourceRange-aspectMask-01670
If aspectMask includes VK_IMAGE_ASPECT_COLOR_BIT, then it must not include any of VK_IMAGE_ASPECT_PLANE_0_BIT, VK_IMAGE_ASPECT_PLANE_1_BIT, or VK_IMAGE_ASPECT_PLANE_2_BIT

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_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;

VK_IMAGE_ASPECT_NONE specifies no image aspect, or the image aspect is not applicable.
VK_IMAGE_ASPECT_COLOR_BIT specifies the color aspect.
VK_IMAGE_ASPECT_DEPTH_BIT specifies the depth aspect.
VK_IMAGE_ASPECT_STENCIL_BIT specifies the stencil aspect.
VK_IMAGE_ASPECT_METADATA_BIT specifies the metadata aspect used for sparse resource operations.
VK_IMAGE_ASPECT_PLANE_0_BIT specifies plane 0 of a multi-planar image format.
VK_IMAGE_ASPECT_PLANE_1_BIT specifies plane 1 of a multi-planar image format.
VK_IMAGE_ASPECT_PLANE_2_BIT specifies plane 2 of a multi-planar image format.

// 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)

VUID-VkComponentMapping-r-parameter
r must be a valid VkComponentSwizzle value
VUID-VkComponentMapping-g-parameter
g must be a valid VkComponentSwizzle value
VUID-VkComponentMapping-b-parameter
b must be a valid VkComponentSwizzle value
VUID-VkComponentMapping-a-parameter
a must be a valid VkComponentSwizzle value

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;

VK_COMPONENT_SWIZZLE_IDENTITY specifies that the component is set to the identity swizzle.
VK_COMPONENT_SWIZZLE_ZERO specifies that the component is set to zero.
VK_COMPONENT_SWIZZLE_ONE specifies that the component is set to either 1 or 1.0, depending on whether the type of the image view format is integer or floating-point respectively, as determined by the Format Definition section for each VkFormat.
VK_COMPONENT_SWIZZLE_R specifies that the component is set to the value of the R component of the image.
VK_COMPONENT_SWIZZLE_G specifies that the component is set to the value of the G component of the image.
VK_COMPONENT_SWIZZLE_B specifies that the component is set to the value of the B component of the image.
VK_COMPONENT_SWIZZLE_A specifies that the component is set to the value of the A component of the image.

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

Table 12. 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`

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

12.5.1. 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.

If Vulkan 1.3 is supported or the VK_KHR_format_feature_flags2 extension is supported, and VkImageViewCreateInfo::image was created with VK_IMAGE_TILING_LINEAR, then the image view’s set of format features is the value of VkFormatProperties3::linearTilingFeatures found by calling vkGetPhysicalDeviceFormatProperties2 on the same format as VkImageViewCreateInfo::format.
If Vulkan 1.3 is not supported and the VK_KHR_format_feature_flags2 extension is not supported, and VkImageViewCreateInfo::image was created with VK_IMAGE_TILING_LINEAR, then the image view’s set of format features is the union of the value of VkFormatProperties::linearTilingFeatures found by calling vkGetPhysicalDeviceFormatProperties on the same format as VkImageViewCreateInfo::format, with:
- VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_DEPTH_COMPARISON_BIT if the format is a depth/stencil format and the image view features also contain VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_BIT.
- VK_FORMAT_FEATURE_2_STORAGE_READ_WITHOUT_FORMAT_BIT if the format is one of the extended storage formats and shaderStorageImageReadWithoutFormat is enabled on the device.
- VK_FORMAT_FEATURE_2_STORAGE_WRITE_WITHOUT_FORMAT_BIT if the format is one of the extended storage formats and shaderStorageImageWriteWithoutFormat is enabled on the device.
If Vulkan 1.3 is supported or the VK_KHR_format_feature_flags2 extension is supported, and VkImageViewCreateInfo::image was created with VK_IMAGE_TILING_OPTIMAL, then the image view’s set of format features is the value of VkFormatProperties::optimalTilingFeatures or VkFormatProperties3::optimalTilingFeatures found by calling vkGetPhysicalDeviceFormatProperties or vkGetPhysicalDeviceImageFormatProperties2 on the same format as VkImageViewCreateInfo::format.
If Vulkan 1.3 is not supported and the VK_KHR_format_feature_flags2 extension is not supported, and VkImageViewCreateInfo::image was created with VK_IMAGE_TILING_OPTIMAL, then the image view’s set of format features is the union of the value of VkFormatProperties::optimalTilingFeatures found by calling vkGetPhysicalDeviceFormatProperties on the same format as VkImageViewCreateInfo::format, with:
- VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_DEPTH_COMPARISON_BIT if the format is a depth/stencil format and the image view features also contain VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_BIT.
- VK_FORMAT_FEATURE_2_STORAGE_READ_WITHOUT_FORMAT_BIT if the format is one of the extended storage formats and shaderStorageImageReadWithoutFormat is enabled on the device.
- VK_FORMAT_FEATURE_2_STORAGE_WRITE_WITHOUT_FORMAT_BIT if the format is one of the extended storage formats and shaderStorageImageWriteWithoutFormat is enabled on the device.

12.6. 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 this extension, 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 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.

Note

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.

Note

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

VUID-vkCreateAccelerationStructureKHR-accelerationStructure-03611
The VkPhysicalDeviceAccelerationStructureFeaturesKHR::accelerationStructure feature must be enabled
VUID-vkCreateAccelerationStructureKHR-deviceAddress-03488
If VkAccelerationStructureCreateInfoKHR::deviceAddress is not zero, the accelerationStructureCaptureReplay feature must be enabled
VUID-vkCreateAccelerationStructureKHR-device-03489
If device was created with multiple physical devices, then the bufferDeviceAddressMultiDevice feature must be enabled

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

Return Codes

Success

VK_SUCCESS

Failure

VK_ERROR_OUT_OF_HOST_MEMORY
VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS_KHR

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 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.

Note

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.

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

Note

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.

Valid Usage

VUID-VkAccelerationStructureCreateInfoKHR-deviceAddress-03612
If deviceAddress is not zero, createFlags must include VK_ACCELERATION_STRUCTURE_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT_KHR
VUID-VkAccelerationStructureCreateInfoKHR-deviceAddress-09488
If deviceAddress is not zero, it must have been retrieved from an identically created acceleration structure, except for buffer and deviceAddress
VUID-VkAccelerationStructureCreateInfoKHR-deviceAddress-09489
If deviceAddress is not zero, buffer must have been created identically to the buffer used to create the acceleration structure from which deviceAddress was retrieved, except for VkBufferOpaqueCaptureAddressCreateInfo::opaqueCaptureAddress
VUID-VkAccelerationStructureCreateInfoKHR-deviceAddress-09490
If deviceAddress is not zero, buffer must have been created with a VkBufferOpaqueCaptureAddressCreateInfo::opaqueCaptureAddress that was retrieved from vkGetBufferOpaqueCaptureAddress for the buffer that was used to create the acceleration structure from which deviceAddress was retrieved
VUID-VkAccelerationStructureCreateInfoKHR-createFlags-03613
If createFlags includes VK_ACCELERATION_STRUCTURE_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT_KHR, VkPhysicalDeviceAccelerationStructureFeaturesKHR::accelerationStructureCaptureReplay must be VK_TRUE
VUID-VkAccelerationStructureCreateInfoKHR-buffer-03614
buffer must have been created with a usage value containing VK_BUFFER_USAGE_ACCELERATION_STRUCTURE_STORAGE_BIT_KHR
VUID-VkAccelerationStructureCreateInfoKHR-buffer-03615
buffer must not have been created with VK_BUFFER_CREATE_SPARSE_RESIDENCY_BIT
VUID-VkAccelerationStructureCreateInfoKHR-offset-03616
The sum of offset and size must be less than the size of buffer
VUID-VkAccelerationStructureCreateInfoKHR-offset-03734
offset must be a multiple of 256 bytes

Valid Usage (Implicit)

VUID-VkAccelerationStructureCreateInfoKHR-sType-sType
sType must be VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_CREATE_INFO_KHR
VUID-VkAccelerationStructureCreateInfoKHR-pNext-pNext
pNext must be NULL
VUID-VkAccelerationStructureCreateInfoKHR-createFlags-parameter
createFlags must be a valid combination of VkAccelerationStructureCreateFlagBitsKHR values
VUID-VkAccelerationStructureCreateInfoKHR-buffer-parameter
buffer must be a valid VkBuffer handle
VUID-VkAccelerationStructureCreateInfoKHR-type-parameter
type must be a valid VkAccelerationStructureTypeKHR value

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 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:

The build command is a host build command, and buildType is VK_ACCELERATION_STRUCTURE_BUILD_TYPE_HOST_KHR or VK_ACCELERATION_STRUCTURE_BUILD_TYPE_HOST_OR_DEVICE_KHR
The build command is a device build command, and buildType is VK_ACCELERATION_STRUCTURE_BUILD_TYPE_DEVICE_KHR or VK_ACCELERATION_STRUCTURE_BUILD_TYPE_HOST_OR_DEVICE_KHR
For VkAccelerationStructureBuildGeometryInfoKHR:
- Its type, and flags members are equal to pBuildInfo->type and pBuildInfo->flags, respectively.
- geometryCount is less than or equal to pBuildInfo->geometryCount.
- For each element of either pGeometries or ppGeometries at a given index, its geometryType member is equal to pBuildInfo->geometryType.
- For each element of either pGeometries or ppGeometries at a given index, its flags member is equal to the corresponding member of the same element in pBuildInfo.
- For each element of either pGeometries or ppGeometries at a given index, with a geometryType member equal to VK_GEOMETRY_TYPE_TRIANGLES_KHR, the vertexFormat and indexType members of geometry.triangles are equal to the corresponding members of the same element in pBuildInfo.
- For each element of either pGeometries or ppGeometries at a given index, with a geometryType member equal to VK_GEOMETRY_TYPE_TRIANGLES_KHR, the maxVertex member of geometry.triangles is less than or equal to the corresponding member of the same element in pBuildInfo.
- For each element of either pGeometries or ppGeometries at a given index, with a geometryType member equal to VK_GEOMETRY_TYPE_TRIANGLES_KHR, if the applicable address in the transformData member of geometry.triangles is not NULL, the corresponding transformData.hostAddress parameter in pBuildInfo is not NULL.
For each VkAccelerationStructureBuildRangeInfoKHR corresponding to the VkAccelerationStructureBuildGeometryInfoKHR:
- Its primitiveCount member is less than or equal to the corresponding element of pMaxPrimitiveCounts.
- For each element of either pGeometries or ppGeometries at a given index, with a geometryType member equal to VK_GEOMETRY_TYPE_TRIANGLES_KHR, if the pNext chain contains VkAccelerationStructureTrianglesOpacityMicromapEXT the corresponding member of pBuildInfo also contains VkAccelerationStructureTrianglesOpacityMicromapEXT and with an equivalent micromap.

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

VUID-vkGetAccelerationStructureBuildSizesKHR-accelerationStructure-08933
The VkPhysicalDeviceAccelerationStructureFeaturesKHR::accelerationStructure feature must be enabled
VUID-vkGetAccelerationStructureBuildSizesKHR-device-03618
If device was created with multiple physical devices, then the bufferDeviceAddressMultiDevice feature must be enabled
VUID-vkGetAccelerationStructureBuildSizesKHR-pBuildInfo-03619
If pBuildInfo->geometryCount is not 0, pMaxPrimitiveCounts must be a valid pointer to an array of pBuildInfo->geometryCount uint32_t values
VUID-vkGetAccelerationStructureBuildSizesKHR-pBuildInfo-03785
If pBuildInfo->pGeometries or pBuildInfo->ppGeometries has a geometryType of VK_GEOMETRY_TYPE_INSTANCES_KHR, each pMaxPrimitiveCounts[i] must be less than or equal to VkPhysicalDeviceAccelerationStructurePropertiesKHR::maxInstanceCount

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;
    const 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)

VUID-VkAccelerationStructureBuildSizesInfoKHR-sType-sType
sType must be VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_BUILD_SIZES_INFO_KHR
VUID-VkAccelerationStructureBuildSizesInfoKHR-pNext-pNext
pNext must be NULL

Values which can be set in VkAccelerationStructureCreateInfoKHR::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,
} VkAccelerationStructureTypeKHR;

VK_ACCELERATION_STRUCTURE_TYPE_TOP_LEVEL_KHR is a top-level acceleration structure containing instance data referring to bottom-level acceleration structures.
VK_ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_KHR is a bottom-level acceleration structure containing the AABBs or geometry to be intersected.
VK_ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR is an acceleration structure whose type is determined at build time used for special circumstances. In these cases, the acceleration structure type is not known at creation time, but must be specified at build time as either top or bottom.

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,
} VkAccelerationStructureCreateFlagBitsKHR;

VK_ACCELERATION_STRUCTURE_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT_KHR specifies that the acceleration structure’s address can be saved and reused on a subsequent run.

// 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 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_EXT_opacity_micromap
    VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_OPACITY_MICROMAP_UPDATE_EXT = 0x00000040,
  // Provided by VK_EXT_opacity_micromap
    VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_DISABLE_OPACITY_MICROMAPS_EXT = 0x00000080,
  // Provided by VK_EXT_opacity_micromap
    VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_OPACITY_MICROMAP_DATA_UPDATE_EXT = 0x00000100,
  // Provided by VK_KHR_ray_tracing_position_fetch
    VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_DATA_ACCESS_KHR = 0x00000800,
} VkBuildAccelerationStructureFlagBitsKHR;

VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_UPDATE_BIT_KHR indicates that the specified acceleration structure can be updated with a mode of VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR in VkAccelerationStructureBuildGeometryInfoKHR .
VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_COMPACTION_BIT_KHR indicates that the specified acceleration structure can act as the source for a copy acceleration structure command with mode of VK_COPY_ACCELERATION_STRUCTURE_MODE_COMPACT_KHR to produce a compacted acceleration structure.
VK_BUILD_ACCELERATION_STRUCTURE_PREFER_FAST_TRACE_BIT_KHR indicates that the given acceleration structure build should prioritize trace performance over build time.
VK_BUILD_ACCELERATION_STRUCTURE_PREFER_FAST_BUILD_BIT_KHR indicates that the given acceleration structure build should prioritize build time over trace performance.
VK_BUILD_ACCELERATION_STRUCTURE_LOW_MEMORY_BIT_KHR indicates that this acceleration structure should minimize the size of the scratch memory and the final result acceleration structure, potentially at the expense of build time or trace performance.
VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_OPACITY_MICROMAP_UPDATE_EXT indicates that the opacity micromaps associated with the specified acceleration structure may change with an acceleration structure update.
VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_OPACITY_MICROMAP_DATA_UPDATE_EXT indicates that the data of the opacity micromaps associated with the specified acceleration structure may change with an acceleration structure update.
VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_DISABLE_OPACITY_MICROMAPS_EXT indicates that the specified acceleration structure may be referenced in an instance with VK_GEOMETRY_INSTANCE_DISABLE_OPACITY_MICROMAPS_EXT set.
VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_DATA_ACCESS_KHR indicates that the specified acceleration structure can be used when fetching the vertex positions of a hit triangle.

Note

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.

// Provided by VK_KHR_acceleration_structure
typedef VkFlags VkBuildAccelerationStructureFlagsKHR;

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

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,
} VkGeometryTypeKHR;

VK_GEOMETRY_TYPE_TRIANGLES_KHR specifies a geometry type consisting of triangles.
VK_GEOMETRY_TYPE_AABBS_KHR specifies a geometry type consisting of axis-aligned bounding boxes.
VK_GEOMETRY_TYPE_INSTANCES_KHR specifies a geometry type consisting of acceleration structure instances.

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,
} VkGeometryFlagBitsKHR;

VK_GEOMETRY_OPAQUE_BIT_KHR indicates 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 indicates 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;

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

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

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;

VK_ACCELERATION_STRUCTURE_BUILD_TYPE_HOST_KHR requests the memory requirement for operations performed by the host.
VK_ACCELERATION_STRUCTURE_BUILD_TYPE_DEVICE_KHR requests the memory requirement for operations performed by the device.
VK_ACCELERATION_STRUCTURE_BUILD_TYPE_HOST_OR_DEVICE_KHR requests the memory requirement for operations performed by either the host, or the device.

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.

Note

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

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)

VUID-VkAccelerationStructureDeviceAddressInfoKHR-sType-sType
sType must be VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_DEVICE_ADDRESS_INFO_KHR
VUID-VkAccelerationStructureDeviceAddressInfoKHR-pNext-pNext
pNext must be NULL
VUID-VkAccelerationStructureDeviceAddressInfoKHR-accelerationStructure-parameter
accelerationStructure must be a valid VkAccelerationStructureKHR handle

12.7. 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 acceleration structure 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.

Note

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

VUID-vkCreateMicromapEXT-micromap-07430
The micromap feature must be enabled
VUID-vkCreateMicromapEXT-deviceAddress-07431
If VkMicromapCreateInfoEXT::deviceAddress is not zero, the micromapCaptureReplay feature must be enabled
VUID-vkCreateMicromapEXT-device-07432
If device was created with multiple physical devices, then the bufferDeviceAddressMultiDevice feature must be enabled

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

Return Codes

Success

VK_SUCCESS

Failure

VK_ERROR_OUT_OF_HOST_MEMORY
VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS_KHR

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.

Note

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.

If the micromap will be the target of a build operation, the required size for a micromap can be queried with vkGetMicromapBuildSizesEXT.

Valid Usage

VUID-VkMicromapCreateInfoEXT-deviceAddress-07433
If deviceAddress is not zero, createFlags must include VK_MICROMAP_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT_EXT
VUID-VkMicromapCreateInfoEXT-createFlags-07434
If createFlags includes VK_MICROMAP_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT_EXT, VkPhysicalDeviceOpacityMicromapFeaturesEXT::micromapCaptureReplay must be VK_TRUE
VUID-VkMicromapCreateInfoEXT-buffer-07435
buffer must have been created with a usage value containing VK_BUFFER_USAGE_MICROMAP_STORAGE_BIT_EXT
VUID-VkMicromapCreateInfoEXT-buffer-07436
buffer must not have been created with VK_BUFFER_CREATE_SPARSE_RESIDENCY_BIT
VUID-VkMicromapCreateInfoEXT-offset-07437
The sum of offset and size must be less than the size of buffer
VUID-VkMicromapCreateInfoEXT-offset-07438
offset must be a multiple of 256 bytes

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

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 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:

The build command is a host build command, and buildType is VK_ACCELERATION_STRUCTURE_BUILD_TYPE_HOST_KHR or VK_ACCELERATION_STRUCTURE_BUILD_TYPE_HOST_OR_DEVICE_KHR
The build command is a device build command, and buildType is VK_ACCELERATION_STRUCTURE_BUILD_TYPE_DEVICE_KHR or VK_ACCELERATION_STRUCTURE_BUILD_TYPE_HOST_OR_DEVICE_KHR
For VkMicromapBuildInfoEXT:
- Its type, and flags members are equal to pBuildInfo->type and pBuildInfo->flags, respectively.
- The sum of usage information in either pUsageCounts or ppUsageCounts is equal to the sum of usage information in either pBuildInfo->pUsageCounts or pBuildInfo->ppUsageCounts.

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)

VUID-VkMicromapBuildSizesInfoEXT-sType-sType
sType must be VK_STRUCTURE_TYPE_MICROMAP_BUILD_SIZES_INFO_EXT
VUID-VkMicromapBuildSizesInfoEXT-pNext-pNext
pNext must be NULL

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,
} VkMicromapTypeEXT;

VK_MICROMAP_TYPE_OPACITY_MICROMAP_EXT is a micromap containing data to control the opacity of a triangle.

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;

VK_MICROMAP_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT_EXT specifies that the micromap’s address can be saved and reused on a subsequent run.

// 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;

VK_BUILD_MICROMAP_PREFER_FAST_TRACE_BIT_EXT indicates that the given micromap build should prioritize trace performance over build time.
VK_BUILD_MICROMAP_PREFER_FAST_BUILD_BIT_EXT indicates that the given micromap build should prioritize build time over trace performance.

// 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-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

12.8. 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 image or buffer 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.

Note

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

VUID-vkGetImageMemoryRequirements-image-01588
image must not have been created with the VK_IMAGE_CREATE_DISJOINT_BIT flag set

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

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.

If the resource being queried was created with the VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_BIT, VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_KMT_BIT, or VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_RESOURCE_BIT external memory handle type, the value of size has no meaning and should be ignored.

The implementation guarantees certain properties about the memory requirements returned by vkGetBufferMemoryRequirements2, vkGetImageMemoryRequirements2, vkGetDeviceBufferMemoryRequirements, vkGetDeviceImageMemoryRequirements, vkGetBufferMemoryRequirements and vkGetImageMemoryRequirements:

The memoryTypeBits member always contains at least one bit set.
If buffer is a VkBuffer not created with the VK_BUFFER_CREATE_SPARSE_BINDING_BIT or VK_BUFFER_CREATE_PROTECTED_BIT bits set, or if image is a linear image that was not created with the VK_IMAGE_CREATE_PROTECTED_BIT bit set, then the memoryTypeBits member always contains at least one bit set corresponding to a VkMemoryType with a propertyFlags that has both the VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT bit and the VK_MEMORY_PROPERTY_HOST_COHERENT_BIT bit set. In other words, mappable coherent memory can always be attached to these objects.
If buffer was created with VkExternalMemoryBufferCreateInfo::handleTypes set to 0 or image was created with VkExternalMemoryImageCreateInfo::handleTypes set to 0, the memoryTypeBits member always contains at least one bit set corresponding to a VkMemoryType with a propertyFlags that has the VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT bit set.
The memoryTypeBits member is identical for all VkBuffer objects created with the same value for the flags and usage members in the VkBufferCreateInfo structure and the handleTypes member of the VkExternalMemoryBufferCreateInfo structure passed to vkCreateBuffer. Further, if usage1 and usage2 of type VkBufferUsageFlags are such that the bits set in usage2 are a subset of the bits set in usage1, and they have the same flags and VkExternalMemoryBufferCreateInfo::handleTypes, then the bits set in memoryTypeBits returned for usage1 must be a subset of the bits set in memoryTypeBits returned for usage2, for all values of flags.
The alignment member is a power of two.
The alignment member is identical for all VkBuffer objects created with the same combination of values for the usage and flags members in the VkBufferCreateInfo structure passed to vkCreateBuffer.
If the maintenance4 feature is enabled, then the alignment member is identical for all VkImage objects created with the same combination of values for the flags, imageType, format, extent, mipLevels, arrayLayers, samples, tiling and usage members in the VkImageCreateInfo structure passed to vkCreateImage.
The alignment member satisfies the buffer descriptor offset alignment requirements associated with the VkBuffer’s usage:
- If usage included VK_BUFFER_USAGE_UNIFORM_TEXEL_BUFFER_BIT or VK_BUFFER_USAGE_STORAGE_TEXEL_BUFFER_BIT, alignment must be an integer multiple of VkPhysicalDeviceLimits::minTexelBufferOffsetAlignment.
- If usage included VK_BUFFER_USAGE_UNIFORM_BUFFER_BIT, alignment must be an integer multiple of VkPhysicalDeviceLimits::minUniformBufferOffsetAlignment.
- If usage included VK_BUFFER_USAGE_STORAGE_BUFFER_BIT, alignment must be an integer multiple of VkPhysicalDeviceLimits::minStorageBufferOffsetAlignment.
For images created with a color format, the memoryTypeBits member is identical for all VkImage objects created with the same combination of values for the tiling member, the VK_IMAGE_CREATE_SPARSE_BINDING_BIT bit of the flags member, the VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT bit of the flags member, the VK_IMAGE_USAGE_HOST_TRANSFER_BIT_EXT bit of the usage member if the VkPhysicalDeviceHostImageCopyPropertiesEXT::identicalMemoryTypeRequirements property is VK_FALSE, handleTypes member of VkExternalMemoryImageCreateInfo, and the VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT of the usage member in the VkImageCreateInfo structure passed to vkCreateImage.
For images created with a depth/stencil format, the memoryTypeBits member is identical for all VkImage objects created with the same combination of values for the format member, the tiling member, the VK_IMAGE_CREATE_SPARSE_BINDING_BIT bit of the flags member, the VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT bit of the flags member, the VK_IMAGE_USAGE_HOST_TRANSFER_BIT_EXT bit of the usage member if the VkPhysicalDeviceHostImageCopyPropertiesEXT::identicalMemoryTypeRequirements property is VK_FALSE, handleTypes member of VkExternalMemoryImageCreateInfo, and the VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT of the usage member in the VkImageCreateInfo structure passed to vkCreateImage.
If the memory requirements are for a VkImage, the memoryTypeBits member must not refer to a VkMemoryType with a propertyFlags that has the VK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT bit set if the image did not have VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT bit set in the usage member of the VkImageCreateInfo structure passed to vkCreateImage.
If the memory requirements are for a VkBuffer, the memoryTypeBits member must not refer to a VkMemoryType with a propertyFlags that has the VK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT bit set.

Note

The implication of this requirement is that lazily allocated memory is disallowed for buffers in all cases.
The size member is identical for all VkBuffer objects created with the same combination of creation parameters specified in VkBufferCreateInfo and its pNext chain.

The size member is identical for all VkImage objects created with the same combination of creation parameters specified in VkImageCreateInfo and its pNext chain.

Note

This, however, does not imply that they interpret the contents of the bound memory identically with each other. That additional guarantee, however, can be explicitly requested using VK_IMAGE_CREATE_ALIAS_BIT.

If the maintenance4 feature is enabled, these additional guarantees apply:
- For a VkBuffer, the size memory requirement is never greater than that of another VkBuffer created with a greater or equal size specified in VkBufferCreateInfo, all other creation parameters being identical.
- For a VkBuffer, the size memory requirement is never greater than the result of aligning VkBufferCreateInfo::size with the alignment memory requirement.
- For a VkImage, the size memory requirement is never greater than that of another VkImage created with a greater or equal value in each of extent.width, extent.height, and extent.depth; all other creation parameters being identical.
- The memory requirements returned by vkGetDeviceBufferMemoryRequirements are identical to those that would be returned by vkGetBufferMemoryRequirements2 if it were called with a VkBuffer created with the same VkBufferCreateInfo values.
- The memory requirements returned by vkGetDeviceImageMemoryRequirements are identical to those that would be returned by vkGetImageMemoryRequirements2 if it were called with a VkImage created with the same VkImageCreateInfo values.

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);

or the equivalent command

// Provided by VK_KHR_get_memory_requirements2
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);

or the equivalent command

// Provided by VK_KHR_maintenance4
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;

or the equivalent

// Provided by VK_KHR_get_memory_requirements2
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)

VUID-VkBufferMemoryRequirementsInfo2-sType-sType
sType must be VK_STRUCTURE_TYPE_BUFFER_MEMORY_REQUIREMENTS_INFO_2
VUID-VkBufferMemoryRequirementsInfo2-pNext-pNext
pNext must be NULL
VUID-VkBufferMemoryRequirementsInfo2-buffer-parameter
buffer must be a valid VkBuffer handle

The VkDeviceBufferMemoryRequirements structure is defined as:

// Provided by VK_VERSION_1_3
typedef struct VkDeviceBufferMemoryRequirements {
    VkStructureType              sType;
    const void*                  pNext;
    const VkBufferCreateInfo*    pCreateInfo;
} VkDeviceBufferMemoryRequirements;

or the equivalent

// Provided by VK_KHR_maintenance4
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)

VUID-VkDeviceBufferMemoryRequirements-sType-sType
sType must be VK_STRUCTURE_TYPE_DEVICE_BUFFER_MEMORY_REQUIREMENTS
VUID-VkDeviceBufferMemoryRequirements-pNext-pNext
pNext must be NULL
VUID-VkDeviceBufferMemoryRequirements-pCreateInfo-parameter
pCreateInfo must be a valid pointer to a valid VkBufferCreateInfo structure

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);

or the equivalent command

// Provided by VK_KHR_get_memory_requirements2
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);

or the equivalent command

// Provided by VK_KHR_maintenance4
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;

or the equivalent

// Provided by VK_KHR_get_memory_requirements2
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

VUID-VkImageMemoryRequirementsInfo2-image-01589
If image was created with a multi-planar format and the VK_IMAGE_CREATE_DISJOINT_BIT flag, there must be a VkImagePlaneMemoryRequirementsInfo included in the pNext chain of the VkImageMemoryRequirementsInfo2 structure
VUID-VkImageMemoryRequirementsInfo2-image-01590
If image was not created with the VK_IMAGE_CREATE_DISJOINT_BIT flag, there must not be a VkImagePlaneMemoryRequirementsInfo included in the pNext chain of the VkImageMemoryRequirementsInfo2 structure
VUID-VkImageMemoryRequirementsInfo2-image-01591
If image was created with a single-plane format, there must not be a VkImagePlaneMemoryRequirementsInfo included in the pNext chain of the VkImageMemoryRequirementsInfo2 structure

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 struct 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;

or the equivalent

// Provided by VK_KHR_maintenance4
typedef VkDeviceImageMemoryRequirements VkDeviceImageMemoryRequirementsKHR;

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.
planeAspect is a VkImageAspectFlagBits value specifying the aspect corresponding to the image plane to query. This parameter is ignored unless pCreateInfo->flags has VK_IMAGE_CREATE_DISJOINT_BIT set.

Valid Usage

VUID-VkDeviceImageMemoryRequirements-pCreateInfo-06416
The pCreateInfo->pNext chain must not contain a VkImageSwapchainCreateInfoKHR structure
VUID-VkDeviceImageMemoryRequirements-pCreateInfo-06417
If pCreateInfo->format specifies a multi-planar format and pCreateInfo->flags has VK_IMAGE_CREATE_DISJOINT_BIT set then planeAspect must not be VK_IMAGE_ASPECT_NONE_KHR
VUID-VkDeviceImageMemoryRequirements-pCreateInfo-06419
If pCreateInfo->flags has VK_IMAGE_CREATE_DISJOINT_BIT set and if the pCreateInfo->tiling is VK_IMAGE_TILING_LINEAR or VK_IMAGE_TILING_OPTIMAL, then planeAspect must be a single valid multi-planar aspect mask bit

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;

or the equivalent

// Provided by VK_KHR_sampler_ycbcr_conversion
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

VUID-VkImagePlaneMemoryRequirementsInfo-planeAspect-02281
If the image’s tiling is VK_IMAGE_TILING_LINEAR or VK_IMAGE_TILING_OPTIMAL, then planeAspect must be a single valid multi-planar aspect mask bit

Valid Usage (Implicit)

VUID-VkImagePlaneMemoryRequirementsInfo-sType-sType
sType must be VK_STRUCTURE_TYPE_IMAGE_PLANE_MEMORY_REQUIREMENTS_INFO
VUID-VkImagePlaneMemoryRequirementsInfo-planeAspect-parameter
planeAspect must be a valid VkImageAspectFlagBits value

The VkMemoryRequirements2 structure is defined as:

// Provided by VK_VERSION_1_1
typedef struct VkMemoryRequirements2 {
    VkStructureType         sType;
    void*                   pNext;
    VkMemoryRequirements    memoryRequirements;
} VkMemoryRequirements2;

or the equivalent

// Provided by VK_KHR_get_memory_requirements2
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)

VUID-VkMemoryRequirements2-sType-sType
sType must be VK_STRUCTURE_TYPE_MEMORY_REQUIREMENTS_2
VUID-VkMemoryRequirements2-pNext-pNext
pNext must be NULL or a pointer to a valid instance of VkMemoryDedicatedRequirements
VUID-VkMemoryRequirements2-sType-unique
The sType value of each struct in the pNext chain must be unique

The VkMemoryDedicatedRequirements structure is defined as:

// Provided by VK_VERSION_1_1
typedef struct VkMemoryDedicatedRequirements {
    VkStructureType    sType;
    void*              pNext;
    VkBool32           prefersDedicatedAllocation;
    VkBool32           requiresDedicatedAllocation;
} VkMemoryDedicatedRequirements;

or the equivalent

// Provided by VK_KHR_dedicated_allocation
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 resource, add a VkMemoryDedicatedRequirements structure to the pNext chain of the VkMemoryRequirements2 structure passed as the pMemoryRequirements parameter of vkGetBufferMemoryRequirements2 or vkGetImageMemoryRequirements2, respectively.

Constraints on the values returned for buffer resources are:

requiresDedicatedAllocation may be VK_TRUE if the pNext chain of VkBufferCreateInfo for the call to vkCreateBuffer used to create the buffer being queried included a VkExternalMemoryBufferCreateInfo structure, and any of the handle types specified in VkExternalMemoryBufferCreateInfo::handleTypes requires dedicated allocation, as reported by vkGetPhysicalDeviceExternalBufferProperties in VkExternalBufferProperties::externalMemoryProperties.externalMemoryFeatures. Otherwise, requiresDedicatedAllocation will be VK_FALSE.
When the implementation sets requiresDedicatedAllocation to VK_TRUE, it must also set prefersDedicatedAllocation to VK_TRUE.
If VK_BUFFER_CREATE_SPARSE_BINDING_BIT was set in VkBufferCreateInfo::flags when buffer was created, then both prefersDedicatedAllocation and requiresDedicatedAllocation will be VK_FALSE.

Constraints on the values returned for image resources are:

requiresDedicatedAllocation may be VK_TRUE if the pNext chain of VkImageCreateInfo for the call to vkCreateImage used to create the image being queried included a VkExternalMemoryImageCreateInfo structure, and any of the handle types specified in VkExternalMemoryImageCreateInfo::handleTypes requires dedicated allocation, as reported by vkGetPhysicalDeviceImageFormatProperties2 in VkExternalImageFormatProperties::externalMemoryProperties.externalMemoryFeatures.
requiresDedicatedAllocation will otherwise be VK_FALSE
If VK_IMAGE_CREATE_SPARSE_BINDING_BIT was set in VkImageCreateInfo::flags when image was created, then both prefersDedicatedAllocation and requiresDedicatedAllocation will be VK_FALSE.

Valid Usage (Implicit)

VUID-VkMemoryDedicatedRequirements-sType-sType
sType must be VK_STRUCTURE_TYPE_MEMORY_DEDICATED_REQUIREMENTS

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

VUID-vkBindBufferMemory-buffer-07459
buffer must not have been bound to a memory object
VUID-vkBindBufferMemory-buffer-01030
buffer must not have been created with any sparse memory binding flags
VUID-vkBindBufferMemory-memoryOffset-01031
memoryOffset must be less than the size of memory
VUID-vkBindBufferMemory-memory-01035
memory must have been allocated using one of the memory types allowed in the memoryTypeBits member of the VkMemoryRequirements structure returned from a call to vkGetBufferMemoryRequirements with buffer
VUID-vkBindBufferMemory-memoryOffset-01036
memoryOffset must be an integer multiple of the alignment member of the VkMemoryRequirements structure returned from a call to vkGetBufferMemoryRequirements with buffer
VUID-vkBindBufferMemory-size-01037
The size member of the VkMemoryRequirements structure returned from a call to vkGetBufferMemoryRequirements with buffer must be less than or equal to the size of memory minus memoryOffset
VUID-vkBindBufferMemory-buffer-01444
If buffer requires a dedicated allocation (as reported by vkGetBufferMemoryRequirements2 in VkMemoryDedicatedRequirements::requiresDedicatedAllocation for buffer), memory must have been allocated with VkMemoryDedicatedAllocateInfo::buffer equal to buffer
VUID-vkBindBufferMemory-memory-01508
If the VkMemoryAllocateInfo provided when memory was allocated included a VkMemoryDedicatedAllocateInfo structure in its pNext chain, and VkMemoryDedicatedAllocateInfo::buffer was not VK_NULL_HANDLE, then buffer must equal VkMemoryDedicatedAllocateInfo::buffer, and memoryOffset must be zero
VUID-vkBindBufferMemory-None-01898
If buffer was created with the VK_BUFFER_CREATE_PROTECTED_BIT bit set, the buffer must be bound to a memory object allocated with a memory type that reports VK_MEMORY_PROPERTY_PROTECTED_BIT
VUID-vkBindBufferMemory-None-01899
If buffer was created with the VK_BUFFER_CREATE_PROTECTED_BIT bit not set, the buffer must not be bound to a memory object allocated with a memory type that reports VK_MEMORY_PROPERTY_PROTECTED_BIT
VUID-vkBindBufferMemory-memory-02726
If the value of VkExportMemoryAllocateInfo::handleTypes used to allocate memory is not 0, it must include at least one of the handles set in VkExternalMemoryBufferCreateInfo::handleTypes when buffer was created
VUID-vkBindBufferMemory-memory-02985
If memory was allocated by a memory import operation, the external handle type of the imported memory must also have been set in VkExternalMemoryBufferCreateInfo::handleTypes when buffer was created
VUID-vkBindBufferMemory-bufferDeviceAddress-03339
If the VkPhysicalDeviceBufferDeviceAddressFeatures::bufferDeviceAddress feature is enabled and buffer was created with the VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT bit set, memory must have been allocated with the VK_MEMORY_ALLOCATE_DEVICE_ADDRESS_BIT bit set
VUID-vkBindBufferMemory-bufferDeviceAddressCaptureReplay-09200
If the VkPhysicalDeviceBufferDeviceAddressFeatures::bufferDeviceAddressCaptureReplay feature is enabled and buffer was created with the VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT bit set, memory must have been allocated with the VK_MEMORY_ALLOCATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT bit set

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

VK_SUCCESS

Failure

VK_ERROR_OUT_OF_HOST_MEMORY
VK_ERROR_OUT_OF_DEVICE_MEMORY
VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS_KHR

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);

or the equivalent command

// Provided by VK_KHR_bind_memory2
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.

Note

If the vkBindBufferMemory2 command failed, VkBindMemoryStatusKHR 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

VK_SUCCESS

Failure

VK_ERROR_OUT_OF_HOST_MEMORY
VK_ERROR_OUT_OF_DEVICE_MEMORY
VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS_KHR

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;

or the equivalent

// Provided by VK_KHR_bind_memory2
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

VUID-VkBindBufferMemoryInfo-buffer-07459
buffer must not have been bound to a memory object
VUID-VkBindBufferMemoryInfo-buffer-01030
buffer must not have been created with any sparse memory binding flags
VUID-VkBindBufferMemoryInfo-memoryOffset-01031
memoryOffset must be less than the size of memory
VUID-VkBindBufferMemoryInfo-memory-01035
memory must have been allocated using one of the memory types allowed in the memoryTypeBits member of the VkMemoryRequirements structure returned from a call to vkGetBufferMemoryRequirements with buffer
VUID-VkBindBufferMemoryInfo-memoryOffset-01036
memoryOffset must be an integer multiple of the alignment member of the VkMemoryRequirements structure returned from a call to vkGetBufferMemoryRequirements with buffer
VUID-VkBindBufferMemoryInfo-size-01037
The size member of the VkMemoryRequirements structure returned from a call to vkGetBufferMemoryRequirements with buffer must be less than or equal to the size of memory minus memoryOffset
VUID-VkBindBufferMemoryInfo-buffer-01444
If buffer requires a dedicated allocation (as reported by vkGetBufferMemoryRequirements2 in VkMemoryDedicatedRequirements::requiresDedicatedAllocation for buffer), memory must have been allocated with VkMemoryDedicatedAllocateInfo::buffer equal to buffer
VUID-VkBindBufferMemoryInfo-memory-01508
If the VkMemoryAllocateInfo provided when memory was allocated included a VkMemoryDedicatedAllocateInfo structure in its pNext chain, and VkMemoryDedicatedAllocateInfo::buffer was not VK_NULL_HANDLE, then buffer must equal VkMemoryDedicatedAllocateInfo::buffer, and memoryOffset must be zero
VUID-VkBindBufferMemoryInfo-None-01898
If buffer was created with the VK_BUFFER_CREATE_PROTECTED_BIT bit set, the buffer must be bound to a memory object allocated with a memory type that reports VK_MEMORY_PROPERTY_PROTECTED_BIT
VUID-VkBindBufferMemoryInfo-None-01899
If buffer was created with the VK_BUFFER_CREATE_PROTECTED_BIT bit not set, the buffer must not be bound to a memory object allocated with a memory type that reports VK_MEMORY_PROPERTY_PROTECTED_BIT
VUID-VkBindBufferMemoryInfo-memory-02726
If the value of VkExportMemoryAllocateInfo::handleTypes used to allocate memory is not 0, it must include at least one of the handles set in VkExternalMemoryBufferCreateInfo::handleTypes when buffer was created
VUID-VkBindBufferMemoryInfo-memory-02985
If memory was allocated by a memory import operation, the external handle type of the imported memory must also have been set in VkExternalMemoryBufferCreateInfo::handleTypes when buffer was created
VUID-VkBindBufferMemoryInfo-bufferDeviceAddress-03339
If the VkPhysicalDeviceBufferDeviceAddressFeatures::bufferDeviceAddress feature is enabled and buffer was created with the VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT bit set, memory must have been allocated with the VK_MEMORY_ALLOCATE_DEVICE_ADDRESS_BIT bit set
VUID-VkBindBufferMemoryInfo-bufferDeviceAddressCaptureReplay-09200
If the VkPhysicalDeviceBufferDeviceAddressFeatures::bufferDeviceAddressCaptureReplay feature is enabled and buffer was created with the VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT bit set, memory must have been allocated with the VK_MEMORY_ALLOCATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT bit set
VUID-VkBindBufferMemoryInfo-pNext-01605
If the pNext chain includes a VkBindBufferMemoryDeviceGroupInfo structure, all instances of memory specified by VkBindBufferMemoryDeviceGroupInfo::pDeviceIndices must have been allocated

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 VkBindMemoryStatusKHR
VUID-VkBindBufferMemoryInfo-sType-unique
The sType value of each struct 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

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;

or the equivalent

// Provided by VK_KHR_bind_memory2 with VK_KHR_device_group
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 VkBindMemoryStatusKHR structure is defined as:

// Provided by VK_KHR_maintenance6
typedef struct VkBindMemoryStatusKHR {
    VkStructureType    sType;
    const void*        pNext;
    VkResult*          pResult;
} 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 VkBindMemoryStatusKHR structure, then the VkBindMemoryStatusKHR::pResult will be populated with a value describing the result of the corresponding memory binding operation.

Valid Usage (Implicit)

VUID-VkBindMemoryStatusKHR-sType-sType
sType must be VK_STRUCTURE_TYPE_BIND_MEMORY_STATUS_KHR
VUID-VkBindMemoryStatusKHR-pResult-parameter
pResult must be a valid pointer to a VkResult value

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

VUID-vkBindImageMemory-image-07460
image must not have been bound to a memory object
VUID-vkBindImageMemory-image-01045
image must not have been created with any sparse memory binding flags
VUID-vkBindImageMemory-memoryOffset-01046
memoryOffset must be less than the size of memory
VUID-vkBindImageMemory-image-01445
If image requires a dedicated allocation (as reported by vkGetImageMemoryRequirements2 in VkMemoryDedicatedRequirements::requiresDedicatedAllocation for image), memory must have been created with VkMemoryDedicatedAllocateInfo::image equal to image
VUID-vkBindImageMemory-memory-02628
If the VkMemoryAllocateInfo provided when memory was allocated included a VkMemoryDedicatedAllocateInfo structure in its pNext chain, and VkMemoryDedicatedAllocateInfo::image was not VK_NULL_HANDLE, then image must equal VkMemoryDedicatedAllocateInfo::image and memoryOffset must be zero
VUID-vkBindImageMemory-None-01901
If image was created with the VK_IMAGE_CREATE_PROTECTED_BIT bit set, the image must be bound to a memory object allocated with a memory type that reports VK_MEMORY_PROPERTY_PROTECTED_BIT
VUID-vkBindImageMemory-None-01902
If image was created with the VK_IMAGE_CREATE_PROTECTED_BIT bit not set, the image must not be bound to a memory object created with a memory type that reports VK_MEMORY_PROPERTY_PROTECTED_BIT
VUID-vkBindImageMemory-memory-02728
If the value of VkExportMemoryAllocateInfo::handleTypes used to allocate memory is not 0, it must include at least one of the handles set in VkExternalMemoryImageCreateInfo::handleTypes when image was created
VUID-vkBindImageMemory-memory-02989
If memory was created by a memory import operation, the external handle type of the imported memory must also have been set in VkExternalMemoryImageCreateInfo::handleTypes when image was created
VUID-vkBindImageMemory-image-01608
image must not have been created with the VK_IMAGE_CREATE_DISJOINT_BIT set
VUID-vkBindImageMemory-memory-01047
memory must have been allocated using one of the memory types allowed in the memoryTypeBits member of the VkMemoryRequirements structure returned from a call to vkGetImageMemoryRequirements with image
VUID-vkBindImageMemory-memoryOffset-01048
memoryOffset must be an integer multiple of the alignment member of the VkMemoryRequirements structure returned from a call to vkGetImageMemoryRequirements with image
VUID-vkBindImageMemory-size-01049
The difference of the size of memory and memoryOffset must be greater than or equal to the size member of the VkMemoryRequirements structure returned from a call to vkGetImageMemoryRequirements with the same image

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

VK_SUCCESS

Failure

VK_ERROR_OUT_OF_HOST_MEMORY
VK_ERROR_OUT_OF_DEVICE_MEMORY

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);

or the equivalent command

// Provided by VK_KHR_bind_memory2
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.

Note

If the vkBindImageMemory2 command failed, VkBindMemoryStatusKHR 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

VUID-vkBindImageMemory2-pBindInfos-02858
If any VkBindImageMemoryInfo::image was created with VK_IMAGE_CREATE_DISJOINT_BIT then all planes of VkBindImageMemoryInfo::image must be bound individually in separate pBindInfos
VUID-vkBindImageMemory2-pBindInfos-04006
pBindInfos must not refer to the same image subresource more than once

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

VK_SUCCESS

Failure

VK_ERROR_OUT_OF_HOST_MEMORY
VK_ERROR_OUT_OF_DEVICE_MEMORY

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;

or the equivalent

// Provided by VK_KHR_bind_memory2
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

VUID-VkBindImageMemoryInfo-image-07460
image must not have been bound to a memory object
VUID-VkBindImageMemoryInfo-image-01045
image must not have been created with any sparse memory binding flags
VUID-VkBindImageMemoryInfo-memoryOffset-01046
memoryOffset must be less than the size of memory
VUID-VkBindImageMemoryInfo-image-01445
If image requires a dedicated allocation (as reported by vkGetImageMemoryRequirements2 in VkMemoryDedicatedRequirements::requiresDedicatedAllocation for image), memory must have been created with VkMemoryDedicatedAllocateInfo::image equal to image
VUID-VkBindImageMemoryInfo-memory-02628
If the VkMemoryAllocateInfo provided when memory was allocated included a VkMemoryDedicatedAllocateInfo structure in its pNext chain, and VkMemoryDedicatedAllocateInfo::image was not VK_NULL_HANDLE, then image must equal VkMemoryDedicatedAllocateInfo::image and memoryOffset must be zero
VUID-VkBindImageMemoryInfo-None-01901
If image was created with the VK_IMAGE_CREATE_PROTECTED_BIT bit set, the image must be bound to a memory object allocated with a memory type that reports VK_MEMORY_PROPERTY_PROTECTED_BIT
VUID-VkBindImageMemoryInfo-None-01902
If image was created with the VK_IMAGE_CREATE_PROTECTED_BIT bit not set, the image must not be bound to a memory object created with a memory type that reports VK_MEMORY_PROPERTY_PROTECTED_BIT
VUID-VkBindImageMemoryInfo-memory-02728
If the value of VkExportMemoryAllocateInfo::handleTypes used to allocate memory is not 0, it must include at least one of the handles set in VkExternalMemoryImageCreateInfo::handleTypes when image was created
VUID-VkBindImageMemoryInfo-memory-02989
If memory was created by a memory import operation, the external handle type of the imported memory must also have been set in VkExternalMemoryImageCreateInfo::handleTypes when image was created
VUID-VkBindImageMemoryInfo-pNext-01615
If the pNext chain does not include a VkBindImagePlaneMemoryInfo structure, memory must have been allocated using one of the memory types allowed in the memoryTypeBits member of the VkMemoryRequirements structure returned from a call to vkGetImageMemoryRequirements2 with image
VUID-VkBindImageMemoryInfo-pNext-01616
If the pNext chain does not include a VkBindImagePlaneMemoryInfo structure, memoryOffset must be an integer multiple of the alignment member of the VkMemoryRequirements structure returned from a call to vkGetImageMemoryRequirements2 with image
VUID-VkBindImageMemoryInfo-pNext-01617
If the pNext chain does not include a VkBindImagePlaneMemoryInfo structure, the difference of the size of memory and memoryOffset must be greater than or equal to the size member of the VkMemoryRequirements structure returned from a call to vkGetImageMemoryRequirements2 with the same image
VUID-VkBindImageMemoryInfo-pNext-01618
If the pNext chain includes a VkBindImagePlaneMemoryInfo structure, image must have been created with the VK_IMAGE_CREATE_DISJOINT_BIT bit set
VUID-VkBindImageMemoryInfo-image-07736
If image was created with the VK_IMAGE_CREATE_DISJOINT_BIT bit set, then the pNext chain must include a VkBindImagePlaneMemoryInfo structure
VUID-VkBindImageMemoryInfo-pNext-01619
If the pNext chain includes a VkBindImagePlaneMemoryInfo structure, memory must have been allocated using one of the memory types allowed in the memoryTypeBits member of the VkMemoryRequirements structure returned from a call to vkGetImageMemoryRequirements2 with image and where VkBindImagePlaneMemoryInfo::planeAspect corresponds to the VkImagePlaneMemoryRequirementsInfo::planeAspect in the VkImageMemoryRequirementsInfo2 structure’s pNext chain
VUID-VkBindImageMemoryInfo-pNext-01620
If the pNext chain includes a VkBindImagePlaneMemoryInfo structure, memoryOffset must be an integer multiple of the alignment member of the VkMemoryRequirements structure returned from a call to vkGetImageMemoryRequirements2 with image and where VkBindImagePlaneMemoryInfo::planeAspect corresponds to the VkImagePlaneMemoryRequirementsInfo::planeAspect in the VkImageMemoryRequirementsInfo2 structure’s pNext chain
VUID-VkBindImageMemoryInfo-pNext-01621
If the pNext chain includes a VkBindImagePlaneMemoryInfo structure, the difference of the size of memory and memoryOffset must be greater than or equal to the size member of the VkMemoryRequirements structure returned from a call to vkGetImageMemoryRequirements2 with the same image and where VkBindImagePlaneMemoryInfo::planeAspect corresponds to the VkImagePlaneMemoryRequirementsInfo::planeAspect in the VkImageMemoryRequirementsInfo2 structure’s pNext chain
VUID-VkBindImageMemoryInfo-pNext-01626
If the pNext chain includes a VkBindImageMemoryDeviceGroupInfo structure, all instances of memory specified by VkBindImageMemoryDeviceGroupInfo::pDeviceIndices must have been allocated
VUID-VkBindImageMemoryInfo-pNext-01627
If the pNext chain includes a VkBindImageMemoryDeviceGroupInfo structure, and VkBindImageMemoryDeviceGroupInfo::splitInstanceBindRegionCount is not zero, then image must have been created with the VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT bit set
VUID-VkBindImageMemoryInfo-pNext-01628
If the pNext chain includes a VkBindImageMemoryDeviceGroupInfo structure, all elements of VkBindImageMemoryDeviceGroupInfo::pSplitInstanceBindRegions must be valid rectangles contained within the dimensions of image
VUID-VkBindImageMemoryInfo-pNext-01629
If the pNext chain includes a VkBindImageMemoryDeviceGroupInfo structure, the union of the areas of all elements of VkBindImageMemoryDeviceGroupInfo::pSplitInstanceBindRegions that correspond to the same instance of image must cover the entire image
VUID-VkBindImageMemoryInfo-image-01630
If image was created with a valid swapchain handle in VkImageSwapchainCreateInfoKHR::swapchain, then the pNext chain must include a VkBindImageMemorySwapchainInfoKHR structure containing the same swapchain handle
VUID-VkBindImageMemoryInfo-pNext-01631
If the pNext chain includes a VkBindImageMemorySwapchainInfoKHR structure, memory must be VK_NULL_HANDLE
VUID-VkBindImageMemoryInfo-pNext-01632
If the pNext chain does not include a VkBindImageMemorySwapchainInfoKHR structure, memory must be a valid VkDeviceMemory handle

Valid Usage (Implicit)

VUID-VkBindImageMemoryInfo-sType-sType
sType must be VK_STRUCTURE_TYPE_BIND_IMAGE_MEMORY_INFO
VUID-VkBindImageMemoryInfo-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 VkBindImageMemoryDeviceGroupInfo, VkBindImageMemorySwapchainInfoKHR, VkBindImagePlaneMemoryInfo, or VkBindMemoryStatusKHR
VUID-VkBindImageMemoryInfo-sType-unique
The sType value of each struct in the pNext chain must be unique
VUID-VkBindImageMemoryInfo-image-parameter
image must be a valid VkImage handle
VUID-VkBindImageMemoryInfo-commonparent
Both of image, and memory that are valid handles of non-ignored parameters must have been created, allocated, or retrieved from the same VkDevice

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;

or the equivalent

// Provided by VK_KHR_bind_memory2 with VK_KHR_device_group
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 N² 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

VUID-VkBindImageMemorySwapchainInfoKHR-imageIndex-01644
imageIndex must be less than the number of images in swapchain

Valid Usage (Implicit)

VUID-VkBindImageMemorySwapchainInfoKHR-sType-sType
sType must be VK_STRUCTURE_TYPE_BIND_IMAGE_MEMORY_SWAPCHAIN_INFO_KHR
VUID-VkBindImageMemorySwapchainInfoKHR-swapchain-parameter
swapchain must be a valid VkSwapchainKHR handle

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;

or the equivalent

// Provided by VK_KHR_sampler_ycbcr_conversion
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

VUID-VkBindImagePlaneMemoryInfo-planeAspect-02283
If the image’s tiling is VK_IMAGE_TILING_LINEAR or VK_IMAGE_TILING_OPTIMAL, then planeAspect must be a single valid multi-planar aspect mask bit

Valid Usage (Implicit)

VUID-VkBindImagePlaneMemoryInfo-sType-sType
sType must be VK_STRUCTURE_TYPE_BIND_IMAGE_PLANE_MEMORY_INFO
VUID-VkBindImagePlaneMemoryInfo-planeAspect-parameter
planeAspect must be a valid VkImageAspectFlagBits value

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.

Note

Despite its name, bufferImageGranularity is really a granularity between “linear” and “non-linear” 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.

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.

Note

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, the application must perform a queue family ownership transfer to make the memory contents of a range or image subresource accessible to a different queue family.

Note

Images still require a layout transition from VK_IMAGE_LAYOUT_UNDEFINED or VK_IMAGE_LAYOUT_PREINITIALIZED before being used on the first queue.

A queue family can take ownership of an image 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 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.

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

Release exclusive ownership from the source instance or API.
Ensure the release operation has completed using semaphores or fences.
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.

Note

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.

12.10. Memory Aliasing

A range of a VkDeviceMemory allocation is aliased if it is bound to multiple resources simultaneously, as described below, via vkBindImageMemory, vkBindBufferMemory, 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, resource_A and resource_B, bound respectively to memory range_A and range_B. Let paddedRange_A and paddedRange_B be, respectively, range_A and range_B 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 range_A and range_B. If one resource is linear and the other is non-linear, then the resources alias the memory in the intersection of paddedRange_A and paddedRange_B.

Applications can alias memory, but use of multiple aliases is subject to several constraints.

Note

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, and linear image subresources in either the VK_IMAGE_LAYOUT_PREINITIALIZED or VK_IMAGE_LAYOUT_GENERAL layouts, are host-accessible subresources. 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, 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.

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:

Both must have been created with the VK_IMAGE_CREATE_DISJOINT_BIT flag.
The single-plane image must have a VkFormat that is equivalent to that of the multi-planar image’s individual plane.
The single-plane image and the individual plane of the multi-planar image must be bound identically to memory except for VkBindImageMemoryDeviceGroupInfo::pDeviceIndices and VkBindImageMemoryDeviceGroupInfo::pSplitInstanceBindRegions.
The width and height of the single-plane image are derived from the multi-planar image’s dimensions in the manner listed for plane compatibility for the aliased plane.
All other creation parameters must be identical

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.

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, 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.

Note

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.

12.10.1. Resource Memory Overlap

Applications can safely access a resource concurrently as long as the memory locations do not overlap as defined in Memory Location. This includes aliased resources if such aliasing is well-defined. It also includes access from different queues and/or queue families if such concurrent access is supported by the resource. Transfer commands only access memory locations specified by the range of the transfer command.

Note

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.

Vulkan® 1.3.283 - A Specification (with all ratified extensions)

12. Resource Creation

12.1. Buffers

12.2. Buffer Views

12.2.1. Buffer View Format Features

12.3. Images

12.3.1. Image Format Features

12.3.2. Image Mip Level Sizing

Conventional Images

12.4. Image Layouts

12.4.1. Image Layout Matching Rules

12.5. Image Views

12.5.1. Image View Format Features

12.6. Acceleration Structures

12.7. Micromaps

12.8. Resource Memory Association

12.9. Resource Sharing Mode

12.9.1. External Resource Sharing

12.10. Memory Aliasing

12.10.1. Resource Memory Overlap

Vulkan^® 1.3.283 - A Specification (with all ratified extensions)