Vulkan® 1.1.114 - A Specification (with all published extensions)

11. Resource Creation

Vulkan supports two primary resource types: buffers and images. Resources are views of memory with associated formatting and dimensionality. Buffers are essentially unformatted arrays of bytes whereas images contain format information, can be multidimensional and may have associated metadata.

11.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 via certain commands, or by directly specifying them as parameters to certain commands.

Buffers are represented by VkBuffer handles:

VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkBuffer)

To create buffers, call:

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 an instance of the VkBufferCreateInfo structure containing parameters affecting creation of the buffer.
pAllocator controls host memory allocation as described in the Memory Allocation chapter.
pBuffer points to a VkBuffer handle in which the resulting buffer object is returned.

Valid Usage

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)

device must be a valid VkDevice handle
pCreateInfo must be a valid pointer to a valid VkBufferCreateInfo structure
If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure
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_DEVICE_ADDRESS_EXT

The VkBufferCreateInfo structure is defined as:

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 the type of this structure.
pNext is NULL or a pointer to an extension-specific 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 list of queue families that will access this buffer (ignored if sharingMode is not VK_SHARING_MODE_CONCURRENT).

editing-note

(Jon) Should the constraint on usage != 0 be converted to a Valid Usage statement? See gitlab #854.

Valid Usage

size must be greater than 0
If sharingMode is VK_SHARING_MODE_CONCURRENT, pQueueFamilyIndices must be a valid pointer to an array of queueFamilyIndexCount uint32_t values
If sharingMode is VK_SHARING_MODE_CONCURRENT, queueFamilyIndexCount must be greater than 1
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
If the sparse bindings feature is not enabled, flags must not contain VK_BUFFER_CREATE_SPARSE_BINDING_BIT
If the sparse buffer residency feature is not enabled, flags must not contain VK_BUFFER_CREATE_SPARSE_RESIDENCY_BIT
If the sparse aliased residency feature is not enabled, flags must not contain VK_BUFFER_CREATE_SPARSE_ALIASED_BIT
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
If the pNext chain contains an instance of VkExternalMemoryBufferCreateInfo, 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
If the protected memory feature is not enabled, flags must not contain VK_BUFFER_CREATE_PROTECTED_BIT
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
If the pNext chain contains an instance of VkDedicatedAllocationBufferCreateInfoNV, and the dedicatedAllocation member of the chained structure is VK_TRUE, then flags must not include VK_BUFFER_CREATE_SPARSE_BINDING_BIT, VK_BUFFER_CREATE_SPARSE_RESIDENCY_BIT, or VK_BUFFER_CREATE_SPARSE_ALIASED_BIT
If VkBufferDeviceAddressCreateInfoEXT::deviceAddress is not zero, flags must include VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT_EXT
If flags includes VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT_EXT, the bufferDeviceAddressCaptureReplay feature must be enabled
If usage includes VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT_EXT, the bufferDeviceAddress feature must be enabled

Valid Usage (Implicit)

sType must be VK_STRUCTURE_TYPE_BUFFER_CREATE_INFO
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 VkBufferDeviceAddressCreateInfoEXT, VkDedicatedAllocationBufferCreateInfoNV, or VkExternalMemoryBufferCreateInfo
Each sType member in the pNext chain must be unique
flags must be a valid combination of VkBufferCreateFlagBits values
usage must be a valid combination of VkBufferUsageFlagBits values
usage must not be 0
sharingMode must be a valid VkSharingMode value

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

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,
    VK_BUFFER_USAGE_TRANSFORM_FEEDBACK_BUFFER_BIT_EXT = 0x00000800,
    VK_BUFFER_USAGE_TRANSFORM_FEEDBACK_COUNTER_BUFFER_BIT_EXT = 0x00001000,
    VK_BUFFER_USAGE_CONDITIONAL_RENDERING_BIT_EXT = 0x00000200,
    VK_BUFFER_USAGE_RAY_TRACING_BIT_NV = 0x00000400,
    VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT_EXT = 0x00020000,
    VK_BUFFER_USAGE_FLAG_BITS_MAX_ENUM = 0x7FFFFFFF
} 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 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, vkCmdDrawMeshTasksIndirectNV, vkCmdDrawMeshTasksIndirectCountNV, or vkCmdDispatchIndirect. It is also suitable for passing as the buffer member of VkIndirectCommandsTokenNVX, or sequencesCountBuffer or sequencesIndexBuffer member of VkCmdProcessCommandsInfoNVX
VK_BUFFER_USAGE_CONDITIONAL_RENDERING_BIT_EXT specifies that the buffer is suitable for passing as the buffer parameter to vkCmdBeginConditionalRenderingEXT.
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_RAY_TRACING_BIT_NV specifies that the buffer is suitable for use in vkCmdTraceRaysNV and vkCmdBuildAccelerationStructureNV.
VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT_EXT specifies that the buffer can be used to retrieve a buffer device address via vkGetBufferDeviceAddressEXT and use that address to access the buffer’s memory from a shader.

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:

typedef enum VkBufferCreateFlagBits {
    VK_BUFFER_CREATE_SPARSE_BINDING_BIT = 0x00000001,
    VK_BUFFER_CREATE_SPARSE_RESIDENCY_BIT = 0x00000002,
    VK_BUFFER_CREATE_SPARSE_ALIASED_BIT = 0x00000004,
    VK_BUFFER_CREATE_PROTECTED_BIT = 0x00000008,
    VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT_EXT = 0x00000010,
    VK_BUFFER_CREATE_FLAG_BITS_MAX_ENUM = 0x7FFFFFFF
} 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_EXT specifies that the buffer’s address can be saved and reused on a subsequent run (e.g. for trace capture and replay), see VkBufferDeviceAddressCreateInfoEXT for more detail.

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

typedef VkFlags VkBufferCreateFlags;

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

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

The VkDedicatedAllocationBufferCreateInfoNV structure is defined as:

typedef struct VkDedicatedAllocationBufferCreateInfoNV {
    VkStructureType    sType;
    const void*        pNext;
    VkBool32           dedicatedAllocation;
} VkDedicatedAllocationBufferCreateInfoNV;

sType is the type of this structure.
pNext is NULL or a pointer to an extension-specific structure.
dedicatedAllocation specifies whether the buffer will have a dedicated allocation bound to it.

Valid Usage (Implicit)

sType must be VK_STRUCTURE_TYPE_DEDICATED_ALLOCATION_BUFFER_CREATE_INFO_NV

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:

typedef struct VkExternalMemoryBufferCreateInfo {
    VkStructureType                    sType;
    const void*                        pNext;
    VkExternalMemoryHandleTypeFlags    handleTypes;
} VkExternalMemoryBufferCreateInfo;

or the equivalent

typedef VkExternalMemoryBufferCreateInfo VkExternalMemoryBufferCreateInfoKHR;

sType is the type of this structure.
pNext is NULL or a pointer to an extension-specific structure.
handleTypes is a bitmask of VkExternalMemoryHandleTypeFlagBits specifying one or more external memory handle types.

Valid Usage (Implicit)

sType must be VK_STRUCTURE_TYPE_EXTERNAL_MEMORY_BUFFER_CREATE_INFO
handleTypes must be a valid combination of VkExternalMemoryHandleTypeFlagBits values

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

typedef struct VkBufferDeviceAddressCreateInfoEXT {
    VkStructureType    sType;
    const void*        pNext;
    VkDeviceAddress    deviceAddress;
} VkBufferDeviceAddressCreateInfoEXT;

sType is the type of this structure.
pNext is NULL or a pointer to an extension-specific structure.
deviceAddress is the device address requested for the buffer.

If deviceAddress is zero, no specific address is requested.

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

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

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_DEVICE_ADDRESS_EXT 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_EXT flag to all buffers that use VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT_EXT, and during capture will save the queried 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_EXT, to avoid address space allocation conflicts.

Valid Usage (Implicit)

sType must be VK_STRUCTURE_TYPE_BUFFER_DEVICE_ADDRESS_CREATE_INFO_EXT

To destroy a buffer, call:

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

All submitted commands that refer to buffer, either directly or via a VkBufferView, must have completed execution
If VkAllocationCallbacks were provided when buffer was created, a compatible set of callbacks must be provided here
If no VkAllocationCallbacks were provided when buffer was created, pAllocator must be NULL

Valid Usage (Implicit)

device must be a valid VkDevice handle
If buffer is not VK_NULL_HANDLE, buffer must be a valid VkBuffer handle
If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure
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

11.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 interpreted as formatted data. 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:

VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkBufferView)

To create a buffer view, call:

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 an instance of the VkBufferViewCreateInfo structure containing parameters to be used to create the buffer.
pAllocator controls host memory allocation as described in the Memory Allocation chapter.
pView points to a VkBufferView handle in which the resulting buffer view object is returned.

Valid Usage (Implicit)

device must be a valid VkDevice handle
pCreateInfo must be a valid pointer to a valid VkBufferViewCreateInfo structure
If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure
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:

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

sType is the type of this structure.
pNext is NULL or a pointer to an extension-specific 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.

Valid Usage

offset must be less than the size of buffer
If the texelBufferAlignment feature is not enabled, offset must be a multiple of VkPhysicalDeviceLimits::minTexelBufferOffsetAlignment
If range is not equal to VK_WHOLE_SIZE, range must be greater than 0
If range is not equal to VK_WHOLE_SIZE, range must be an integer multiple of the texel block size of format
If range is not equal to VK_WHOLE_SIZE, range divided by the texel block size of format, multiplied by the number of texels per texel block for that format (as defined in the Compatible Formats table), must be less than or equal to VkPhysicalDeviceLimits::maxTexelBufferElements
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
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
If buffer was created with usage containing VK_BUFFER_USAGE_UNIFORM_TEXEL_BUFFER_BIT, format must be supported for uniform texel buffers, as specified by the VK_FORMAT_FEATURE_UNIFORM_TEXEL_BUFFER_BIT flag in VkFormatProperties::bufferFeatures returned by vkGetPhysicalDeviceFormatProperties
If buffer was created with usage containing VK_BUFFER_USAGE_STORAGE_TEXEL_BUFFER_BIT, format must be supported for storage texel buffers, as specified by the VK_FORMAT_FEATURE_STORAGE_TEXEL_BUFFER_BIT flag in VkFormatProperties::bufferFeatures returned by vkGetPhysicalDeviceFormatProperties
If buffer is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object
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 VkPhysicalDeviceTexelBufferAlignmentPropertiesEXT::storageTexelBufferOffsetAlignmentBytes or, if VkPhysicalDeviceTexelBufferAlignmentPropertiesEXT::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
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 VkPhysicalDeviceTexelBufferAlignmentPropertiesEXT::uniformTexelBufferOffsetAlignmentBytes or, if VkPhysicalDeviceTexelBufferAlignmentPropertiesEXT::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

Valid Usage (Implicit)

sType must be VK_STRUCTURE_TYPE_BUFFER_VIEW_CREATE_INFO
pNext must be NULL
flags must be 0
buffer must be a valid VkBuffer handle
format must be a valid VkFormat value

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:

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

All submitted commands that refer to bufferView must have completed execution
If VkAllocationCallbacks were provided when bufferView was created, a compatible set of callbacks must be provided here
If no VkAllocationCallbacks were provided when bufferView was created, pAllocator must be NULL

Valid Usage (Implicit)

device must be a valid VkDevice handle
If bufferView is not VK_NULL_HANDLE, bufferView must be a valid VkBufferView handle
If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure
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

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

VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkImage)

To create images, call:

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 an instance of the VkImageCreateInfo structure containing parameters to be used to create the image.
pAllocator controls host memory allocation as described in the Memory Allocation chapter.
pImage points to a VkImage handle in which the resulting image object is returned.

Valid Usage

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)

device must be a valid VkDevice handle
pCreateInfo must be a valid pointer to a valid VkImageCreateInfo structure
If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure
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

The VkImageCreateInfo structure is defined as:

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 the type of this structure.
pNext is NULL or a pointer to an extension-specific 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 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 list of queue families that will access this image (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 a format from one of those listed in Formats requiring sampler Y’C_BC_R conversion for VK_IMAGE_ASPECT_COLOR_BIT image views 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
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.

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 uint64_t imageCreateDrmFormatModifiers[] be the set of Linux DRM format modifiers that the resultant image may have.
- If tiling is not VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then imageCreateDrmFormatModifiers is empty.
- If VkImageCreateInfo::pNext contains VkImageDrmFormatModifierExplicitCreateInfoEXT, then imageCreateDrmFormatModifiers contains exactly one modifier, VkImageDrmFormatModifierExplicitCreateInfoEXT::drmFormatModifier.
- If VkImageCreateInfo::pNext contains VkImageDrmFormatModifierListCreateInfoEXT, then imageCreateDrmFormatModifiers contains the exactly the modifiers in VkImageDrmFormatModifierListCreateInfoEXT::pDrmFormatModifiers.
Let VkBool32 imageCreateMaybeLinear indicate if the resultant image may be linear.
- If tiling is VK_IMAGE_TILING_LINEAR, then imageCreateMaybeLinear is true.
- If tiling is VK_IMAGE_TILING_OPTIMAL, then imageCreateMaybeLinear is false.
- If tiling is VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then imageCreateMaybeLinear_ is true if and only if imageCreateDrmFormatModifiers contains DRM_FORMAT_MOD_LINEAR.
Let VkFormatFeatureFlags imageCreateFormatFeatures be the set of format features available during image creation.
- If tiling is VK_IMAGE_TILING_LINEAR, then imageCreateFormatFeatures is the value of VkImageFormatProperties::linearTilingFeatures found by calling vkGetPhysicalDeviceFormatProperties with parameter format equal to VkImageCreateInfo::format.
- If tiling is VK_IMAGE_TILING_OPTIMAL, and if the pNext chain contains no instance of VkExternalFormatANDROID with non-zero externalFormat, then imageCreateFormatFeatures is value of VkImageFormatProperties::optimalTilingFeatures found by calling vkGetPhysicalDeviceFormatProperties with parameter format equal to VkImageCreateInfo::format.
- If tiling is VK_IMAGE_TILING_OPTIMAL, and if the pNext chain contains an instance of VkExternalFormatANDROID with non-zero externalFormat, then imageCreateFormatFeatures is the value of VkAndroidHardwareBufferFormatPropertiesANDROID::formatFeatures obtained by vkGetAndroidHardwareBufferPropertiesANDROID with a matching externalFormat value.
- If tiling is VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then the value of imageCreateFormatFeatures is found by calling vkGetPhysicalDeviceFormatProperties2 with VkImageFormatProperties::format equal to VkImageCreateInfo::format and with VkDrmFormatModifierPropertiesListEXT chained into VkImageFormatProperties2; by collecting all members of the returned array VkDrmFormatModifierPropertiesListEXT::pDrmFormatModifierProperties whose drmFormatModifier belongs to imageCreateDrmFormatModifiers; and by taking the bitwise intersection, over the collected array members, of drmFormatModifierTilingFeatures. (The resultant imageCreateFormatFeatures may be empty).
Let VkImageFormatProperties2 imageCreateImageFormatPropertiesList[] be defined as follows.
- If VkImageCreateInfo::pNext contains no instance of VkExternalFormatANDROID with non-zero externalFormat, then imageCreateImageFormatPropertiesList is 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 an instance of VkExternalMemoryImageCreateInfo where handleTypes is not 0, then VkPhysicalDeviceImageFormatInfo2::pNext must contain an instance of VkPhysicalDeviceExternalImageFormatInfo where 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 instance of VkExternalMemoryImageCreateInfo or contains an instance where handleTypes is 0, then VkPhysicalDeviceImageFormatInfo2::pNext must either contain no instance of VkPhysicalDeviceExternalImageFormatInfo or contain an instance where handleType is 0.
  - If tiling is VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then VkPhysicalDeviceImageFormatInfo2::pNext must contain an instance of VkPhysicalDeviceImageDrmFormatModifierInfoEXT where sharingMode is equal to VkImageCreateInfo::sharingMode; and, if sharingMode is VK_SHARING_MODE_CONCURRENT, then queueFamilyIndexCount and pQueueFamilyIndices must be equal to those in VkImageCreateInfo; and, if flags contains VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT, then the instance of VkImageFormatListCreateInfoKHR in the pNext chain of VkPhysicalDeviceImageFormatInfo2 must be equivalent to the one in the pNext chain of VkImageCreateInfo; and vkGetPhysicalDeviceImageFormatProperties2 must be called for each modifier in imageCreateDrmFormatModifiers, successively setting VkPhysicalDeviceImageDrmFormatModifierInfoEXT::drmFormatModifier on each call.
  - If tiling is not VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then VkPhysicalDeviceImageFormatInfo2::pNext must contain no instance of VkPhysicalDeviceImageDrmFormatModifierInfoEXT.
  - If any call to vkGetPhysicalDeviceImageFormatProperties2 returns an error, then imageCreateImageFormatPropertiesList is defined to be the empty list.
- If VkImageCreateInfo::pNext contains an instance of VkExternalFormatANDROID with non-zero externalFormat, then imageCreateImageFormatPropertiesList contains a single element where:
  - VkImageFormatProperties::maxMipLevels is ⌊log₂(max(extent.width, extent.height, extent.depth))⌋ + 1.
  - VkImageFormatProperties::maxArrayLayers is VkPhysicalDeviceLimits::maxImageArrayLayers.
  - Each component of VkImageFormatProperties::maxExtent is VkPhysicalDeviceLimits::maxImageDimension2D.
  - VkImageFormatProperties::sampleCounts contains exactly VK_SAMPLE_COUNT_1_BIT.
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.

Valid Usage

Each of the following values (as described in Image Creation Limits) must not be undefined imageCreateMaxMipLevels, imageCreateMaxArrayLayers, imageCreateMaxExtent, and imageCreateSampleCounts.
If sharingMode is VK_SHARING_MODE_CONCURRENT, pQueueFamilyIndices must be a valid pointer to an array of queueFamilyIndexCount uint32_t values
If sharingMode is VK_SHARING_MODE_CONCURRENT, queueFamilyIndexCount must be greater than 1
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
If the pNext chain contains an instance of VkExternalFormatANDROID, and its member externalFormat is non-zero the format must be VK_FORMAT_UNDEFINED.
If the pNext chain does not contain an instance of VkExternalFormatANDROID, or does and its member externalFormat is 0 the format must not be VK_FORMAT_UNDEFINED.
extent::width must be greater than 0.
extent::height must be greater than 0.
extent::depth must be greater than 0.
mipLevels must be greater than 0
arrayLayers must be greater than 0
If flags contains VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT, imageType must be VK_IMAGE_TYPE_2D
If flags contains VK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT, imageType must be VK_IMAGE_TYPE_2D
If flags contains VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT, imageType must be VK_IMAGE_TYPE_3D
extent.width must be less than or equal to imageCreateMaxExtent.width (as defined in Image Creation Limits).
extent.height must be less than or equal to imageCreateMaxExtent.height (as defined in Image Creation Limits).
extent.depth must be less than or equal to imageCreateMaxExtent.depth (as defined in Image Creation Limits).
If imageType is VK_IMAGE_TYPE_2D and flags contains VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT, extent.width and extent.height must be equal and arrayLayers must be greater than or equal to 6
If imageType is VK_IMAGE_TYPE_1D, both extent.height and extent.depth must be 1
If imageType is VK_IMAGE_TYPE_2D, extent.depth must be 1
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.
mipLevels must be less than or equal to imageCreateMaxMipLevels (as defined in Image Creation Limits).
arrayLayers must be less than or equal to imageCreateMaxArrayLayers (as defined in Image Creation Limits).
If imageType is VK_IMAGE_TYPE_3D, arrayLayers must be 1.
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 false,
If samples is not VK_SAMPLE_COUNT_1_BIT, usage must not contain VK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT
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
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
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
If usage includes VK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT, extent.width must be less than or equal to \(\lceil{\frac{maxFramebufferWidth}{minFragmentDensityTexelSize_{width}}}\rceil\)
If usage includes VK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT, extent.height must be less than or equal to \(\lceil{\frac{maxFramebufferHeight}{minFragmentDensityTexelSize_{height}}}\rceil\)
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.
samples must be a bit value that is set in imageCreateSampleCounts (as defined in Image Creation Limits).
If the multisampled storage images feature is not enabled, and usage contains VK_IMAGE_USAGE_STORAGE_BIT, samples must be VK_SAMPLE_COUNT_1_BIT
If the sparse bindings feature is not enabled, flags must not contain VK_IMAGE_CREATE_SPARSE_BINDING_BIT
If the sparse aliased residency feature is not enabled, flags must not contain VK_IMAGE_CREATE_SPARSE_ALIASED_BIT
If imageType is VK_IMAGE_TYPE_1D, flags must not contain VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT
If the sparse residency for 2D images feature is not enabled, and imageType is VK_IMAGE_TYPE_2D, flags must not contain VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT
If the sparse residency for 3D images feature is not enabled, and imageType is VK_IMAGE_TYPE_3D, flags must not contain VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT
If the sparse residency for images with 2 samples 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
If the sparse residency for images with 4 samples 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
If the sparse residency for images with 8 samples 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
If the sparse residency for images with 16 samples 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
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
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
If the protected memory feature is not enabled, flags must not contain VK_IMAGE_CREATE_PROTECTED_BIT.
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.
If the pNext chain contains an instance of VkExternalMemoryImageCreateInfoNV, it must not contain an instance of VkExternalMemoryImageCreateInfo.
If the pNext chain contains an instance of VkExternalMemoryImageCreateInfo, 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 an instance of VkPhysicalDeviceExternalImageFormatInfo in the pNext chain, with a handleType equal to any one of the handle types specified in VkExternalMemoryImageCreateInfo::handleTypes
If the pNext chain contains an instance of VkExternalMemoryImageCreateInfoNV, its handleTypes member must only contain bits that are also in VkExternalImageFormatPropertiesNV::externalMemoryProperties.compatibleHandleTypes, as returned by vkGetPhysicalDeviceExternalImageFormatPropertiesNV with format, imageType, tiling, usage, and flags equal to those in this structure, and with externalHandleType equal to any one of the handle types specified in VkExternalMemoryImageCreateInfoNV::handleTypes
If the logical device was created with VkDeviceGroupDeviceCreateInfo::physicalDeviceCount equal to 1, flags must not contain VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT
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 false.
If flags contains VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT, then format must be a block-compressed image format, an ETC compressed image format, or an ASTC compressed image format.
If flags contains VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT, then flags must also contain VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT.
initialLayout must be VK_IMAGE_LAYOUT_UNDEFINED or VK_IMAGE_LAYOUT_PREINITIALIZED.
If the pNext chain includes a VkExternalMemoryImageCreateInfo or VkExternalMemoryImageCreateInfoNV structure whose handleTypes member is not 0, initialLayout must be VK_IMAGE_LAYOUT_UNDEFINED
If the image format is one of those listed in Formats requiring sampler Y’C_BC_R conversion for VK_IMAGE_ASPECT_COLOR_BIT image views, then mipLevels must be 1
If the image format is one of those listed in Formats requiring sampler Y’C_BC_R conversion for VK_IMAGE_ASPECT_COLOR_BIT image views, samples must be VK_SAMPLE_COUNT_1_BIT
If the image format is one of those listed in Formats requiring sampler Y’C_BC_R conversion for VK_IMAGE_ASPECT_COLOR_BIT image views, imageType must be VK_IMAGE_TYPE_2D
If the image format is one of those listed in Formats requiring sampler Y’C_BC_R conversion for VK_IMAGE_ASPECT_COLOR_BIT image views, and the ycbcrImageArrays feature is not enabled, arrayLayers must be 1
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.
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
If tiling is VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then the pNext chain must contain exactly one of VkImageDrmFormatModifierListCreateInfoEXT or VkImageDrmFormatModifierExplicitCreateInfoEXT.
If the pNext chain contains VkImageDrmFormatModifierListCreateInfoEXT or VkImageDrmFormatModifierExplicitCreateInfoEXT, then tiling must be VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT.
If tiling is VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT and flags contains VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT, then the pNext chain must contain VkImageFormatListCreateInfoKHR with non-zero viewFormatCount.
If flags contains VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT format must be a depth or depth/stencil format
If the pNext chain includes a VkExternalMemoryImageCreateInfo structure whose handleTypes member includes VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID, imageType must be VK_IMAGE_TYPE_2D.
If the pNext chain includes a VkExternalMemoryImageCreateInfo structure whose handleTypes member includes VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID, mipLevels must either be 1 or equal to the number of levels in the complete mipmap chain based on extent.width, extent.height, and extent.depth.
If the pNext chain includes a VkExternalFormatANDROID structure whose externalFormat member is not 0, flags must not include VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT.
If the pNext chain includes a VkExternalFormatANDROID structure whose externalFormat member is not 0, usage must not include any usages except VK_IMAGE_USAGE_SAMPLED_BIT.
If the pNext chain includes a VkExternalFormatANDROID structure whose externalFormat member is not 0, tiling must be VK_IMAGE_TILING_OPTIMAL.
If format is a depth-stencil format and the pNext chain contains an instance of VkImageStencilUsageCreateInfoEXT, then its stencilUsage member must only include VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT if usage also includes it
If format is a depth-stencil format and the pNext chain contains an instance of VkImageStencilUsageCreateInfoEXT, then its stencilUsage member must only include VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT if usage also includes it
If Format is a depth-stencil format and the pNext chain contains an instance of VkImageStencilUsageCreateInfoEXT with its stencilUsage member including VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT, extent.width must be less than or equal to VkPhysicalDeviceLimits::maxFramebufferWidth
If format is a depth-stencil format and the pNext chain contains an instance of VkImageStencilUsageCreateInfoEXT with its stencilUsage member including VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT, extent.height must be less than or equal to VkPhysicalDeviceLimits::maxFramebufferHeight
If the multisampled storage images feature is not enabled, format is a depth-stencil format and the pNext chain contains an instance of VkImageStencilUsageCreateInfoEXT with its stencilUsage including VK_IMAGE_USAGE_STORAGE_BIT, samples must be VK_SAMPLE_COUNT_1_BIT
If flags contains VK_IMAGE_CREATE_CORNER_SAMPLED_BIT_NV, imageType must be VK_IMAGE_TYPE_2D or VK_IMAGE_TYPE_3D
If flags contains VK_IMAGE_CREATE_CORNER_SAMPLED_BIT_NV, it must not contain VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT and the format must not be a depth/stencil format
If flags contains VK_IMAGE_CREATE_CORNER_SAMPLED_BIT_NV and imageType is VK_IMAGE_TYPE_2D, extent::width and extent::height must be greater than 1
If flags contains VK_IMAGE_CREATE_CORNER_SAMPLED_BIT_NV and imageType is VK_IMAGE_TYPE_3D, extent::width, extent::height, and extent::depth must be greater than 1
If usage includes VK_IMAGE_USAGE_SHADING_RATE_IMAGE_BIT_NV, imageType must be VK_IMAGE_TYPE_2D.
If usage includes VK_IMAGE_USAGE_SHADING_RATE_IMAGE_BIT_NV, samples must be VK_SAMPLE_COUNT_1_BIT.
If usage includes VK_IMAGE_USAGE_SHADING_RATE_IMAGE_BIT_NV, tiling must be VK_IMAGE_TILING_OPTIMAL.
If flags contains VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT, tiling must be VK_IMAGE_TILING_OPTIMAL
If flags contains VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT, imageType must be VK_IMAGE_TYPE_2D
If flags contains VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT, flags must not contain VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT
If flags contains VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT, mipLevels must be 1

Valid Usage (Implicit)

sType must be VK_STRUCTURE_TYPE_IMAGE_CREATE_INFO
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 VkDedicatedAllocationImageCreateInfoNV, VkExternalFormatANDROID, VkExternalMemoryImageCreateInfo, VkExternalMemoryImageCreateInfoNV, VkImageDrmFormatModifierExplicitCreateInfoEXT, VkImageDrmFormatModifierListCreateInfoEXT, VkImageFormatListCreateInfoKHR, VkImageStencilUsageCreateInfoEXT, or VkImageSwapchainCreateInfoKHR
Each sType member in the pNext chain must be unique
flags must be a valid combination of VkImageCreateFlagBits values
imageType must be a valid VkImageType value
format must be a valid VkFormat value
samples must be a valid VkSampleCountFlagBits value
tiling must be a valid VkImageTiling value
usage must be a valid combination of VkImageUsageFlagBits values
usage must not be 0
sharingMode must be a valid VkSharingMode value
initialLayout must be a valid VkImageLayout value

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

The VkImageStencilUsageCreateInfoEXT structure is defined as:

typedef struct VkImageStencilUsageCreateInfoEXT {
    VkStructureType      sType;
    const void*          pNext;
    VkImageUsageFlags    stencilUsage;
} VkImageStencilUsageCreateInfoEXT;

sType is the type of this structure.
pNext is NULL or a pointer to an extension-specific structure.
stencilUsage is a bitmask of VkImageUsageFlagBits describing the intended usage of the stencil aspect of the image.

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 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 present in the pNext chain of VkPhysicalDeviceImageFormatInfo2 then the implicit value of stencilUsage matches that of VkPhysicalDeviceImageFormatInfo2::usage.

Valid Usage

If stencilUsage includes VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT, then bits other than VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, and VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT must not be set

Valid Usage (Implicit)

sType must be VK_STRUCTURE_TYPE_IMAGE_STENCIL_USAGE_CREATE_INFO_EXT
stencilUsage must be a valid combination of VkImageUsageFlagBits values
stencilUsage must not be 0

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

The VkDedicatedAllocationImageCreateInfoNV structure is defined as:

typedef struct VkDedicatedAllocationImageCreateInfoNV {
    VkStructureType    sType;
    const void*        pNext;
    VkBool32           dedicatedAllocation;
} VkDedicatedAllocationImageCreateInfoNV;

sType is the type of this structure.
pNext is NULL or a pointer to an extension-specific structure.
dedicatedAllocation specifies whether the image will have a dedicated allocation bound to it.

Note

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

Valid Usage

If dedicatedAllocation is VK_TRUE, VkImageCreateInfo::flags must not include VK_IMAGE_CREATE_SPARSE_BINDING_BIT, VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT, or VK_IMAGE_CREATE_SPARSE_ALIASED_BIT

Valid Usage (Implicit)

sType must be VK_STRUCTURE_TYPE_DEDICATED_ALLOCATION_IMAGE_CREATE_INFO_NV

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:

typedef struct VkExternalMemoryImageCreateInfo {
    VkStructureType                    sType;
    const void*                        pNext;
    VkExternalMemoryHandleTypeFlags    handleTypes;
} VkExternalMemoryImageCreateInfo;

or the equivalent

typedef VkExternalMemoryImageCreateInfo VkExternalMemoryImageCreateInfoKHR;

sType is the type of this structure.
pNext is NULL or a pointer to an extension-specific structure.
handleTypes is a bitmask of VkExternalMemoryHandleTypeFlagBits specifying one or more external memory handle types.

Valid Usage (Implicit)

sType must be VK_STRUCTURE_TYPE_EXTERNAL_MEMORY_IMAGE_CREATE_INFO
handleTypes must be a valid combination of VkExternalMemoryHandleTypeFlagBits values
handleTypes must not be 0

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

The VkExternalMemoryImageCreateInfoNV structure is defined as:

typedef struct VkExternalMemoryImageCreateInfoNV {
    VkStructureType                      sType;
    const void*                          pNext;
    VkExternalMemoryHandleTypeFlagsNV    handleTypes;
} VkExternalMemoryImageCreateInfoNV;

sType is the type of this structure.
pNext is NULL or a pointer to an extension-specific structure.
handleTypes is a bitmask of VkExternalMemoryHandleTypeFlagBitsNV specifying one or more external memory handle types.

Valid Usage (Implicit)

sType must be VK_STRUCTURE_TYPE_EXTERNAL_MEMORY_IMAGE_CREATE_INFO_NV
handleTypes must be a valid combination of VkExternalMemoryHandleTypeFlagBitsNV values

To create an image with an external format, include an instance of VkExternalFormatANDROID in the pNext chain of VkImageCreateInfo. VkExternalFormatANDROID is defined as:

typedef struct VkExternalFormatANDROID {
    VkStructureType    sType;
    void*              pNext;
    uint64_t           externalFormat;
} VkExternalFormatANDROID;

sType is the type of this structure.
pNext is NULL or a pointer to an extension-specific structure.
externalFormat is an implementation-defined identifier for the external format

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

Valid Usage

externalFormat must be 0 or a value returned in the externalFormat member of VkAndroidHardwareBufferFormatPropertiesANDROID by an earlier call to vkGetAndroidHardwareBufferPropertiesANDROID

Valid Usage (Implicit)

sType must be VK_STRUCTURE_TYPE_EXTERNAL_FORMAT_ANDROID

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:

typedef struct VkImageSwapchainCreateInfoKHR {
    VkStructureType    sType;
    const void*        pNext;
    VkSwapchainKHR     swapchain;
} VkImageSwapchainCreateInfoKHR;

sType is the type of this structure.
pNext is NULL or a pointer to an extension-specific structure.
swapchain is VK_NULL_HANDLE or a handle of a swapchain that the image will be bound to.

Valid Usage

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

Valid Usage (Implicit)

sType must be VK_STRUCTURE_TYPE_IMAGE_SWAPCHAIN_CREATE_INFO_KHR
If swapchain is not VK_NULL_HANDLE, swapchain must be a valid VkSwapchainKHR handle

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

The VkImageFormatListCreateInfoKHR structure is defined as:

typedef struct VkImageFormatListCreateInfoKHR {
    VkStructureType    sType;
    const void*        pNext;
    uint32_t           viewFormatCount;
    const VkFormat*    pViewFormats;
} VkImageFormatListCreateInfoKHR;

sType is the type of this structure.
pNext is NULL or a pointer to an extension-specific structure.
viewFormatCount is the number of entries in the pViewFormats array.
pViewFormats is an array which lists of 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 VkImageFormatListCreateInfoKHR structure were not included in the pNext list of VkImageCreateInfo.

Valid Usage

If viewFormatCount is not 0, all of the formats in the pViewFormats array must be compatible with the format specified in the format field of VkImageCreateInfo, as described in the compatibility table.
If VkImageCreateInfo::flags does not contain VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT, viewFormatCount must be 0 or 1.
If viewFormatCount is not 0, VkImageCreateInfo::format must be in pViewFormats.

Valid Usage (Implicit)

sType must be VK_STRUCTURE_TYPE_IMAGE_FORMAT_LIST_CREATE_INFO_KHR
If viewFormatCount is not 0, pViewFormats must be a valid pointer to an array of viewFormatCount valid VkFormat values

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

The VkImageDrmFormatModifierListCreateInfoEXT structure is defined as:

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

sType is the type of this structure.
pNext is NULL or a pointer to an extension-specific structure.
drmFormatModifierCount is the length of the pDrmFormatModifiers array.
pDrmFormatModifiers is an array of Linux DRM format modifiers.

Valid Usage

Each modifier in pDrmFormatModifiers must be compatible with the parameters in VkImageCreateInfo and its pNext chain, as determined by querying VkPhysicalDeviceImageFormatInfo2 extended with VkPhysicalDeviceImageDrmFormatModifierInfoEXT.

Valid Usage (Implicit)

sType must be VK_STRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_LIST_CREATE_INFO_EXT
pDrmFormatModifiers must be a valid pointer to an array of drmFormatModifierCount uint64_t values
drmFormatModifierCount must be greater than 0

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

The VkImageDrmFormatModifierExplicitCreateInfoEXT structure is defined as:

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

sType is the type of this structure.
pNext is NULL or a pointer to an extension-specific structure.
drmFormatModifier is the Linux DRM format modifier with which the image will be created.
drmFormatModifierPlaneCount is the number of memory planes in the image (as reported by VkDrmFormatModifierPropertiesEXT) as well as the length of the pPlaneLayouts array.
pPlaneLayouts is an array of VkSubresourceLayout structures that describe the image’s memory planes.

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

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

Valid Usage

drmFormatModifier must be compatible with the parameters in VkImageCreateInfo and its pNext chain, as determined by querying VkPhysicalDeviceImageFormatInfo2KHR extended with VkPhysicalDeviceImageDrmFormatModifierInfoEXT.
drmFormatModifierPlaneCount must be equal to the VkDrmFormatModifierPropertiesEXT::drmFormatModifierPlaneCount associated with VkImageCreateInfo::format and drmFormatModifier, as found by querying VkDrmFormatModifierPropertiesListEXT.
For each element of pPlaneLayouts, size must be 0
For each element of pPlaneLayouts, arrayPitch must be 0 if VkImageCreateInfo::arrayLayers is 1.
For each element of pPlaneLayouts, depthPitch must be 0 if VkImageCreateInfo::extent::depth is 1.

Valid Usage (Implicit)

sType must be VK_STRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_EXPLICIT_CREATE_INFO_EXT
If drmFormatModifierPlaneCount is not 0, pPlaneLayouts must be a valid pointer to an array of drmFormatModifierPlaneCount VkSubresourceLayout structures

Bits which can be set in VkImageCreateInfo::usage, specifying intended usage of an image, are:

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,
    VK_IMAGE_USAGE_SHADING_RATE_IMAGE_BIT_NV = 0x00000100,
    VK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT = 0x00000200,
    VK_IMAGE_USAGE_FLAG_BITS_MAX_ENUM = 0x7FFFFFFF
} 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 the memory bound to this image will have been allocated with the VK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT (see Memory Allocation for more detail). 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_SHADING_RATE_IMAGE_BIT_NV specifies that the image can be used to create a VkImageView suitable for use as a shading rate image.

typedef VkFlags VkImageUsageFlags;

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

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

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,
    VK_IMAGE_CREATE_ALIAS_BIT = 0x00000400,
    VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT = 0x00000040,
    VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT = 0x00000020,
    VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT = 0x00000080,
    VK_IMAGE_CREATE_EXTENDED_USAGE_BIT = 0x00000100,
    VK_IMAGE_CREATE_PROTECTED_BIT = 0x00000800,
    VK_IMAGE_CREATE_DISJOINT_BIT = 0x00000200,
    VK_IMAGE_CREATE_CORNER_SAMPLED_BIT_NV = 0x00002000,
    VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT = 0x00001000,
    VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT = 0x00004000,
    VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT_KHR = VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT,
    VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT_KHR = VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT,
    VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT_KHR = VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT,
    VK_IMAGE_CREATE_EXTENDED_USAGE_BIT_KHR = VK_IMAGE_CREATE_EXTENDED_USAGE_BIT,
    VK_IMAGE_CREATE_DISJOINT_BIT_KHR = VK_IMAGE_CREATE_DISJOINT_BIT,
    VK_IMAGE_CREATE_ALIAS_BIT_KHR = VK_IMAGE_CREATE_ALIAS_BIT,
    VK_IMAGE_CREATE_FLAG_BITS_MAX_ENUM = 0x7FFFFFFF
} 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 or VkExternalMemoryImageCreateInfoNV structure whose handleTypes member is not 0, it is as if VK_IMAGE_CREATE_ALIAS_BIT is set.
VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT specifies that an image with a depth or depth/stencil format can be used with custom sample locations when used as a depth/stencil attachment.
VK_IMAGE_CREATE_CORNER_SAMPLED_BIT_NV specifies that the image is a corner-sampled image.
VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT specifies that an image can be in a subsampled format which may be more optimal when written as an attachment by a render pass that has a fragment density map attachment. Accessing a subsampled image has additional considerations:
- Image data read as an image sampler is undefined if the sampler was not created with flags containing VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT or was not sampled through the use of a combined image sampler with an immutable sampler in VkDescriptorSetLayoutBinding.
- Image data read with an input attachment is undefined if the contents were not written as an attachment in an earlier subpass of the same render pass.
- Image data read with load operations may be resampled to the fragment density of the render pass.
- Image contents outside of the render area become undefined if the image is stored as a render pass attachment.

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

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:

typedef enum VkImageType {
    VK_IMAGE_TYPE_1D = 0,
    VK_IMAGE_TYPE_2D = 1,
    VK_IMAGE_TYPE_3D = 2,
    VK_IMAGE_TYPE_MAX_ENUM = 0x7FFFFFFF
} 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:

typedef enum VkImageTiling {
    VK_IMAGE_TILING_OPTIMAL = 0,
    VK_IMAGE_TILING_LINEAR = 1,
    VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT = 1000158000,
    VK_IMAGE_TILING_MAX_ENUM = 0x7FFFFFFF
} VkImageTiling;

VK_IMAGE_TILING_OPTIMAL specifies optimal tiling (texels are laid out in an implementation-dependent arrangement, for more optimal 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).
VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT indicates that the image’s tiling is defined by a Linux DRM format modifier. The modifier is specified at image creation with VkImageDrmFormatModifierListCreateInfoEXT or VkImageDrmFormatModifierExplicitCreateInfoEXT, and can be queried with vkGetImageDrmFormatModifierPropertiesEXT.

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

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 for the image subresource.
pLayout points to a VkSubresourceLayout structure in which the layout is returned.

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

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

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

Valid Usage

image must have been created with tiling equal to VK_IMAGE_TILING_LINEAR or VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT
The aspectMask member of pSubresource must only have a single bit set
The mipLevel member of pSubresource must be less than the mipLevels specified in VkImageCreateInfo when image was created
The arrayLayer member of pSubresource must be less than the arrayLayers specified in VkImageCreateInfo when image was created
If the tiling of the image is VK_IMAGE_TILING_LINEAR and its format is a multi-planar format with two planes, the aspectMask member of pSubresource must be VK_IMAGE_ASPECT_PLANE_0_BIT or VK_IMAGE_ASPECT_PLANE_1_BIT
If the tiling of the image is VK_IMAGE_TILING_LINEAR and its format is a multi-planar format with three planes, the aspectMask member of pSubresource must be VK_IMAGE_ASPECT_PLANE_0_BIT, VK_IMAGE_ASPECT_PLANE_1_BIT or VK_IMAGE_ASPECT_PLANE_2_BIT
If image was created with the VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID external memory handle type, then image must be bound to memory.
If the tiling of the image is VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then the aspectMask member of pSubresource must be VK_IMAGE_ASPECT_MEMORY_PLANE_i_BIT_EXT and the index i must be less than the drmFormatModifierPlaneCount associated with the image’s format and drmFormatModifier.

Valid Usage (Implicit)

device must be a valid VkDevice handle
image must be a valid VkImage handle
pSubresource must be a valid pointer to a valid VkImageSubresource structure
pLayout must be a valid pointer to a VkSubresourceLayout structure
image must have been created, allocated, or retrieved from device

The VkImageSubresource structure is defined as:

typedef struct VkImageSubresource {
    VkImageAspectFlags    aspectMask;
    uint32_t              mipLevel;
    uint32_t              arrayLayer;
} VkImageSubresource;

aspectMask is a VkImageAspectFlags selecting the image aspect.
mipLevel selects the mipmap level.
arrayLayer selects the array layer.

Valid Usage (Implicit)

aspectMask must be a valid combination of VkImageAspectFlagBits values
aspectMask must not be 0

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

typedef struct VkSubresourceLayout {
    VkDeviceSize    offset;
    VkDeviceSize    size;
    VkDeviceSize    rowPitch;
    VkDeviceSize    arrayPitch;
    VkDeviceSize    depthPitch;
} VkSubresourceLayout;

offset is the byte offset from the start of the image or the plane where the image subresource begins.
size is the size in bytes of the image subresource. size includes any extra memory that is required based on rowPitch.
rowPitch describes the number of bytes between each row of texels in an image.
arrayPitch describes the number of bytes between each array layer of an image.
depthPitch describes the number of bytes between each slice of 3D image.

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

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

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

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

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

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

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

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

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

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

VkResult vkGetImageDrmFormatModifierPropertiesEXT(
    VkDevice                                    device,
    VkImage                                     image,
    VkImageDrmFormatModifierPropertiesEXT*      pProperties);

device is the logical device that owns the image.
image is the queried image.
pProperties will return properties of the image’s DRM format modifier.

Valid Usage

image must have been created with tiling equal to VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT.

Valid Usage (Implicit)

device must be a valid VkDevice handle
image must be a valid VkImage handle
pProperties must be a valid pointer to a VkImageDrmFormatModifierPropertiesEXT structure
image must have been created, allocated, or retrieved from device

Return Codes

Success

VK_SUCCESS

The VkImageDrmFormatModifierPropertiesEXT structure is defined as:

typedef struct VkImageDrmFormatModifierPropertiesEXT {
    VkStructureType    sType;
    void*              pNext;
    uint64_t           drmFormatModifier;
} VkImageDrmFormatModifierPropertiesEXT;

sType is the type of this structure.
pNext is NULL or a pointer to an extension-specific structure.
drmFormatModifier returns the image’s Linux DRM format modifier.

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

Valid Usage (Implicit)

sType must be VK_STRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_PROPERTIES_EXT
pNext must be NULL

To destroy an image, call:

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

All submitted commands that refer to image, either directly or via a VkImageView, must have completed execution
If VkAllocationCallbacks were provided when image was created, a compatible set of callbacks must be provided here
If no VkAllocationCallbacks were provided when image was created, pAllocator must be NULL

Valid Usage (Implicit)

device must be a valid VkDevice handle
If image is not VK_NULL_HANDLE, image must be a valid VkImage handle
If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure
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

11.3.1. Image Format Features

Valid usage of a VkImage may be constrained by 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, but without an external format, then its set of format features is the value of VkFormatProperties::optimalTilingFeatures found by calling vkGetPhysicalDeviceFormatProperties on the same format as VkImageCreateInfo::format.
If the image was created with an external format, then its set of format features is the value of VkAndroidHardwareBufferFormatPropertiesANDROID::formatFeatures found by calling vkGetAndroidHardwareBufferPropertiesANDROID on the Android hardware buffer that was imported to the VkDeviceMemory to which the image is bound.
If the image was created with VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then:
- The image’s DRM format modifier is the value of VkImageDrmFormatModifierListCreateInfoEXT::drmFormatModifier found by calling vkGetImageDrmFormatModifierPropertiesEXT.
- Let VkDrmFormatModifierPropertiesListEXT::pDrmFormatModifierProperties be the array found by calling vkGetPhysicalDeviceFormatProperties2 on the same format as VkImageCreateInfo::format.
- Let VkDrmFormatModifierPropertiesEXT prop be the array element whose drmFormatModifier member is the value of the image’s DRM format modifier.
- Then the image set of format features is the value of prop::drmFormatModifierTilingFeatures.

11.3.2. Corner-Sampled Images

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

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

Texels are centered on integer coordinates. See Unnormalized Texel Coordinate Operations
Normalized coordinates are scaled using coord * (dim - 1) rather than coord * dim, where dim is the size of one dimension of the image. See normalized texel coordinate transform.
Partial derivatives are scaled using coord * (dim - 1) rather than coord * dim. See Scale Factor Operation.
Calculation of the next higher lod size goes according to ⌈dim / 2⌉ rather than ⌊dim / 2⌋. See Image Miplevel Sizing.
The minimum level size is 2x2 for 2D images and 2x2x2 for 3D images. See Image Miplevel Sizing.

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

11.3.3. Image Miplevel Sizing

A complete mipmap chain is the full set of miplevels, from the largest miplevel provided, down to the minimum miplevel size.

Conventional Images

For conventional images, the dimensions of each successive miplevel, 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 miplevel, n.

The minimum miplevel 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) miplevel, 0.

Corner-Sampled Images

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

: width_n+1 = max(⌈width_n/2⌉, 2)
: height_n+1 = max(⌈height_n/2⌉, 2)
: depth_n+1 = max(⌈depth_n/2⌉, 2)

where width_n, height_n, and depth_n are the dimensions of the next larger miplevel, n.

The minimum miplevel size is:

2x2 for two-dimensional images, and
2x2x2 for three-dimensional images.

The number of levels in a complete mipmap chain is:

: ⌈log₂(max(width₀, height₀, depth₀))⌉

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

11.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). The image layout is per-image subresource, and separate image subresources of the same image can be in different layouts at the same time with one exception - depth and stencil aspects of a given image subresource must always be in the same layout.

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 [glossary-linear-resource] 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:

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,
    VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL = 1000117000,
    VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL = 1000117001,
    VK_IMAGE_LAYOUT_PRESENT_SRC_KHR = 1000001002,
    VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR = 1000111000,
    VK_IMAGE_LAYOUT_SHADING_RATE_OPTIMAL_NV = 1000164003,
    VK_IMAGE_LAYOUT_FRAGMENT_DENSITY_MAP_OPTIMAL_EXT = 1000218000,
    VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL_KHR = VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL,
    VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL_KHR = VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL,
    VK_IMAGE_LAYOUT_MAX_ENUM = 0x7FFFFFFF
} VkImageLayout;

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

VK_IMAGE_LAYOUT_UNDEFINED does not support device access. This layout must only be used as the initialLayout member of VkImageCreateInfo or VkAttachmentDescription, or as the oldLayout in an image transition. When transitioning out of this layout, the contents of the memory are not guaranteed to be preserved.
VK_IMAGE_LAYOUT_PREINITIALIZED does not support device access. This layout must only be used as the initialLayout member of VkImageCreateInfo or VkAttachmentDescription, or as the oldLayout in an image transition. When transitioning out of this layout, the contents of the memory are preserved. 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_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 must only be used as a depth/stencil or depth/stencil resolve attachment in a VkFramebuffer. This layout is valid only for image subresources of images created with the VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT usage bit enabled.
VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL must only be used as a read-only depth/stencil attachment in a VkFramebuffer and/or as a read-only image in a shader (which can be read as a sampled image, combined image/sampler and/or input attachment). This layout is valid only for image subresources of images created with the VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT usage bit enabled. Only image views created with a usage value including VK_IMAGE_USAGE_SAMPLED_BIT can be used as a sampled image or combined image/sampler in a shader. Similarly, only image views created with a usage value including VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT can be used as input attachments.
VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL: must only be used as a depth/stencil attachment in a VkFramebuffer, where the depth aspect is read-only, and/or as a read-only image in a shader (which can be read as a sampled image, combined image/sampler and/or input attachment) where only the depth aspect is accessed. This layout is valid only for image subresources of images created with the VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT usage bit enabled. Only image views created with a usage value including VK_IMAGE_USAGE_SAMPLED_BIT can be used as a sampled image or combined image/sampler in a shader. Similarly, only image views created with a usage value including VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT can be used as input attachments.
VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL: must only be used as a depth/stencil attachment in a VkFramebuffer, where the stencil aspect is read-only, and/or as a read-only image in a shader (which can be read as a sampled image, combined image/sampler and/or input attachment) where only the stencil aspect is accessed. This layout is valid only for image subresources of images created with the VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT usage bit enabled. Only image views created with a usage value including VK_IMAGE_USAGE_SAMPLED_BIT can be used as a sampled image or combined image/sampler in a shader. Similarly, only image views created with a usage value including VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT can be used as input attachments.
VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL must only be used as a read-only image in a shader (which can be read as a sampled image, combined image/sampler and/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 bit 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. A swapchain’s image must be transitioned to this layout before calling vkQueuePresentKHR, and must be transitioned away from this layout after calling vkAcquireNextImageKHR.
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_SHADING_RATE_OPTIMAL_NV must only be used as a read-only shading-rate-image. This layout is valid only for image subresources of images created with the VK_IMAGE_USAGE_SHADING_RATE_IMAGE_BIT_NV usage bit enabled.
VK_IMAGE_LAYOUT_FRAGMENT_DENSITY_MAP_OPTIMAL_EXT must only be used as a fragment density map attachment in a VkRenderPass. This layout is valid only for image subresources of images created with the VK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT usage bit enabled.

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

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

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

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

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

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

VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkImageView)

The types of image views that can be created are:

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,
    VK_IMAGE_VIEW_TYPE_MAX_ENUM = 0x7FFFFFFF
} VkImageViewType;

The exact image view type is partially implicit, based on the image’s type and sample count, as well as the view creation parameters as described in the image view compatibility table for vkCreateImageView. This table also shows which SPIR-V OpTypeImage Dim and Arrayed parameters correspond to each image view type.

To create an image view, call:

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 an instance of the 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 points to a VkImageView handle in which the resulting image view object is returned.

Valid Usage (Implicit)

device must be a valid VkDevice handle
pCreateInfo must be a valid pointer to a valid VkImageViewCreateInfo structure
If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure
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

The VkImageViewCreateInfo structure is defined as:

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

sType is the type of this structure.
pNext is NULL or a pointer to an extension-specific structure.
flags is a bitmask of VkImageViewCreateFlagBits describing 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 describing the format and type used to interpret texel blocks in the image.
components is a VkComponentMapping specifies a remapping of color components (or of depth or stencil components after they have been converted into color components).
subresourceRange is a VkImageSubresourceRange 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. If the image was has a depth-stencil format and was created with an instance of VkImageStencilUsageCreateInfoEXT 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 VkImageStencilUsageCreateInfoEXT::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 VkImageStencilUsageCreateInfoEXT::stencilUsage. The implicit usage can be overriden by including an instance of VkImageViewUsageCreateInfo structure in the pNext chain.

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

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, as defined for copying data between images 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.

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 added to 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 and subresourceRange.aspectMask is VK_IMAGE_ASPECT_COLOR_BIT, 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.

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 channels 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 15. Image and image view parameter compatibility requirements
Dim, Arrayed, MS	Image parameters	View parameters
	`imageType` = ci.`imageType` `width` = ci.`extent.width` `height` = ci.`extent.height` `depth` = ci.`extent.depth` `arrayLayers` = ci.`arrayLayers` `samples` = ci.`samples` `flags` = ci.`flags` where ci is the VkImageCreateInfo used to create `image`.	`baseArrayLayer`, `layerCount`, and `levelCount` are members of the `subresourceRange` member.
1D, 0, 0	`imageType` = `VK_IMAGE_TYPE_1D` `width` ≥ 1 `height` = 1 `depth` = 1 `arrayLayers` ≥ 1 `samples` = 1	`viewType` = `VK_IMAGE_VIEW_TYPE_1D` `baseArrayLayer` ≥ 0 `layerCount` = 1
1D, 1, 0	`imageType` = `VK_IMAGE_TYPE_1D` `width` ≥ 1 `height` = 1 `depth` = 1 `arrayLayers` ≥ 1 `samples` = 1	`viewType` = `VK_IMAGE_VIEW_TYPE_1D_ARRAY` `baseArrayLayer` ≥ 0 `layerCount` ≥ 1
2D, 0, 0	`imageType` = `VK_IMAGE_TYPE_2D` `width` ≥ 1 `height` ≥ 1 `depth` = 1 `arrayLayers` ≥ 1 `samples` = 1	`viewType` = `VK_IMAGE_VIEW_TYPE_2D` `baseArrayLayer` ≥ 0 `layerCount` = 1
2D, 1, 0	`imageType` = `VK_IMAGE_TYPE_2D` `width` ≥ 1 `height` ≥ 1 `depth` = 1 `arrayLayers` ≥ 1 `samples` = 1	`viewType` = `VK_IMAGE_VIEW_TYPE_2D_ARRAY` `baseArrayLayer` ≥ 0 `layerCount` ≥ 1
2D, 0, 1	`imageType` = `VK_IMAGE_TYPE_2D` `width` ≥ 1 `height` ≥ 1 `depth` = 1 `arrayLayers` ≥ 1 `samples` > 1	`viewType` = `VK_IMAGE_VIEW_TYPE_2D` `baseArrayLayer` ≥ 0 `layerCount` = 1
2D, 1, 1	`imageType` = `VK_IMAGE_TYPE_2D` `width` ≥ 1 `height` ≥ 1 `depth` = 1 `arrayLayers` ≥ 1 `samples` > 1	`viewType` = `VK_IMAGE_VIEW_TYPE_2D_ARRAY` `baseArrayLayer` ≥ 0 `layerCount` ≥ 1
CUBE, 0, 0	`imageType` = `VK_IMAGE_TYPE_2D` `width` ≥ 1 `height` = `width` `depth` = 1 `arrayLayers` ≥ 6 `samples` = 1 `flags` includes `VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT`	`viewType` = `VK_IMAGE_VIEW_TYPE_CUBE` `baseArrayLayer` ≥ 0 `layerCount` = 6
CUBE, 1, 0	`imageType` = `VK_IMAGE_TYPE_2D` `width` ≥ 1 `height` = width `depth` = 1 N ≥ 1 `arrayLayers` ≥ 6 × N `samples` = 1 `flags` includes `VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT`	`viewType` = `VK_IMAGE_VIEW_TYPE_CUBE_ARRAY` `baseArrayLayer` ≥ 0 `layerCount` = 6 × N, N ≥ 1
3D, 0, 0	`imageType` = `VK_IMAGE_TYPE_3D` `width` ≥ 1 `height` ≥ 1 `depth` ≥ 1 `arrayLayers` = 1 `samples` = 1	`viewType` = `VK_IMAGE_VIEW_TYPE_3D` `baseArrayLayer` = 0 `layerCount` = 1
3D, 0, 0	`imageType` = `VK_IMAGE_TYPE_3D` `width` ≥ 1 `height` ≥ 1 `depth` ≥ 1 `arrayLayers` = 1 `samples` = 1 `flags` includes `VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT` `flags` does not include `VK_IMAGE_CREATE_SPARSE_BINDING_BIT`, `VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT`, and `VK_IMAGE_CREATE_SPARSE_ALIASED_BIT`	`viewType` = `VK_IMAGE_VIEW_TYPE_2D` `levelCount` = 1 `baseArrayLayer` ≥ 0 `layerCount` = 1
3D, 0, 0	`imageType` = `VK_IMAGE_TYPE_3D` `width` ≥ 1 `height` ≥ 1 `depth` ≥ 1 `arrayLayers` = 1 `samples` = 1 `flags` includes `VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT` `flags` does not include `VK_IMAGE_CREATE_SPARSE_BINDING_BIT`, `VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT`, and `VK_IMAGE_CREATE_SPARSE_ALIASED_BIT`	`viewType` = `VK_IMAGE_VIEW_TYPE_2D_ARRAY` `levelCount` = 1 `baseArrayLayer` ≥ 0 `layerCount` ≥ 1

Valid Usage

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
If the image cubemap arrays feature is not enabled, viewType must not be VK_IMAGE_VIEW_TYPE_CUBE_ARRAY
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 or VK_IMAGE_VIEW_TYPE_2D_ARRAY
image must have been created with a usage value containing at least one of 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_SHADING_RATE_IMAGE_BIT_NV, or VK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT
The format features of the resultant image view must contain at least one bit.
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.
If usage contains VK_IMAGE_USAGE_STORAGE_BIT, then the image view’s format features must contain VK_FORMAT_FEATURE_STORAGE_IMAGE_BIT.
If usage contains VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT, then the image view’s format features must contain VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT.
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.
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.
subresourceRange.baseMipLevel must be less than the mipLevels specified in VkImageCreateInfo when image was created
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
If image was created with usage containing VK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT, subresourceRange.levelCount must be 1
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
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
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 Miplevel Sizing.
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 Miplevel Sizing.
If image was created with the VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT flag, format must be compatible with the format used to create image, as defined in Format Compatibility Classes
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
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.
If image was created with the VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT flag, the levelCount and layerCount members of subresourceRange must both be 1.
If a VkImageFormatListCreateInfoKHR structure was included in the pNext chain of the VkImageCreateInfo struct used when creating image and the viewFormatCount field of VkImageFormatListCreateInfoKHR is not zero then format must be one of the formats in VkImageFormatListCreateInfoKHR::pViewFormats.
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 VK_IMAGE_ASPECT_PLANE_0_BIT, VK_IMAGE_ASPECT_PLANE_1_BIT, or VK_IMAGE_ASPECT_PLANE_2_BIT, 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
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
If the pNext chain contains an instance of VkSamplerYcbcrConversionInfo with a conversion value other than VK_NULL_HANDLE, all members of components must have the value VK_COMPONENT_SWIZZLE_IDENTITY.
If image is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object
subresourceRange and viewType must be compatible with the image, as described in the compatibility table
If image has an external format, format must be VK_FORMAT_UNDEFINED.
If image has an external format, the pNext chain must contain an instance of VkSamplerYcbcrConversionInfo with a conversion object created with the same external format as image.
If image has an external format, all members of components must be VK_COMPONENT_SWIZZLE_IDENTITY.
If image was created with usage containing VK_IMAGE_USAGE_SHADING_RATE_IMAGE_BIT_NV, viewType must be VK_IMAGE_VIEW_TYPE_2D or VK_IMAGE_VIEW_TYPE_2D_ARRAY
If image was created with usage containing VK_IMAGE_USAGE_SHADING_RATE_IMAGE_BIT_NV, format must be VK_FORMAT_R8_UINT
If dynamic fragment density map feature is not enabled, flags must not contain VK_IMAGE_VIEW_CREATE_FRAGMENT_DENSITY_MAP_DYNAMIC_BIT_EXT
If dynamic fragment density map feature is not enabled and image was created with usage containing VK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT, flags must not contain any of VK_IMAGE_CREATE_PROTECTED_BIT, VK_IMAGE_CREATE_SPARSE_BINDING_BIT, VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT, or VK_IMAGE_CREATE_SPARSE_ALIASED_BIT
If the pNext chain includes an instance of VkImageViewUsageCreateInfo, and image was not created with an instance of VkImageStencilUsageCreateInfoEXT 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
If the pNext chain includes an instance of VkImageViewUsageCreateInfo, image was created with an instance of VkImageStencilUsageCreateInfoEXT in the pNext chain of VkImageCreateInfo, and subResourceRange.aspectMask includes VK_IMAGE_ASPECT_STENCIL_BIT, the usage member of the VkImageViewUsageCreateInfo instance must not include any bits that were not set in the usage member of the VkImageStencilUsageCreateInfoEXT structure used to create image
If the pNext chain includes an instance of VkImageViewUsageCreateInfo, image was created with an instance of VkImageStencilUsageCreateInfoEXT in the pNext chain of VkImageCreateInfo, and subResourceRange.aspectMask includes bits other than VK_IMAGE_ASPECT_STENCIL_BIT, the usage member of the VkImageViewUsageCreateInfo instance must not include any bits that were not set in the usage member of the VkImageCreateInfo structure used to create image

Valid Usage (Implicit)

sType must be VK_STRUCTURE_TYPE_IMAGE_VIEW_CREATE_INFO
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 VkImageViewASTCDecodeModeEXT, VkImageViewUsageCreateInfo, or VkSamplerYcbcrConversionInfo
Each sType member in the pNext chain must be unique
flags must be a valid combination of VkImageViewCreateFlagBits values
image must be a valid VkImage handle
viewType must be a valid VkImageViewType value
format must be a valid VkFormat value
components must be a valid VkComponentMapping structure
subresourceRange must be a valid VkImageSubresourceRange structure

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

typedef enum VkImageViewCreateFlagBits {
    VK_IMAGE_VIEW_CREATE_FRAGMENT_DENSITY_MAP_DYNAMIC_BIT_EXT = 0x00000001,
    VK_IMAGE_VIEW_CREATE_FLAG_BITS_MAX_ENUM = 0x7FFFFFFF
} VkImageViewCreateFlagBits;

VK_IMAGE_VIEW_CREATE_FRAGMENT_DENSITY_MAP_DYNAMIC_BIT_EXT prohibits the implementation from accessing the fragment density map by the host during vkCmdBeginRenderPass as the contents are expected to change after recording

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 chaining a VkImageViewUsageCreateInfo structure through the pNext member to VkImageViewCreateInfo.

The VkImageViewUsageCreateInfo structure is defined as:

typedef struct VkImageViewUsageCreateInfo {
    VkStructureType      sType;
    const void*          pNext;
    VkImageUsageFlags    usage;
} VkImageViewUsageCreateInfo;

or the equivalent

typedef VkImageViewUsageCreateInfo VkImageViewUsageCreateInfoKHR;

sType is the type of this structure.
pNext is NULL or a pointer to an extension-specific structure.
usage is a bitmask describing the allowed usages of the image view. See VkImageUsageFlagBits for a description of the supported bits.

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)

sType must be VK_STRUCTURE_TYPE_IMAGE_VIEW_USAGE_CREATE_INFO
usage must be a valid combination of VkImageUsageFlagBits values
usage must not be 0

The VkImageSubresourceRange structure is defined as:

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

The components member is of type VkComponentMapping, and describes a remapping from components of the image to components of the vector returned by shader image instructions. This remapping must be identity 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.

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

If levelCount is not VK_REMAINING_MIP_LEVELS, it must be greater than 0
If layerCount is not VK_REMAINING_ARRAY_LAYERS, it must be greater than 0
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
aspectMask must not include VK_IMAGE_ASPECT_MEMORY_PLANE_i_BIT_EXT for any index i.

Valid Usage (Implicit)

aspectMask must be a valid combination of VkImageAspectFlagBits values
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:

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,
    VK_IMAGE_ASPECT_PLANE_0_BIT = 0x00000010,
    VK_IMAGE_ASPECT_PLANE_1_BIT = 0x00000020,
    VK_IMAGE_ASPECT_PLANE_2_BIT = 0x00000040,
    VK_IMAGE_ASPECT_MEMORY_PLANE_0_BIT_EXT = 0x00000080,
    VK_IMAGE_ASPECT_MEMORY_PLANE_1_BIT_EXT = 0x00000100,
    VK_IMAGE_ASPECT_MEMORY_PLANE_2_BIT_EXT = 0x00000200,
    VK_IMAGE_ASPECT_MEMORY_PLANE_3_BIT_EXT = 0x00000400,
    VK_IMAGE_ASPECT_PLANE_0_BIT_KHR = VK_IMAGE_ASPECT_PLANE_0_BIT,
    VK_IMAGE_ASPECT_PLANE_1_BIT_KHR = VK_IMAGE_ASPECT_PLANE_1_BIT,
    VK_IMAGE_ASPECT_PLANE_2_BIT_KHR = VK_IMAGE_ASPECT_PLANE_2_BIT,
    VK_IMAGE_ASPECT_FLAG_BITS_MAX_ENUM = 0x7FFFFFFF
} VkImageAspectFlagBits;

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 sparse resource operations.

typedef VkFlags VkImageAspectFlags;

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

The VkComponentMapping structure is defined as:

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)

r must be a valid VkComponentSwizzle value
g must be a valid VkComponentSwizzle value
b must be a valid VkComponentSwizzle value
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:

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,
    VK_COMPONENT_SWIZZLE_MAX_ENUM = 0x7FFFFFFF
} 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 16. Component Mappings Equivalent To `VK_COMPONENT_SWIZZLE_IDENTITY`
Component	Identity Mapping
`components.r`	`VK_COMPONENT_SWIZZLE_R`
`components.g`	`VK_COMPONENT_SWIZZLE_G`
`components.b`	`VK_COMPONENT_SWIZZLE_B`
`components.a`	`VK_COMPONENT_SWIZZLE_A`

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

The VkImageViewASTCDecodeModeEXT structure is defined as:

typedef struct VkImageViewASTCDecodeModeEXT {
    VkStructureType    sType;
    const void*        pNext;
    VkFormat           decodeMode;
} VkImageViewASTCDecodeModeEXT;

sType is the type of this structure.
pNext is NULL or a pointer to an extension-specific structure.
decodeMode is the intermediate format used to decode ASTC compressed formats.

Valid Usage

decodeMode must be one of VK_FORMAT_R16G16B16A16_SFLOAT, VK_FORMAT_R8G8B8A8_UNORM, or VK_FORMAT_E5B9G9R9_UFLOAT_PACK32
If the decodeModeSharedExponent feature is not enabled, decodeMode must not be VK_FORMAT_E5B9G9R9_UFLOAT_PACK32
If decodeMode is VK_FORMAT_R8G8B8A8_UNORM the image view must not include blocks using any of the ASTC HDR modes
format of the image view must be one of VK_FORMAT_ASTC_4x4_UNORM_BLOCK, VK_FORMAT_ASTC_4x4_SRGB_BLOCK, VK_FORMAT_ASTC_5x4_UNORM_BLOCK, VK_FORMAT_ASTC_5x4_SRGB_BLOCK, VK_FORMAT_ASTC_5x5_UNORM_BLOCK, VK_FORMAT_ASTC_5x5_SRGB_BLOCK, VK_FORMAT_ASTC_6x5_UNORM_BLOCK, VK_FORMAT_ASTC_6x5_SRGB_BLOCK, VK_FORMAT_ASTC_6x6_UNORM_BLOCK, VK_FORMAT_ASTC_6x6_SRGB_BLOCK, VK_FORMAT_ASTC_8x5_UNORM_BLOCK, VK_FORMAT_ASTC_8x5_SRGB_BLOCK, VK_FORMAT_ASTC_8x6_UNORM_BLOCK, VK_FORMAT_ASTC_8x6_SRGB_BLOCK, VK_FORMAT_ASTC_8x8_UNORM_BLOCK, VK_FORMAT_ASTC_8x8_SRGB_BLOCK, VK_FORMAT_ASTC_10x5_UNORM_BLOCK, VK_FORMAT_ASTC_10x5_SRGB_BLOCK, VK_FORMAT_ASTC_10x6_UNORM_BLOCK, VK_FORMAT_ASTC_10x6_SRGB_BLOCK, VK_FORMAT_ASTC_10x8_UNORM_BLOCK, VK_FORMAT_ASTC_10x8_SRGB_BLOCK, VK_FORMAT_ASTC_10x10_UNORM_BLOCK, VK_FORMAT_ASTC_10x10_SRGB_BLOCK, VK_FORMAT_ASTC_12x10_UNORM_BLOCK, VK_FORMAT_ASTC_12x10_SRGB_BLOCK, VK_FORMAT_ASTC_12x12_UNORM_BLOCK, or VK_FORMAT_ASTC_12x12_SRGB_BLOCK

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

Valid Usage (Implicit)

sType must be VK_STRUCTURE_TYPE_IMAGE_VIEW_ASTC_DECODE_MODE_EXT
decodeMode must be a valid VkFormat value

To destroy an image view, call:

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

All submitted commands that refer to imageView must have completed execution
If VkAllocationCallbacks were provided when imageView was created, a compatible set of callbacks must be provided here
If no VkAllocationCallbacks were provided when imageView was created, pAllocator must be NULL

Valid Usage (Implicit)

device must be a valid VkDevice handle
If imageView is not VK_NULL_HANDLE, imageView must be a valid VkImageView handle
If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure
If imageView is a valid handle, it must have been created, allocated, or retrieved from device

Host Synchronization

Host access to imageView must be externally synchronized

To get the handle for an image view, call:

uint32_t vkGetImageViewHandleNVX(
    VkDevice                                    device,
    const VkImageViewHandleInfoNVX*             pInfo);

device is the logical device that owns the image view.
pInfo describes the image view to query and type of handle.

Valid Usage (Implicit)

device must be a valid VkDevice handle
pInfo must be a valid pointer to a valid VkImageViewHandleInfoNVX structure

The VkImageViewHandleInfoNVX structure is defined as:

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

sType is the type of this structure.
pNext is NULL or a pointer to an extension-specific structure.
imageView is the image view to query.
descriptorType is the type of descriptor for which to query a handle.
sampler is the sampler to combine with the image view when generating the handle.

Valid Usage

descriptorType must be VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE, VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, or VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER
sampler must be a valid VkSampler if descriptorType is VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER
If descriptorType is VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE or VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, the image that imageView was created from must have been created with the VK_IMAGE_USAGE_SAMPLED_BIT usage bit set
If descriptorType is VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, the image that imageView was created from must have been created with the VK_IMAGE_USAGE_STORAGE_BIT usage bit set

Valid Usage (Implicit)

sType must be VK_STRUCTURE_TYPE_IMAGE_VIEW_HANDLE_INFO_NVX
pNext must be NULL
imageView must be a valid VkImageView handle
descriptorType must be a valid VkDescriptorType value
If sampler is not VK_NULL_HANDLE, sampler must be a valid VkSampler handle
Both of imageView, and sampler that are valid handles must have been created, allocated, or retrieved from the same VkDevice

11.5.1. Image View Format Features

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

If the view’s image was created with VK_IMAGE_TILING_LINEAR, then the image view’s set of format features is the value of VkFormatProperties::linearTilingFeatures found by calling vkGetPhysicalDeviceFormatProperties on the same format as VkImageViewCreateInfo::format.
If the view’s image was created with VK_IMAGE_TILING_OPTIMAL, but without an external format, then the image view’s set of format features is the value of VkFormatProperties::optimalTilingFeatures found by calling vkGetPhysicalDeviceFormatProperties on the same format as VkImageViewCreateInfo::format.
If the view’s image was created with an external format, then the image views’s set of format features is the value of VkAndroidHardwareBufferFormatPropertiesANDROID::formatFeatures found by calling vkGetAndroidHardwareBufferPropertiesANDROID on the Android hardware buffer that was imported to the VkDeviceMemory to which the image is bound.
If the view’s image was created with VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then:
- The image’s DRM format modifier is the value of VkImageDrmFormatModifierListCreateInfoEXT::drmFormatModifier found by calling vkGetImageDrmFormatModifierPropertiesEXT.
- Let VkDrmFormatModifierPropertiesListEXT::pDrmFormatModifierProperties be the array found by calling vkGetPhysicalDeviceFormatProperties2 on the same format as VkImageViewCreateInfo::format.
- Let VkDrmFormatModifierPropertiesEXT prop be the array element whose drmFormatModifier member is the value of the image’s DRM format modifier.
- Then the image view’s set of format features is the value of prop::drmFormatModifierTilingFeatures.

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

void vkGetBufferMemoryRequirements(
    VkDevice                                    device,
    VkBuffer                                    buffer,
    VkMemoryRequirements*                       pMemoryRequirements);

device is the logical device that owns the buffer.
buffer is the buffer to query.
pMemoryRequirements points to an instance of the VkMemoryRequirements structure in which the memory requirements of the buffer object are returned.

Valid Usage (Implicit)

device must be a valid VkDevice handle
buffer must be a valid VkBuffer handle
pMemoryRequirements must be a valid pointer to a VkMemoryRequirements structure
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:

void vkGetImageMemoryRequirements(
    VkDevice                                    device,
    VkImage                                     image,
    VkMemoryRequirements*                       pMemoryRequirements);

device is the logical device that owns the image.
image is the image to query.
pMemoryRequirements points to an instance of the VkMemoryRequirements structure in which the memory requirements of the image object are returned.

Valid Usage

image must not have been created with the VK_IMAGE_CREATE_DISJOINT_BIT flag set

Valid Usage (Implicit)

device must be a valid VkDevice handle
image must be a valid VkImage handle
pMemoryRequirements must be a valid pointer to a VkMemoryRequirements structure
image must have been created, allocated, or retrieved from device

The VkMemoryRequirements structure is defined as:

typedef struct VkMemoryRequirements {
    VkDeviceSize    size;
    VkDeviceSize    alignment;
    uint32_t        memoryTypeBits;
} VkMemoryRequirements;

size is the size, in bytes, of the memory allocation required for the resource.
alignment is the alignment, in bytes, of the offset within the allocation required for the resource.
memoryTypeBits is a bitmask and contains one bit set for every supported memory type for the resource. Bit i is set if and only if the memory type i in the VkPhysicalDeviceMemoryProperties structure for the physical device is supported for the resource.

The precise size of images that will be bound to external Android hardware buffer memory is unknown until the memory has been imported or allocated, so applications must not call vkGetImageMemoryRequirements with such an image before it has been bound to memory. When importing Android hardware buffer memory, the allocationSize can be determined by calling vkGetAndroidHardwareBufferPropertiesANDROID. When allocating new memory for an image that can be exported to an Android hardware buffer, the memory’s allocationSize must be zero; the actual size will be determined by the dedicated image’s parameters. After the memory has been allocated, the amount of space allocated from the memory’s heap can be obtained by getting the image’s memory requirements or by calling vkGetAndroidHardwareBufferPropertiesANDROID with the Android hardware buffer exported from the memory.

The implementation guarantees certain properties about the memory requirements returned by 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 bit set, or if image is linear image, 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.
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, 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, 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.

To determine the memory requirements for a buffer resource, call:

void vkGetBufferMemoryRequirements2(
    VkDevice                                    device,
    const VkBufferMemoryRequirementsInfo2*      pInfo,
    VkMemoryRequirements2*                      pMemoryRequirements);

or the equivalent command

void vkGetBufferMemoryRequirements2KHR(
    VkDevice                                    device,
    const VkBufferMemoryRequirementsInfo2*      pInfo,
    VkMemoryRequirements2*                      pMemoryRequirements);

device is the logical device that owns the buffer.
pInfo is a pointer to an instance of the VkBufferMemoryRequirementsInfo2 structure containing parameters required for the memory requirements query.
pMemoryRequirements points to an instance of the VkMemoryRequirements2 structure in which the memory requirements of the buffer object are returned.

Valid Usage (Implicit)

device must be a valid VkDevice handle
pInfo must be a valid pointer to a valid VkBufferMemoryRequirementsInfo2 structure
pMemoryRequirements must be a valid pointer to a VkMemoryRequirements2 structure

The VkBufferMemoryRequirementsInfo2 structure is defined as:

typedef struct VkBufferMemoryRequirementsInfo2 {
    VkStructureType    sType;
    const void*        pNext;
    VkBuffer           buffer;
} VkBufferMemoryRequirementsInfo2;

or the equivalent

typedef VkBufferMemoryRequirementsInfo2 VkBufferMemoryRequirementsInfo2KHR;

sType is the type of this structure.
pNext is NULL or a pointer to an extension-specific structure.
buffer is the buffer to query.

Valid Usage (Implicit)

sType must be VK_STRUCTURE_TYPE_BUFFER_MEMORY_REQUIREMENTS_INFO_2
pNext must be NULL
buffer must be a valid VkBuffer handle

To determine the memory requirements for an image resource, call:

void vkGetImageMemoryRequirements2(
    VkDevice                                    device,
    const VkImageMemoryRequirementsInfo2*       pInfo,
    VkMemoryRequirements2*                      pMemoryRequirements);

or the equivalent command

void vkGetImageMemoryRequirements2KHR(
    VkDevice                                    device,
    const VkImageMemoryRequirementsInfo2*       pInfo,
    VkMemoryRequirements2*                      pMemoryRequirements);

device is the logical device that owns the image.
pInfo is a pointer to an instance of the VkImageMemoryRequirementsInfo2 structure containing parameters required for the memory requirements query.
pMemoryRequirements points to an instance of the VkMemoryRequirements2 structure in which the memory requirements of the image object are returned.

Valid Usage (Implicit)

device must be a valid VkDevice handle
pInfo must be a valid pointer to a valid VkImageMemoryRequirementsInfo2 structure
pMemoryRequirements must be a valid pointer to a VkMemoryRequirements2 structure

The VkImageMemoryRequirementsInfo2 structure is defined as:

typedef struct VkImageMemoryRequirementsInfo2 {
    VkStructureType    sType;
    const void*        pNext;
    VkImage            image;
} VkImageMemoryRequirementsInfo2;

or the equivalent

typedef VkImageMemoryRequirementsInfo2 VkImageMemoryRequirementsInfo2KHR;

sType is the type of this structure.
pNext is NULL or a pointer to an extension-specific structure.
image is the image to query.

Valid Usage

If image was created with a multi-planar format and the VK_IMAGE_CREATE_DISJOINT_BIT flag, there must be a VkImagePlaneMemoryRequirementsInfo in the pNext chain of the VkImageMemoryRequirementsInfo2 structure
If image was created with VK_IMAGE_CREATE_DISJOINT_BIT and with VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then there must be a VkImagePlaneMemoryRequirementsInfo in the pNext chain of the VkImageMemoryRequirementsInfo2 structure
If image was not created with the VK_IMAGE_CREATE_DISJOINT_BIT flag, there must not be a VkImagePlaneMemoryRequirementsInfo in the pNext chain of the VkImageMemoryRequirementsInfo2 structure
If image was created with a single-plane format and with any tiling other than VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then there must not be a VkImagePlaneMemoryRequirementsInfo in the pNext chain of the VkImageMemoryRequirementsInfo2 structure
If image was created with the VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID external memory handle type, then image must be bound to memory.

Valid Usage (Implicit)

sType must be VK_STRUCTURE_TYPE_IMAGE_MEMORY_REQUIREMENTS_INFO_2
pNext must be NULL or a pointer to a valid instance of VkImagePlaneMemoryRequirementsInfo
image must be a valid VkImage handle

To determine the memory requirements for a plane of a disjoint image, add a VkImagePlaneMemoryRequirementsInfo to the pNext chain of the VkImageMemoryRequirementsInfo2 structure.

The VkImagePlaneMemoryRequirementsInfo structure is defined as:

typedef struct VkImagePlaneMemoryRequirementsInfo {
    VkStructureType          sType;
    const void*              pNext;
    VkImageAspectFlagBits    planeAspect;
} VkImagePlaneMemoryRequirementsInfo;

or the equivalent

typedef VkImagePlaneMemoryRequirementsInfo VkImagePlaneMemoryRequirementsInfoKHR;

sType is the type of this structure.
pNext is NULL or a pointer to an extension-specific structure.
planeAspect is the aspect corresponding to the image plane to query.

Valid Usage

If the image’s tiling is VK_IMAGE_TILING_LINEAR or VK_IMAGE_TILING_OPTIMAL, then planeAspect must be a single valid format plane for the image. (That is, for a two-plane image planeAspect must be VK_IMAGE_ASPECT_PLANE_0_BIT or VK_IMAGE_ASPECT_PLANE_1_BIT, and for a three-plane image planeAspect must be VK_IMAGE_ASPECT_PLANE_0_BIT, VK_IMAGE_ASPECT_PLANE_1_BIT or VK_IMAGE_ASPECT_PLANE_2_BIT).
If the image’s tiling is VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then planeAspect must be a single valid memory plane for the image. (That is, aspectMask must specify a plane index that is less than the drmFormatModifierPlaneCount associated with the image’s format and drmFormatModifier.)

Valid Usage (Implicit)

sType must be VK_STRUCTURE_TYPE_IMAGE_PLANE_MEMORY_REQUIREMENTS_INFO
planeAspect must be a valid VkImageAspectFlagBits value

The VkMemoryRequirements2 structure is defined as:

typedef struct VkMemoryRequirements2 {
    VkStructureType         sType;
    void*                   pNext;
    VkMemoryRequirements    memoryRequirements;
} VkMemoryRequirements2;

or the equivalent

typedef VkMemoryRequirements2 VkMemoryRequirements2KHR;

sType is the type of this structure.
pNext is NULL or a pointer to an extension-specific structure.
memoryRequirements is a structure of type VkMemoryRequirements describing the memory requirements of the resource.

Valid Usage (Implicit)

sType must be VK_STRUCTURE_TYPE_MEMORY_REQUIREMENTS_2
pNext must be NULL or a pointer to a valid instance of VkMemoryDedicatedRequirements

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.

The VkMemoryDedicatedRequirements structure is defined as:

typedef struct VkMemoryDedicatedRequirements {
    VkStructureType    sType;
    void*              pNext;
    VkBool32           prefersDedicatedAllocation;
    VkBool32           requiresDedicatedAllocation;
} VkMemoryDedicatedRequirements;

or the equivalent

typedef VkMemoryDedicatedRequirements VkMemoryDedicatedRequirementsKHR;

sType is the type of this structure.
pNext is NULL or a pointer to an extension-specific 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.

When the implementation sets requiresDedicatedAllocation to VK_TRUE, it must also set prefersDedicatedAllocation to VK_TRUE.

If the VkMemoryDedicatedRequirements structure is included in the pNext chain of the VkMemoryRequirements2 structure passed as the pMemoryRequirements parameter of a vkGetBufferMemoryRequirements2 call, requiresDedicatedAllocation may be VK_TRUE under one of the following conditions:

The pNext chain of VkBufferCreateInfo for the call to vkCreateBuffer used to create the buffer being queried contained an instance of VkExternalMemoryBufferCreateInfo, and any of the handle types specified in VkExternalMemoryBufferCreateInfo::handleTypes requires dedicated allocation, as reported by vkGetPhysicalDeviceExternalBufferProperties in VkExternalBufferProperties::externalMemoryProperties::externalMemoryFeatures, the requiresDedicatedAllocation field will be set to VK_TRUE.

In all other cases, requiresDedicatedAllocation must be set to VK_FALSE by the implementation whenever a VkMemoryDedicatedRequirements structure is included in the pNext chain of the VkMemoryRequirements2 structure passed to a call to vkGetBufferMemoryRequirements2.

If the VkMemoryDedicatedRequirements structure is included in the pNext chain of the VkMemoryRequirements2 structure passed as the pMemoryRequirements parameter of a vkGetBufferMemoryRequirements2 call and VK_BUFFER_CREATE_SPARSE_BINDING_BIT was set in VkBufferCreateInfo::flags when buffer was created then the implementation must set both prefersDedicatedAllocation and requiresDedicatedAllocation to VK_FALSE.

The pNext chain of VkImageCreateInfo for the call to vkCreateImage used to create the image being queried contained an instance of VkExternalMemoryImageCreateInfo, and any of the handle types specified in VkExternalMemoryImageCreateInfo::handleTypes requires dedicated allocation, as reported by vkGetPhysicalDeviceImageFormatProperties2 in VkExternalImageFormatProperties::externalMemoryProperties::externalMemoryFeatures, the requiresDedicatedAllocation field will be set to VK_TRUE.

If the VkMemoryDedicatedRequirements structure is included in the pNext chain of the VkMemoryRequirements2 structure passed as the pMemoryRequirements parameter of a vkGetImageMemoryRequirements2 call and VK_IMAGE_CREATE_SPARSE_BINDING_BIT was set in VkImageCreateInfo::flags when image was created then the implementation must set both prefersDedicatedAllocation and requiresDedicatedAllocation to VK_FALSE.

Valid Usage (Implicit)

sType must be VK_STRUCTURE_TYPE_MEMORY_DEDICATED_REQUIREMENTS

To attach memory to a buffer object, call:

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

buffer must not already be backed by a memory object
buffer must not have been created with any sparse memory binding flags
memoryOffset must be less than the size of memory
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
memoryOffset must be an integer multiple of the alignment member of the VkMemoryRequirements structure returned from a call to vkGetBufferMemoryRequirements with buffer
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
If buffer requires a dedicated allocation(as reported by vkGetBufferMemoryRequirements2 in VkMemoryDedicatedRequirements::requiresDedicatedAllocation for buffer), memory must have been created with VkMemoryDedicatedAllocateInfo::buffer equal to buffer
If the VkMemoryAllocateInfo provided when memory was allocated included an instance of VkMemoryDedicatedAllocateInfo in its pNext chain, and VkMemoryDedicatedAllocateInfo::buffer was not VK_NULL_HANDLE, then buffer must equal VkMemoryDedicatedAllocateInfo::buffer, and memoryOffset must be zero.
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
If buffer was created with the VK_BUFFER_CREATE_PROTECTED_BIT bit not set, the buffer must not be bound to a memory object created with a memory type that reports VK_MEMORY_PROPERTY_PROTECTED_BIT
If buffer was created with VkDedicatedAllocationBufferCreateInfoNV::dedicatedAllocation equal to VK_TRUE, memory must have been created with VkDedicatedAllocationMemoryAllocateInfoNV::buffer equal to a buffer handle created with identical creation parameters to buffer and memoryOffset must be zero
If memory was allocated with VkExportMemoryAllocateInfo::handleTypes not equal to 0, at least one handle type it contained must also have been set in VkExternalMemoryBufferCreateInfo::handleTypes when buffer was created.
If memory was created 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.

Valid Usage (Implicit)

device must be a valid VkDevice handle
buffer must be a valid VkBuffer handle
memory must be a valid VkDeviceMemory handle
buffer must have been created, allocated, or retrieved from device
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

To attach memory to buffer objects for one or more buffers at a time, call:

VkResult vkBindBufferMemory2(
    VkDevice                                    device,
    uint32_t                                    bindInfoCount,
    const VkBindBufferMemoryInfo*               pBindInfos);

or the equivalent command

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 structures of type VkBindBufferMemoryInfo, describing buffers and memory to bind.

On some implementations, it may be more efficient to batch memory bindings into a single command.

Valid Usage (Implicit)

device must be a valid VkDevice handle
pBindInfos must be a valid pointer to an array of bindInfoCount valid VkBindBufferMemoryInfo structures
bindInfoCount must be greater than 0

Return Codes

Success

VK_SUCCESS

Failure

VK_ERROR_OUT_OF_HOST_MEMORY
VK_ERROR_OUT_OF_DEVICE_MEMORY

VkBindBufferMemoryInfo contains members corresponding to the parameters of vkBindBufferMemory.

The VkBindBufferMemoryInfo structure is defined as:

typedef struct VkBindBufferMemoryInfo {
    VkStructureType    sType;
    const void*        pNext;
    VkBuffer           buffer;
    VkDeviceMemory     memory;
    VkDeviceSize       memoryOffset;
} VkBindBufferMemoryInfo;

or the equivalent

typedef VkBindBufferMemoryInfo VkBindBufferMemoryInfoKHR;

sType is the type of this structure.
pNext is NULL or a pointer to an extension-specific 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

buffer must not already be backed by a memory object
buffer must not have been created with any sparse memory binding flags
memoryOffset must be less than the size of memory
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
memoryOffset must be an integer multiple of the alignment member of the VkMemoryRequirements structure returned from a call to vkGetBufferMemoryRequirements with buffer
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
If buffer requires a dedicated allocation(as reported by vkGetBufferMemoryRequirements2 in VkMemoryDedicatedRequirements::requiresDedicatedAllocation for buffer), memory must have been created with VkMemoryDedicatedAllocateInfo::buffer equal to buffer and memoryOffset must be zero
If the VkMemoryAllocateInfo provided when memory was allocated included an instance of VkMemoryDedicatedAllocateInfo in its pNext chain, and VkMemoryDedicatedAllocateInfo::buffer was not VK_NULL_HANDLE, then buffer must equal VkMemoryDedicatedAllocateInfo::buffer and memoryOffset must be zero.
If buffer was created with VkDedicatedAllocationBufferCreateInfoNV::dedicatedAllocation equal to VK_TRUE, memory must have been created with VkDedicatedAllocationMemoryAllocateInfoNV::buffer equal to buffer and memoryOffset must be zero
If the pNext chain includes VkBindBufferMemoryDeviceGroupInfo, all instances of memory specified by VkBindBufferMemoryDeviceGroupInfo::pDeviceIndices must have been allocated

Valid Usage (Implicit)

sType must be VK_STRUCTURE_TYPE_BIND_BUFFER_MEMORY_INFO
pNext must be NULL or a pointer to a valid instance of VkBindBufferMemoryDeviceGroupInfo
buffer must be a valid VkBuffer handle
memory must be a valid VkDeviceMemory handle
Both of buffer, and memory must have been created, allocated, or retrieved from the same VkDevice

typedef struct VkBindBufferMemoryDeviceGroupInfo {
    VkStructureType    sType;
    const void*        pNext;
    uint32_t           deviceIndexCount;
    const uint32_t*    pDeviceIndices;
} VkBindBufferMemoryDeviceGroupInfo;

or the equivalent

typedef VkBindBufferMemoryDeviceGroupInfo VkBindBufferMemoryDeviceGroupInfoKHR;

If the pNext list of VkBindBufferMemoryInfo includes a VkBindBufferMemoryDeviceGroupInfo structure, then that structure determines how memory is bound to buffers across multiple devices in a device group.

The VkBindBufferMemoryDeviceGroupInfo structure is defined as:

sType is the type of this structure.
pNext is NULL or a pointer to an extension-specific structure.
deviceIndexCount is the number of elements in pDeviceIndices.
pDeviceIndices is a pointer to an array of device indices.

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

deviceIndexCount must either be zero or equal to the number of physical devices in the logical device
All elements of pDeviceIndices must be valid device indices

Valid Usage (Implicit)

sType must be VK_STRUCTURE_TYPE_BIND_BUFFER_MEMORY_DEVICE_GROUP_INFO
If deviceIndexCount is not 0, pDeviceIndices must be a valid pointer to an array of deviceIndexCount uint32_t values

To attach memory to a VkImage object created without the VK_IMAGE_CREATE_DISJOINT_BIT set, call:

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

image must not have been created with the VK_IMAGE_CREATE_DISJOINT_BIT set.
image must not already be backed by a memory object
image must not have been created with any sparse memory binding flags
memoryOffset must be less than the size of memory
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
memoryOffset must be an integer multiple of the alignment member of the VkMemoryRequirements structure returned from a call to vkGetImageMemoryRequirements with image
The size member of the VkMemoryRequirements structure returned from a call to vkGetImageMemoryRequirements with image must be less than or equal to the size of memory minus memoryOffset
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
If the dedicated allocation image aliasing feature is not enabled, and the VkMemoryAllocateInfo provided when memory was allocated included an instance of VkMemoryDedicatedAllocateInfo in its pNext chain, and VkMemoryDedicatedAllocateInfo::image was not VK_NULL_HANDLE, then image must equal VkMemoryDedicatedAllocateInfo::image and memoryOffset must be zero.
If the dedicated allocation image aliasing feature is enabled, and the VkMemoryAllocateInfo provided when memory was allocated included an instance of VkMemoryDedicatedAllocateInfo in its pNext chain, and VkMemoryDedicatedAllocateInfo::image was not VK_NULL_HANDLE, then memoryOffset must be zero, and image must be either equal to VkMemoryDedicatedAllocateInfo::image or an image that was created using the same parameters in VkImageCreateInfo, with the exception that extent and arrayLayers may differ subject to the following restrictions: every dimension in the extent parameter of the image being bound must be equal to or smaller than the original image for which the allocation was created; and the arrayLayers parameter of the image being bound must be equal to or smaller than the original image for which the allocation was created.
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
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
If image was created with VkDedicatedAllocationImageCreateInfoNV::dedicatedAllocation equal to VK_TRUE, memory must have been created with VkDedicatedAllocationMemoryAllocateInfoNV::image equal to an image handle created with identical creation parameters to image and memoryOffset must be zero
If memory was allocated with VkExportMemoryAllocateInfo::handleTypes not equal to 0, at least one handle type it contained must also have been set in VkExternalMemoryImageCreateInfo::handleTypes when image was created.
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.

Valid Usage (Implicit)

device must be a valid VkDevice handle
image must be a valid VkImage handle
memory must be a valid VkDeviceMemory handle
image must have been created, allocated, or retrieved from device
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:

VkResult vkBindImageMemory2(
    VkDevice                                    device,
    uint32_t                                    bindInfoCount,
    const VkBindImageMemoryInfo*                pBindInfos);

or the equivalent command

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 structures of type VkBindImageMemoryInfo, describing images and memory to bind.

On some implementations, it may be more efficient to batch memory bindings into a single command.

Valid Usage (Implicit)

device must be a valid VkDevice handle
pBindInfos must be a valid pointer to an array of bindInfoCount valid VkBindImageMemoryInfo structures
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:

typedef struct VkBindImageMemoryInfo {
    VkStructureType    sType;
    const void*        pNext;
    VkImage            image;
    VkDeviceMemory     memory;
    VkDeviceSize       memoryOffset;
} VkBindImageMemoryInfo;

or the equivalent

typedef VkBindImageMemoryInfo VkBindImageMemoryInfoKHR;

sType is the type of this structure.
pNext is NULL or a pointer to an extension-specific 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

image must not already be backed by a memory object
image must not have been created with any sparse memory binding flags
memoryOffset must be less than the size of memory
If the pNext chain does not include an instance of the 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
If the pNext chain does not include an instance of the VkBindImagePlaneMemoryInfo structure, memoryOffset must be an integer multiple of the alignment member of the VkMemoryRequirements structure returned from a call to vkGetImageMemoryRequirements2 with image
If the pNext chain does not include an instance of the 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
If the pNext chain includes an instance of the VkBindImagePlaneMemoryInfo structure, image must have been created with the VK_IMAGE_CREATE_DISJOINT_BIT bit set.
If the pNext chain includes an instance of the 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 the correct planeAspect for this plane in the VkImagePlaneMemoryRequirementsInfo structure attached to the VkImageMemoryRequirementsInfo2’s pNext chain
If the pNext chain includes an instance of the 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 the correct planeAspect for this plane in the VkImagePlaneMemoryRequirementsInfo structure attached to the VkImageMemoryRequirementsInfo2’s pNext chain
If the pNext chain includes an instance of the 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 the correct planeAspect for this plane in the VkImagePlaneMemoryRequirementsInfo structure attached to the VkImageMemoryRequirementsInfo2’s pNext chain
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 and memoryOffset must be zero
If the dedicated allocation image aliasing feature is not enabled, and the VkMemoryAllocateInfo provided when memory was allocated included an instance of VkMemoryDedicatedAllocateInfo in its pNext chain, and VkMemoryDedicatedAllocateInfo::image was not VK_NULL_HANDLE, then image must equal VkMemoryDedicatedAllocateInfo::image and memoryOffset must be zero.
If the dedicated allocation image aliasing feature is enabled, and the VkMemoryAllocateInfo provided when memory was allocated included an instance of VkMemoryDedicatedAllocateInfo in its pNext chain, and VkMemoryDedicatedAllocateInfo::image was not VK_NULL_HANDLE, then memoryOffset must be zero, and image must be either equal to VkMemoryDedicatedAllocateInfo::image or an image that was created using the same parameters in VkImageCreateInfo, with the exception that extent and arrayLayers may differ subject to the following restrictions: every dimension in the extent parameter of the image being bound must be equal to or smaller than the original image for which the allocation was created; and the arrayLayers parameter of the image being bound must be equal to or smaller than the original image for which the allocation was created.
If image was created with VkDedicatedAllocationImageCreateInfoNV::dedicatedAllocation equal to VK_TRUE, memory must have been created with VkDedicatedAllocationMemoryAllocateInfoNV::image equal to image and memoryOffset must be zero
If the pNext chain includes VkBindImageMemoryDeviceGroupInfo, all instances of memory specified by VkBindImageMemoryDeviceGroupInfo::pDeviceIndices must have been allocated
If the pNext chain includes VkBindImageMemoryDeviceGroupInfo, and VkBindImageMemoryDeviceGroupInfo::splitInstanceBindRegionCount is not zero, then image must have been created with the VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT bit set
If the pNext chain includes VkBindImageMemoryDeviceGroupInfo, all elements of VkBindImageMemoryDeviceGroupInfo::pSplitInstanceBindRegions must be valid rectangles contained within the dimensions of image
If the pNext chain includes VkBindImageMemoryDeviceGroupInfo, the union of the areas of all elements of VkBindImageMemoryDeviceGroupInfo::pSplitInstanceBindRegions that correspond to the same instance of image must cover the entire image.
If image was created with a valid swapchain handle in VkImageSwapchainCreateInfoKHR::swapchain, then the pNext chain must include a valid instance of VkBindImageMemorySwapchainInfoKHR
If the pNext chain includes an instance of VkBindImageMemorySwapchainInfoKHR, memory must be VK_NULL_HANDLE
If the pNext chain does not include an instance of VkBindImageMemorySwapchainInfoKHR, memory must be a valid VkDeviceMemory handle

Valid Usage (Implicit)

sType must be VK_STRUCTURE_TYPE_BIND_IMAGE_MEMORY_INFO
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, or VkBindImagePlaneMemoryInfo
Each sType member in the pNext chain must be unique
image must be a valid VkImage handle
Both of image, and memory that are valid handles must have been created, allocated, or retrieved from the same VkDevice

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

typedef VkBindImageMemoryDeviceGroupInfo VkBindImageMemoryDeviceGroupInfoKHR;

If the pNext list of VkBindImageMemoryInfo includes a VkBindImageMemoryDeviceGroupInfo structure, then that structure determines how memory is bound to images across multiple devices in a device group.

The VkBindImageMemoryDeviceGroupInfo structure is defined as:

sType is the type of this structure.
pNext is NULL or a pointer to an extension-specific 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 rectangles describing which regions of the image are attached to each instance of memory.

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

At least one of deviceIndexCount and splitInstanceBindRegionCount must be zero.
deviceIndexCount must either be zero or equal to the number of physical devices in the logical device
All elements of pDeviceIndices must be valid device indices.
splitInstanceBindRegionCount must either be zero or equal to the number of physical devices in the logical device squared
Elements of pSplitInstanceBindRegions that correspond to the same instance of an image must not overlap.
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
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
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
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 width of the image subresource

Valid Usage (Implicit)

sType must be VK_STRUCTURE_TYPE_BIND_IMAGE_MEMORY_DEVICE_GROUP_INFO
If deviceIndexCount is not 0, pDeviceIndices must be a valid pointer to an array of deviceIndexCount uint32_t values
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:

typedef struct VkBindImageMemorySwapchainInfoKHR {
    VkStructureType    sType;
    const void*        pNext;
    VkSwapchainKHR     swapchain;
    uint32_t           imageIndex;
} VkBindImageMemorySwapchainInfoKHR;

sType is the type of this structure.
pNext is NULL or a pointer to an extension-specific 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

imageIndex must be less than the number of images in swapchain

Valid Usage (Implicit)

sType must be VK_STRUCTURE_TYPE_BIND_IMAGE_MEMORY_SWAPCHAIN_INFO_KHR
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, include a VkBindImagePlaneMemoryInfo structure in the pNext chain of VkBindImageMemoryInfo.

The VkBindImagePlaneMemoryInfo structure is defined as:

typedef struct VkBindImagePlaneMemoryInfo {
    VkStructureType          sType;
    const void*              pNext;
    VkImageAspectFlagBits    planeAspect;
} VkBindImagePlaneMemoryInfo;

or the equivalent

typedef VkBindImagePlaneMemoryInfo VkBindImagePlaneMemoryInfoKHR;

sType is the type of this structure.
pNext is NULL or a pointer to an extension-specific structure.
planeAspect is the aspect of the disjoint image plane to bind.

Valid Usage

If the image’s tiling is VK_IMAGE_TILING_LINEAR or VK_IMAGE_TILING_OPTIMAL, then planeAspect must be a single valid format plane for the image. (That is, planeAspect must be VK_IMAGE_ASPECT_PLANE_0_BIT or VK_IMAGE_ASPECT_PLANE_1_BIT for “_2PLANE” formats and planeAspect must be VK_IMAGE_ASPECT_PLANE_0_BIT, VK_IMAGE_ASPECT_PLANE_1_BIT, or VK_IMAGE_ASPECT_PLANE_2_BIT for “_3PLANE” formats.)
If the image’s tiling is VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then planeAspect must be a single valid memory plane for the image. (That is, aspectMask must specify a plane index that is less than the drmFormatModifierPlaneCount associated with the image’s format and drmFormatModifier.)
A single call to vkBindImageMemory2 must bind all or none of the planes of an image (i.e. bindings to all planes of an image must be made in a single vkBindImageMemory2 call), as separate bindings

Valid Usage (Implicit)

sType must be VK_STRUCTURE_TYPE_BIND_IMAGE_PLANE_MEMORY_INFO
planeAspect must be a valid VkImageAspectFlagBits value

Buffer-Image Granularity

There is an implementation-dependent limit, bufferImageGranularity, which 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:

typedef enum VkSharingMode {
    VK_SHARING_MODE_EXCLUSIVE = 0,
    VK_SHARING_MODE_CONCURRENT = 1,
    VK_SHARING_MODE_MAX_ENUM = 0x7FFFFFFF
} 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. 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 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. 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.

11.8. 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 invididual 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.
If either image’s tiling is VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then both images must be linear.
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 a 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.

11.9. Acceleration Structures

Acceleration structures are an opaque structure that is 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 to trace inside the shader in the ray tracing pipeline.

Acceleration structures are represented by VkAccelerationStructureNV handles:

VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkAccelerationStructureNV)

To create acceleration structures, call:

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

device is the logical device that creates the buffer object.
pCreateInfo is a pointer to an instance of the VkAccelerationStructureCreateInfoNV structure containing parameters affecting creation of the acceleration structure.
pAllocator controls host memory allocation as described in the Memory Allocation chapter.
pAccelerationStructure points to a VkAccelerationStructureNV 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” as specified by the information in VkAccelerationStructureInfoNV and compactedSize in pCreateInfo. Populating the data in the object after allocating and binding memory is done with vkCmdBuildAccelerationStructureNV and vkCmdCopyAccelerationStructureNV.

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

Valid Usage (Implicit)

device must be a valid VkDevice handle
pCreateInfo must be a valid pointer to a valid VkAccelerationStructureCreateInfoNV structure
If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure
pAccelerationStructure must be a valid pointer to a VkAccelerationStructureNV handle

Return Codes

Success

VK_SUCCESS

Failure

VK_ERROR_OUT_OF_HOST_MEMORY

The VkAccelerationStructureCreateInfoNV structure is defined as:

typedef struct VkAccelerationStructureCreateInfoNV {
    VkStructureType                  sType;
    const void*                      pNext;
    VkDeviceSize                     compactedSize;
    VkAccelerationStructureInfoNV    info;
} VkAccelerationStructureCreateInfoNV;

sType is the type of this structure.
pNext is NULL or a pointer to an extension-specific structure.
compactedSize is the size from the result of vkCmdWriteAccelerationStructuresPropertiesNV if this acceleration structure is going to be the target of a compacting copy.
info is the VkAccelerationStructureInfoNV structure that specifies further parameters of the created acceleration structure.

Valid Usage

If compactedSize is not 0 then both info.geometryCount and info.instanceCount must be 0

Valid Usage (Implicit)

sType must be VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_CREATE_INFO_NV
pNext must be NULL
info must be a valid VkAccelerationStructureInfoNV structure

The VkAccelerationStructureInfoNV structure is defined as:

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

sType is the type of this structure.
pNext is NULL or a pointer to an extension-specific structure.
type is a VkAccelerationStructureTypeNV value specifying the type of acceleration structure that will be created.
flags is a bitmask of VkBuildAccelerationStructureFlagBitsNV specifying additional parameters of the acceleration structure.
instanceCount specifies the number of instances that will be in the new acceleration structure.
geometryCount specifies the number of geometries that will be in the new acceleration structure.
pGeometries is an array of VkGeometryNV structures, which contain the scene data being passed into the acceleration structure.

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

Valid Usage

geometryCount must be less than or equal to VkPhysicalDeviceRayTracingPropertiesNV::maxGeometryCount
instanceCount must be less than or equal to VkPhysicalDeviceRayTracingPropertiesNV::maxInstanceCount
The total number of triangles in all geometries must be less than or equal to VkPhysicalDeviceRayTracingPropertiesNV::maxTriangleCount
If type is VK_ACCELERATION_STRUCTURE_TYPE_TOP_LEVEL_NV then geometryCount must be 0
If type is VK_ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_NV then instanceCount must be 0
If flags has the VK_BUILD_ACCELERATION_STRUCTURE_PREFER_FAST_TRACE_BIT_NV bit set, then it must not have the VK_BUILD_ACCELERATION_STRUCTURE_PREFER_FAST_BUILD_BIT_NV bit set

Valid Usage (Implicit)

sType must be VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_INFO_NV
pNext must be NULL
type must be a valid VkAccelerationStructureTypeNV value
flags must be a valid combination of VkBuildAccelerationStructureFlagBitsNV values
If geometryCount is not 0, pGeometries must be a valid pointer to an array of geometryCount valid VkGeometryNV structures

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

typedef enum VkAccelerationStructureTypeNV {
    VK_ACCELERATION_STRUCTURE_TYPE_TOP_LEVEL_NV = 0,
    VK_ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_NV = 1,
    VK_ACCELERATION_STRUCTURE_TYPE_MAX_ENUM_NV = 0x7FFFFFFF
} VkAccelerationStructureTypeNV;

VK_ACCELERATION_STRUCTURE_TYPE_TOP_LEVEL_NV is a top-level acceleration structure containing instance data referring to bottom-level level acceleration structures.
VK_ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_NV is a bottom-level acceleration structure containing the AABBs or geometry to be intersected.

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

typedef enum VkBuildAccelerationStructureFlagBitsNV {
    VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_UPDATE_BIT_NV = 0x00000001,
    VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_COMPACTION_BIT_NV = 0x00000002,
    VK_BUILD_ACCELERATION_STRUCTURE_PREFER_FAST_TRACE_BIT_NV = 0x00000004,
    VK_BUILD_ACCELERATION_STRUCTURE_PREFER_FAST_BUILD_BIT_NV = 0x00000008,
    VK_BUILD_ACCELERATION_STRUCTURE_LOW_MEMORY_BIT_NV = 0x00000010,
    VK_BUILD_ACCELERATION_STRUCTURE_FLAG_BITS_MAX_ENUM_NV = 0x7FFFFFFF
} VkBuildAccelerationStructureFlagBitsNV;

VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_UPDATE_BIT_NV indicates that the specified acceleration structure can be updated with update of VK_TRUE in vkCmdBuildAccelerationStructureNV.
VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_COMPACTION_BIT_NV indicates that the specified acceleration structure can act as the source for vkCmdCopyAccelerationStructureNV with mode of VK_COPY_ACCELERATION_STRUCTURE_MODE_COMPACT_NV to produce a compacted acceleration structure.
VK_BUILD_ACCELERATION_STRUCTURE_PREFER_FAST_TRACE_BIT_NV indicates that the given acceleration structure build should prioritize trace performance over build time.
VK_BUILD_ACCELERATION_STRUCTURE_PREFER_FAST_BUILD_BIT_NV indicates that the given acceleration structure build should prioritize build time over trace performance.
VK_BUILD_ACCELERATION_STRUCTURE_LOW_MEMORY_BIT_NV indicates that this acceleration structure should minimize the size of the scratch memory and the final result build, potentially at the expense of build time or trace performance.

Note

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

typedef VkFlags VkBuildAccelerationStructureFlagsNV;

VkBuildAccelerationStructureFlagsNV is a bitmask type for setting a mask of zero or more VkBuildAccelerationStructureFlagBitsNV.

The VkGeometryNV structure is defined as:

typedef struct VkGeometryNV {
    VkStructureType      sType;
    const void*          pNext;
    VkGeometryTypeNV     geometryType;
    VkGeometryDataNV     geometry;
    VkGeometryFlagsNV    flags;
} VkGeometryNV;

sType is the type of this structure.
pNext is NULL or a pointer to an extension-specific structure.
geometryType describes which type of geometry this VkGeometryNV refers to.
geometry contains the geometry data as described in VkGeometryDataNV.
flags has flags describing options for this geometry.

Valid Usage (Implicit)

sType must be VK_STRUCTURE_TYPE_GEOMETRY_NV
pNext must be NULL
geometryType must be a valid VkGeometryTypeNV value
geometry must be a valid VkGeometryDataNV structure
flags must be a valid combination of VkGeometryFlagBitsNV values

Geometry types are specified by VkGeometryTypeNV, which takes values:

typedef enum VkGeometryTypeNV {
    VK_GEOMETRY_TYPE_TRIANGLES_NV = 0,
    VK_GEOMETRY_TYPE_AABBS_NV = 1,
    VK_GEOMETRY_TYPE_MAX_ENUM_NV = 0x7FFFFFFF
} VkGeometryTypeNV;

VK_GEOMETRY_TYPE_TRIANGLES_NV indicates that the triangles of VkGeometryDataNV contains valid data.
VK_GEOMETRY_TYPE_AABBS_NV indicates that the aabbs of VkGeometryDataNV contains valid data.

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

typedef enum VkGeometryFlagBitsNV {
    VK_GEOMETRY_OPAQUE_BIT_NV = 0x00000001,
    VK_GEOMETRY_NO_DUPLICATE_ANY_HIT_INVOCATION_BIT_NV = 0x00000002,
    VK_GEOMETRY_FLAG_BITS_MAX_ENUM_NV = 0x7FFFFFFF
} VkGeometryFlagBitsNV;

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

typedef VkFlags VkGeometryFlagsNV;

VkGeometryFlagsNV is a bitmask type for setting a mask of zero or more VkGeometryFlagBitsNV.

The VkGeometryDataNV structure is defined as:

typedef struct VkGeometryDataNV {
    VkGeometryTrianglesNV    triangles;
    VkGeometryAABBNV         aabbs;
} VkGeometryDataNV;

triangles contains triangle data if VkGeometryNV::geometryType is VK_GEOMETRY_TYPE_TRIANGLES_NV.
aabbs contains axis-aligned bounding box data if VkGeometryNV::geometryType is VK_GEOMETRY_TYPE_AABBS_NV.

Valid Usage (Implicit)

triangles must be a valid VkGeometryTrianglesNV structure
aabbs must be a valid VkGeometryAABBNV structure

The VkGeometryTrianglesNV structure is defined as:

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

sType is the type of this structure.
pNext is NULL or a pointer to an extension-specific structure.
vertexData is the buffer containing vertex data for this geometry.
vertexOffset is the offset in bytes within vertexData containing vertex data for this geometry.
vertexCount is the number of valid vertices.
vertexStride is the stride in bytes between each vertex.
vertexFormat is the format of each vertex element.
indexData is the buffer containing index data for this geometry.
indexOffset is the offset in bytes within indexData containing index data for this geometry.
indexCount is the number of indices to include in this geometry.
indexType is the format of each index.
transformData is a buffer containing optional reference to an array of 32-bit floats representing a 3x4 row major affine transformation matrix for this geometry.
transformOffset is the offset in bytes in transformData of the transform information described above.

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

Valid Usage

vertexOffset must be less than the size of vertexData
vertexOffset must be a multiple of the component size of vertexFormat
vertexFormat must be one of VK_FORMAT_R32G32B32_SFLOAT, VK_FORMAT_R32G32_SFLOAT, VK_FORMAT_R16G16B16_SFLOAT, VK_FORMAT_R16G16_SFLOAT, VK_FORMAT_R16G16_SNORM, or VK_FORMAT_R16G16B16_SNORM
indexOffset must be less than the size of indexData
indexOffset must be a multiple of the element size of indexType
indexType must be VK_INDEX_TYPE_UINT16, VK_INDEX_TYPE_UINT32, or VK_INDEX_TYPE_NONE_NV
indexData must be VK_NULL_HANDLE if indexType is VK_INDEX_TYPE_NONE_NV
indexData must be a valid VkBuffer handle if indexType is not VK_INDEX_TYPE_NONE_NV
indexCount must be 0 if indexType is VK_INDEX_TYPE_NONE_NV
transformOffset must be less than the size of transformData
transformOffset must be a multiple of 16

Valid Usage (Implicit)

sType must be VK_STRUCTURE_TYPE_GEOMETRY_TRIANGLES_NV
pNext must be NULL
If vertexData is not VK_NULL_HANDLE, vertexData must be a valid VkBuffer handle
vertexFormat must be a valid VkFormat value
If indexData is not VK_NULL_HANDLE, indexData must be a valid VkBuffer handle
indexType must be a valid VkIndexType value
If transformData is not VK_NULL_HANDLE, transformData must be a valid VkBuffer handle
Each of indexData, transformData, and vertexData that are valid handles must have been created, allocated, or retrieved from the same VkDevice

The VkGeometryAABBNV structure is defined as:

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

sType is the type of this structure.
pNext is NULL or a pointer to an extension-specific structure.
aabbData is the buffer containing axis-aligned bounding box data.
numAABBs is the number of AABBs in this geometry.
stride is the stride in bytes between AABBs in aabbData.
offset is the offset in bytes of the first AABB in aabbData.

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

Valid Usage

offset must be less than the size of aabbData
offset must be a multiple of 8
stride must be a multiple of 8

Valid Usage (Implicit)

sType must be VK_STRUCTURE_TYPE_GEOMETRY_AABB_NV
pNext must be NULL
If aabbData is not VK_NULL_HANDLE, aabbData must be a valid VkBuffer handle

To destroy an acceleration structure, call:

void vkDestroyAccelerationStructureNV(
    VkDevice                                    device,
    VkAccelerationStructureNV                   accelerationStructure,
    const VkAllocationCallbacks*                pAllocator);

device is the logical device that destroys the buffer.
accelerationStructure is the acceleration structure to destroy.
pAllocator controls host memory allocation as described in the Memory Allocation chapter.

Valid Usage

All submitted commands that refer to accelerationStructure must have completed execution
If VkAllocationCallbacks were provided when accelerationStructure was created, a compatible set of callbacks must be provided here
If no VkAllocationCallbacks were provided when accelerationStructure was created, pAllocator must be NULL

Valid Usage (Implicit)

device must be a valid VkDevice handle
accelerationStructure must be a valid VkAccelerationStructureNV handle
If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure
accelerationStructure must have been created, allocated, or retrieved from device

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

To query the memory requirements call:

void vkGetAccelerationStructureMemoryRequirementsNV(
    VkDevice                                    device,
    const VkAccelerationStructureMemoryRequirementsInfoNV* pInfo,
    VkMemoryRequirements2KHR*                   pMemoryRequirements);

device is the logical device on which the acceleration structure was created.
pInfo specifies the acceleration structure to get memory requirements for.
pMemoryRequirements returns the requested acceleration structure memory requirements.

Valid Usage (Implicit)

device must be a valid VkDevice handle
pInfo must be a valid pointer to a valid VkAccelerationStructureMemoryRequirementsInfoNV structure
pMemoryRequirements must be a valid pointer to a VkMemoryRequirements2KHR structure

The VkAccelerationStructureMemoryRequirementsInfoNV structure is defined as:

typedef struct VkAccelerationStructureMemoryRequirementsInfoNV {
    VkStructureType                                    sType;
    const void*                                        pNext;
    VkAccelerationStructureMemoryRequirementsTypeNV    type;
    VkAccelerationStructureNV                          accelerationStructure;
} VkAccelerationStructureMemoryRequirementsInfoNV;

sType is the type of this structure.
pNext is NULL or a pointer to an extension-specific structure.
type selects the type of memory requirement being queried. VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_OBJECT_NV returns the memory requirements for the object itself. VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_BUILD_SCRATCH_NV returns the memory requirements for the scratch memory when doing a build. VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_UPDATE_SCRATCH_NV returns the memory requirements for the scratch memory when doing an update.
accelerationStructure is the acceleration structure to be queried for memory requirements.

Valid Usage (Implicit)

sType must be VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_INFO_NV
pNext must be NULL
type must be a valid VkAccelerationStructureMemoryRequirementsTypeNV value
accelerationStructure must be a valid VkAccelerationStructureNV handle

Possible values of type in VkAccelerationStructureMemoryRequirementsInfoNV are:,

typedef enum VkAccelerationStructureMemoryRequirementsTypeNV {
    VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_OBJECT_NV = 0,
    VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_BUILD_SCRATCH_NV = 1,
    VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_UPDATE_SCRATCH_NV = 2,
    VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_MAX_ENUM_NV = 0x7FFFFFFF
} VkAccelerationStructureMemoryRequirementsTypeNV;

VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_OBJECT_NV requests the memory requirement for the VkAccelerationStructureNV backing store.
VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_BUILD_SCRATCH_NV requests the memory requirement for scratch space during the initial build.
VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_UPDATE_SCRATCH_NV requests the memory requirement for scratch space during an update.

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

VkResult vkBindAccelerationStructureMemoryNV(
    VkDevice                                    device,
    uint32_t                                    bindInfoCount,
    const VkBindAccelerationStructureMemoryInfoNV* pBindInfos);

device is the logical device that owns the acceleration structures and memory.
bindInfoCount is the number of elements in pBindInfos.
pBindInfos is a pointer to an array of structures of type VkBindAccelerationStructureMemoryInfoNV, describing images and memory to bind.

Valid Usage (Implicit)

device must be a valid VkDevice handle
pBindInfos must be a valid pointer to an array of bindInfoCount valid VkBindAccelerationStructureMemoryInfoNV structures
bindInfoCount must be greater than 0

Return Codes

Success

VK_SUCCESS

Failure

VK_ERROR_OUT_OF_HOST_MEMORY
VK_ERROR_OUT_OF_DEVICE_MEMORY

The VkBindAccelerationStructureMemoryInfoNV structure is defined as:

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

sType is the type of this structure.
pNext is NULL or a pointer to an extension-specific structure.
accelerationStructure is the acceleration structure to be attached to memory.
memory is a VkDeviceMemory object describing the device memory to attach.
memoryOffset is the start offset of the region of memory that is to be bound to the acceleration structure. The number of bytes returned in the VkMemoryRequirements::size member in memory, starting from memoryOffset bytes, will be bound to the specified acceleration structure.
deviceIndexCount is the number of elements in pDeviceIndices.
pDeviceIndices is a pointer to an array of device indices.

Valid Usage

accelerationStructure must not already be backed by a memory object
memoryOffset must be less than the size of memory
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 vkGetAccelerationStructureMemoryRequirementsNV with accelerationStructure and type of VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_OBJECT_NV
memoryOffset must be an integer multiple of the alignment member of the VkMemoryRequirements structure returned from a call to vkGetAccelerationStructureMemoryRequirementsNV with accelerationStructure and type of VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_OBJECT_NV
The size member of the VkMemoryRequirements structure returned from a call to vkGetAccelerationStructureMemoryRequirementsNV with accelerationStructure and type of VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_OBJECT_NV must be less than or equal to the size of memory minus memoryOffset

Valid Usage (Implicit)

sType must be VK_STRUCTURE_TYPE_BIND_ACCELERATION_STRUCTURE_MEMORY_INFO_NV
pNext must be NULL
accelerationStructure must be a valid VkAccelerationStructureNV handle
memory must be a valid VkDeviceMemory handle
If deviceIndexCount is not 0, pDeviceIndices must be a valid pointer to an array of deviceIndexCount uint32_t values
Both of accelerationStructure, and memory must have been created, allocated, or retrieved from the same VkDevice

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

VkResult vkGetAccelerationStructureHandleNV(
    VkDevice                                    device,
    VkAccelerationStructureNV                   accelerationStructure,
    size_t                                      dataSize,
    void*                                       pData);

device is the logical device that owns the acceleration structures.
accelerationStructure is the acceleration structure.
dataSize is the size in bytes of the buffer pointed to by pData.
pData is a pointer to a user-allocated buffer where the results will be written.

Valid Usage

dataSize must be large enough to contain the result of the query, as described above

Valid Usage (Implicit)

device must be a valid VkDevice handle
accelerationStructure must be a valid VkAccelerationStructureNV handle
pData must be a valid pointer to an array of dataSize bytes
dataSize must be greater than 0
accelerationStructure must have been created, allocated, or retrieved from device

Return Codes

Success

VK_SUCCESS

Failure

VK_ERROR_OUT_OF_HOST_MEMORY
VK_ERROR_OUT_OF_DEVICE_MEMORY

Vulkan® 1.1.114 - A Specification (with all published extensions)

11. Resource Creation

11.1. Buffers

11.2. Buffer Views

11.3. Images

11.3.1. Image Format Features

11.3.2. Corner-Sampled Images

11.3.3. Image Miplevel Sizing

Conventional Images

Corner-Sampled Images

11.4. Image Layouts

11.4.1. Image Layout Matching Rules

11.5. Image Views

11.5.1. Image View Format Features

11.6. Resource Memory Association

11.7. Resource Sharing Mode

11.7.1. External Resource Sharing

11.8. Memory Aliasing

11.9. Acceleration Structures

Vulkan^® 1.1.114 - A Specification (with all published extensions)