Copy Commands

An application can copy buffer and image data using several methods described in this chapter, depending on the type of data transfer.

All copy commands are treated as “transfer” operations for the purposes of synchronization barriers.

All copy commands that have a source format with an X component in its format description read undefined values from those bits.

All copy commands that have a destination format with an X component in its format description write undefined values to those bits.

Copying Data Between Buffers

To copy data between buffer objects, call:

// Provided by VK_VERSION_1_0
void vkCmdCopyBuffer(
    VkCommandBuffer                             commandBuffer,
    VkBuffer                                    srcBuffer,
    VkBuffer                                    dstBuffer,
    uint32_t                                    regionCount,
    const VkBufferCopy*                         pRegions);
  • commandBuffer is the command buffer into which the command will be recorded.

  • srcBuffer is the source buffer.

  • dstBuffer is the destination buffer.

  • regionCount is the number of regions to copy.

  • pRegions is a pointer to an array of VkBufferCopy structures specifying the regions to copy.

Each source region specified by pRegions is copied from the source buffer to the destination region of the destination buffer. If any of the specified regions in srcBuffer overlaps in memory with any of the specified regions in dstBuffer, values read from those overlapping regions are undefined.

Valid Usage
  • VUID-vkCmdCopyBuffer-commandBuffer-01822
    If commandBuffer is an unprotected command buffer and protectedNoFault is not supported, srcBuffer must not be a protected buffer

  • VUID-vkCmdCopyBuffer-commandBuffer-01823
    If commandBuffer is an unprotected command buffer and protectedNoFault is not supported, dstBuffer must not be a protected buffer

  • VUID-vkCmdCopyBuffer-commandBuffer-01824
    If commandBuffer is a protected command buffer and protectedNoFault is not supported, dstBuffer must not be an unprotected buffer

  • VUID-vkCmdCopyBuffer-srcOffset-00113
    The srcOffset member of each element of pRegions must be less than the size of srcBuffer

  • VUID-vkCmdCopyBuffer-dstOffset-00114
    The dstOffset member of each element of pRegions must be less than the size of dstBuffer

  • VUID-vkCmdCopyBuffer-size-00115
    The size member of each element of pRegions must be less than or equal to the size of srcBuffer minus srcOffset

  • VUID-vkCmdCopyBuffer-size-00116
    The size member of each element of pRegions must be less than or equal to the size of dstBuffer minus dstOffset

  • VUID-vkCmdCopyBuffer-pRegions-00117
    The union of the source regions, and the union of the destination regions, specified by the elements of pRegions, must not overlap in memory

  • VUID-vkCmdCopyBuffer-srcBuffer-00118
    srcBuffer must have been created with VK_BUFFER_USAGE_TRANSFER_SRC_BIT usage flag

  • VUID-vkCmdCopyBuffer-srcBuffer-00119
    If srcBuffer is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-vkCmdCopyBuffer-dstBuffer-00120
    dstBuffer must have been created with VK_BUFFER_USAGE_TRANSFER_DST_BIT usage flag

  • VUID-vkCmdCopyBuffer-dstBuffer-00121
    If dstBuffer is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

Valid Usage (Implicit)
  • VUID-vkCmdCopyBuffer-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdCopyBuffer-srcBuffer-parameter
    srcBuffer must be a valid VkBuffer handle

  • VUID-vkCmdCopyBuffer-dstBuffer-parameter
    dstBuffer must be a valid VkBuffer handle

  • VUID-vkCmdCopyBuffer-pRegions-parameter
    pRegions must be a valid pointer to an array of regionCount valid VkBufferCopy structures

  • VUID-vkCmdCopyBuffer-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdCopyBuffer-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support transfer, graphics, or compute operations

  • VUID-vkCmdCopyBuffer-renderpass
    This command must only be called outside of a render pass instance

  • VUID-vkCmdCopyBuffer-videocoding
    This command must only be called outside of a video coding scope

  • VUID-vkCmdCopyBuffer-regionCount-arraylength
    regionCount must be greater than 0

  • VUID-vkCmdCopyBuffer-commonparent
    Each of commandBuffer, dstBuffer, and srcBuffer must have been created, allocated, or retrieved from the same VkDevice

Host Synchronization
  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type

Primary
Secondary

Outside

Outside

Transfer
Graphics
Compute

Action

The VkBufferCopy structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkBufferCopy {
    VkDeviceSize    srcOffset;
    VkDeviceSize    dstOffset;
    VkDeviceSize    size;
} VkBufferCopy;
  • srcOffset is the starting offset in bytes from the start of srcBuffer.

  • dstOffset is the starting offset in bytes from the start of dstBuffer.

  • size is the number of bytes to copy.

Valid Usage
  • VUID-VkBufferCopy-size-01988
    The size must be greater than 0

A more extensible version of the copy buffer command is defined below.

To copy data between buffer objects, call:

// Provided by VK_VERSION_1_3
void vkCmdCopyBuffer2(
    VkCommandBuffer                             commandBuffer,
    const VkCopyBufferInfo2*                    pCopyBufferInfo);

or the equivalent command

// Provided by VK_KHR_copy_commands2
void vkCmdCopyBuffer2KHR(
    VkCommandBuffer                             commandBuffer,
    const VkCopyBufferInfo2*                    pCopyBufferInfo);
  • commandBuffer is the command buffer into which the command will be recorded.

  • pCopyBufferInfo is a pointer to a VkCopyBufferInfo2 structure describing the copy parameters.

Each source region specified by pCopyBufferInfo->pRegions is copied from the source buffer to the destination region of the destination buffer. If any of the specified regions in pCopyBufferInfo->srcBuffer overlaps in memory with any of the specified regions in pCopyBufferInfo->dstBuffer, values read from those overlapping regions are undefined.

Valid Usage
  • VUID-vkCmdCopyBuffer2-commandBuffer-01822
    If commandBuffer is an unprotected command buffer and protectedNoFault is not supported, srcBuffer must not be a protected buffer

  • VUID-vkCmdCopyBuffer2-commandBuffer-01823
    If commandBuffer is an unprotected command buffer and protectedNoFault is not supported, dstBuffer must not be a protected buffer

  • VUID-vkCmdCopyBuffer2-commandBuffer-01824
    If commandBuffer is a protected command buffer and protectedNoFault is not supported, dstBuffer must not be an unprotected buffer

Valid Usage (Implicit)
  • VUID-vkCmdCopyBuffer2-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdCopyBuffer2-pCopyBufferInfo-parameter
    pCopyBufferInfo must be a valid pointer to a valid VkCopyBufferInfo2 structure

  • VUID-vkCmdCopyBuffer2-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdCopyBuffer2-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support transfer, graphics, or compute operations

  • VUID-vkCmdCopyBuffer2-renderpass
    This command must only be called outside of a render pass instance

  • VUID-vkCmdCopyBuffer2-videocoding
    This command must only be called outside of a video coding scope

Host Synchronization
  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type

Primary
Secondary

Outside

Outside

Transfer
Graphics
Compute

Action

The VkCopyBufferInfo2 structure is defined as:

// Provided by VK_VERSION_1_3
typedef struct VkCopyBufferInfo2 {
    VkStructureType         sType;
    const void*             pNext;
    VkBuffer                srcBuffer;
    VkBuffer                dstBuffer;
    uint32_t                regionCount;
    const VkBufferCopy2*    pRegions;
} VkCopyBufferInfo2;

or the equivalent

// Provided by VK_KHR_copy_commands2
typedef VkCopyBufferInfo2 VkCopyBufferInfo2KHR;
  • sType is a VkStructureType value identifying this structure.

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

  • srcBuffer is the source buffer.

  • dstBuffer is the destination buffer.

  • regionCount is the number of regions to copy.

  • pRegions is a pointer to an array of VkBufferCopy2 structures specifying the regions to copy.

Valid Usage
  • VUID-VkCopyBufferInfo2-srcOffset-00113
    The srcOffset member of each element of pRegions must be less than the size of srcBuffer

  • VUID-VkCopyBufferInfo2-dstOffset-00114
    The dstOffset member of each element of pRegions must be less than the size of dstBuffer

  • VUID-VkCopyBufferInfo2-size-00115
    The size member of each element of pRegions must be less than or equal to the size of srcBuffer minus srcOffset

  • VUID-VkCopyBufferInfo2-size-00116
    The size member of each element of pRegions must be less than or equal to the size of dstBuffer minus dstOffset

  • VUID-VkCopyBufferInfo2-pRegions-00117
    The union of the source regions, and the union of the destination regions, specified by the elements of pRegions, must not overlap in memory

  • VUID-VkCopyBufferInfo2-srcBuffer-00118
    srcBuffer must have been created with VK_BUFFER_USAGE_TRANSFER_SRC_BIT usage flag

  • VUID-VkCopyBufferInfo2-srcBuffer-00119
    If srcBuffer is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-VkCopyBufferInfo2-dstBuffer-00120
    dstBuffer must have been created with VK_BUFFER_USAGE_TRANSFER_DST_BIT usage flag

  • VUID-VkCopyBufferInfo2-dstBuffer-00121
    If dstBuffer is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

Valid Usage (Implicit)
  • VUID-VkCopyBufferInfo2-sType-sType
    sType must be VK_STRUCTURE_TYPE_COPY_BUFFER_INFO_2

  • VUID-VkCopyBufferInfo2-pNext-pNext
    pNext must be NULL

  • VUID-VkCopyBufferInfo2-srcBuffer-parameter
    srcBuffer must be a valid VkBuffer handle

  • VUID-VkCopyBufferInfo2-dstBuffer-parameter
    dstBuffer must be a valid VkBuffer handle

  • VUID-VkCopyBufferInfo2-pRegions-parameter
    pRegions must be a valid pointer to an array of regionCount valid VkBufferCopy2 structures

  • VUID-VkCopyBufferInfo2-regionCount-arraylength
    regionCount must be greater than 0

  • VUID-VkCopyBufferInfo2-commonparent
    Both of dstBuffer, and srcBuffer must have been created, allocated, or retrieved from the same VkDevice

The VkBufferCopy2 structure is defined as:

// Provided by VK_VERSION_1_3
typedef struct VkBufferCopy2 {
    VkStructureType    sType;
    const void*        pNext;
    VkDeviceSize       srcOffset;
    VkDeviceSize       dstOffset;
    VkDeviceSize       size;
} VkBufferCopy2;

or the equivalent

// Provided by VK_KHR_copy_commands2
typedef VkBufferCopy2 VkBufferCopy2KHR;
  • sType is a VkStructureType value identifying this structure.

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

  • srcOffset is the starting offset in bytes from the start of srcBuffer.

  • dstOffset is the starting offset in bytes from the start of dstBuffer.

  • size is the number of bytes to copy.

Valid Usage
  • VUID-VkBufferCopy2-size-01988
    The size must be greater than 0

Valid Usage (Implicit)
  • VUID-VkBufferCopy2-sType-sType
    sType must be VK_STRUCTURE_TYPE_BUFFER_COPY_2

  • VUID-VkBufferCopy2-pNext-pNext
    pNext must be NULL

Copying Data Between Images

To copy data between image objects, call:

// Provided by VK_VERSION_1_0
void vkCmdCopyImage(
    VkCommandBuffer                             commandBuffer,
    VkImage                                     srcImage,
    VkImageLayout                               srcImageLayout,
    VkImage                                     dstImage,
    VkImageLayout                               dstImageLayout,
    uint32_t                                    regionCount,
    const VkImageCopy*                          pRegions);
  • commandBuffer is the command buffer into which the command will be recorded.

  • srcImage is the source image.

  • srcImageLayout is the current layout of the source image subresource.

  • dstImage is the destination image.

  • dstImageLayout is the current layout of the destination image subresource.

  • regionCount is the number of regions to copy.

  • pRegions is a pointer to an array of VkImageCopy structures specifying the regions to copy.

Each source region specified by pRegions is copied from the source image to the destination region of the destination image. If any of the specified regions in srcImage overlaps in memory with any of the specified regions in dstImage, values read from those overlapping regions are undefined.

Multi-planar images can only be copied on a per-plane basis, and the subresources used in each region when copying to or from such images must specify only one plane, though different regions can specify different planes. When copying planes of multi-planar images, the format considered is the compatible format for that plane, rather than the format of the multi-planar image.

If the format of the destination image has a different block extent than the source image (e.g. one is a compressed format), the offset and extent for each of the regions specified is scaled according to the block extents of each format to match in size. Copy regions for each image must be aligned to a multiple of the texel block extent in each dimension, except at the edges of the image, where region extents must match the edge of the image.

Image data can be copied between images with different image types. If one image is VK_IMAGE_TYPE_3D and the other image is VK_IMAGE_TYPE_2D with multiple layers, then each slice is copied to or from a different layer; depth slices in the 3D image correspond to layerCount layers in the 2D image, with an effective depth of 1 used for the 2D image. If maintenance5 is enabled, all other combinations are allowed and function as if 1D images are 2D images with a height of 1. Otherwise, other combinations of image types are disallowed.

Valid Usage
  • VUID-vkCmdCopyImage-commandBuffer-01825
    If commandBuffer is an unprotected command buffer and protectedNoFault is not supported, srcImage must not be a protected image

  • VUID-vkCmdCopyImage-commandBuffer-01826
    If commandBuffer is an unprotected command buffer and protectedNoFault is not supported, dstImage must not be a protected image

  • VUID-vkCmdCopyImage-commandBuffer-01827
    If commandBuffer is a protected command buffer and protectedNoFault is not supported, dstImage must not be an unprotected image

  • VUID-vkCmdCopyImage-pRegions-00124
    The union of all source regions, and the union of all destination regions, specified by the elements of pRegions, must not overlap in memory

  • VUID-vkCmdCopyImage-srcImage-01995
    The format features of srcImage must contain VK_FORMAT_FEATURE_TRANSFER_SRC_BIT

  • VUID-vkCmdCopyImage-srcImageLayout-00128
    srcImageLayout must specify the layout of the image subresources of srcImage specified in pRegions at the time this command is executed on a VkDevice

  • VUID-vkCmdCopyImage-srcImageLayout-01917
    srcImageLayout must be VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR, VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL, or VK_IMAGE_LAYOUT_GENERAL

  • VUID-vkCmdCopyImage-srcImage-09460
    If srcImage and dstImage are the same, and any elements of pRegions contains the srcSubresource and dstSubresource with matching mipLevel and overlapping array layers, then the srcImageLayout and dstImageLayout must be VK_IMAGE_LAYOUT_GENERAL or VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR

  • VUID-vkCmdCopyImage-dstImage-01996
    The format features of dstImage must contain VK_FORMAT_FEATURE_TRANSFER_DST_BIT

  • VUID-vkCmdCopyImage-dstImageLayout-00133
    dstImageLayout must specify the layout of the image subresources of dstImage specified in pRegions at the time this command is executed on a VkDevice

  • VUID-vkCmdCopyImage-dstImageLayout-01395
    dstImageLayout must be VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR, VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL, or VK_IMAGE_LAYOUT_GENERAL

  • VUID-vkCmdCopyImage-srcImage-01548
    If the VkFormat of each of srcImage and dstImage is not a multi-planar format, the VkFormat of each of srcImage and dstImage must be size-compatible

  • VUID-vkCmdCopyImage-None-01549
    In a copy to or from a plane of a multi-planar image, the VkFormat of the image and plane must be compatible according to the description of compatible planes for the plane being copied

  • VUID-vkCmdCopyImage-srcImage-09247
    If the VkFormat of each of srcImage and dstImage is a compressed image format, the formats must have the same texel block extent

  • VUID-vkCmdCopyImage-srcImage-00136
    The sample count of srcImage and dstImage must match

  • VUID-vkCmdCopyImage-srcOffset-01783
    The srcOffset and extent members of each element of pRegions must respect the image transfer granularity requirements of commandBuffer’s command pool’s queue family, as described in VkQueueFamilyProperties

  • VUID-vkCmdCopyImage-dstOffset-01784
    The dstOffset and extent members of each element of pRegions must respect the image transfer granularity requirements of commandBuffer’s command pool’s queue family, as described in VkQueueFamilyProperties

  • VUID-vkCmdCopyImage-srcImage-01551
    If neither srcImage nor dstImage has a multi-planar image format then for each element of pRegions, srcSubresource.aspectMask and dstSubresource.aspectMask must match

  • VUID-vkCmdCopyImage-srcImage-08713
    If srcImage has a multi-planar image format, then for each element of pRegions, srcSubresource.aspectMask must be a single valid multi-planar aspect mask bit

  • VUID-vkCmdCopyImage-dstImage-08714
    If dstImage has a multi-planar image format, then for each element of pRegions, dstSubresource.aspectMask must be a single valid multi-planar aspect mask bit

  • VUID-vkCmdCopyImage-srcImage-01556
    If srcImage has a multi-planar image format and the dstImage does not have a multi-planar image format, then for each element of pRegions, dstSubresource.aspectMask must be VK_IMAGE_ASPECT_COLOR_BIT

  • VUID-vkCmdCopyImage-dstImage-01557
    If dstImage has a multi-planar image format and the srcImage does not have a multi-planar image format, then for each element of pRegions, srcSubresource.aspectMask must be VK_IMAGE_ASPECT_COLOR_BIT

  • VUID-vkCmdCopyImage-apiVersion-07932
    If the VK_KHR_maintenance1 extension is not enabled, or VkPhysicalDeviceProperties::apiVersion is less than Vulkan 1.1, and either srcImage or dstImage is of type VK_IMAGE_TYPE_3D, then for each element of pRegions, srcSubresource.baseArrayLayer and dstSubresource.baseArrayLayer must both be 0, and srcSubresource.layerCount and dstSubresource.layerCount must both be 1

  • VUID-vkCmdCopyImage-srcImage-04443
    If srcImage is of type VK_IMAGE_TYPE_3D, then for each element of pRegions, srcSubresource.baseArrayLayer must be 0 and srcSubresource.layerCount must be 1

  • VUID-vkCmdCopyImage-dstImage-04444
    If dstImage is of type VK_IMAGE_TYPE_3D, then for each element of pRegions, dstSubresource.baseArrayLayer must be 0 and dstSubresource.layerCount must be 1

  • VUID-vkCmdCopyImage-aspectMask-00142
    For each element of pRegions, srcSubresource.aspectMask must specify aspects present in srcImage

  • VUID-vkCmdCopyImage-aspectMask-00143
    For each element of pRegions, dstSubresource.aspectMask must specify aspects present in dstImage

  • VUID-vkCmdCopyImage-srcOffset-00144
    For each element of pRegions, srcOffset.x and (extent.width + srcOffset.x) must both be greater than or equal to 0 and less than or equal to the width of the specified srcSubresource of srcImage

  • VUID-vkCmdCopyImage-srcOffset-00145
    For each element of pRegions, srcOffset.y and (extent.height + srcOffset.y) must both be greater than or equal to 0 and less than or equal to the height of the specified srcSubresource of srcImage

  • VUID-vkCmdCopyImage-srcImage-00146
    If srcImage is of type VK_IMAGE_TYPE_1D, then for each element of pRegions, srcOffset.y must be 0 and extent.height must be 1

  • VUID-vkCmdCopyImage-srcOffset-00147
    If srcImage is of type VK_IMAGE_TYPE_3D, then for each element of pRegions, srcOffset.z and (extent.depth + srcOffset.z) must both be greater than or equal to 0 and less than or equal to the depth of the specified srcSubresource of srcImage

  • VUID-vkCmdCopyImage-srcImage-01785
    If srcImage is of type VK_IMAGE_TYPE_1D, then for each element of pRegions, srcOffset.z must be 0 and extent.depth must be 1

  • VUID-vkCmdCopyImage-dstImage-01786
    If dstImage is of type VK_IMAGE_TYPE_1D, then for each element of pRegions, dstOffset.z must be 0 and extent.depth must be 1

  • VUID-vkCmdCopyImage-srcImage-01787
    If srcImage is of type VK_IMAGE_TYPE_2D, then for each element of pRegions, srcOffset.z must be 0

  • VUID-vkCmdCopyImage-dstImage-01788
    If dstImage is of type VK_IMAGE_TYPE_2D, then for each element of pRegions, dstOffset.z must be 0

  • VUID-vkCmdCopyImage-apiVersion-07933
    If the VK_KHR_maintenance1 extension is not enabled, and VkPhysicalDeviceProperties::apiVersion is less than Vulkan 1.1, srcImage and dstImage must have the same VkImageType

  • VUID-vkCmdCopyImage-apiVersion-08969
    If the VK_KHR_maintenance1 extension is not enabled, and VkPhysicalDeviceProperties::apiVersion is less than Vulkan 1.1, srcImage or dstImage is of type VK_IMAGE_TYPE_2D, then for each element of pRegions, extent.depth must be 1

  • VUID-vkCmdCopyImage-srcImage-07743
    If srcImage and dstImage have a different VkImageType, and maintenance5 is not enabled, one must be VK_IMAGE_TYPE_3D and the other must be VK_IMAGE_TYPE_2D

  • VUID-vkCmdCopyImage-srcImage-08793
    If srcImage and dstImage have the same VkImageType, for each element of pRegions, if neither of the layerCount members of srcSubresource or dstSubresource are VK_REMAINING_ARRAY_LAYERS, the layerCount members of srcSubresource or dstSubresource must match

  • VUID-vkCmdCopyImage-srcImage-08794
    If srcImage and dstImage have the same VkImageType, and one of the layerCount members of srcSubresource or dstSubresource is VK_REMAINING_ARRAY_LAYERS, the other member must be either VK_REMAINING_ARRAY_LAYERS or equal to the arrayLayers member of the VkImageCreateInfo used to create the image minus baseArrayLayer

  • VUID-vkCmdCopyImage-srcImage-01790
    If srcImage and dstImage are both of type VK_IMAGE_TYPE_2D, then for each element of pRegions, extent.depth must be 1

  • VUID-vkCmdCopyImage-srcImage-01791
    If srcImage is of type VK_IMAGE_TYPE_2D, and dstImage is of type VK_IMAGE_TYPE_3D, then for each element of pRegions, extent.depth must equal srcSubresource.layerCount

  • VUID-vkCmdCopyImage-dstImage-01792
    If dstImage is of type VK_IMAGE_TYPE_2D, and srcImage is of type VK_IMAGE_TYPE_3D, then for each element of pRegions, extent.depth must equal dstSubresource.layerCount

  • VUID-vkCmdCopyImage-dstOffset-00150
    For each element of pRegions, dstOffset.x and (extent.width + dstOffset.x) must both be greater than or equal to 0 and less than or equal to the width of the specified dstSubresource of dstImage

  • VUID-vkCmdCopyImage-dstOffset-00151
    For each element of pRegions, dstOffset.y and (extent.height + dstOffset.y) must both be greater than or equal to 0 and less than or equal to the height of the specified dstSubresource of dstImage

  • VUID-vkCmdCopyImage-dstImage-00152
    If dstImage is of type VK_IMAGE_TYPE_1D, then for each element of pRegions, dstOffset.y must be 0 and extent.height must be 1

  • VUID-vkCmdCopyImage-dstOffset-00153
    If dstImage is of type VK_IMAGE_TYPE_3D, then for each element of pRegions, dstOffset.z and (extent.depth + dstOffset.z) must both be greater than or equal to 0 and less than or equal to the depth of the specified dstSubresource of dstImage

  • VUID-vkCmdCopyImage-pRegions-07278
    For each element of pRegions, srcOffset.x must be a multiple of the texel block extent width of the VkFormat of srcImage

  • VUID-vkCmdCopyImage-pRegions-07279
    For each element of pRegions, srcOffset.y must be a multiple of the texel block extent height of the VkFormat of srcImage

  • VUID-vkCmdCopyImage-pRegions-07280
    For each element of pRegions, srcOffset.z must be a multiple of the texel block extent depth of the VkFormat of srcImage

  • VUID-vkCmdCopyImage-pRegions-07281
    For each element of pRegions, dstOffset.x must be a multiple of the texel block extent width of the VkFormat of dstImage

  • VUID-vkCmdCopyImage-pRegions-07282
    For each element of pRegions, dstOffset.y must be a multiple of the texel block extent height of the VkFormat of dstImage

  • VUID-vkCmdCopyImage-pRegions-07283
    For each element of pRegions, dstOffset.z must be a multiple of the texel block extent depth of the VkFormat of dstImage

  • VUID-vkCmdCopyImage-srcImage-01728
    For each element of pRegions, if the sum of srcOffset.x and extent.width does not equal the width of the subresource specified by srcSubresource, extent.width must be a multiple of the texel block extent width of the VkFormat of srcImage

  • VUID-vkCmdCopyImage-srcImage-01729
    For each element of pRegions, if the sum of srcOffset.y and extent.height does not equal the height of the subresource specified by srcSubresource, extent.height must be a multiple of the texel block extent height of the VkFormat of srcImage

  • VUID-vkCmdCopyImage-srcImage-01730
    For each element of pRegions, if the sum of srcOffset.z and extent.depth does not equal the depth of the subresource specified by srcSubresource, extent.depth must be a multiple of the texel block extent depth of the VkFormat of srcImage

  • VUID-vkCmdCopyImage-dstImage-01732
    For each element of pRegions, if the sum of dstOffset.x and extent.width does not equal the width of the subresource specified by dstSubresource, extent.width must be a multiple of the texel block extent width of the VkFormat of dstImage

  • VUID-vkCmdCopyImage-dstImage-01733
    For each element of pRegions, if the sum of dstOffset.y and extent.height does not equal the height of the subresource specified by dstSubresource, extent.height must be a multiple of the texel block extent height of the VkFormat of dstImage

  • VUID-vkCmdCopyImage-dstImage-01734
    For each element of pRegions, if the sum of dstOffset.z and extent.depth does not equal the depth of the subresource specified by dstSubresource, extent.depth must be a multiple of the texel block extent depth of the VkFormat of dstImage

  • VUID-vkCmdCopyImage-aspect-06662
    If the aspect member of any element of pRegions includes any flag other than VK_IMAGE_ASPECT_STENCIL_BIT or srcImage was not created with separate stencil usage, VK_IMAGE_USAGE_TRANSFER_SRC_BIT must have been included in the VkImageCreateInfo::usage used to create srcImage

  • VUID-vkCmdCopyImage-aspect-06663
    If the aspect member of any element of pRegions includes any flag other than VK_IMAGE_ASPECT_STENCIL_BIT or dstImage was not created with separate stencil usage, VK_IMAGE_USAGE_TRANSFER_DST_BIT must have been included in the VkImageCreateInfo::usage used to create dstImage

  • VUID-vkCmdCopyImage-aspect-06664
    If the aspect member of any element of pRegions includes VK_IMAGE_ASPECT_STENCIL_BIT, and srcImage was created with separate stencil usage, VK_IMAGE_USAGE_TRANSFER_SRC_BIT must have been included in the VkImageStencilUsageCreateInfo::stencilUsage used to create srcImage

  • VUID-vkCmdCopyImage-aspect-06665
    If the aspect member of any element of pRegions includes VK_IMAGE_ASPECT_STENCIL_BIT, and dstImage was created with separate stencil usage, VK_IMAGE_USAGE_TRANSFER_DST_BIT must have been included in the VkImageStencilUsageCreateInfo::stencilUsage used to create dstImage

  • VUID-vkCmdCopyImage-srcImage-07966
    If srcImage is non-sparse then the image or the specified disjoint plane must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-vkCmdCopyImage-srcSubresource-07967
    The srcSubresource.mipLevel member of each element of pRegions must be less than the mipLevels specified in VkImageCreateInfo when srcImage was created

  • VUID-vkCmdCopyImage-srcSubresource-07968
    If srcSubresource.layerCount is not VK_REMAINING_ARRAY_LAYERS, srcSubresource.baseArrayLayer + srcSubresource.layerCount of each element of pRegions must be less than or equal to the arrayLayers specified in VkImageCreateInfo when srcImage was created

  • VUID-vkCmdCopyImage-srcImage-07969
    srcImage must not have been created with flags containing VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT

  • VUID-vkCmdCopyImage-dstImage-07966
    If dstImage is non-sparse then the image or the specified disjoint plane must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-vkCmdCopyImage-dstSubresource-07967
    The dstSubresource.mipLevel member of each element of pRegions must be less than the mipLevels specified in VkImageCreateInfo when dstImage was created

  • VUID-vkCmdCopyImage-dstSubresource-07968
    If dstSubresource.layerCount is not VK_REMAINING_ARRAY_LAYERS, dstSubresource.baseArrayLayer + dstSubresource.layerCount of each element of pRegions must be less than or equal to the arrayLayers specified in VkImageCreateInfo when dstImage was created

  • VUID-vkCmdCopyImage-dstImage-07969
    dstImage must not have been created with flags containing VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT

Valid Usage (Implicit)
  • VUID-vkCmdCopyImage-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdCopyImage-srcImage-parameter
    srcImage must be a valid VkImage handle

  • VUID-vkCmdCopyImage-srcImageLayout-parameter
    srcImageLayout must be a valid VkImageLayout value

  • VUID-vkCmdCopyImage-dstImage-parameter
    dstImage must be a valid VkImage handle

  • VUID-vkCmdCopyImage-dstImageLayout-parameter
    dstImageLayout must be a valid VkImageLayout value

  • VUID-vkCmdCopyImage-pRegions-parameter
    pRegions must be a valid pointer to an array of regionCount valid VkImageCopy structures

  • VUID-vkCmdCopyImage-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdCopyImage-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support transfer, graphics, or compute operations

  • VUID-vkCmdCopyImage-renderpass
    This command must only be called outside of a render pass instance

  • VUID-vkCmdCopyImage-videocoding
    This command must only be called outside of a video coding scope

  • VUID-vkCmdCopyImage-regionCount-arraylength
    regionCount must be greater than 0

  • VUID-vkCmdCopyImage-commonparent
    Each of commandBuffer, dstImage, and srcImage must have been created, allocated, or retrieved from the same VkDevice

Host Synchronization
  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type

Primary
Secondary

Outside

Outside

Transfer
Graphics
Compute

Action

The VkImageCopy structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkImageCopy {
    VkImageSubresourceLayers    srcSubresource;
    VkOffset3D                  srcOffset;
    VkImageSubresourceLayers    dstSubresource;
    VkOffset3D                  dstOffset;
    VkExtent3D                  extent;
} VkImageCopy;
  • srcSubresource and dstSubresource are VkImageSubresourceLayers structures specifying the image subresources of the images used for the source and destination image data, respectively.

  • srcOffset and dstOffset select the initial x, y, and z offsets in texels of the sub-regions of the source and destination image data.

  • extent is the size in texels of the image to copy in width, height and depth.

Valid Usage
  • VUID-VkImageCopy-apiVersion-07940
    If the VK_KHR_sampler_ycbcr_conversion extension is not enabled, and VkPhysicalDeviceProperties::apiVersion is less than Vulkan 1.1, the aspectMask member of srcSubresource and dstSubresource must match

  • VUID-VkImageCopy-apiVersion-07941
    If the VK_KHR_maintenance1 extension is not enabled, and VkPhysicalDeviceProperties::apiVersion is less than Vulkan 1.1, the layerCount member of srcSubresource and dstSubresource must match

  • VUID-VkImageCopy-extent-06668
    extent.width must not be 0

  • VUID-VkImageCopy-extent-06669
    extent.height must not be 0

  • VUID-VkImageCopy-extent-06670
    extent.depth must not be 0

Valid Usage (Implicit)

The VkImageSubresourceLayers structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkImageSubresourceLayers {
    VkImageAspectFlags    aspectMask;
    uint32_t              mipLevel;
    uint32_t              baseArrayLayer;
    uint32_t              layerCount;
} VkImageSubresourceLayers;
  • aspectMask is a combination of VkImageAspectFlagBits, selecting the color, depth and/or stencil aspects to be copied.

  • mipLevel is the mipmap level to copy

  • baseArrayLayer and layerCount are the starting layer and number of layers to copy.

Valid Usage
  • VUID-VkImageSubresourceLayers-aspectMask-00167
    If aspectMask contains VK_IMAGE_ASPECT_COLOR_BIT, it must not contain either of VK_IMAGE_ASPECT_DEPTH_BIT or VK_IMAGE_ASPECT_STENCIL_BIT

  • VUID-VkImageSubresourceLayers-aspectMask-00168
    aspectMask must not contain VK_IMAGE_ASPECT_METADATA_BIT

  • VUID-VkImageSubresourceLayers-aspectMask-02247
    aspectMask must not include VK_IMAGE_ASPECT_MEMORY_PLANE_i_BIT_EXT for any index i

  • VUID-VkImageSubresourceLayers-layerCount-09243
    If the maintenance5 feature is not enabled, layerCount must not be VK_REMAINING_ARRAY_LAYERS

  • VUID-VkImageSubresourceLayers-layerCount-01700
    If layerCount is not VK_REMAINING_ARRAY_LAYERS, it must be greater than 0

Valid Usage (Implicit)
  • VUID-VkImageSubresourceLayers-aspectMask-parameter
    aspectMask must be a valid combination of VkImageAspectFlagBits values

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

A more extensible version of the copy image command is defined below.

To copy data between image objects, call:

// Provided by VK_VERSION_1_3
void vkCmdCopyImage2(
    VkCommandBuffer                             commandBuffer,
    const VkCopyImageInfo2*                     pCopyImageInfo);

or the equivalent command

// Provided by VK_KHR_copy_commands2
void vkCmdCopyImage2KHR(
    VkCommandBuffer                             commandBuffer,
    const VkCopyImageInfo2*                     pCopyImageInfo);
  • commandBuffer is the command buffer into which the command will be recorded.

  • pCopyImageInfo is a pointer to a VkCopyImageInfo2 structure describing the copy parameters.

This command is functionally identical to vkCmdCopyImage, but includes extensible sub-structures that include sType and pNext parameters, allowing them to be more easily extended.

Valid Usage
  • VUID-vkCmdCopyImage2-commandBuffer-01825
    If commandBuffer is an unprotected command buffer and protectedNoFault is not supported, srcImage must not be a protected image

  • VUID-vkCmdCopyImage2-commandBuffer-01826
    If commandBuffer is an unprotected command buffer and protectedNoFault is not supported, dstImage must not be a protected image

  • VUID-vkCmdCopyImage2-commandBuffer-01827
    If commandBuffer is a protected command buffer and protectedNoFault is not supported, dstImage must not be an unprotected image

Valid Usage (Implicit)
  • VUID-vkCmdCopyImage2-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdCopyImage2-pCopyImageInfo-parameter
    pCopyImageInfo must be a valid pointer to a valid VkCopyImageInfo2 structure

  • VUID-vkCmdCopyImage2-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdCopyImage2-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support transfer, graphics, or compute operations

  • VUID-vkCmdCopyImage2-renderpass
    This command must only be called outside of a render pass instance

  • VUID-vkCmdCopyImage2-videocoding
    This command must only be called outside of a video coding scope

Host Synchronization
  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type

Primary
Secondary

Outside

Outside

Transfer
Graphics
Compute

Action

The VkCopyImageInfo2 structure is defined as:

// Provided by VK_VERSION_1_3
typedef struct VkCopyImageInfo2 {
    VkStructureType        sType;
    const void*            pNext;
    VkImage                srcImage;
    VkImageLayout          srcImageLayout;
    VkImage                dstImage;
    VkImageLayout          dstImageLayout;
    uint32_t               regionCount;
    const VkImageCopy2*    pRegions;
} VkCopyImageInfo2;

or the equivalent

// Provided by VK_KHR_copy_commands2
typedef VkCopyImageInfo2 VkCopyImageInfo2KHR;
  • sType is a VkStructureType value identifying this structure.

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

  • srcImage is the source image.

  • srcImageLayout is the current layout of the source image subresource.

  • dstImage is the destination image.

  • dstImageLayout is the current layout of the destination image subresource.

  • regionCount is the number of regions to copy.

  • pRegions is a pointer to an array of VkImageCopy2 structures specifying the regions to copy.

Valid Usage
  • VUID-VkCopyImageInfo2-pRegions-00124
    The union of all source regions, and the union of all destination regions, specified by the elements of pRegions, must not overlap in memory

  • VUID-VkCopyImageInfo2-srcImage-01995
    The format features of srcImage must contain VK_FORMAT_FEATURE_TRANSFER_SRC_BIT

  • VUID-VkCopyImageInfo2-srcImageLayout-00128
    srcImageLayout must specify the layout of the image subresources of srcImage specified in pRegions at the time this command is executed on a VkDevice

  • VUID-VkCopyImageInfo2-srcImageLayout-01917
    srcImageLayout must be VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR, VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL, or VK_IMAGE_LAYOUT_GENERAL

  • VUID-VkCopyImageInfo2-srcImage-09460
    If srcImage and dstImage are the same, and any elements of pRegions contains the srcSubresource and dstSubresource with matching mipLevel and overlapping array layers, then the srcImageLayout and dstImageLayout must be VK_IMAGE_LAYOUT_GENERAL or VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR

  • VUID-VkCopyImageInfo2-dstImage-01996
    The format features of dstImage must contain VK_FORMAT_FEATURE_TRANSFER_DST_BIT

  • VUID-VkCopyImageInfo2-dstImageLayout-00133
    dstImageLayout must specify the layout of the image subresources of dstImage specified in pRegions at the time this command is executed on a VkDevice

  • VUID-VkCopyImageInfo2-dstImageLayout-01395
    dstImageLayout must be VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR, VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL, or VK_IMAGE_LAYOUT_GENERAL

  • VUID-VkCopyImageInfo2-srcImage-01548
    If the VkFormat of each of srcImage and dstImage is not a multi-planar format, the VkFormat of each of srcImage and dstImage must be size-compatible

  • VUID-VkCopyImageInfo2-None-01549
    In a copy to or from a plane of a multi-planar image, the VkFormat of the image and plane must be compatible according to the description of compatible planes for the plane being copied

  • VUID-VkCopyImageInfo2-srcImage-09247
    If the VkFormat of each of srcImage and dstImage is a compressed image format, the formats must have the same texel block extent

  • VUID-VkCopyImageInfo2-srcImage-00136
    The sample count of srcImage and dstImage must match

  • VUID-VkCopyImageInfo2-srcOffset-01783
    The srcOffset and extent members of each element of pRegions must respect the image transfer granularity requirements of commandBuffer’s command pool’s queue family, as described in VkQueueFamilyProperties

  • VUID-VkCopyImageInfo2-dstOffset-01784
    The dstOffset and extent members of each element of pRegions must respect the image transfer granularity requirements of commandBuffer’s command pool’s queue family, as described in VkQueueFamilyProperties

  • VUID-VkCopyImageInfo2-srcImage-01551
    If neither srcImage nor dstImage has a multi-planar image format then for each element of pRegions, srcSubresource.aspectMask and dstSubresource.aspectMask must match

  • VUID-VkCopyImageInfo2-srcImage-08713
    If srcImage has a multi-planar image format, then for each element of pRegions, srcSubresource.aspectMask must be a single valid multi-planar aspect mask bit

  • VUID-VkCopyImageInfo2-dstImage-08714
    If dstImage has a multi-planar image format, then for each element of pRegions, dstSubresource.aspectMask must be a single valid multi-planar aspect mask bit

  • VUID-VkCopyImageInfo2-srcImage-01556
    If srcImage has a multi-planar image format and the dstImage does not have a multi-planar image format, then for each element of pRegions, dstSubresource.aspectMask must be VK_IMAGE_ASPECT_COLOR_BIT

  • VUID-VkCopyImageInfo2-dstImage-01557
    If dstImage has a multi-planar image format and the srcImage does not have a multi-planar image format, then for each element of pRegions, srcSubresource.aspectMask must be VK_IMAGE_ASPECT_COLOR_BIT

  • VUID-VkCopyImageInfo2-apiVersion-07932
    If the VK_KHR_maintenance1 extension is not enabled, or VkPhysicalDeviceProperties::apiVersion is less than Vulkan 1.1, and either srcImage or dstImage is of type VK_IMAGE_TYPE_3D, then for each element of pRegions, srcSubresource.baseArrayLayer and dstSubresource.baseArrayLayer must both be 0, and srcSubresource.layerCount and dstSubresource.layerCount must both be 1

  • VUID-VkCopyImageInfo2-srcImage-04443
    If srcImage is of type VK_IMAGE_TYPE_3D, then for each element of pRegions, srcSubresource.baseArrayLayer must be 0 and srcSubresource.layerCount must be 1

  • VUID-VkCopyImageInfo2-dstImage-04444
    If dstImage is of type VK_IMAGE_TYPE_3D, then for each element of pRegions, dstSubresource.baseArrayLayer must be 0 and dstSubresource.layerCount must be 1

  • VUID-VkCopyImageInfo2-aspectMask-00142
    For each element of pRegions, srcSubresource.aspectMask must specify aspects present in srcImage

  • VUID-VkCopyImageInfo2-aspectMask-00143
    For each element of pRegions, dstSubresource.aspectMask must specify aspects present in dstImage

  • VUID-VkCopyImageInfo2-srcOffset-00144
    For each element of pRegions, srcOffset.x and (extent.width + srcOffset.x) must both be greater than or equal to 0 and less than or equal to the width of the specified srcSubresource of srcImage

  • VUID-VkCopyImageInfo2-srcOffset-00145
    For each element of pRegions, srcOffset.y and (extent.height + srcOffset.y) must both be greater than or equal to 0 and less than or equal to the height of the specified srcSubresource of srcImage

  • VUID-VkCopyImageInfo2-srcImage-00146
    If srcImage is of type VK_IMAGE_TYPE_1D, then for each element of pRegions, srcOffset.y must be 0 and extent.height must be 1

  • VUID-VkCopyImageInfo2-srcOffset-00147
    If srcImage is of type VK_IMAGE_TYPE_3D, then for each element of pRegions, srcOffset.z and (extent.depth + srcOffset.z) must both be greater than or equal to 0 and less than or equal to the depth of the specified srcSubresource of srcImage

  • VUID-VkCopyImageInfo2-srcImage-01785
    If srcImage is of type VK_IMAGE_TYPE_1D, then for each element of pRegions, srcOffset.z must be 0 and extent.depth must be 1

  • VUID-VkCopyImageInfo2-dstImage-01786
    If dstImage is of type VK_IMAGE_TYPE_1D, then for each element of pRegions, dstOffset.z must be 0 and extent.depth must be 1

  • VUID-VkCopyImageInfo2-srcImage-01787
    If srcImage is of type VK_IMAGE_TYPE_2D, then for each element of pRegions, srcOffset.z must be 0

  • VUID-VkCopyImageInfo2-dstImage-01788
    If dstImage is of type VK_IMAGE_TYPE_2D, then for each element of pRegions, dstOffset.z must be 0

  • VUID-VkCopyImageInfo2-apiVersion-07933
    If the VK_KHR_maintenance1 extension is not enabled, and VkPhysicalDeviceProperties::apiVersion is less than Vulkan 1.1, srcImage and dstImage must have the same VkImageType

  • VUID-VkCopyImageInfo2-apiVersion-08969
    If the VK_KHR_maintenance1 extension is not enabled, and VkPhysicalDeviceProperties::apiVersion is less than Vulkan 1.1, srcImage or dstImage is of type VK_IMAGE_TYPE_2D, then for each element of pRegions, extent.depth must be 1

  • VUID-VkCopyImageInfo2-srcImage-07743
    If srcImage and dstImage have a different VkImageType, and maintenance5 is not enabled, one must be VK_IMAGE_TYPE_3D and the other must be VK_IMAGE_TYPE_2D

  • VUID-VkCopyImageInfo2-srcImage-08793
    If srcImage and dstImage have the same VkImageType, for each element of pRegions, if neither of the layerCount members of srcSubresource or dstSubresource are VK_REMAINING_ARRAY_LAYERS, the layerCount members of srcSubresource or dstSubresource must match

  • VUID-VkCopyImageInfo2-srcImage-08794
    If srcImage and dstImage have the same VkImageType, and one of the layerCount members of srcSubresource or dstSubresource is VK_REMAINING_ARRAY_LAYERS, the other member must be either VK_REMAINING_ARRAY_LAYERS or equal to the arrayLayers member of the VkImageCreateInfo used to create the image minus baseArrayLayer

  • VUID-VkCopyImageInfo2-srcImage-01790
    If srcImage and dstImage are both of type VK_IMAGE_TYPE_2D, then for each element of pRegions, extent.depth must be 1

  • VUID-VkCopyImageInfo2-srcImage-01791
    If srcImage is of type VK_IMAGE_TYPE_2D, and dstImage is of type VK_IMAGE_TYPE_3D, then for each element of pRegions, extent.depth must equal srcSubresource.layerCount

  • VUID-VkCopyImageInfo2-dstImage-01792
    If dstImage is of type VK_IMAGE_TYPE_2D, and srcImage is of type VK_IMAGE_TYPE_3D, then for each element of pRegions, extent.depth must equal dstSubresource.layerCount

  • VUID-VkCopyImageInfo2-dstOffset-00150
    For each element of pRegions, dstOffset.x and (extent.width + dstOffset.x) must both be greater than or equal to 0 and less than or equal to the width of the specified dstSubresource of dstImage

  • VUID-VkCopyImageInfo2-dstOffset-00151
    For each element of pRegions, dstOffset.y and (extent.height + dstOffset.y) must both be greater than or equal to 0 and less than or equal to the height of the specified dstSubresource of dstImage

  • VUID-VkCopyImageInfo2-dstImage-00152
    If dstImage is of type VK_IMAGE_TYPE_1D, then for each element of pRegions, dstOffset.y must be 0 and extent.height must be 1

  • VUID-VkCopyImageInfo2-dstOffset-00153
    If dstImage is of type VK_IMAGE_TYPE_3D, then for each element of pRegions, dstOffset.z and (extent.depth + dstOffset.z) must both be greater than or equal to 0 and less than or equal to the depth of the specified dstSubresource of dstImage

  • VUID-VkCopyImageInfo2-pRegions-07278
    For each element of pRegions, srcOffset.x must be a multiple of the texel block extent width of the VkFormat of srcImage

  • VUID-VkCopyImageInfo2-pRegions-07279
    For each element of pRegions, srcOffset.y must be a multiple of the texel block extent height of the VkFormat of srcImage

  • VUID-VkCopyImageInfo2-pRegions-07280
    For each element of pRegions, srcOffset.z must be a multiple of the texel block extent depth of the VkFormat of srcImage

  • VUID-VkCopyImageInfo2-pRegions-07281
    For each element of pRegions, dstOffset.x must be a multiple of the texel block extent width of the VkFormat of dstImage

  • VUID-VkCopyImageInfo2-pRegions-07282
    For each element of pRegions, dstOffset.y must be a multiple of the texel block extent height of the VkFormat of dstImage

  • VUID-VkCopyImageInfo2-pRegions-07283
    For each element of pRegions, dstOffset.z must be a multiple of the texel block extent depth of the VkFormat of dstImage

  • VUID-VkCopyImageInfo2-srcImage-01728
    For each element of pRegions, if the sum of srcOffset.x and extent.width does not equal the width of the subresource specified by srcSubresource, extent.width must be a multiple of the texel block extent width of the VkFormat of srcImage

  • VUID-VkCopyImageInfo2-srcImage-01729
    For each element of pRegions, if the sum of srcOffset.y and extent.height does not equal the height of the subresource specified by srcSubresource, extent.height must be a multiple of the texel block extent height of the VkFormat of srcImage

  • VUID-VkCopyImageInfo2-srcImage-01730
    For each element of pRegions, if the sum of srcOffset.z and extent.depth does not equal the depth of the subresource specified by srcSubresource, extent.depth must be a multiple of the texel block extent depth of the VkFormat of srcImage

  • VUID-VkCopyImageInfo2-dstImage-01732
    For each element of pRegions, if the sum of dstOffset.x and extent.width does not equal the width of the subresource specified by dstSubresource, extent.width must be a multiple of the texel block extent width of the VkFormat of dstImage

  • VUID-VkCopyImageInfo2-dstImage-01733
    For each element of pRegions, if the sum of dstOffset.y and extent.height does not equal the height of the subresource specified by dstSubresource, extent.height must be a multiple of the texel block extent height of the VkFormat of dstImage

  • VUID-VkCopyImageInfo2-dstImage-01734
    For each element of pRegions, if the sum of dstOffset.z and extent.depth does not equal the depth of the subresource specified by dstSubresource, extent.depth must be a multiple of the texel block extent depth of the VkFormat of dstImage

  • VUID-VkCopyImageInfo2-aspect-06662
    If the aspect member of any element of pRegions includes any flag other than VK_IMAGE_ASPECT_STENCIL_BIT or srcImage was not created with separate stencil usage, VK_IMAGE_USAGE_TRANSFER_SRC_BIT must have been included in the VkImageCreateInfo::usage used to create srcImage

  • VUID-VkCopyImageInfo2-aspect-06663
    If the aspect member of any element of pRegions includes any flag other than VK_IMAGE_ASPECT_STENCIL_BIT or dstImage was not created with separate stencil usage, VK_IMAGE_USAGE_TRANSFER_DST_BIT must have been included in the VkImageCreateInfo::usage used to create dstImage

  • VUID-VkCopyImageInfo2-aspect-06664
    If the aspect member of any element of pRegions includes VK_IMAGE_ASPECT_STENCIL_BIT, and srcImage was created with separate stencil usage, VK_IMAGE_USAGE_TRANSFER_SRC_BIT must have been included in the VkImageStencilUsageCreateInfo::stencilUsage used to create srcImage

  • VUID-VkCopyImageInfo2-aspect-06665
    If the aspect member of any element of pRegions includes VK_IMAGE_ASPECT_STENCIL_BIT, and dstImage was created with separate stencil usage, VK_IMAGE_USAGE_TRANSFER_DST_BIT must have been included in the VkImageStencilUsageCreateInfo::stencilUsage used to create dstImage

  • VUID-VkCopyImageInfo2-srcImage-07966
    If srcImage is non-sparse then the image or the specified disjoint plane must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-VkCopyImageInfo2-srcSubresource-07967
    The srcSubresource.mipLevel member of each element of pRegions must be less than the mipLevels specified in VkImageCreateInfo when srcImage was created

  • VUID-VkCopyImageInfo2-srcSubresource-07968
    If srcSubresource.layerCount is not VK_REMAINING_ARRAY_LAYERS, srcSubresource.baseArrayLayer + srcSubresource.layerCount of each element of pRegions must be less than or equal to the arrayLayers specified in VkImageCreateInfo when srcImage was created

  • VUID-VkCopyImageInfo2-srcImage-07969
    srcImage must not have been created with flags containing VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT

  • VUID-VkCopyImageInfo2-dstImage-07966
    If dstImage is non-sparse then the image or the specified disjoint plane must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-VkCopyImageInfo2-dstSubresource-07967
    The dstSubresource.mipLevel member of each element of pRegions must be less than the mipLevels specified in VkImageCreateInfo when dstImage was created

  • VUID-VkCopyImageInfo2-dstSubresource-07968
    If dstSubresource.layerCount is not VK_REMAINING_ARRAY_LAYERS, dstSubresource.baseArrayLayer + dstSubresource.layerCount of each element of pRegions must be less than or equal to the arrayLayers specified in VkImageCreateInfo when dstImage was created

  • VUID-VkCopyImageInfo2-dstImage-07969
    dstImage must not have been created with flags containing VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT

Valid Usage (Implicit)
  • VUID-VkCopyImageInfo2-sType-sType
    sType must be VK_STRUCTURE_TYPE_COPY_IMAGE_INFO_2

  • VUID-VkCopyImageInfo2-pNext-pNext
    pNext must be NULL

  • VUID-VkCopyImageInfo2-srcImage-parameter
    srcImage must be a valid VkImage handle

  • VUID-VkCopyImageInfo2-srcImageLayout-parameter
    srcImageLayout must be a valid VkImageLayout value

  • VUID-VkCopyImageInfo2-dstImage-parameter
    dstImage must be a valid VkImage handle

  • VUID-VkCopyImageInfo2-dstImageLayout-parameter
    dstImageLayout must be a valid VkImageLayout value

  • VUID-VkCopyImageInfo2-pRegions-parameter
    pRegions must be a valid pointer to an array of regionCount valid VkImageCopy2 structures

  • VUID-VkCopyImageInfo2-regionCount-arraylength
    regionCount must be greater than 0

  • VUID-VkCopyImageInfo2-commonparent
    Both of dstImage, and srcImage must have been created, allocated, or retrieved from the same VkDevice

The VkImageCopy2 structure is defined as:

// Provided by VK_VERSION_1_3
typedef struct VkImageCopy2 {
    VkStructureType             sType;
    const void*                 pNext;
    VkImageSubresourceLayers    srcSubresource;
    VkOffset3D                  srcOffset;
    VkImageSubresourceLayers    dstSubresource;
    VkOffset3D                  dstOffset;
    VkExtent3D                  extent;
} VkImageCopy2;

or the equivalent

// Provided by VK_KHR_copy_commands2
typedef VkImageCopy2 VkImageCopy2KHR;
  • sType is a VkStructureType value identifying this structure.

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

  • srcSubresource and dstSubresource are VkImageSubresourceLayers structures specifying the image subresources of the images used for the source and destination image data, respectively.

  • srcOffset and dstOffset select the initial x, y, and z offsets in texels of the sub-regions of the source and destination image data.

  • extent is the size in texels of the image to copy in width, height and depth.

Valid Usage
  • VUID-VkImageCopy2-apiVersion-07940
    If the VK_KHR_sampler_ycbcr_conversion extension is not enabled, and VkPhysicalDeviceProperties::apiVersion is less than Vulkan 1.1, the aspectMask member of srcSubresource and dstSubresource must match

  • VUID-VkImageCopy2-apiVersion-07941
    If the VK_KHR_maintenance1 extension is not enabled, and VkPhysicalDeviceProperties::apiVersion is less than Vulkan 1.1, the layerCount member of srcSubresource and dstSubresource must match

  • VUID-VkImageCopy2-extent-06668
    extent.width must not be 0

  • VUID-VkImageCopy2-extent-06669
    extent.height must not be 0

  • VUID-VkImageCopy2-extent-06670
    extent.depth must not be 0

Valid Usage (Implicit)
  • VUID-VkImageCopy2-sType-sType
    sType must be VK_STRUCTURE_TYPE_IMAGE_COPY_2

  • VUID-VkImageCopy2-pNext-pNext
    pNext must be NULL

  • VUID-VkImageCopy2-srcSubresource-parameter
    srcSubresource must be a valid VkImageSubresourceLayers structure

  • VUID-VkImageCopy2-dstSubresource-parameter
    dstSubresource must be a valid VkImageSubresourceLayers structure

Copying Data Between Buffers and Images

Data can be copied between buffers and images, enabling applications to load and store data between images and application-defined offsets in buffer memory.

When copying between a buffer and an image, whole texel blocks are always copied; each texel block in the specified extent in the image to be copied will be written to a region in the buffer, specified according to the position of the texel block, and the texel block extent and size of the format being copied.

For a set of coordinates (x,y,z,layer), where:

x is in the range [imageOffset.x / blockWidth, ⌈(imageOffset.x + imageExtent.width) / blockWidth⌉),

y is in the range [imageOffset.y / blockHeight, ⌈(imageOffset.y + imageExtent.height) / blockHeight⌉),

z is in the range [imageOffset.z / blockDepth, ⌈(imageOffset.z + imageExtent.depth) / blockDepth⌉),

layer is in the range [imageSubresource.baseArrayLayer, imageSubresource.baseArrayLayer + imageSubresource.layerCount),

and where blockWidth, blockHeight, and blockDepth are the dimensions of the texel block extent of the image’s format.

For each (x,y,z,layer) coordinate, texels in the image layer selected by layer are accessed in the following ranges:

[x × blockWidth, max( (x × blockWidth) + blockWidth, imageWidth) )

[y × blockHeight, max( (y × blockHeight) + blockHeight, imageHeight) )

[z × blockDepth, max( (z × blockDepth) + blockDepth, imageDepth) )

where imageWidth, imageHeight, and imageDepth are the dimensions of the image subresource.

For each (x,y,z,layer) coordinate, bytes in the buffer are accessed at offsets in the range [texelOffset, texelOffset + blockSize), where:

texelOffset = bufferOffset + (x × blockSize) + (y × rowExtent) + (z × sliceExtent) + (layer × layerExtent)

blockSize is the size of the block in bytes for the format

rowExtent = max(bufferRowLength, ⌈imageExtent.width / blockWidth⌉ × blockSize)

sliceExtent = max(bufferImageHeight, imageExtent.height × rowExtent)

layerExtent = imageExtent.depth × sliceExtent

If a rotation is specified by VkCopyCommandTransformInfoQCOM, the 2D region of the image being addressed is rotated around the offset, modifying the range of x and y coordinates for the image address according to the specified VkSurfaceTransformFlagBitsKHR:

  • If VK_SURFACE_TRANSFORM_IDENTITY_BIT_KHR is specified, no rotation is performed:

    x' is in the same range as x

    y' is in the same range as y

    blockWidth' = blockWidth

    blockHeight' = blockHeight

    imageWidth' = imageWidth

    imageHeight' = imageHeight

  • If VK_SURFACE_TRANSFORM_ROTATE_90_BIT_KHR is specified

    x' is in the range [⌈(imageOffset.x - imageExtent.height) / blockHeight⌉, imageOffset.x - image/ blockHeight)

    y' is in the range [imageOffset.y / blockWidth, ⌈(imageOffset.y + imageExtent.width) / blockWidth⌉)

    blockWidth' = blockHeight

    blockHeight' = blockWidth

    imageWidth' = imageHeight

    imageHeight' = imageWidth

  • If VK_SURFACE_TRANSFORM_ROTATE_180_BIT_KHR is specified:

    x' is in the range [⌈(imageOffset.x - imageExtent.width) / blockWidth⌉, imageOffset.x / blockWidth),

    y' is in the range [⌈(imageOffset.x + imageExtent.height) / blockHeight⌉, imageOffset.x / blockHeight),

    blockWidth' = blockWidth

    blockHeight' = blockHeight

    imageWidth' = imageWidth

    imageHeight' = imageHeight

  • If VK_SURFACE_TRANSFORM_ROTATE_270_BIT_KHR is specified:

    x is in the range [imageOffset.x / blockHeight, ⌈(imageOffset.x + imageExtent.height) / blockHeight⌉)

    y is in the range [⌈(imageOffset.y - imageExtent.width) / blockWidth⌉, imageOffset.y / blockWidth).

    blockWidth' = blockHeight

    blockHeight' = blockWidth

    imageWidth' = imageHeight

    imageHeight' = imageWidth

When rotation is performed, for each (x,y,z,layer) coordinate, texels in the image layer selected by layer are instead accessed in the following ranges:

[x' × blockWidth', max( (x' × blockWidth') + blockWidth', imageWidth') )

[y' × blockHeight', max( (y' × blockHeight') + blockHeight', imageHeight') )

[z' × blockDepth', max( (z' × blockDepth') + blockDepth', imageDepth') )

Buffer addressing calculations are unaffected by this rotation.

When copying between a buffer and the depth or stencil aspect of an image, data in the buffer is assumed to be laid out as separate planes rather than interleaved. Addressing calculations are thus performed for a different format than the base image, according to the aspect, as described in the following table:

Table 1. Depth/Stencil Aspect Copy Table
Base Format Depth Aspect Format Stencil Aspect Format

VK_FORMAT_D16_UNORM

VK_FORMAT_D16_UNORM

-

VK_FORMAT_X8_D24_UNORM_PACK32

VK_FORMAT_X8_D24_UNORM_PACK32

-

VK_FORMAT_D32_SFLOAT

VK_FORMAT_D32_SFLOAT

-

VK_FORMAT_S8_UINT

-

VK_FORMAT_S8_UINT

VK_FORMAT_D16_UNORM_S8_UINT

VK_FORMAT_D16_UNORM

VK_FORMAT_S8_UINT

VK_FORMAT_D24_UNORM_S8_UINT

VK_FORMAT_X8_D24_UNORM_PACK32

VK_FORMAT_S8_UINT

VK_FORMAT_D32_SFLOAT_S8_UINT

VK_FORMAT_D32_SFLOAT

VK_FORMAT_S8_UINT

When copying between a buffer and any plane of a multi-planar image, addressing calculations are performed using the compatible format for that plane, rather than the format of the multi-planar image.

Each texel block is copied from one resource to the other according to the above addressing equations.

To copy data from a buffer object to an image object, call:

// Provided by VK_VERSION_1_0
void vkCmdCopyBufferToImage(
    VkCommandBuffer                             commandBuffer,
    VkBuffer                                    srcBuffer,
    VkImage                                     dstImage,
    VkImageLayout                               dstImageLayout,
    uint32_t                                    regionCount,
    const VkBufferImageCopy*                    pRegions);
  • commandBuffer is the command buffer into which the command will be recorded.

  • srcBuffer is the source buffer.

  • dstImage is the destination image.

  • dstImageLayout is the layout of the destination image subresources for the copy.

  • regionCount is the number of regions to copy.

  • pRegions is a pointer to an array of VkBufferImageCopy structures specifying the regions to copy.

Each source region specified by pRegions is copied from the source buffer to the destination region of the destination image according to the addressing calculations for each resource. If any of the specified regions in srcBuffer overlaps in memory with any of the specified regions in dstImage, values read from those overlapping regions are undefined. If any region accesses a depth aspect in dstImage and the VK_EXT_depth_range_unrestricted extension is not enabled, values copied from srcBuffer outside of the range [0,1] will be written as undefined values to the destination image.

Copy regions for the image must be aligned to a multiple of the texel block extent in each dimension, except at the edges of the image, where region extents must match the edge of the image.

Valid Usage
  • VUID-vkCmdCopyBufferToImage-dstImage-07966
    If dstImage is non-sparse then the image or the specified disjoint plane must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-vkCmdCopyBufferToImage-imageSubresource-07967
    The imageSubresource.mipLevel member of each element of pRegions must be less than the mipLevels specified in VkImageCreateInfo when dstImage was created

  • VUID-vkCmdCopyBufferToImage-imageSubresource-07968
    If imageSubresource.layerCount is not VK_REMAINING_ARRAY_LAYERS, imageSubresource.baseArrayLayer + imageSubresource.layerCount of each element of pRegions must be less than or equal to the arrayLayers specified in VkImageCreateInfo when dstImage was created

  • VUID-vkCmdCopyBufferToImage-dstImage-07969
    dstImage must not have been created with flags containing VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT

  • VUID-vkCmdCopyBufferToImage-imageSubresource-07970
    The image region specified by each element of pRegions must be contained within the specified imageSubresource of dstImage

  • VUID-vkCmdCopyBufferToImage-imageSubresource-07971
    For each element of pRegions, imageOffset.x and (imageExtent.width + imageOffset.x) must both be greater than or equal to 0 and less than or equal to the width of the specified imageSubresource of dstImage

  • VUID-vkCmdCopyBufferToImage-imageSubresource-07972
    For each element of pRegions, imageOffset.y and (imageExtent.height + imageOffset.y) must both be greater than or equal to 0 and less than or equal to the height of the specified imageSubresource of dstImage

  • VUID-vkCmdCopyBufferToImage-dstImage-07973
    dstImage must have a sample count equal to VK_SAMPLE_COUNT_1_BIT

  • VUID-vkCmdCopyBufferToImage-commandBuffer-01828
    If commandBuffer is an unprotected command buffer and protectedNoFault is not supported, srcBuffer must not be a protected buffer

  • VUID-vkCmdCopyBufferToImage-commandBuffer-01829
    If commandBuffer is an unprotected command buffer and protectedNoFault is not supported, dstImage must not be a protected image

  • VUID-vkCmdCopyBufferToImage-commandBuffer-01830
    If commandBuffer is a protected command buffer and protectedNoFault is not supported, dstImage must not be an unprotected image

  • VUID-vkCmdCopyBufferToImage-commandBuffer-07737
    If the queue family used to create the VkCommandPool which commandBuffer was allocated from does not support VK_QUEUE_GRAPHICS_BIT or VK_QUEUE_COMPUTE_BIT, the bufferOffset member of any element of pRegions must be a multiple of 4

  • VUID-vkCmdCopyBufferToImage-imageOffset-07738
    The imageOffset and imageExtent members of each element of pRegions must respect the image transfer granularity requirements of commandBuffer’s command pool’s queue family, as described in VkQueueFamilyProperties

  • VUID-vkCmdCopyBufferToImage-commandBuffer-07739
    If the queue family used to create the VkCommandPool which commandBuffer was allocated from does not support VK_QUEUE_GRAPHICS_BIT, for each element of pRegions, the aspectMask member of imageSubresource must not be VK_IMAGE_ASPECT_DEPTH_BIT or VK_IMAGE_ASPECT_STENCIL_BIT

  • VUID-vkCmdCopyBufferToImage-pRegions-00171
    srcBuffer must be large enough to contain all buffer locations that are accessed according to Buffer and Image Addressing, for each element of pRegions

  • VUID-vkCmdCopyBufferToImage-pRegions-00173
    The union of all source regions, and the union of all destination regions, specified by the elements of pRegions, must not overlap in memory

  • VUID-vkCmdCopyBufferToImage-srcBuffer-00174
    srcBuffer must have been created with VK_BUFFER_USAGE_TRANSFER_SRC_BIT usage flag

  • VUID-vkCmdCopyBufferToImage-dstImage-01997
    The format features of dstImage must contain VK_FORMAT_FEATURE_TRANSFER_DST_BIT

  • VUID-vkCmdCopyBufferToImage-srcBuffer-00176
    If srcBuffer is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-vkCmdCopyBufferToImage-dstImage-00177
    dstImage must have been created with VK_IMAGE_USAGE_TRANSFER_DST_BIT usage flag

  • VUID-vkCmdCopyBufferToImage-dstImageLayout-00180
    dstImageLayout must specify the layout of the image subresources of dstImage specified in pRegions at the time this command is executed on a VkDevice

  • VUID-vkCmdCopyBufferToImage-dstImageLayout-01396
    dstImageLayout must be VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR, VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL, or VK_IMAGE_LAYOUT_GENERAL

  • VUID-vkCmdCopyBufferToImage-pRegions-07931
    If VK_EXT_depth_range_unrestricted is not enabled, for each element of pRegions whose imageSubresource contains a depth aspect, the data in srcBuffer must be in the range [0,1]

  • VUID-vkCmdCopyBufferToImage-dstImage-07979
    If dstImage is of type VK_IMAGE_TYPE_1D, then for each element of pRegions, imageOffset.y must be 0 and imageExtent.height must be 1

  • VUID-vkCmdCopyBufferToImage-imageOffset-09104
    For each element of pRegions, imageOffset.z and (imageExtent.depth + imageOffset.z) must both be greater than or equal to 0 and less than or equal to the depth of the specified imageSubresource of dstImage

  • VUID-vkCmdCopyBufferToImage-dstImage-07980
    If dstImage is of type VK_IMAGE_TYPE_1D or VK_IMAGE_TYPE_2D, then for each element of pRegions, imageOffset.z must be 0 and imageExtent.depth must be 1

  • VUID-vkCmdCopyBufferToImage-dstImage-07274
    For each element of pRegions, imageOffset.x must be a multiple of the texel block extent width of the VkFormat of dstImage

  • VUID-vkCmdCopyBufferToImage-dstImage-07275
    For each element of pRegions, imageOffset.y must be a multiple of the texel block extent height of the VkFormat of dstImage

  • VUID-vkCmdCopyBufferToImage-dstImage-07276
    For each element of pRegions, imageOffset.z must be a multiple of the texel block extent depth of the VkFormat of dstImage

  • VUID-vkCmdCopyBufferToImage-dstImage-00207
    For each element of pRegions, if the sum of imageOffset.x and extent.width does not equal the width of the subresource specified by srcSubresource, extent.width must be a multiple of the texel block extent width of the VkFormat of dstImage

  • VUID-vkCmdCopyBufferToImage-dstImage-00208
    For each element of pRegions, if the sum of imageOffset.y and extent.height does not equal the height of the subresource specified by srcSubresource, extent.height must be a multiple of the texel block extent height of the VkFormat of dstImage

  • VUID-vkCmdCopyBufferToImage-dstImage-00209
    For each element of pRegions, if the sum of imageOffset.z and extent.depth does not equal the depth of the subresource specified by srcSubresource, extent.depth must be a multiple of the texel block extent depth of the VkFormat of dstImage

  • VUID-vkCmdCopyBufferToImage-imageSubresource-09105
    For each element of pRegions, imageSubresource.aspectMask must specify aspects present in dstImage

  • VUID-vkCmdCopyBufferToImage-dstImage-07981
    If dstImage has a multi-planar image format, then for each element of pRegions, imageSubresource.aspectMask must be a single valid multi-planar aspect mask bit

  • VUID-vkCmdCopyBufferToImage-dstImage-07983
    If dstImage is of type VK_IMAGE_TYPE_3D, for each element of pRegions, imageSubresource.baseArrayLayer must be 0 and imageSubresource.layerCount must be 1

  • VUID-vkCmdCopyBufferToImage-bufferRowLength-09106
    For each element of pRegions, bufferRowLength must be a multiple of the texel block extent width of the VkFormat of dstImage

  • VUID-vkCmdCopyBufferToImage-bufferImageHeight-09107
    For each element of pRegions, bufferImageHeight must be a multiple of the texel block extent height of the VkFormat of dstImage

  • VUID-vkCmdCopyBufferToImage-bufferRowLength-09108
    For each element of pRegions, bufferRowLength divided by the texel block extent width and then multiplied by the texel block size of dstImage must be less than or equal to 231-1

  • VUID-vkCmdCopyBufferToImage-dstImage-07975
    If dstImage does not have either a depth/stencil format or a multi-planar format, then for each element of pRegions, bufferOffset must be a multiple of the texel block size

  • VUID-vkCmdCopyBufferToImage-dstImage-07976
    If dstImage has a multi-planar format, then for each element of pRegions, bufferOffset must be a multiple of the element size of the compatible format for the format and the aspectMask of the imageSubresource as defined in Compatible Formats of Planes of Multi-Planar Formats

  • VUID-vkCmdCopyBufferToImage-dstImage-07978
    If dstImage has a depth/stencil format, the bufferOffset member of any element of pRegions must be a multiple of 4

Valid Usage (Implicit)
  • VUID-vkCmdCopyBufferToImage-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdCopyBufferToImage-srcBuffer-parameter
    srcBuffer must be a valid VkBuffer handle

  • VUID-vkCmdCopyBufferToImage-dstImage-parameter
    dstImage must be a valid VkImage handle

  • VUID-vkCmdCopyBufferToImage-dstImageLayout-parameter
    dstImageLayout must be a valid VkImageLayout value

  • VUID-vkCmdCopyBufferToImage-pRegions-parameter
    pRegions must be a valid pointer to an array of regionCount valid VkBufferImageCopy structures

  • VUID-vkCmdCopyBufferToImage-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdCopyBufferToImage-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support transfer, graphics, or compute operations

  • VUID-vkCmdCopyBufferToImage-renderpass
    This command must only be called outside of a render pass instance

  • VUID-vkCmdCopyBufferToImage-videocoding
    This command must only be called outside of a video coding scope

  • VUID-vkCmdCopyBufferToImage-regionCount-arraylength
    regionCount must be greater than 0

  • VUID-vkCmdCopyBufferToImage-commonparent
    Each of commandBuffer, dstImage, and srcBuffer must have been created, allocated, or retrieved from the same VkDevice

Host Synchronization
  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type

Primary
Secondary

Outside

Outside

Transfer
Graphics
Compute

Action

To copy data from an image object to a buffer object, call:

// Provided by VK_VERSION_1_0
void vkCmdCopyImageToBuffer(
    VkCommandBuffer                             commandBuffer,
    VkImage                                     srcImage,
    VkImageLayout                               srcImageLayout,
    VkBuffer                                    dstBuffer,
    uint32_t                                    regionCount,
    const VkBufferImageCopy*                    pRegions);
  • commandBuffer is the command buffer into which the command will be recorded.

  • srcImage is the source image.

  • srcImageLayout is the layout of the source image subresources for the copy.

  • dstBuffer is the destination buffer.

  • regionCount is the number of regions to copy.

  • pRegions is a pointer to an array of VkBufferImageCopy structures specifying the regions to copy.

Each source region specified by pRegions is copied from the source image to the destination region of the destination buffer according to the addressing calculations for each resource. If any of the specified regions in srcImage overlaps in memory with any of the specified regions in dstBuffer, values read from those overlapping regions are undefined.

Copy regions for the image must be aligned to a multiple of the texel block extent in each dimension, except at the edges of the image, where region extents must match the edge of the image.

Valid Usage
  • VUID-vkCmdCopyImageToBuffer-srcImage-07966
    If srcImage is non-sparse then the image or the specified disjoint plane must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-vkCmdCopyImageToBuffer-imageSubresource-07967
    The imageSubresource.mipLevel member of each element of pRegions must be less than the mipLevels specified in VkImageCreateInfo when srcImage was created

  • VUID-vkCmdCopyImageToBuffer-imageSubresource-07968
    If imageSubresource.layerCount is not VK_REMAINING_ARRAY_LAYERS, imageSubresource.baseArrayLayer + imageSubresource.layerCount of each element of pRegions must be less than or equal to the arrayLayers specified in VkImageCreateInfo when srcImage was created

  • VUID-vkCmdCopyImageToBuffer-srcImage-07969
    srcImage must not have been created with flags containing VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT

  • VUID-vkCmdCopyImageToBuffer-imageSubresource-07970
    The image region specified by each element of pRegions must be contained within the specified imageSubresource of srcImage

  • VUID-vkCmdCopyImageToBuffer-imageSubresource-07971
    For each element of pRegions, imageOffset.x and (imageExtent.width + imageOffset.x) must both be greater than or equal to 0 and less than or equal to the width of the specified imageSubresource of srcImage

  • VUID-vkCmdCopyImageToBuffer-imageSubresource-07972
    For each element of pRegions, imageOffset.y and (imageExtent.height + imageOffset.y) must both be greater than or equal to 0 and less than or equal to the height of the specified imageSubresource of srcImage

  • VUID-vkCmdCopyImageToBuffer-srcImage-07973
    srcImage must have a sample count equal to VK_SAMPLE_COUNT_1_BIT

  • VUID-vkCmdCopyImageToBuffer-commandBuffer-01831
    If commandBuffer is an unprotected command buffer and protectedNoFault is not supported, srcImage must not be a protected image

  • VUID-vkCmdCopyImageToBuffer-commandBuffer-01832
    If commandBuffer is an unprotected command buffer and protectedNoFault is not supported, dstBuffer must not be a protected buffer

  • VUID-vkCmdCopyImageToBuffer-commandBuffer-01833
    If commandBuffer is a protected command buffer and protectedNoFault is not supported, dstBuffer must not be an unprotected buffer

  • VUID-vkCmdCopyImageToBuffer-commandBuffer-07746
    If the queue family used to create the VkCommandPool which commandBuffer was allocated from does not support VK_QUEUE_GRAPHICS_BIT or VK_QUEUE_COMPUTE_BIT, the bufferOffset member of any element of pRegions must be a multiple of 4

  • VUID-vkCmdCopyImageToBuffer-imageOffset-07747
    The imageOffset and imageExtent members of each element of pRegions must respect the image transfer granularity requirements of commandBuffer’s command pool’s queue family, as described in VkQueueFamilyProperties

  • VUID-vkCmdCopyImageToBuffer-pRegions-00183
    dstBuffer must be large enough to contain all buffer locations that are accessed according to Buffer and Image Addressing, for each element of pRegions

  • VUID-vkCmdCopyImageToBuffer-pRegions-00184
    The union of all source regions, and the union of all destination regions, specified by the elements of pRegions, must not overlap in memory

  • VUID-vkCmdCopyImageToBuffer-srcImage-00186
    srcImage must have been created with VK_IMAGE_USAGE_TRANSFER_SRC_BIT usage flag

  • VUID-vkCmdCopyImageToBuffer-srcImage-01998
    The format features of srcImage must contain VK_FORMAT_FEATURE_TRANSFER_SRC_BIT

  • VUID-vkCmdCopyImageToBuffer-dstBuffer-00191
    dstBuffer must have been created with VK_BUFFER_USAGE_TRANSFER_DST_BIT usage flag

  • VUID-vkCmdCopyImageToBuffer-dstBuffer-00192
    If dstBuffer is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-vkCmdCopyImageToBuffer-srcImageLayout-00189
    srcImageLayout must specify the layout of the image subresources of srcImage specified in pRegions at the time this command is executed on a VkDevice

  • VUID-vkCmdCopyImageToBuffer-srcImageLayout-01397
    srcImageLayout must be VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR, VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL, or VK_IMAGE_LAYOUT_GENERAL

  • VUID-vkCmdCopyImageToBuffer-srcImage-07979
    If srcImage is of type VK_IMAGE_TYPE_1D, then for each element of pRegions, imageOffset.y must be 0 and imageExtent.height must be 1

  • VUID-vkCmdCopyImageToBuffer-imageOffset-09104
    For each element of pRegions, imageOffset.z and (imageExtent.depth + imageOffset.z) must both be greater than or equal to 0 and less than or equal to the depth of the specified imageSubresource of srcImage

  • VUID-vkCmdCopyImageToBuffer-srcImage-07980
    If srcImage is of type VK_IMAGE_TYPE_1D or VK_IMAGE_TYPE_2D, then for each element of pRegions, imageOffset.z must be 0 and imageExtent.depth must be 1

  • VUID-vkCmdCopyImageToBuffer-srcImage-07274
    For each element of pRegions, imageOffset.x must be a multiple of the texel block extent width of the VkFormat of srcImage

  • VUID-vkCmdCopyImageToBuffer-srcImage-07275
    For each element of pRegions, imageOffset.y must be a multiple of the texel block extent height of the VkFormat of srcImage

  • VUID-vkCmdCopyImageToBuffer-srcImage-07276
    For each element of pRegions, imageOffset.z must be a multiple of the texel block extent depth of the VkFormat of srcImage

  • VUID-vkCmdCopyImageToBuffer-srcImage-00207
    For each element of pRegions, if the sum of imageOffset.x and extent.width does not equal the width of the subresource specified by srcSubresource, extent.width must be a multiple of the texel block extent width of the VkFormat of srcImage

  • VUID-vkCmdCopyImageToBuffer-srcImage-00208
    For each element of pRegions, if the sum of imageOffset.y and extent.height does not equal the height of the subresource specified by srcSubresource, extent.height must be a multiple of the texel block extent height of the VkFormat of srcImage

  • VUID-vkCmdCopyImageToBuffer-srcImage-00209
    For each element of pRegions, if the sum of imageOffset.z and extent.depth does not equal the depth of the subresource specified by srcSubresource, extent.depth must be a multiple of the texel block extent depth of the VkFormat of srcImage

  • VUID-vkCmdCopyImageToBuffer-imageSubresource-09105
    For each element of pRegions, imageSubresource.aspectMask must specify aspects present in srcImage

  • VUID-vkCmdCopyImageToBuffer-srcImage-07981
    If srcImage has a multi-planar image format, then for each element of pRegions, imageSubresource.aspectMask must be a single valid multi-planar aspect mask bit

  • VUID-vkCmdCopyImageToBuffer-srcImage-07983
    If srcImage is of type VK_IMAGE_TYPE_3D, for each element of pRegions, imageSubresource.baseArrayLayer must be 0 and imageSubresource.layerCount must be 1

  • VUID-vkCmdCopyImageToBuffer-bufferRowLength-09106
    For each element of pRegions, bufferRowLength must be a multiple of the texel block extent width of the VkFormat of srcImage

  • VUID-vkCmdCopyImageToBuffer-bufferImageHeight-09107
    For each element of pRegions, bufferImageHeight must be a multiple of the texel block extent height of the VkFormat of srcImage

  • VUID-vkCmdCopyImageToBuffer-bufferRowLength-09108
    For each element of pRegions, bufferRowLength divided by the texel block extent width and then multiplied by the texel block size of srcImage must be less than or equal to 231-1

  • VUID-vkCmdCopyImageToBuffer-srcImage-07975
    If srcImage does not have either a depth/stencil format or a multi-planar format, then for each element of pRegions, bufferOffset must be a multiple of the texel block size

  • VUID-vkCmdCopyImageToBuffer-srcImage-07976
    If srcImage has a multi-planar format, then for each element of pRegions, bufferOffset must be a multiple of the element size of the compatible format for the format and the aspectMask of the imageSubresource as defined in Compatible Formats of Planes of Multi-Planar Formats

  • VUID-vkCmdCopyImageToBuffer-srcImage-07978
    If srcImage has a depth/stencil format, the bufferOffset member of any element of pRegions must be a multiple of 4

Valid Usage (Implicit)
  • VUID-vkCmdCopyImageToBuffer-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdCopyImageToBuffer-srcImage-parameter
    srcImage must be a valid VkImage handle

  • VUID-vkCmdCopyImageToBuffer-srcImageLayout-parameter
    srcImageLayout must be a valid VkImageLayout value

  • VUID-vkCmdCopyImageToBuffer-dstBuffer-parameter
    dstBuffer must be a valid VkBuffer handle

  • VUID-vkCmdCopyImageToBuffer-pRegions-parameter
    pRegions must be a valid pointer to an array of regionCount valid VkBufferImageCopy structures

  • VUID-vkCmdCopyImageToBuffer-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdCopyImageToBuffer-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support transfer, graphics, or compute operations

  • VUID-vkCmdCopyImageToBuffer-renderpass
    This command must only be called outside of a render pass instance

  • VUID-vkCmdCopyImageToBuffer-videocoding
    This command must only be called outside of a video coding scope

  • VUID-vkCmdCopyImageToBuffer-regionCount-arraylength
    regionCount must be greater than 0

  • VUID-vkCmdCopyImageToBuffer-commonparent
    Each of commandBuffer, dstBuffer, and srcImage must have been created, allocated, or retrieved from the same VkDevice

Host Synchronization
  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type

Primary
Secondary

Outside

Outside

Transfer
Graphics
Compute

Action

For both vkCmdCopyBufferToImage and vkCmdCopyImageToBuffer, each element of pRegions is a structure defined as:

// Provided by VK_VERSION_1_0
typedef struct VkBufferImageCopy {
    VkDeviceSize                bufferOffset;
    uint32_t                    bufferRowLength;
    uint32_t                    bufferImageHeight;
    VkImageSubresourceLayers    imageSubresource;
    VkOffset3D                  imageOffset;
    VkExtent3D                  imageExtent;
} VkBufferImageCopy;
  • bufferOffset is the offset in bytes from the start of the buffer object where the image data is copied from or to.

  • bufferRowLength and bufferImageHeight specify in texels a subregion of a larger two- or three-dimensional image in buffer memory, and control the addressing calculations. If either of these values is zero, that aspect of the buffer memory is considered to be tightly packed according to the imageExtent.

  • imageSubresource is a VkImageSubresourceLayers used to specify the specific image subresources of the image used for the source or destination image data.

  • imageOffset selects the initial x, y, z offsets in texels of the sub-region of the source or destination image data.

  • imageExtent is the size in texels of the image to copy in width, height and depth.

Valid Usage
  • VUID-VkBufferImageCopy-bufferRowLength-09101
    bufferRowLength must be 0, or greater than or equal to the width member of imageExtent

  • VUID-VkBufferImageCopy-bufferImageHeight-09102
    bufferImageHeight must be 0, or greater than or equal to the height member of imageExtent

  • VUID-VkBufferImageCopy-aspectMask-09103
    The aspectMask member of imageSubresource must only have a single bit set

  • VUID-VkBufferImageCopy-imageExtent-06659
    imageExtent.width must not be 0

  • VUID-VkBufferImageCopy-imageExtent-06660
    imageExtent.height must not be 0

  • VUID-VkBufferImageCopy-imageExtent-06661
    imageExtent.depth must not be 0

Valid Usage (Implicit)

More extensible versions of the commands to copy between buffers and images are defined below.

To copy data from a buffer object to an image object, call:

// Provided by VK_VERSION_1_3
void vkCmdCopyBufferToImage2(
    VkCommandBuffer                             commandBuffer,
    const VkCopyBufferToImageInfo2*             pCopyBufferToImageInfo);

or the equivalent command

// Provided by VK_KHR_copy_commands2
void vkCmdCopyBufferToImage2KHR(
    VkCommandBuffer                             commandBuffer,
    const VkCopyBufferToImageInfo2*             pCopyBufferToImageInfo);
  • commandBuffer is the command buffer into which the command will be recorded.

  • pCopyBufferToImageInfo is a pointer to a VkCopyBufferToImageInfo2 structure describing the copy parameters.

This command is functionally identical to vkCmdCopyBufferToImage, but includes extensible sub-structures that include sType and pNext parameters, allowing them to be more easily extended.

Valid Usage
  • VUID-vkCmdCopyBufferToImage2-commandBuffer-01828
    If commandBuffer is an unprotected command buffer and protectedNoFault is not supported, srcBuffer must not be a protected buffer

  • VUID-vkCmdCopyBufferToImage2-commandBuffer-01829
    If commandBuffer is an unprotected command buffer and protectedNoFault is not supported, dstImage must not be a protected image

  • VUID-vkCmdCopyBufferToImage2-commandBuffer-01830
    If commandBuffer is a protected command buffer and protectedNoFault is not supported, dstImage must not be an unprotected image

  • VUID-vkCmdCopyBufferToImage2-commandBuffer-07737
    If the queue family used to create the VkCommandPool which commandBuffer was allocated from does not support VK_QUEUE_GRAPHICS_BIT or VK_QUEUE_COMPUTE_BIT, the bufferOffset member of any element of pCopyBufferToImageInfo->pRegions must be a multiple of 4

  • VUID-vkCmdCopyBufferToImage2-imageOffset-07738
    The imageOffset and imageExtent members of each element of pCopyBufferToImageInfo->pRegions must respect the image transfer granularity requirements of commandBuffer’s command pool’s queue family, as described in VkQueueFamilyProperties

  • VUID-vkCmdCopyBufferToImage2-commandBuffer-07739
    If the queue family used to create the VkCommandPool which commandBuffer was allocated from does not support VK_QUEUE_GRAPHICS_BIT, for each element of pCopyBufferToImageInfo->pRegions, the aspectMask member of imageSubresource must not be VK_IMAGE_ASPECT_DEPTH_BIT or VK_IMAGE_ASPECT_STENCIL_BIT

Valid Usage (Implicit)
  • VUID-vkCmdCopyBufferToImage2-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdCopyBufferToImage2-pCopyBufferToImageInfo-parameter
    pCopyBufferToImageInfo must be a valid pointer to a valid VkCopyBufferToImageInfo2 structure

  • VUID-vkCmdCopyBufferToImage2-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdCopyBufferToImage2-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support transfer, graphics, or compute operations

  • VUID-vkCmdCopyBufferToImage2-renderpass
    This command must only be called outside of a render pass instance

  • VUID-vkCmdCopyBufferToImage2-videocoding
    This command must only be called outside of a video coding scope

Host Synchronization
  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type

Primary
Secondary

Outside

Outside

Transfer
Graphics
Compute

Action

The VkCopyBufferToImageInfo2 structure is defined as:

// Provided by VK_VERSION_1_3
typedef struct VkCopyBufferToImageInfo2 {
    VkStructureType              sType;
    const void*                  pNext;
    VkBuffer                     srcBuffer;
    VkImage                      dstImage;
    VkImageLayout                dstImageLayout;
    uint32_t                     regionCount;
    const VkBufferImageCopy2*    pRegions;
} VkCopyBufferToImageInfo2;

or the equivalent

// Provided by VK_KHR_copy_commands2
typedef VkCopyBufferToImageInfo2 VkCopyBufferToImageInfo2KHR;
  • sType is a VkStructureType value identifying this structure.

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

  • srcBuffer is the source buffer.

  • dstImage is the destination image.

  • dstImageLayout is the layout of the destination image subresources for the copy.

  • regionCount is the number of regions to copy.

  • pRegions is a pointer to an array of VkBufferImageCopy2 structures specifying the regions to copy.

Valid Usage
  • VUID-VkCopyBufferToImageInfo2-pRegions-00171
    srcBuffer must be large enough to contain all buffer locations that are accessed according to Buffer and Image Addressing, for each element of pRegions

  • VUID-VkCopyBufferToImageInfo2-pRegions-00173
    The union of all source regions, and the union of all destination regions, specified by the elements of pRegions, must not overlap in memory

  • VUID-VkCopyBufferToImageInfo2-srcBuffer-00174
    srcBuffer must have been created with VK_BUFFER_USAGE_TRANSFER_SRC_BIT usage flag

  • VUID-VkCopyBufferToImageInfo2-dstImage-01997
    The format features of dstImage must contain VK_FORMAT_FEATURE_TRANSFER_DST_BIT

  • VUID-VkCopyBufferToImageInfo2-srcBuffer-00176
    If srcBuffer is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-VkCopyBufferToImageInfo2-dstImage-00177
    dstImage must have been created with VK_IMAGE_USAGE_TRANSFER_DST_BIT usage flag

  • VUID-VkCopyBufferToImageInfo2-dstImageLayout-00180
    dstImageLayout must specify the layout of the image subresources of dstImage specified in pRegions at the time this command is executed on a VkDevice

  • VUID-VkCopyBufferToImageInfo2-dstImageLayout-01396
    dstImageLayout must be VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR, VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL, or VK_IMAGE_LAYOUT_GENERAL

  • VUID-VkCopyBufferToImageInfo2-pRegions-07931
    If VK_EXT_depth_range_unrestricted is not enabled, for each element of pRegions whose imageSubresource contains a depth aspect, the data in srcBuffer must be in the range [0,1]

  • VUID-VkCopyBufferToImageInfo2-dstImage-07966
    If dstImage is non-sparse then the image or the specified disjoint plane must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-VkCopyBufferToImageInfo2-imageSubresource-07967
    The imageSubresource.mipLevel member of each element of pRegions must be less than the mipLevels specified in VkImageCreateInfo when dstImage was created

  • VUID-VkCopyBufferToImageInfo2-imageSubresource-07968
    If imageSubresource.layerCount is not VK_REMAINING_ARRAY_LAYERS, imageSubresource.baseArrayLayer + imageSubresource.layerCount of each element of pRegions must be less than or equal to the arrayLayers specified in VkImageCreateInfo when dstImage was created

  • VUID-VkCopyBufferToImageInfo2-dstImage-07969
    dstImage must not have been created with flags containing VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT

  • VUID-VkCopyBufferToImageInfo2-dstImage-07973
    dstImage must have a sample count equal to VK_SAMPLE_COUNT_1_BIT

  • VUID-VkCopyBufferToImageInfo2-dstImage-07979
    If dstImage is of type VK_IMAGE_TYPE_1D, then for each element of pRegions, imageOffset.y must be 0 and imageExtent.height must be 1

  • VUID-VkCopyBufferToImageInfo2-imageOffset-09104
    For each element of pRegions, imageOffset.z and (imageExtent.depth + imageOffset.z) must both be greater than or equal to 0 and less than or equal to the depth of the specified imageSubresource of dstImage

  • VUID-VkCopyBufferToImageInfo2-dstImage-07980
    If dstImage is of type VK_IMAGE_TYPE_1D or VK_IMAGE_TYPE_2D, then for each element of pRegions, imageOffset.z must be 0 and imageExtent.depth must be 1

  • VUID-VkCopyBufferToImageInfo2-dstImage-07274
    For each element of pRegions, imageOffset.x must be a multiple of the texel block extent width of the VkFormat of dstImage

  • VUID-VkCopyBufferToImageInfo2-dstImage-07275
    For each element of pRegions, imageOffset.y must be a multiple of the texel block extent height of the VkFormat of dstImage

  • VUID-VkCopyBufferToImageInfo2-dstImage-07276
    For each element of pRegions, imageOffset.z must be a multiple of the texel block extent depth of the VkFormat of dstImage

  • VUID-VkCopyBufferToImageInfo2-dstImage-00207
    For each element of pRegions, if the sum of imageOffset.x and extent.width does not equal the width of the subresource specified by srcSubresource, extent.width must be a multiple of the texel block extent width of the VkFormat of dstImage

  • VUID-VkCopyBufferToImageInfo2-dstImage-00208
    For each element of pRegions, if the sum of imageOffset.y and extent.height does not equal the height of the subresource specified by srcSubresource, extent.height must be a multiple of the texel block extent height of the VkFormat of dstImage

  • VUID-VkCopyBufferToImageInfo2-dstImage-00209
    For each element of pRegions, if the sum of imageOffset.z and extent.depth does not equal the depth of the subresource specified by srcSubresource, extent.depth must be a multiple of the texel block extent depth of the VkFormat of dstImage

  • VUID-VkCopyBufferToImageInfo2-imageSubresource-09105
    For each element of pRegions, imageSubresource.aspectMask must specify aspects present in dstImage

  • VUID-VkCopyBufferToImageInfo2-dstImage-07981
    If dstImage has a multi-planar image format, then for each element of pRegions, imageSubresource.aspectMask must be a single valid multi-planar aspect mask bit

  • VUID-VkCopyBufferToImageInfo2-dstImage-07983
    If dstImage is of type VK_IMAGE_TYPE_3D, for each element of pRegions, imageSubresource.baseArrayLayer must be 0 and imageSubresource.layerCount must be 1

  • VUID-VkCopyBufferToImageInfo2-bufferRowLength-09106
    For each element of pRegions, bufferRowLength must be a multiple of the texel block extent width of the VkFormat of dstImage

  • VUID-VkCopyBufferToImageInfo2-bufferImageHeight-09107
    For each element of pRegions, bufferImageHeight must be a multiple of the texel block extent height of the VkFormat of dstImage

  • VUID-VkCopyBufferToImageInfo2-bufferRowLength-09108
    For each element of pRegions, bufferRowLength divided by the texel block extent width and then multiplied by the texel block size of dstImage must be less than or equal to 231-1

  • VUID-VkCopyBufferToImageInfo2-dstImage-07975
    If dstImage does not have either a depth/stencil format or a multi-planar format, then for each element of pRegions, bufferOffset must be a multiple of the texel block size

  • VUID-VkCopyBufferToImageInfo2-dstImage-07976
    If dstImage has a multi-planar format, then for each element of pRegions, bufferOffset must be a multiple of the element size of the compatible format for the format and the aspectMask of the imageSubresource as defined in Compatible Formats of Planes of Multi-Planar Formats

  • VUID-VkCopyBufferToImageInfo2-dstImage-07978
    If dstImage has a depth/stencil format, the bufferOffset member of any element of pRegions must be a multiple of 4

  • VUID-VkCopyBufferToImageInfo2-pRegions-06223
    For each element of pRegions not containing VkCopyCommandTransformInfoQCOM in its pNext chain, imageOffset.x and (imageExtent.width + imageOffset.x) must both be greater than or equal to 0 and less than or equal to the width of the specified imageSubresource of dstImage

  • VUID-VkCopyBufferToImageInfo2-pRegions-06224
    For each element of pRegions not containing VkCopyCommandTransformInfoQCOM in its pNext chain, imageOffset.y and (imageExtent.height + imageOffset.y) must both be greater than or equal to 0 and less than or equal to the height of the specified imageSubresource of dstImage

Valid Usage (Implicit)
  • VUID-VkCopyBufferToImageInfo2-sType-sType
    sType must be VK_STRUCTURE_TYPE_COPY_BUFFER_TO_IMAGE_INFO_2

  • VUID-VkCopyBufferToImageInfo2-pNext-pNext
    pNext must be NULL

  • VUID-VkCopyBufferToImageInfo2-srcBuffer-parameter
    srcBuffer must be a valid VkBuffer handle

  • VUID-VkCopyBufferToImageInfo2-dstImage-parameter
    dstImage must be a valid VkImage handle

  • VUID-VkCopyBufferToImageInfo2-dstImageLayout-parameter
    dstImageLayout must be a valid VkImageLayout value

  • VUID-VkCopyBufferToImageInfo2-pRegions-parameter
    pRegions must be a valid pointer to an array of regionCount valid VkBufferImageCopy2 structures

  • VUID-VkCopyBufferToImageInfo2-regionCount-arraylength
    regionCount must be greater than 0

  • VUID-VkCopyBufferToImageInfo2-commonparent
    Both of dstImage, and srcBuffer must have been created, allocated, or retrieved from the same VkDevice

To copy data from an image object to a buffer object, call:

// Provided by VK_VERSION_1_3
void vkCmdCopyImageToBuffer2(
    VkCommandBuffer                             commandBuffer,
    const VkCopyImageToBufferInfo2*             pCopyImageToBufferInfo);

or the equivalent command

// Provided by VK_KHR_copy_commands2
void vkCmdCopyImageToBuffer2KHR(
    VkCommandBuffer                             commandBuffer,
    const VkCopyImageToBufferInfo2*             pCopyImageToBufferInfo);
  • commandBuffer is the command buffer into which the command will be recorded.

  • pCopyImageToBufferInfo is a pointer to a VkCopyImageToBufferInfo2 structure describing the copy parameters.

This command is functionally identical to vkCmdCopyImageToBuffer, but includes extensible sub-structures that include sType and pNext parameters, allowing them to be more easily extended.

Valid Usage
  • VUID-vkCmdCopyImageToBuffer2-commandBuffer-01831
    If commandBuffer is an unprotected command buffer and protectedNoFault is not supported, srcImage must not be a protected image

  • VUID-vkCmdCopyImageToBuffer2-commandBuffer-01832
    If commandBuffer is an unprotected command buffer and protectedNoFault is not supported, dstBuffer must not be a protected buffer

  • VUID-vkCmdCopyImageToBuffer2-commandBuffer-01833
    If commandBuffer is a protected command buffer and protectedNoFault is not supported, dstBuffer must not be an unprotected buffer

  • VUID-vkCmdCopyImageToBuffer2-commandBuffer-07746
    If the queue family used to create the VkCommandPool which commandBuffer was allocated from does not support VK_QUEUE_GRAPHICS_BIT or VK_QUEUE_COMPUTE_BIT, the bufferOffset member of any element of pCopyImageToBufferInfo->pRegions must be a multiple of 4

  • VUID-vkCmdCopyImageToBuffer2-imageOffset-07747
    The imageOffset and imageExtent members of each element of pCopyImageToBufferInfo->pRegions must respect the image transfer granularity requirements of commandBuffer’s command pool’s queue family, as described in VkQueueFamilyProperties

Valid Usage (Implicit)
  • VUID-vkCmdCopyImageToBuffer2-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdCopyImageToBuffer2-pCopyImageToBufferInfo-parameter
    pCopyImageToBufferInfo must be a valid pointer to a valid VkCopyImageToBufferInfo2 structure

  • VUID-vkCmdCopyImageToBuffer2-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdCopyImageToBuffer2-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support transfer, graphics, or compute operations

  • VUID-vkCmdCopyImageToBuffer2-renderpass
    This command must only be called outside of a render pass instance

  • VUID-vkCmdCopyImageToBuffer2-videocoding
    This command must only be called outside of a video coding scope

Host Synchronization
  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type

Primary
Secondary

Outside

Outside

Transfer
Graphics
Compute

Action

The VkCopyImageToBufferInfo2 structure is defined as:

// Provided by VK_VERSION_1_3
typedef struct VkCopyImageToBufferInfo2 {
    VkStructureType              sType;
    const void*                  pNext;
    VkImage                      srcImage;
    VkImageLayout                srcImageLayout;
    VkBuffer                     dstBuffer;
    uint32_t                     regionCount;
    const VkBufferImageCopy2*    pRegions;
} VkCopyImageToBufferInfo2;

or the equivalent

// Provided by VK_KHR_copy_commands2
typedef VkCopyImageToBufferInfo2 VkCopyImageToBufferInfo2KHR;
  • sType is a VkStructureType value identifying this structure.

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

  • srcImage is the source image.

  • srcImageLayout is the layout of the source image subresources for the copy.

  • dstBuffer is the destination buffer.

  • regionCount is the number of regions to copy.

  • pRegions is a pointer to an array of VkBufferImageCopy2 structures specifying the regions to copy.

Valid Usage
  • VUID-VkCopyImageToBufferInfo2-pRegions-00183
    dstBuffer must be large enough to contain all buffer locations that are accessed according to Buffer and Image Addressing, for each element of pRegions

  • VUID-VkCopyImageToBufferInfo2-pRegions-00184
    The union of all source regions, and the union of all destination regions, specified by the elements of pRegions, must not overlap in memory

  • VUID-VkCopyImageToBufferInfo2-srcImage-00186
    srcImage must have been created with VK_IMAGE_USAGE_TRANSFER_SRC_BIT usage flag

  • VUID-VkCopyImageToBufferInfo2-srcImage-01998
    The format features of srcImage must contain VK_FORMAT_FEATURE_TRANSFER_SRC_BIT

  • VUID-VkCopyImageToBufferInfo2-dstBuffer-00191
    dstBuffer must have been created with VK_BUFFER_USAGE_TRANSFER_DST_BIT usage flag

  • VUID-VkCopyImageToBufferInfo2-dstBuffer-00192
    If dstBuffer is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-VkCopyImageToBufferInfo2-srcImageLayout-00189
    srcImageLayout must specify the layout of the image subresources of srcImage specified in pRegions at the time this command is executed on a VkDevice

  • VUID-VkCopyImageToBufferInfo2-srcImageLayout-01397
    srcImageLayout must be VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR, VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL, or VK_IMAGE_LAYOUT_GENERAL

  • VUID-VkCopyImageToBufferInfo2-srcImage-07966
    If srcImage is non-sparse then the image or the specified disjoint plane must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-VkCopyImageToBufferInfo2-imageSubresource-07967
    The imageSubresource.mipLevel member of each element of pRegions must be less than the mipLevels specified in VkImageCreateInfo when srcImage was created

  • VUID-VkCopyImageToBufferInfo2-imageSubresource-07968
    If imageSubresource.layerCount is not VK_REMAINING_ARRAY_LAYERS, imageSubresource.baseArrayLayer + imageSubresource.layerCount of each element of pRegions must be less than or equal to the arrayLayers specified in VkImageCreateInfo when srcImage was created

  • VUID-VkCopyImageToBufferInfo2-srcImage-07969
    srcImage must not have been created with flags containing VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT

  • VUID-VkCopyImageToBufferInfo2-srcImage-07973
    srcImage must have a sample count equal to VK_SAMPLE_COUNT_1_BIT

  • VUID-VkCopyImageToBufferInfo2-srcImage-07979
    If srcImage is of type VK_IMAGE_TYPE_1D, then for each element of pRegions, imageOffset.y must be 0 and imageExtent.height must be 1

  • VUID-VkCopyImageToBufferInfo2-imageOffset-09104
    For each element of pRegions, imageOffset.z and (imageExtent.depth + imageOffset.z) must both be greater than or equal to 0 and less than or equal to the depth of the specified imageSubresource of srcImage

  • VUID-VkCopyImageToBufferInfo2-srcImage-07980
    If srcImage is of type VK_IMAGE_TYPE_1D or VK_IMAGE_TYPE_2D, then for each element of pRegions, imageOffset.z must be 0 and imageExtent.depth must be 1

  • VUID-VkCopyImageToBufferInfo2-srcImage-07274
    For each element of pRegions, imageOffset.x must be a multiple of the texel block extent width of the VkFormat of srcImage

  • VUID-VkCopyImageToBufferInfo2-srcImage-07275
    For each element of pRegions, imageOffset.y must be a multiple of the texel block extent height of the VkFormat of srcImage

  • VUID-VkCopyImageToBufferInfo2-srcImage-07276
    For each element of pRegions, imageOffset.z must be a multiple of the texel block extent depth of the VkFormat of srcImage

  • VUID-VkCopyImageToBufferInfo2-srcImage-00207
    For each element of pRegions, if the sum of imageOffset.x and extent.width does not equal the width of the subresource specified by srcSubresource, extent.width must be a multiple of the texel block extent width of the VkFormat of srcImage

  • VUID-VkCopyImageToBufferInfo2-srcImage-00208
    For each element of pRegions, if the sum of imageOffset.y and extent.height does not equal the height of the subresource specified by srcSubresource, extent.height must be a multiple of the texel block extent height of the VkFormat of srcImage

  • VUID-VkCopyImageToBufferInfo2-srcImage-00209
    For each element of pRegions, if the sum of imageOffset.z and extent.depth does not equal the depth of the subresource specified by srcSubresource, extent.depth must be a multiple of the texel block extent depth of the VkFormat of srcImage

  • VUID-VkCopyImageToBufferInfo2-imageSubresource-09105
    For each element of pRegions, imageSubresource.aspectMask must specify aspects present in srcImage

  • VUID-VkCopyImageToBufferInfo2-srcImage-07981
    If srcImage has a multi-planar image format, then for each element of pRegions, imageSubresource.aspectMask must be a single valid multi-planar aspect mask bit

  • VUID-VkCopyImageToBufferInfo2-srcImage-07983
    If srcImage is of type VK_IMAGE_TYPE_3D, for each element of pRegions, imageSubresource.baseArrayLayer must be 0 and imageSubresource.layerCount must be 1

  • VUID-VkCopyImageToBufferInfo2-bufferRowLength-09106
    For each element of pRegions, bufferRowLength must be a multiple of the texel block extent width of the VkFormat of srcImage

  • VUID-VkCopyImageToBufferInfo2-bufferImageHeight-09107
    For each element of pRegions, bufferImageHeight must be a multiple of the texel block extent height of the VkFormat of srcImage

  • VUID-VkCopyImageToBufferInfo2-bufferRowLength-09108
    For each element of pRegions, bufferRowLength divided by the texel block extent width and then multiplied by the texel block size of srcImage must be less than or equal to 231-1

  • VUID-VkCopyImageToBufferInfo2-srcImage-07975
    If srcImage does not have either a depth/stencil format or a multi-planar format, then for each element of pRegions, bufferOffset must be a multiple of the texel block size

  • VUID-VkCopyImageToBufferInfo2-srcImage-07976
    If srcImage has a multi-planar format, then for each element of pRegions, bufferOffset must be a multiple of the element size of the compatible format for the format and the aspectMask of the imageSubresource as defined in Compatible Formats of Planes of Multi-Planar Formats

  • VUID-VkCopyImageToBufferInfo2-srcImage-07978
    If srcImage has a depth/stencil format, the bufferOffset member of any element of pRegions must be a multiple of 4

  • VUID-VkCopyImageToBufferInfo2-imageOffset-00197
    For each element of pRegions not containing VkCopyCommandTransformInfoQCOM in its pNext chain, imageOffset.x and (imageExtent.width + imageOffset.x) must both be greater than or equal to 0 and less than or equal to the width of the specified imageSubresource of srcImage

  • VUID-VkCopyImageToBufferInfo2-imageOffset-00198
    For each element of pRegions not containing VkCopyCommandTransformInfoQCOM in its pNext chain, imageOffset.y and (imageExtent.height + imageOffset.y) must both be greater than or equal to 0 and less than or equal to the height of the specified imageSubresource of srcImage

Valid Usage (Implicit)
  • VUID-VkCopyImageToBufferInfo2-sType-sType
    sType must be VK_STRUCTURE_TYPE_COPY_IMAGE_TO_BUFFER_INFO_2

  • VUID-VkCopyImageToBufferInfo2-pNext-pNext
    pNext must be NULL

  • VUID-VkCopyImageToBufferInfo2-srcImage-parameter
    srcImage must be a valid VkImage handle

  • VUID-VkCopyImageToBufferInfo2-srcImageLayout-parameter
    srcImageLayout must be a valid VkImageLayout value

  • VUID-VkCopyImageToBufferInfo2-dstBuffer-parameter
    dstBuffer must be a valid VkBuffer handle

  • VUID-VkCopyImageToBufferInfo2-pRegions-parameter
    pRegions must be a valid pointer to an array of regionCount valid VkBufferImageCopy2 structures

  • VUID-VkCopyImageToBufferInfo2-regionCount-arraylength
    regionCount must be greater than 0

  • VUID-VkCopyImageToBufferInfo2-commonparent
    Both of dstBuffer, and srcImage must have been created, allocated, or retrieved from the same VkDevice

For both vkCmdCopyBufferToImage2 and vkCmdCopyImageToBuffer2, each element of pRegions is a structure defined as:

// Provided by VK_VERSION_1_3
typedef struct VkBufferImageCopy2 {
    VkStructureType             sType;
    const void*                 pNext;
    VkDeviceSize                bufferOffset;
    uint32_t                    bufferRowLength;
    uint32_t                    bufferImageHeight;
    VkImageSubresourceLayers    imageSubresource;
    VkOffset3D                  imageOffset;
    VkExtent3D                  imageExtent;
} VkBufferImageCopy2;

or the equivalent

// Provided by VK_KHR_copy_commands2
typedef VkBufferImageCopy2 VkBufferImageCopy2KHR;
  • sType is a VkStructureType value identifying this structure.

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

  • bufferOffset is the offset in bytes from the start of the buffer object where the image data is copied from or to.

  • bufferRowLength and bufferImageHeight specify in texels a subregion of a larger two- or three-dimensional image in buffer memory, and control the addressing calculations. If either of these values is zero, that aspect of the buffer memory is considered to be tightly packed according to the imageExtent.

  • imageSubresource is a VkImageSubresourceLayers used to specify the specific image subresources of the image used for the source or destination image data.

  • imageOffset selects the initial x, y, z offsets in texels of the sub-region of the source or destination image data.

  • imageExtent is the size in texels of the image to copy in width, height and depth.

This structure is functionally identical to VkBufferImageCopy, but adds sType and pNext parameters, allowing it to be more easily extended.

Valid Usage
  • VUID-VkBufferImageCopy2-bufferRowLength-09101
    bufferRowLength must be 0, or greater than or equal to the width member of imageExtent

  • VUID-VkBufferImageCopy2-bufferImageHeight-09102
    bufferImageHeight must be 0, or greater than or equal to the height member of imageExtent

  • VUID-VkBufferImageCopy2-aspectMask-09103
    The aspectMask member of imageSubresource must only have a single bit set

  • VUID-VkBufferImageCopy2-imageExtent-06659
    imageExtent.width must not be 0

  • VUID-VkBufferImageCopy2-imageExtent-06660
    imageExtent.height must not be 0

  • VUID-VkBufferImageCopy2-imageExtent-06661
    imageExtent.depth must not be 0

Valid Usage (Implicit)
  • VUID-VkBufferImageCopy2-sType-sType
    sType must be VK_STRUCTURE_TYPE_BUFFER_IMAGE_COPY_2

  • VUID-VkBufferImageCopy2-pNext-pNext
    pNext must be NULL or a pointer to a valid instance of VkCopyCommandTransformInfoQCOM

  • VUID-VkBufferImageCopy2-sType-unique
    The sType value of each struct in the pNext chain must be unique

  • VUID-VkBufferImageCopy2-imageSubresource-parameter
    imageSubresource must be a valid VkImageSubresourceLayers structure

The VkCopyCommandTransformInfoQCOM structure is defined as:

// Provided by VK_QCOM_rotated_copy_commands
typedef struct VkCopyCommandTransformInfoQCOM {
    VkStructureType                  sType;
    const void*                      pNext;
    VkSurfaceTransformFlagBitsKHR    transform;
} VkCopyCommandTransformInfoQCOM;
  • sType is a VkStructureType value identifying this structure.

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

  • transform is a VkSurfaceTransformFlagBitsKHR value describing the transform to be applied.

Including this structure in the pNext chain of VkBufferImageCopy2 defines a rotation to be performed when copying between an image and a buffer. Including this structure in the pNext chain of VkBlitImageInfo2 defines a rotation to be performed when blitting between two images. If this structure is not specified in either case, the implementation behaves as if it was specified with a transform equal to VK_SURFACE_TRANSFORM_IDENTITY_BIT_KHR.

Specifying a transform for a copy between an image and a buffer rotates the region accessed in the image around the offset. Specifying a transform for a blit performs a similar transform as described in Image Blits with Scaling and Rotation.

Rotations other than VK_SURFACE_TRANSFORM_IDENTITY_BIT_KHR can only be specified for single-plane 2D images with a 1x1x1 texel block extent.

Valid Usage
  • VUID-VkCopyCommandTransformInfoQCOM-transform-04560
    transform must be VK_SURFACE_TRANSFORM_IDENTITY_BIT_KHR, VK_SURFACE_TRANSFORM_ROTATE_90_BIT_KHR, VK_SURFACE_TRANSFORM_ROTATE_180_BIT_KHR, or VK_SURFACE_TRANSFORM_ROTATE_270_BIT_KHR

Valid Usage (Implicit)
  • VUID-VkCopyCommandTransformInfoQCOM-sType-sType
    sType must be VK_STRUCTURE_TYPE_COPY_COMMAND_TRANSFORM_INFO_QCOM

The following commands can be used to copy between host memory and images.

To copy data from host memory to an image object, call:

// Provided by VK_EXT_host_image_copy
VkResult vkCopyMemoryToImageEXT(
    VkDevice                                    device,
    const VkCopyMemoryToImageInfoEXT*           pCopyMemoryToImageInfo);
  • device is the device which owns pCopyMemoryToImageInfo->dstImage.

  • pCopyMemoryToImageInfo is a pointer to a VkCopyMemoryToImageInfoEXT structure describing the copy parameters.

This command is functionally similar to vkCmdCopyBufferToImage2, except it is executed on the host and reads from host memory instead of a buffer. The memory of pCopyMemoryToImageInfo->dstImage is accessed by the host as if coherent.

Note

Because queue submissions automatically make host memory visible to the device, there would not be a need for a memory barrier before using the results of this copy operation on the device.

Valid Usage
  • VUID-vkCopyMemoryToImageEXT-hostImageCopy-09058
    The hostImageCopy feature must be enabled

Valid Usage (Implicit)
  • VUID-vkCopyMemoryToImageEXT-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkCopyMemoryToImageEXT-pCopyMemoryToImageInfo-parameter
    pCopyMemoryToImageInfo must be a valid pointer to a valid VkCopyMemoryToImageInfoEXT structure

Return Codes
Success
  • VK_SUCCESS

Failure
  • VK_ERROR_INITIALIZATION_FAILED

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

  • VK_ERROR_MEMORY_MAP_FAILED

The VkCopyMemoryToImageInfoEXT structure is defined as:

// Provided by VK_EXT_host_image_copy
typedef struct VkCopyMemoryToImageInfoEXT {
    VkStructureType                  sType;
    const void*                      pNext;
    VkHostImageCopyFlagsEXT          flags;
    VkImage                          dstImage;
    VkImageLayout                    dstImageLayout;
    uint32_t                         regionCount;
    const VkMemoryToImageCopyEXT*    pRegions;
} VkCopyMemoryToImageInfoEXT;
  • sType is a VkStructureType value identifying this structure.

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

  • flags is a bitmask of VkHostImageCopyFlagBitsEXT values describing additional copy parameters.

  • dstImage is the destination image.

  • dstImageLayout is the layout of the destination image subresources for the copy.

  • regionCount is the number of regions to copy.

  • pRegions is a pointer to an array of VkMemoryToImageCopyEXT structures specifying the regions to copy.

vkCopyMemoryToImageEXT does not check whether the device memory associated with dstImage is currently in use before performing the copy. The application must guarantee that any previously submitted command that reads from or writes to the copy regions has completed before the host performs the copy.

Copy regions for the image must be aligned to a multiple of the texel block extent in each dimension, except at the edges of the image, where region extents must match the edge of the image.

Valid Usage
  • VUID-VkCopyMemoryToImageInfoEXT-dstImage-09109
    If dstImage is sparse then all memory ranges accessed by the copy command must be bound as described in Binding Resource Memory

  • VUID-VkCopyMemoryToImageInfoEXT-dstImage-09111
    If the stencil aspect of dstImage is accessed, and dstImage was not created with separate stencil usage, dstImage must have been created with VK_IMAGE_USAGE_HOST_TRANSFER_BIT_EXT set in VkImageCreateInfo::usage

  • VUID-VkCopyMemoryToImageInfoEXT-dstImage-09112
    If the stencil aspect of dstImage is accessed, and dstImage was created with separate stencil usage, dstImage must have been created with VK_IMAGE_USAGE_HOST_TRANSFER_BIT_EXT set in VkImageStencilUsageCreateInfo::stencilUsage

  • VUID-VkCopyMemoryToImageInfoEXT-dstImage-09113
    If non-stencil aspects of dstImage are accessed, dstImage must have been created with VK_IMAGE_USAGE_HOST_TRANSFER_BIT_EXT set in VkImageCreateInfo::usage

  • VUID-VkCopyMemoryToImageInfoEXT-imageOffset-09114
    If flags contains VK_HOST_IMAGE_COPY_MEMCPY_EXT, the x, y, and z members of the imageOffset member of each element of pRegions must be 0

  • VUID-VkCopyMemoryToImageInfoEXT-dstImage-09115
    If flags contains VK_HOST_IMAGE_COPY_MEMCPY_EXT, the imageExtent member of each element of pRegions must equal the extents of dstImage identified by imageSubresource

  • VUID-VkCopyMemoryToImageInfoEXT-dstImage-07966
    If dstImage is non-sparse then the image or the specified disjoint plane must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-VkCopyMemoryToImageInfoEXT-imageSubresource-07967
    The imageSubresource.mipLevel member of each element of pRegions must be less than the mipLevels specified in VkImageCreateInfo when dstImage was created

  • VUID-VkCopyMemoryToImageInfoEXT-imageSubresource-07968
    If imageSubresource.layerCount is not VK_REMAINING_ARRAY_LAYERS, imageSubresource.baseArrayLayer + imageSubresource.layerCount of each element of pRegions must be less than or equal to the arrayLayers specified in VkImageCreateInfo when dstImage was created

  • VUID-VkCopyMemoryToImageInfoEXT-dstImage-07969
    dstImage must not have been created with flags containing VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT

  • VUID-VkCopyMemoryToImageInfoEXT-imageSubresource-07970
    The image region specified by each element of pRegions must be contained within the specified imageSubresource of dstImage

  • VUID-VkCopyMemoryToImageInfoEXT-imageSubresource-07971
    For each element of pRegions, imageOffset.x and (imageExtent.width + imageOffset.x) must both be greater than or equal to 0 and less than or equal to the width of the specified imageSubresource of dstImage

  • VUID-VkCopyMemoryToImageInfoEXT-imageSubresource-07972
    For each element of pRegions, imageOffset.y and (imageExtent.height + imageOffset.y) must both be greater than or equal to 0 and less than or equal to the height of the specified imageSubresource of dstImage

  • VUID-VkCopyMemoryToImageInfoEXT-dstImage-07973
    dstImage must have a sample count equal to VK_SAMPLE_COUNT_1_BIT

  • VUID-VkCopyMemoryToImageInfoEXT-dstImage-07979
    If dstImage is of type VK_IMAGE_TYPE_1D, then for each element of pRegions, imageOffset.y must be 0 and imageExtent.height must be 1

  • VUID-VkCopyMemoryToImageInfoEXT-imageOffset-09104
    For each element of pRegions, imageOffset.z and (imageExtent.depth + imageOffset.z) must both be greater than or equal to 0 and less than or equal to the depth of the specified imageSubresource of dstImage

  • VUID-VkCopyMemoryToImageInfoEXT-dstImage-07980
    If dstImage is of type VK_IMAGE_TYPE_1D or VK_IMAGE_TYPE_2D, then for each element of pRegions, imageOffset.z must be 0 and imageExtent.depth must be 1

  • VUID-VkCopyMemoryToImageInfoEXT-dstImage-07274
    For each element of pRegions, imageOffset.x must be a multiple of the texel block extent width of the VkFormat of dstImage

  • VUID-VkCopyMemoryToImageInfoEXT-dstImage-07275
    For each element of pRegions, imageOffset.y must be a multiple of the texel block extent height of the VkFormat of dstImage

  • VUID-VkCopyMemoryToImageInfoEXT-dstImage-07276
    For each element of pRegions, imageOffset.z must be a multiple of the texel block extent depth of the VkFormat of dstImage

  • VUID-VkCopyMemoryToImageInfoEXT-dstImage-00207
    For each element of pRegions, if the sum of imageOffset.x and extent.width does not equal the width of the subresource specified by srcSubresource, extent.width must be a multiple of the texel block extent width of the VkFormat of dstImage

  • VUID-VkCopyMemoryToImageInfoEXT-dstImage-00208
    For each element of pRegions, if the sum of imageOffset.y and extent.height does not equal the height of the subresource specified by srcSubresource, extent.height must be a multiple of the texel block extent height of the VkFormat of dstImage

  • VUID-VkCopyMemoryToImageInfoEXT-dstImage-00209
    For each element of pRegions, if the sum of imageOffset.z and extent.depth does not equal the depth of the subresource specified by srcSubresource, extent.depth must be a multiple of the texel block extent depth of the VkFormat of dstImage

  • VUID-VkCopyMemoryToImageInfoEXT-imageSubresource-09105
    For each element of pRegions, imageSubresource.aspectMask must specify aspects present in dstImage

  • VUID-VkCopyMemoryToImageInfoEXT-dstImage-07981
    If dstImage has a multi-planar image format, then for each element of pRegions, imageSubresource.aspectMask must be a single valid multi-planar aspect mask bit

  • VUID-VkCopyMemoryToImageInfoEXT-dstImage-07983
    If dstImage is of type VK_IMAGE_TYPE_3D, for each element of pRegions, imageSubresource.baseArrayLayer must be 0 and imageSubresource.layerCount must be 1

  • VUID-VkCopyMemoryToImageInfoEXT-memoryRowLength-09106
    For each element of pRegions, memoryRowLength must be a multiple of the texel block extent width of the VkFormat of dstImage

  • VUID-VkCopyMemoryToImageInfoEXT-memoryImageHeight-09107
    For each element of pRegions, memoryImageHeight must be a multiple of the texel block extent height of the VkFormat of dstImage

  • VUID-VkCopyMemoryToImageInfoEXT-memoryRowLength-09108
    For each element of pRegions, memoryRowLength divided by the texel block extent width and then multiplied by the texel block size of dstImage must be less than or equal to 231-1

  • VUID-VkCopyMemoryToImageInfoEXT-dstImageLayout-09059
    dstImageLayout must specify the current layout of the image subresources of dstImage specified in pRegions

  • VUID-VkCopyMemoryToImageInfoEXT-dstImageLayout-09060
    dstImageLayout must be one of the image layouts returned in VkPhysicalDeviceHostImageCopyPropertiesEXT::pCopyDstLayouts

  • VUID-VkCopyMemoryToImageInfoEXT-flags-09393
    If flags includes VK_HOST_IMAGE_COPY_MEMCPY_EXT, for each region in pRegions, memoryRowLength and memoryImageHeight must both be 0

Valid Usage (Implicit)
  • VUID-VkCopyMemoryToImageInfoEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_COPY_MEMORY_TO_IMAGE_INFO_EXT

  • VUID-VkCopyMemoryToImageInfoEXT-pNext-pNext
    pNext must be NULL

  • VUID-VkCopyMemoryToImageInfoEXT-flags-parameter
    flags must be a valid combination of VkHostImageCopyFlagBitsEXT values

  • VUID-VkCopyMemoryToImageInfoEXT-dstImage-parameter
    dstImage must be a valid VkImage handle

  • VUID-VkCopyMemoryToImageInfoEXT-dstImageLayout-parameter
    dstImageLayout must be a valid VkImageLayout value

  • VUID-VkCopyMemoryToImageInfoEXT-pRegions-parameter
    pRegions must be a valid pointer to an array of regionCount valid VkMemoryToImageCopyEXT structures

  • VUID-VkCopyMemoryToImageInfoEXT-regionCount-arraylength
    regionCount must be greater than 0

Each element of VkCopyMemoryToImageInfoEXT::pRegions is a structure defined as:

// Provided by VK_EXT_host_image_copy
typedef struct VkMemoryToImageCopyEXT {
    VkStructureType             sType;
    const void*                 pNext;
    const void*                 pHostPointer;
    uint32_t                    memoryRowLength;
    uint32_t                    memoryImageHeight;
    VkImageSubresourceLayers    imageSubresource;
    VkOffset3D                  imageOffset;
    VkExtent3D                  imageExtent;
} VkMemoryToImageCopyEXT;
  • sType is a VkStructureType value identifying this structure.

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

  • pHostPointer is the host memory address which is the source of the copy.

  • memoryRowLength and memoryImageHeight specify in texels a subregion of a larger two- or three-dimensional image in host memory, and control the addressing calculations. If either of these values is zero, that aspect of the host memory is considered to be tightly packed according to the imageExtent.

  • imageSubresource is a VkImageSubresourceLayers used to specify the specific image subresources of the image used for the source or destination image data.

  • imageOffset selects the initial x, y, z offsets in texels of the sub-region of the destination image data.

  • imageExtent is the size in texels of the image to copy in width, height and depth.

This structure is functionally similar to VkBufferImageCopy2, except it defines host memory as the source of copy instead of a buffer. In particular, the same data packing rules and restrictions as that structure apply here as well.

Valid Usage
  • VUID-VkMemoryToImageCopyEXT-pHostPointer-09061
    pHostPointer must point to memory that is large enough to contain all memory locations that are accessed according to Buffer and Image Addressing, for each element of pRegions

  • VUID-VkMemoryToImageCopyEXT-pRegions-09062
    The union of all source regions, and the union of all destination regions, specified by the elements of pRegions, must not overlap in memory

  • VUID-VkMemoryToImageCopyEXT-memoryRowLength-09101
    memoryRowLength must be 0, or greater than or equal to the width member of imageExtent

  • VUID-VkMemoryToImageCopyEXT-memoryImageHeight-09102
    memoryImageHeight must be 0, or greater than or equal to the height member of imageExtent

  • VUID-VkMemoryToImageCopyEXT-aspectMask-09103
    The aspectMask member of imageSubresource must only have a single bit set

  • VUID-VkMemoryToImageCopyEXT-imageExtent-06659
    imageExtent.width must not be 0

  • VUID-VkMemoryToImageCopyEXT-imageExtent-06660
    imageExtent.height must not be 0

  • VUID-VkMemoryToImageCopyEXT-imageExtent-06661
    imageExtent.depth must not be 0

Valid Usage (Implicit)
  • VUID-VkMemoryToImageCopyEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_MEMORY_TO_IMAGE_COPY_EXT

  • VUID-VkMemoryToImageCopyEXT-pNext-pNext
    pNext must be NULL

  • VUID-VkMemoryToImageCopyEXT-pHostPointer-parameter
    pHostPointer must be a pointer value

  • VUID-VkMemoryToImageCopyEXT-imageSubresource-parameter
    imageSubresource must be a valid VkImageSubresourceLayers structure

To copy data from an image object to host memory, call:

// Provided by VK_EXT_host_image_copy
VkResult vkCopyImageToMemoryEXT(
    VkDevice                                    device,
    const VkCopyImageToMemoryInfoEXT*           pCopyImageToMemoryInfo);
  • device is the device which owns pCopyImageToMemoryInfo->srcImage.

  • pCopyImageToMemoryInfo is a pointer to a VkCopyImageToMemoryInfoEXT structure describing the copy parameters.

This command is functionally similar to vkCmdCopyImageToBuffer2, except it is executed on the host and writes to host memory instead of a buffer. The memory of pCopyImageToMemoryInfo->srcImage is accessed by the host as if coherent.

Note

If the device has written to the image memory, it is not automatically made available to the host. Before this copy command can be called, a memory barrier for this image must have been issued on the device with the second synchronization scope including VK_PIPELINE_STAGE_HOST_BIT and VK_ACCESS_HOST_READ_BIT.

Valid Usage
  • VUID-vkCopyImageToMemoryEXT-hostImageCopy-09063
    The hostImageCopy feature must be enabled

Valid Usage (Implicit)
  • VUID-vkCopyImageToMemoryEXT-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkCopyImageToMemoryEXT-pCopyImageToMemoryInfo-parameter
    pCopyImageToMemoryInfo must be a valid pointer to a valid VkCopyImageToMemoryInfoEXT structure

Return Codes
Success
  • VK_SUCCESS

Failure
  • VK_ERROR_INITIALIZATION_FAILED

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

  • VK_ERROR_MEMORY_MAP_FAILED

The VkCopyImageToMemoryInfoEXT structure is defined as:

// Provided by VK_EXT_host_image_copy
typedef struct VkCopyImageToMemoryInfoEXT {
    VkStructureType                  sType;
    const void*                      pNext;
    VkHostImageCopyFlagsEXT          flags;
    VkImage                          srcImage;
    VkImageLayout                    srcImageLayout;
    uint32_t                         regionCount;
    const VkImageToMemoryCopyEXT*    pRegions;
} VkCopyImageToMemoryInfoEXT;
  • sType is a VkStructureType value identifying this structure.

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

  • flags is a bitmask of VkHostImageCopyFlagBitsEXT values describing additional copy parameters.

  • srcImage is the source image.

  • srcImageLayout is the layout of the source image subresources for the copy.

  • regionCount is the number of regions to copy.

  • pRegions is a pointer to an array of VkImageToMemoryCopyEXT structures specifying the regions to copy.

vkCopyImageToMemoryEXT does not check whether the device memory associated with srcImage is currently in use before performing the copy. The application must guarantee that any previously submitted command that writes to the copy regions has completed before the host performs the copy.

Copy regions for the image must be aligned to a multiple of the texel block extent in each dimension, except at the edges of the image, where region extents must match the edge of the image.

Valid Usage
  • VUID-VkCopyImageToMemoryInfoEXT-srcImage-09109
    If srcImage is sparse then all memory ranges accessed by the copy command must be bound as described in Binding Resource Memory

  • VUID-VkCopyImageToMemoryInfoEXT-srcImage-09111
    If the stencil aspect of srcImage is accessed, and srcImage was not created with separate stencil usage, srcImage must have been created with VK_IMAGE_USAGE_HOST_TRANSFER_BIT_EXT set in VkImageCreateInfo::usage

  • VUID-VkCopyImageToMemoryInfoEXT-srcImage-09112
    If the stencil aspect of srcImage is accessed, and srcImage was created with separate stencil usage, srcImage must have been created with VK_IMAGE_USAGE_HOST_TRANSFER_BIT_EXT set in VkImageStencilUsageCreateInfo::stencilUsage

  • VUID-VkCopyImageToMemoryInfoEXT-srcImage-09113
    If non-stencil aspects of srcImage are accessed, srcImage must have been created with VK_IMAGE_USAGE_HOST_TRANSFER_BIT_EXT set in VkImageCreateInfo::usage

  • VUID-VkCopyImageToMemoryInfoEXT-imageOffset-09114
    If flags contains VK_HOST_IMAGE_COPY_MEMCPY_EXT, the x, y, and z members of the imageOffset member of each element of pRegions must be 0

  • VUID-VkCopyImageToMemoryInfoEXT-srcImage-09115
    If flags contains VK_HOST_IMAGE_COPY_MEMCPY_EXT, the imageExtent member of each element of pRegions must equal the extents of srcImage identified by imageSubresource

  • VUID-VkCopyImageToMemoryInfoEXT-srcImage-07966
    If srcImage is non-sparse then the image or the specified disjoint plane must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-VkCopyImageToMemoryInfoEXT-imageSubresource-07967
    The imageSubresource.mipLevel member of each element of pRegions must be less than the mipLevels specified in VkImageCreateInfo when srcImage was created

  • VUID-VkCopyImageToMemoryInfoEXT-imageSubresource-07968
    If imageSubresource.layerCount is not VK_REMAINING_ARRAY_LAYERS, imageSubresource.baseArrayLayer + imageSubresource.layerCount of each element of pRegions must be less than or equal to the arrayLayers specified in VkImageCreateInfo when srcImage was created

  • VUID-VkCopyImageToMemoryInfoEXT-srcImage-07969
    srcImage must not have been created with flags containing VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT

  • VUID-VkCopyImageToMemoryInfoEXT-imageSubresource-07970
    The image region specified by each element of pRegions must be contained within the specified imageSubresource of srcImage

  • VUID-VkCopyImageToMemoryInfoEXT-imageSubresource-07971
    For each element of pRegions, imageOffset.x and (imageExtent.width + imageOffset.x) must both be greater than or equal to 0 and less than or equal to the width of the specified imageSubresource of srcImage

  • VUID-VkCopyImageToMemoryInfoEXT-imageSubresource-07972
    For each element of pRegions, imageOffset.y and (imageExtent.height + imageOffset.y) must both be greater than or equal to 0 and less than or equal to the height of the specified imageSubresource of srcImage

  • VUID-VkCopyImageToMemoryInfoEXT-srcImage-07973
    srcImage must have a sample count equal to VK_SAMPLE_COUNT_1_BIT

  • VUID-VkCopyImageToMemoryInfoEXT-srcImage-07979
    If srcImage is of type VK_IMAGE_TYPE_1D, then for each element of pRegions, imageOffset.y must be 0 and imageExtent.height must be 1

  • VUID-VkCopyImageToMemoryInfoEXT-imageOffset-09104
    For each element of pRegions, imageOffset.z and (imageExtent.depth + imageOffset.z) must both be greater than or equal to 0 and less than or equal to the depth of the specified imageSubresource of srcImage

  • VUID-VkCopyImageToMemoryInfoEXT-srcImage-07980
    If srcImage is of type VK_IMAGE_TYPE_1D or VK_IMAGE_TYPE_2D, then for each element of pRegions, imageOffset.z must be 0 and imageExtent.depth must be 1

  • VUID-VkCopyImageToMemoryInfoEXT-srcImage-07274
    For each element of pRegions, imageOffset.x must be a multiple of the texel block extent width of the VkFormat of srcImage

  • VUID-VkCopyImageToMemoryInfoEXT-srcImage-07275
    For each element of pRegions, imageOffset.y must be a multiple of the texel block extent height of the VkFormat of srcImage

  • VUID-VkCopyImageToMemoryInfoEXT-srcImage-07276
    For each element of pRegions, imageOffset.z must be a multiple of the texel block extent depth of the VkFormat of srcImage

  • VUID-VkCopyImageToMemoryInfoEXT-srcImage-00207
    For each element of pRegions, if the sum of imageOffset.x and extent.width does not equal the width of the subresource specified by srcSubresource, extent.width must be a multiple of the texel block extent width of the VkFormat of srcImage

  • VUID-VkCopyImageToMemoryInfoEXT-srcImage-00208
    For each element of pRegions, if the sum of imageOffset.y and extent.height does not equal the height of the subresource specified by srcSubresource, extent.height must be a multiple of the texel block extent height of the VkFormat of srcImage

  • VUID-VkCopyImageToMemoryInfoEXT-srcImage-00209
    For each element of pRegions, if the sum of imageOffset.z and extent.depth does not equal the depth of the subresource specified by srcSubresource, extent.depth must be a multiple of the texel block extent depth of the VkFormat of srcImage

  • VUID-VkCopyImageToMemoryInfoEXT-imageSubresource-09105
    For each element of pRegions, imageSubresource.aspectMask must specify aspects present in srcImage

  • VUID-VkCopyImageToMemoryInfoEXT-srcImage-07981
    If srcImage has a multi-planar image format, then for each element of pRegions, imageSubresource.aspectMask must be a single valid multi-planar aspect mask bit

  • VUID-VkCopyImageToMemoryInfoEXT-srcImage-07983
    If srcImage is of type VK_IMAGE_TYPE_3D, for each element of pRegions, imageSubresource.baseArrayLayer must be 0 and imageSubresource.layerCount must be 1

  • VUID-VkCopyImageToMemoryInfoEXT-memoryRowLength-09106
    For each element of pRegions, memoryRowLength must be a multiple of the texel block extent width of the VkFormat of srcImage

  • VUID-VkCopyImageToMemoryInfoEXT-memoryImageHeight-09107
    For each element of pRegions, memoryImageHeight must be a multiple of the texel block extent height of the VkFormat of srcImage

  • VUID-VkCopyImageToMemoryInfoEXT-memoryRowLength-09108
    For each element of pRegions, memoryRowLength divided by the texel block extent width and then multiplied by the texel block size of srcImage must be less than or equal to 231-1

  • VUID-VkCopyImageToMemoryInfoEXT-srcImageLayout-09064
    srcImageLayout must specify the current layout of the image subresources of srcImage specified in pRegions

  • VUID-VkCopyImageToMemoryInfoEXT-srcImageLayout-09065
    srcImageLayout must be one of the image layouts returned in VkPhysicalDeviceHostImageCopyPropertiesEXT::pCopySrcLayouts

  • VUID-VkCopyImageToMemoryInfoEXT-flags-09394
    If flags includes VK_HOST_IMAGE_COPY_MEMCPY_EXT, for each region in pRegions, memoryRowLength and memoryImageHeight must both be 0

Valid Usage (Implicit)
  • VUID-VkCopyImageToMemoryInfoEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_COPY_IMAGE_TO_MEMORY_INFO_EXT

  • VUID-VkCopyImageToMemoryInfoEXT-pNext-pNext
    pNext must be NULL

  • VUID-VkCopyImageToMemoryInfoEXT-flags-parameter
    flags must be a valid combination of VkHostImageCopyFlagBitsEXT values

  • VUID-VkCopyImageToMemoryInfoEXT-srcImage-parameter
    srcImage must be a valid VkImage handle

  • VUID-VkCopyImageToMemoryInfoEXT-srcImageLayout-parameter
    srcImageLayout must be a valid VkImageLayout value

  • VUID-VkCopyImageToMemoryInfoEXT-pRegions-parameter
    pRegions must be a valid pointer to an array of regionCount valid VkImageToMemoryCopyEXT structures

  • VUID-VkCopyImageToMemoryInfoEXT-regionCount-arraylength
    regionCount must be greater than 0

Each element of VkCopyImageToMemoryInfoEXT::pRegions is a structure defined as:

// Provided by VK_EXT_host_image_copy
typedef struct VkImageToMemoryCopyEXT {
    VkStructureType             sType;
    const void*                 pNext;
    void*                       pHostPointer;
    uint32_t                    memoryRowLength;
    uint32_t                    memoryImageHeight;
    VkImageSubresourceLayers    imageSubresource;
    VkOffset3D                  imageOffset;
    VkExtent3D                  imageExtent;
} VkImageToMemoryCopyEXT;
  • sType is a VkStructureType value identifying this structure.

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

  • pHostPointer is the host memory address which is the destination of the copy.

  • memoryRowLength and memoryImageHeight specify in texels a subregion of a larger two- or three-dimensional image in host memory, and control the addressing calculations. If either of these values is zero, that aspect of the host memory is considered to be tightly packed according to the imageExtent.

  • imageSubresource is a VkImageSubresourceLayers used to specify the specific image subresources of the image used for the source or destination image data.

  • imageOffset selects the initial x, y, z offsets in texels of the sub-region of the source image data.

  • imageExtent is the size in texels of the image to copy in width, height and depth.

This structure is functionally similar to VkBufferImageCopy2, except it defines host memory as the target of copy instead of a buffer. In particular, the same data packing rules and restrictions as that structure apply here as well.

Valid Usage
  • VUID-VkImageToMemoryCopyEXT-pHostPointer-09066
    pHostPointer must point to memory that is large enough to contain all memory locations that are accessed according to Buffer and Image Addressing, for each element of pRegions

  • VUID-VkImageToMemoryCopyEXT-pRegions-09067
    The union of all source regions, and the union of all destination regions, specified by the elements of pRegions, must not overlap in memory

  • VUID-VkImageToMemoryCopyEXT-memoryRowLength-09101
    memoryRowLength must be 0, or greater than or equal to the width member of imageExtent

  • VUID-VkImageToMemoryCopyEXT-memoryImageHeight-09102
    memoryImageHeight must be 0, or greater than or equal to the height member of imageExtent

  • VUID-VkImageToMemoryCopyEXT-aspectMask-09103
    The aspectMask member of imageSubresource must only have a single bit set

  • VUID-VkImageToMemoryCopyEXT-imageExtent-06659
    imageExtent.width must not be 0

  • VUID-VkImageToMemoryCopyEXT-imageExtent-06660
    imageExtent.height must not be 0

  • VUID-VkImageToMemoryCopyEXT-imageExtent-06661
    imageExtent.depth must not be 0

Valid Usage (Implicit)
  • VUID-VkImageToMemoryCopyEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_IMAGE_TO_MEMORY_COPY_EXT

  • VUID-VkImageToMemoryCopyEXT-pNext-pNext
    pNext must be NULL

  • VUID-VkImageToMemoryCopyEXT-pHostPointer-parameter
    pHostPointer must be a pointer value

  • VUID-VkImageToMemoryCopyEXT-imageSubresource-parameter
    imageSubresource must be a valid VkImageSubresourceLayers structure

Bits which can be set in VkCopyMemoryToImageInfoEXT::flags, VkCopyImageToMemoryInfoEXT::flags, and VkCopyImageToImageInfoEXT::flags, specifying additional copy parameters are:

// Provided by VK_EXT_host_image_copy
typedef enum VkHostImageCopyFlagBitsEXT {
    VK_HOST_IMAGE_COPY_MEMCPY_EXT = 0x00000001,
} VkHostImageCopyFlagBitsEXT;
  • VK_HOST_IMAGE_COPY_MEMCPY_EXT specifies that no memory layout swizzling is to be applied during data copy. For copies between memory and images, this flag indicates that image data in host memory is swizzled in exactly the same way as the image data on the device. Using this flag indicates that the implementations may use a simple memory copy to transfer the data between the host memory and the device memory. The format of the swizzled data in host memory is platform dependent and is not defined in this specification.

// Provided by VK_EXT_host_image_copy
typedef VkFlags VkHostImageCopyFlagsEXT;

VkHostImageCopyFlagsEXT is a bitmask type for setting a mask of zero or more VkHostImageCopyFlagBitsEXT.

To copy data from an image object to another image object using the host, call:

// Provided by VK_EXT_host_image_copy
VkResult vkCopyImageToImageEXT(
    VkDevice                                    device,
    const VkCopyImageToImageInfoEXT*            pCopyImageToImageInfo);
  • device is the device which owns pCopyImageToImageInfo->srcImage and pCopyImageToImageInfo->dstImage.

  • pCopyImageToImageInfo is a pointer to a VkCopyImageToImageInfoEXT structure describing the copy parameters.

This command is functionally similar to vkCmdCopyImage2, except it is executed on the host. The memory of pCopyImageToImageInfo->srcImage and pCopyImageToImageInfo->dstImage is accessed by the host as if coherent.

Note

If the device has written to the memory of pCopyImageToImageInfo->srcImage, it is not automatically made available to the host. Before this copy command can be called, a memory barrier for this image must have been issued on the device with the second synchronization scope including VK_PIPELINE_STAGE_HOST_BIT and VK_ACCESS_HOST_READ_BIT.

Because queue submissions automatically make host memory visible to the device, there would not be a need for a memory barrier before using the results of this copy operation in pCopyMemoryToImageInfo->dstImage on the device.

Valid Usage
  • VUID-vkCopyImageToImageEXT-hostImageCopy-09068
    The hostImageCopy feature must be enabled

Valid Usage (Implicit)
  • VUID-vkCopyImageToImageEXT-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkCopyImageToImageEXT-pCopyImageToImageInfo-parameter
    pCopyImageToImageInfo must be a valid pointer to a valid VkCopyImageToImageInfoEXT structure

Return Codes
Success
  • VK_SUCCESS

Failure
  • VK_ERROR_INITIALIZATION_FAILED

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

  • VK_ERROR_MEMORY_MAP_FAILED

The VkCopyImageToImageInfoEXT structure is defined as:

// Provided by VK_EXT_host_image_copy
typedef struct VkCopyImageToImageInfoEXT {
    VkStructureType            sType;
    const void*                pNext;
    VkHostImageCopyFlagsEXT    flags;
    VkImage                    srcImage;
    VkImageLayout              srcImageLayout;
    VkImage                    dstImage;
    VkImageLayout              dstImageLayout;
    uint32_t                   regionCount;
    const VkImageCopy2*        pRegions;
} VkCopyImageToImageInfoEXT;
  • sType is a VkStructureType value identifying this structure.

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

  • flags is a bitmask of VkHostImageCopyFlagBitsEXT values describing additional copy parameters.

  • srcImage is the source image.

  • srcImageLayout is the layout of the source image subresources for the copy.

  • dstImage is the destination image.

  • dstImageLayout is the layout of the destination image subresources for the copy.

  • regionCount is the number of regions to copy.

  • pRegions is a pointer to an array of VkImageCopy2 structures specifying the regions to copy.

vkCopyImageToImageEXT does not check whether the device memory associated with srcImage or dstImage is currently in use before performing the copy. The application must guarantee that any previously submitted command that writes to the copy regions has completed before the host performs the copy.

Valid Usage
  • VUID-VkCopyImageToImageInfoEXT-srcImage-09069
    srcImage and dstImage must have been created with identical image creation parameters

  • VUID-VkCopyImageToImageInfoEXT-srcImage-09109
    If srcImage is sparse then all memory ranges accessed by the copy command must be bound as described in Binding Resource Memory

  • VUID-VkCopyImageToImageInfoEXT-srcImage-09111
    If the stencil aspect of srcImage is accessed, and srcImage was not created with separate stencil usage, srcImage must have been created with VK_IMAGE_USAGE_HOST_TRANSFER_BIT_EXT set in VkImageCreateInfo::usage

  • VUID-VkCopyImageToImageInfoEXT-srcImage-09112
    If the stencil aspect of srcImage is accessed, and srcImage was created with separate stencil usage, srcImage must have been created with VK_IMAGE_USAGE_HOST_TRANSFER_BIT_EXT set in VkImageStencilUsageCreateInfo::stencilUsage

  • VUID-VkCopyImageToImageInfoEXT-srcImage-09113
    If non-stencil aspects of srcImage are accessed, srcImage must have been created with VK_IMAGE_USAGE_HOST_TRANSFER_BIT_EXT set in VkImageCreateInfo::usage

  • VUID-VkCopyImageToImageInfoEXT-srcOffset-09114
    If flags contains VK_HOST_IMAGE_COPY_MEMCPY_EXT, the x, y, and z members of the srcOffset member of each element of pRegions must be 0

  • VUID-VkCopyImageToImageInfoEXT-srcImage-09115
    If flags contains VK_HOST_IMAGE_COPY_MEMCPY_EXT, the extent member of each element of pRegions must equal the extents of srcImage identified by srcSubresource

  • VUID-VkCopyImageToImageInfoEXT-srcImage-07966
    If srcImage is non-sparse then the image or the specified disjoint plane must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-VkCopyImageToImageInfoEXT-srcSubresource-07967
    The srcSubresource.mipLevel member of each element of pRegions must be less than the mipLevels specified in VkImageCreateInfo when srcImage was created

  • VUID-VkCopyImageToImageInfoEXT-srcSubresource-07968
    If srcSubresource.layerCount is not VK_REMAINING_ARRAY_LAYERS, srcSubresource.baseArrayLayer + srcSubresource.layerCount of each element of pRegions must be less than or equal to the arrayLayers specified in VkImageCreateInfo when srcImage was created

  • VUID-VkCopyImageToImageInfoEXT-srcImage-07969
    srcImage must not have been created with flags containing VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT

  • VUID-VkCopyImageToImageInfoEXT-srcSubresource-07970
    The image region specified by each element of pRegions must be contained within the specified srcSubresource of srcImage

  • VUID-VkCopyImageToImageInfoEXT-srcSubresource-07971
    For each element of pRegions, srcOffset.x and (extent.width + srcOffset.x) must both be greater than or equal to 0 and less than or equal to the width of the specified srcSubresource of srcImage

  • VUID-VkCopyImageToImageInfoEXT-srcSubresource-07972
    For each element of pRegions, srcOffset.y and (extent.height + srcOffset.y) must both be greater than or equal to 0 and less than or equal to the height of the specified srcSubresource of srcImage

  • VUID-VkCopyImageToImageInfoEXT-srcImage-07979
    If srcImage is of type VK_IMAGE_TYPE_1D, then for each element of pRegions, srcOffset.y must be 0 and extent.height must be 1

  • VUID-VkCopyImageToImageInfoEXT-srcOffset-09104
    For each element of pRegions, srcOffset.z and (extent.depth + srcOffset.z) must both be greater than or equal to 0 and less than or equal to the depth of the specified srcSubresource of srcImage

  • VUID-VkCopyImageToImageInfoEXT-srcImage-07980
    If srcImage is of type VK_IMAGE_TYPE_1D or VK_IMAGE_TYPE_2D, then for each element of pRegions, srcOffset.z must be 0 and extent.depth must be 1

  • VUID-VkCopyImageToImageInfoEXT-srcImage-07274
    For each element of pRegions, srcOffset.x must be a multiple of the texel block extent width of the VkFormat of srcImage

  • VUID-VkCopyImageToImageInfoEXT-srcImage-07275
    For each element of pRegions, srcOffset.y must be a multiple of the texel block extent height of the VkFormat of srcImage

  • VUID-VkCopyImageToImageInfoEXT-srcImage-07276
    For each element of pRegions, srcOffset.z must be a multiple of the texel block extent depth of the VkFormat of srcImage

  • VUID-VkCopyImageToImageInfoEXT-srcImage-00207
    For each element of pRegions, if the sum of srcOffset.x and extent.width does not equal the width of the subresource specified by srcSubresource, extent.width must be a multiple of the texel block extent width of the VkFormat of srcImage

  • VUID-VkCopyImageToImageInfoEXT-srcImage-00208
    For each element of pRegions, if the sum of srcOffset.y and extent.height does not equal the height of the subresource specified by srcSubresource, extent.height must be a multiple of the texel block extent height of the VkFormat of srcImage

  • VUID-VkCopyImageToImageInfoEXT-srcImage-00209
    For each element of pRegions, if the sum of srcOffset.z and extent.depth does not equal the depth of the subresource specified by srcSubresource, extent.depth must be a multiple of the texel block extent depth of the VkFormat of srcImage

  • VUID-VkCopyImageToImageInfoEXT-srcSubresource-09105
    For each element of pRegions, srcSubresource.aspectMask must specify aspects present in srcImage

  • VUID-VkCopyImageToImageInfoEXT-srcImage-07981
    If srcImage has a multi-planar image format, then for each element of pRegions, srcSubresource.aspectMask must be a single valid multi-planar aspect mask bit

  • VUID-VkCopyImageToImageInfoEXT-srcImage-07983
    If srcImage is of type VK_IMAGE_TYPE_3D, for each element of pRegions, srcSubresource.baseArrayLayer must be 0 and srcSubresource.layerCount must be 1

  • VUID-VkCopyImageToImageInfoEXT-dstImage-09109
    If dstImage is sparse then all memory ranges accessed by the copy command must be bound as described in Binding Resource Memory

  • VUID-VkCopyImageToImageInfoEXT-dstImage-09111
    If the stencil aspect of dstImage is accessed, and dstImage was not created with separate stencil usage, dstImage must have been created with VK_IMAGE_USAGE_HOST_TRANSFER_BIT_EXT set in VkImageCreateInfo::usage

  • VUID-VkCopyImageToImageInfoEXT-dstImage-09112
    If the stencil aspect of dstImage is accessed, and dstImage was created with separate stencil usage, dstImage must have been created with VK_IMAGE_USAGE_HOST_TRANSFER_BIT_EXT set in VkImageStencilUsageCreateInfo::stencilUsage

  • VUID-VkCopyImageToImageInfoEXT-dstImage-09113
    If non-stencil aspects of dstImage are accessed, dstImage must have been created with VK_IMAGE_USAGE_HOST_TRANSFER_BIT_EXT set in VkImageCreateInfo::usage

  • VUID-VkCopyImageToImageInfoEXT-dstOffset-09114
    If flags contains VK_HOST_IMAGE_COPY_MEMCPY_EXT, the x, y, and z members of the dstOffset member of each element of pRegions must be 0

  • VUID-VkCopyImageToImageInfoEXT-dstImage-09115
    If flags contains VK_HOST_IMAGE_COPY_MEMCPY_EXT, the extent member of each element of pRegions must equal the extents of dstImage identified by dstSubresource

  • VUID-VkCopyImageToImageInfoEXT-dstImage-07966
    If dstImage is non-sparse then the image or the specified disjoint plane must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-VkCopyImageToImageInfoEXT-dstSubresource-07967
    The dstSubresource.mipLevel member of each element of pRegions must be less than the mipLevels specified in VkImageCreateInfo when dstImage was created

  • VUID-VkCopyImageToImageInfoEXT-dstSubresource-07968
    If dstSubresource.layerCount is not VK_REMAINING_ARRAY_LAYERS, dstSubresource.baseArrayLayer + dstSubresource.layerCount of each element of pRegions must be less than or equal to the arrayLayers specified in VkImageCreateInfo when dstImage was created

  • VUID-VkCopyImageToImageInfoEXT-dstImage-07969
    dstImage must not have been created with flags containing VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT

  • VUID-VkCopyImageToImageInfoEXT-dstSubresource-07970
    The image region specified by each element of pRegions must be contained within the specified dstSubresource of dstImage

  • VUID-VkCopyImageToImageInfoEXT-dstSubresource-07971
    For each element of pRegions, dstOffset.x and (extent.width + dstOffset.x) must both be greater than or equal to 0 and less than or equal to the width of the specified dstSubresource of dstImage

  • VUID-VkCopyImageToImageInfoEXT-dstSubresource-07972
    For each element of pRegions, dstOffset.y and (extent.height + dstOffset.y) must both be greater than or equal to 0 and less than or equal to the height of the specified dstSubresource of dstImage

  • VUID-VkCopyImageToImageInfoEXT-dstImage-07979
    If dstImage is of type VK_IMAGE_TYPE_1D, then for each element of pRegions, dstOffset.y must be 0 and extent.height must be 1

  • VUID-VkCopyImageToImageInfoEXT-dstOffset-09104
    For each element of pRegions, dstOffset.z and (extent.depth + dstOffset.z) must both be greater than or equal to 0 and less than or equal to the depth of the specified dstSubresource of dstImage

  • VUID-VkCopyImageToImageInfoEXT-dstImage-07980
    If dstImage is of type VK_IMAGE_TYPE_1D or VK_IMAGE_TYPE_2D, then for each element of pRegions, dstOffset.z must be 0 and extent.depth must be 1

  • VUID-VkCopyImageToImageInfoEXT-dstImage-07274
    For each element of pRegions, dstOffset.x must be a multiple of the texel block extent width of the VkFormat of dstImage

  • VUID-VkCopyImageToImageInfoEXT-dstImage-07275
    For each element of pRegions, dstOffset.y must be a multiple of the texel block extent height of the VkFormat of dstImage

  • VUID-VkCopyImageToImageInfoEXT-dstImage-07276
    For each element of pRegions, dstOffset.z must be a multiple of the texel block extent depth of the VkFormat of dstImage

  • VUID-VkCopyImageToImageInfoEXT-dstImage-00207
    For each element of pRegions, if the sum of dstOffset.x and extent.width does not equal the width of the subresource specified by srcSubresource, extent.width must be a multiple of the texel block extent width of the VkFormat of dstImage

  • VUID-VkCopyImageToImageInfoEXT-dstImage-00208
    For each element of pRegions, if the sum of dstOffset.y and extent.height does not equal the height of the subresource specified by srcSubresource, extent.height must be a multiple of the texel block extent height of the VkFormat of dstImage

  • VUID-VkCopyImageToImageInfoEXT-dstImage-00209
    For each element of pRegions, if the sum of dstOffset.z and extent.depth does not equal the depth of the subresource specified by srcSubresource, extent.depth must be a multiple of the texel block extent depth of the VkFormat of dstImage

  • VUID-VkCopyImageToImageInfoEXT-dstSubresource-09105
    For each element of pRegions, dstSubresource.aspectMask must specify aspects present in dstImage

  • VUID-VkCopyImageToImageInfoEXT-dstImage-07981
    If dstImage has a multi-planar image format, then for each element of pRegions, dstSubresource.aspectMask must be a single valid multi-planar aspect mask bit

  • VUID-VkCopyImageToImageInfoEXT-dstImage-07983
    If dstImage is of type VK_IMAGE_TYPE_3D, for each element of pRegions, dstSubresource.baseArrayLayer must be 0 and dstSubresource.layerCount must be 1

  • VUID-VkCopyImageToImageInfoEXT-srcImageLayout-09070
    srcImageLayout must specify the current layout of the image subresources of srcImage specified in pRegions

  • VUID-VkCopyImageToImageInfoEXT-dstImageLayout-09071
    dstImageLayout must specify the current layout of the image subresources of dstImage specified in pRegions

  • VUID-VkCopyImageToImageInfoEXT-srcImageLayout-09072
    srcImageLayout must be one of the image layouts returned in VkPhysicalDeviceHostImageCopyPropertiesEXT::pCopySrcLayouts

  • VUID-VkCopyImageToImageInfoEXT-dstImageLayout-09073
    dstImageLayout must be one of the image layouts returned in VkPhysicalDeviceHostImageCopyPropertiesEXT::pCopyDstLayouts

Valid Usage (Implicit)
  • VUID-VkCopyImageToImageInfoEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_COPY_IMAGE_TO_IMAGE_INFO_EXT

  • VUID-VkCopyImageToImageInfoEXT-pNext-pNext
    pNext must be NULL

  • VUID-VkCopyImageToImageInfoEXT-flags-parameter
    flags must be a valid combination of VkHostImageCopyFlagBitsEXT values

  • VUID-VkCopyImageToImageInfoEXT-srcImage-parameter
    srcImage must be a valid VkImage handle

  • VUID-VkCopyImageToImageInfoEXT-srcImageLayout-parameter
    srcImageLayout must be a valid VkImageLayout value

  • VUID-VkCopyImageToImageInfoEXT-dstImage-parameter
    dstImage must be a valid VkImage handle

  • VUID-VkCopyImageToImageInfoEXT-dstImageLayout-parameter
    dstImageLayout must be a valid VkImageLayout value

  • VUID-VkCopyImageToImageInfoEXT-pRegions-parameter
    pRegions must be a valid pointer to an array of regionCount valid VkImageCopy2 structures

  • VUID-VkCopyImageToImageInfoEXT-regionCount-arraylength
    regionCount must be greater than 0

  • VUID-VkCopyImageToImageInfoEXT-commonparent
    Both of dstImage, and srcImage must have been created, allocated, or retrieved from the same VkDevice

Indirect Copies

An application can use indirect copies when the copy parameters are not known during the command buffer creation time.

To copy data between two memory regions by specifying copy parameters indirectly in a buffer, call:

// Provided by VK_NV_copy_memory_indirect
void vkCmdCopyMemoryIndirectNV(
    VkCommandBuffer                             commandBuffer,
    VkDeviceAddress                             copyBufferAddress,
    uint32_t                                    copyCount,
    uint32_t                                    stride);
  • commandBuffer is the command buffer into which the command will be recorded.

  • copyBufferAddress is the buffer address specifying the copy parameters. This buffer is laid out in memory as an array of VkCopyMemoryIndirectCommandNV structures.

  • copyCount is the number of copies to execute, and can be zero.

  • stride is the stride in bytes between successive sets of copy parameters.

Each region read from copyBufferAddress is copied from the source region to the specified destination region. The results are undefined if any of the source and destination regions overlap in memory.

Valid Usage
  • VUID-vkCmdCopyMemoryIndirectNV-None-07653
    The indirectCopy feature must be enabled

  • VUID-vkCmdCopyMemoryIndirectNV-copyBufferAddress-07654
    copyBufferAddress must be 4 byte aligned

  • VUID-vkCmdCopyMemoryIndirectNV-stride-07655
    stride must be a multiple of 4 and must be greater than or equal to sizeof(VkCopyMemoryIndirectCommandNV)

  • VUID-vkCmdCopyMemoryIndirectNV-commandBuffer-07656
    The VkCommandPool that commandBuffer was allocated from must support at least one of the VkPhysicalDeviceCopyMemoryIndirectPropertiesNV::supportedQueues

Valid Usage (Implicit)
  • VUID-vkCmdCopyMemoryIndirectNV-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdCopyMemoryIndirectNV-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdCopyMemoryIndirectNV-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support transfer, graphics, or compute operations

  • VUID-vkCmdCopyMemoryIndirectNV-renderpass
    This command must only be called outside of a render pass instance

  • VUID-vkCmdCopyMemoryIndirectNV-videocoding
    This command must only be called outside of a video coding scope

Host Synchronization
  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type

Primary
Secondary

Outside

Outside

Transfer
Graphics
Compute

Action

The structure describing source and destination memory regions, VkCopyMemoryIndirectCommandNV is defined as:

// Provided by VK_NV_copy_memory_indirect
typedef struct VkCopyMemoryIndirectCommandNV {
    VkDeviceAddress    srcAddress;
    VkDeviceAddress    dstAddress;
    VkDeviceSize       size;
} VkCopyMemoryIndirectCommandNV;
  • srcAddress is the starting address of the source device memory to copy from.

  • dstAddress is the starting address of the destination device memory to copy to.

  • size is the size of the copy in bytes.

Valid Usage
  • VUID-VkCopyMemoryIndirectCommandNV-srcAddress-07657
    The srcAddress must be 4 byte aligned

  • VUID-VkCopyMemoryIndirectCommandNV-dstAddress-07658
    The dstAddress must be 4 byte aligned

  • VUID-VkCopyMemoryIndirectCommandNV-size-07659
    The size must be 4 byte aligned

To copy data from a memory region to an image object by specifying copy parameters in a buffer, call:

// Provided by VK_NV_copy_memory_indirect
void vkCmdCopyMemoryToImageIndirectNV(
    VkCommandBuffer                             commandBuffer,
    VkDeviceAddress                             copyBufferAddress,
    uint32_t                                    copyCount,
    uint32_t                                    stride,
    VkImage                                     dstImage,
    VkImageLayout                               dstImageLayout,
    const VkImageSubresourceLayers*             pImageSubresources);
  • commandBuffer is the command buffer into which the command will be recorded.

  • copyBufferAddress is the buffer address specifying the copy parameters. This buffer is laid out in memory as an array of VkCopyMemoryToImageIndirectCommandNV structures.

  • copyCount is the number of copies to execute, and can be zero.

  • stride is the byte stride between successive sets of copy parameters.

  • dstImage is the destination image.

  • dstImageLayout is the layout of the destination image subresources for the copy.

  • pImageSubresources is a pointer to an array of size copyCount of VkImageSubresourceLayers used to specify the specific image subresource of the destination image data for that copy.

Each region in copyBufferAddress is copied from the source memory region to an image region in the destination image. If the destination image is of type VK_IMAGE_TYPE_3D, the starting slice and number of slices to copy are specified in pImageSubresources->baseArrayLayer and pImageSubresources->layerCount respectively. The copy must be performed on a queue that supports indirect copy operations, see VkPhysicalDeviceCopyMemoryIndirectPropertiesNV.

Valid Usage
  • VUID-vkCmdCopyMemoryToImageIndirectNV-None-07660
    The indirectCopy feature must be enabled

  • VUID-vkCmdCopyMemoryToImageIndirectNV-dstImage-07661
    dstImage must not be a protected image

  • VUID-vkCmdCopyMemoryToImageIndirectNV-aspectMask-07662
    The aspectMask member for every subresource in pImageSubresources must only have a single bit set

  • VUID-vkCmdCopyMemoryToImageIndirectNV-dstImage-07663
    The image region specified by each element in copyBufferAddress must be a region that is contained within dstImage

  • VUID-vkCmdCopyMemoryToImageIndirectNV-dstImage-07664
    dstImage must have been created with VK_IMAGE_USAGE_TRANSFER_DST_BIT usage flag

  • VUID-vkCmdCopyMemoryToImageIndirectNV-dstImage-07665
    If dstImage is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-vkCmdCopyMemoryToImageIndirectNV-dstImage-07973
    dstImage must have a sample count equal to VK_SAMPLE_COUNT_1_BIT

  • VUID-vkCmdCopyMemoryToImageIndirectNV-dstImageLayout-07667
    dstImageLayout must specify the layout of the image subresources of dstImage at the time this command is executed on a VkDevice

  • VUID-vkCmdCopyMemoryToImageIndirectNV-dstImageLayout-07669
    dstImageLayout must be VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL, VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR, or VK_IMAGE_LAYOUT_GENERAL

  • VUID-vkCmdCopyMemoryToImageIndirectNV-mipLevel-07670
    The specified mipLevel of each region must be less than the mipLevels specified in VkImageCreateInfo when dstImage was created

  • VUID-vkCmdCopyMemoryToImageIndirectNV-layerCount-08764
    If layerCount is not VK_REMAINING_ARRAY_LAYERS, the specified baseArrayLayer + layerCount of each region must be less than or equal to the arrayLayers specified in VkImageCreateInfo when dstImage was created

  • VUID-vkCmdCopyMemoryToImageIndirectNV-imageOffset-07672
    The imageOffset and imageExtent members of each region must respect the image transfer granularity requirements of commandBuffer’s command pool’s queue family, as described in VkQueueFamilyProperties

  • VUID-vkCmdCopyMemoryToImageIndirectNV-dstImage-07673
    dstImage must not have been created with flags containing VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT

  • VUID-vkCmdCopyMemoryToImageIndirectNV-commandBuffer-07674
    If the queue family used to create the VkCommandPool which commandBuffer was allocated from does not support VK_QUEUE_GRAPHICS_BIT, for each region, the aspectMask member of pImageSubresources must not be VK_IMAGE_ASPECT_DEPTH_BIT or VK_IMAGE_ASPECT_STENCIL_BIT

  • VUID-vkCmdCopyMemoryToImageIndirectNV-imageOffset-07675
    For each region in copyBufferAddress, imageOffset.y and (imageExtent.height + imageOffset.y) must both be greater than or equal to 0 and less than or equal to the height of the specified subresource

  • VUID-vkCmdCopyMemoryToImageIndirectNV-offset-07676
    offset must be 4 byte aligned

  • VUID-vkCmdCopyMemoryToImageIndirectNV-stride-07677
    stride must be a multiple of 4 and must be greater than or equal to sizeof(VkCopyMemoryToImageIndirectCommandNV)

Valid Usage (Implicit)
  • VUID-vkCmdCopyMemoryToImageIndirectNV-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdCopyMemoryToImageIndirectNV-dstImage-parameter
    dstImage must be a valid VkImage handle

  • VUID-vkCmdCopyMemoryToImageIndirectNV-dstImageLayout-parameter
    dstImageLayout must be a valid VkImageLayout value

  • VUID-vkCmdCopyMemoryToImageIndirectNV-pImageSubresources-parameter
    pImageSubresources must be a valid pointer to an array of copyCount valid VkImageSubresourceLayers structures

  • VUID-vkCmdCopyMemoryToImageIndirectNV-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdCopyMemoryToImageIndirectNV-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support transfer, graphics, or compute operations

  • VUID-vkCmdCopyMemoryToImageIndirectNV-renderpass
    This command must only be called outside of a render pass instance

  • VUID-vkCmdCopyMemoryToImageIndirectNV-videocoding
    This command must only be called outside of a video coding scope

  • VUID-vkCmdCopyMemoryToImageIndirectNV-copyCount-arraylength
    copyCount must be greater than 0

  • VUID-vkCmdCopyMemoryToImageIndirectNV-commonparent
    Both of commandBuffer, and dstImage must have been created, allocated, or retrieved from the same VkDevice

Host Synchronization
  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type

Primary
Secondary

Outside

Outside

Transfer
Graphics
Compute

Action

The VkCopyMemoryToImageIndirectCommandNV is defined as:

// Provided by VK_NV_copy_memory_indirect
typedef struct VkCopyMemoryToImageIndirectCommandNV {
    VkDeviceAddress             srcAddress;
    uint32_t                    bufferRowLength;
    uint32_t                    bufferImageHeight;
    VkImageSubresourceLayers    imageSubresource;
    VkOffset3D                  imageOffset;
    VkExtent3D                  imageExtent;
} VkCopyMemoryToImageIndirectCommandNV;
  • srcAddress is the starting address of the source device memory to copy from.

  • bufferRowLength and bufferImageHeight specify in texels a subregion of a larger two- or three-dimensional image in buffer memory, and control the addressing calculations. If either of these values is zero, that aspect of the buffer memory is considered to be tightly packed according to the imageExtent.

  • imageSubresource is a VkImageSubresourceLayers used to specify the specific image subresources of the image used for the destination image data, which must match the values specified in pImageSubresources parameter of vkCmdCopyMemoryToImageIndirectNV during command recording.

  • imageOffset selects the initial x, y, z offsets in texels of the sub-region of the destination image data.

  • imageExtent is the size in texels of the destination image in width, height and depth.

Valid Usage
  • VUID-VkCopyMemoryToImageIndirectCommandNV-srcAddress-07678
    The srcAddress must be 4 byte aligned

  • VUID-VkCopyMemoryToImageIndirectCommandNV-bufferRowLength-07679
    bufferRowLength must be 0, or greater than or equal to the width member of imageExtent

  • VUID-VkCopyMemoryToImageIndirectCommandNV-bufferImageHeight-07680
    bufferImageHeight must be 0, or greater than or equal to the height member of imageExtent

  • VUID-VkCopyMemoryToImageIndirectCommandNV-imageOffset-07681
    imageOffset must specify a valid offset in the destination image

  • VUID-VkCopyMemoryToImageIndirectCommandNV-imageExtent-07682
    imageExtent must specify a valid region in the destination image and can be 0

Valid Usage (Implicit)
  • VUID-VkCopyMemoryToImageIndirectCommandNV-imageSubresource-parameter
    imageSubresource must be a valid VkImageSubresourceLayers structure

Image Copies With Scaling

To copy regions of a source image into a destination image, potentially performing format conversion, arbitrary scaling, and filtering, call:

// Provided by VK_VERSION_1_0
void vkCmdBlitImage(
    VkCommandBuffer                             commandBuffer,
    VkImage                                     srcImage,
    VkImageLayout                               srcImageLayout,
    VkImage                                     dstImage,
    VkImageLayout                               dstImageLayout,
    uint32_t                                    regionCount,
    const VkImageBlit*                          pRegions,
    VkFilter                                    filter);
  • commandBuffer is the command buffer into which the command will be recorded.

  • srcImage is the source image.

  • srcImageLayout is the layout of the source image subresources for the blit.

  • dstImage is the destination image.

  • dstImageLayout is the layout of the destination image subresources for the blit.

  • regionCount is the number of regions to blit.

  • pRegions is a pointer to an array of VkImageBlit structures specifying the regions to blit.

  • filter is a VkFilter specifying the filter to apply if the blits require scaling.

vkCmdBlitImage must not be used for multisampled source or destination images. Use vkCmdResolveImage for this purpose.

As the sizes of the source and destination extents can differ in any dimension, texels in the source extent are scaled and filtered to the destination extent. Scaling occurs via the following operations:

  • For each destination texel, the integer coordinate of that texel is converted to an unnormalized texture coordinate, using the effective inverse of the equations described in unnormalized to integer conversion:

    ubase = i + ½

    vbase = j + ½

    wbase = k + ½

  • These base coordinates are then offset by the first destination offset:

    uoffset = ubase - xdst0

    voffset = vbase - ydst0

    woffset = wbase - zdst0

    aoffset = a - baseArrayCountdst

  • The scale is determined from the source and destination regions, and applied to the offset coordinates:

    scaleu = (xsrc1 - xsrc0) / (xdst1 - xdst0)

    scalev = (ysrc1 - ysrc0) / (ydst1 - ydst0)

    scalew = (zsrc1 - zsrc0) / (zdst1 - zdst0)

    uscaled = uoffset × scaleu

    vscaled = voffset × scalev

    wscaled = woffset × scalew

  • Finally the source offset is added to the scaled coordinates, to determine the final unnormalized coordinates used to sample from srcImage:

    u = uscaled + xsrc0

    v = vscaled + ysrc0

    w = wscaled + zsrc0

    q = mipLevel

    a = aoffset + baseArrayCountsrc

These coordinates are used to sample from the source image, as described in Image Operations chapter, with the filter mode equal to that of filter, a mipmap mode of VK_SAMPLER_MIPMAP_MODE_NEAREST and an address mode of VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE. Implementations must clamp at the edge of the source image, and may additionally clamp to the edge of the source region.

Note

Due to allowable rounding errors in the generation of the source texture coordinates, it is not always possible to guarantee exactly which source texels will be sampled for a given blit. As rounding errors are implementation-dependent, the exact results of a blitting operation are also implementation-dependent.

Blits are done layer by layer starting with the baseArrayLayer member of srcSubresource for the source and dstSubresource for the destination. layerCount layers are blitted to the destination image.

When blitting 3D textures, slices in the destination region bounded by dstOffsets[0].z and dstOffsets[1].z are sampled from slices in the source region bounded by srcOffsets[0].z and srcOffsets[1].z. If the filter parameter is VK_FILTER_LINEAR then the value sampled from the source image is taken by doing linear filtering using the interpolated z coordinate represented by w in the previous equations. If the filter parameter is VK_FILTER_NEAREST then the value sampled from the source image is taken from the single nearest slice, with an implementation-dependent arithmetic rounding mode.

The following filtering and conversion rules apply:

  • Integer formats can only be converted to other integer formats with the same signedness.

  • No format conversion is supported between depth/stencil images. The formats must match.

  • Format conversions on unorm, snorm, scaled and packed float formats of the copied aspect of the image are performed by first converting the pixels to float values.

  • For sRGB source formats, nonlinear RGB values are converted to linear representation prior to filtering.

  • After filtering, the float values are first clamped and then cast to the destination image format. In case of sRGB destination format, linear RGB values are converted to nonlinear representation before writing the pixel to the image.

Signed and unsigned integers are converted by first clamping to the representable range of the destination format, then casting the value.

Valid Usage
  • VUID-vkCmdBlitImage-commandBuffer-01834
    If commandBuffer is an unprotected command buffer and protectedNoFault is not supported, srcImage must not be a protected image

  • VUID-vkCmdBlitImage-commandBuffer-01835
    If commandBuffer is an unprotected command buffer and protectedNoFault is not supported, dstImage must not be a protected image

  • VUID-vkCmdBlitImage-commandBuffer-01836
    If commandBuffer is a protected command buffer and protectedNoFault is not supported, dstImage must not be an unprotected image

  • VUID-vkCmdBlitImage-pRegions-00215
    The source region specified by each element of pRegions must be a region that is contained within srcImage

  • VUID-vkCmdBlitImage-pRegions-00216
    The destination region specified by each element of pRegions must be a region that is contained within dstImage

  • VUID-vkCmdBlitImage-pRegions-00217
    The union of all destination regions, specified by the elements of pRegions, must not overlap in memory with any texel that may be sampled during the blit operation

  • VUID-vkCmdBlitImage-srcImage-01999
    The format features of srcImage must contain VK_FORMAT_FEATURE_BLIT_SRC_BIT

  • VUID-vkCmdBlitImage-srcImage-06421
    srcImage must not use a format that requires a sampler Y′CBCR conversion

  • VUID-vkCmdBlitImage-srcImage-00219
    srcImage must have been created with VK_IMAGE_USAGE_TRANSFER_SRC_BIT usage flag

  • VUID-vkCmdBlitImage-srcImage-00220
    If srcImage is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-vkCmdBlitImage-srcImageLayout-00221
    srcImageLayout must specify the layout of the image subresources of srcImage specified in pRegions at the time this command is executed on a VkDevice

  • VUID-vkCmdBlitImage-srcImageLayout-01398
    srcImageLayout must be VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR, VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL or VK_IMAGE_LAYOUT_GENERAL

  • VUID-vkCmdBlitImage-srcImage-09459
    If srcImage and dstImage are the same, and an elements of pRegions contains the srcSubresource and dstSubresource with matching mipLevel and overlapping array layers, then the srcImageLayout and dstImageLayout must be VK_IMAGE_LAYOUT_GENERAL or VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR

  • VUID-vkCmdBlitImage-dstImage-02000
    The format features of dstImage must contain VK_FORMAT_FEATURE_BLIT_DST_BIT

  • VUID-vkCmdBlitImage-dstImage-06422
    dstImage must not use a format that requires a sampler Y′CBCR conversion

  • VUID-vkCmdBlitImage-dstImage-00224
    dstImage must have been created with VK_IMAGE_USAGE_TRANSFER_DST_BIT usage flag

  • VUID-vkCmdBlitImage-dstImage-00225
    If dstImage is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-vkCmdBlitImage-dstImageLayout-00226
    dstImageLayout must specify the layout of the image subresources of dstImage specified in pRegions at the time this command is executed on a VkDevice

  • VUID-vkCmdBlitImage-dstImageLayout-01399
    dstImageLayout must be VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR, VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL or VK_IMAGE_LAYOUT_GENERAL

  • VUID-vkCmdBlitImage-srcImage-00229
    If either of srcImage or dstImage was created with a signed integer VkFormat, the other must also have been created with a signed integer VkFormat

  • VUID-vkCmdBlitImage-srcImage-00230
    If either of srcImage or dstImage was created with an unsigned integer VkFormat, the other must also have been created with an unsigned integer VkFormat

  • VUID-vkCmdBlitImage-srcImage-00231
    If either of srcImage or dstImage was created with a depth/stencil format, the other must have exactly the same format

  • VUID-vkCmdBlitImage-srcImage-00232
    If srcImage was created with a depth/stencil format, filter must be VK_FILTER_NEAREST

  • VUID-vkCmdBlitImage-srcImage-00233
    srcImage must have been created with a samples value of VK_SAMPLE_COUNT_1_BIT

  • VUID-vkCmdBlitImage-dstImage-00234
    dstImage must have been created with a samples value of VK_SAMPLE_COUNT_1_BIT

  • VUID-vkCmdBlitImage-filter-02001
    If filter is VK_FILTER_LINEAR, then the format features of srcImage must contain VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT

  • VUID-vkCmdBlitImage-filter-02002
    If filter is VK_FILTER_CUBIC_EXT, then the format features of srcImage must contain VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_CUBIC_BIT_EXT

  • VUID-vkCmdBlitImage-filter-00237
    If filter is VK_FILTER_CUBIC_EXT, srcImage must be of type VK_IMAGE_TYPE_2D

  • VUID-vkCmdBlitImage-srcSubresource-01705
    The srcSubresource.mipLevel member of each element of pRegions must be less than the mipLevels specified in VkImageCreateInfo when srcImage was created

  • VUID-vkCmdBlitImage-dstSubresource-01706
    The dstSubresource.mipLevel member of each element of pRegions must be less than the mipLevels specified in VkImageCreateInfo when dstImage was created

  • VUID-vkCmdBlitImage-srcSubresource-01707
    If srcSubresource.layerCount is not VK_REMAINING_ARRAY_LAYERS, srcSubresource.baseArrayLayer + srcSubresource.layerCount of each element of pRegions must be less than or equal to the arrayLayers specified in VkImageCreateInfo when srcImage was created

  • VUID-vkCmdBlitImage-dstSubresource-01708
    If srcSubresource.layerCount is not VK_REMAINING_ARRAY_LAYERS, dstSubresource.baseArrayLayer + dstSubresource.layerCount of each element of pRegions must be less than or equal to the arrayLayers specified in VkImageCreateInfo when dstImage was created

  • VUID-vkCmdBlitImage-dstImage-02545
    dstImage and srcImage must not have been created with flags containing VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT

  • VUID-vkCmdBlitImage-srcImage-00240
    If either srcImage or dstImage is of type VK_IMAGE_TYPE_3D, then for each element of pRegions, srcSubresource.baseArrayLayer and dstSubresource.baseArrayLayer must each be 0, and srcSubresource.layerCount and dstSubresource.layerCount must each be 1

  • VUID-vkCmdBlitImage-aspectMask-00241
    For each element of pRegions, srcSubresource.aspectMask must specify aspects present in srcImage

  • VUID-vkCmdBlitImage-aspectMask-00242
    For each element of pRegions, dstSubresource.aspectMask must specify aspects present in dstImage

  • VUID-vkCmdBlitImage-srcOffset-00243
    For each element of pRegions, srcOffsets[0].x and srcOffsets[1].x must both be greater than or equal to 0 and less than or equal to the width of the specified srcSubresource of srcImage

  • VUID-vkCmdBlitImage-srcOffset-00244
    For each element of pRegions, srcOffsets[0].y and srcOffsets[1].y must both be greater than or equal to 0 and less than or equal to the height of the specified srcSubresource of srcImage

  • VUID-vkCmdBlitImage-srcImage-00245
    If srcImage is of type VK_IMAGE_TYPE_1D, then for each element of pRegions, srcOffsets[0].y must be 0 and srcOffsets[1].y must be 1

  • VUID-vkCmdBlitImage-srcOffset-00246
    For each element of pRegions, srcOffsets[0].z and srcOffsets[1].z must both be greater than or equal to 0 and less than or equal to the depth of the specified srcSubresource of srcImage

  • VUID-vkCmdBlitImage-srcImage-00247
    If srcImage is of type VK_IMAGE_TYPE_1D or VK_IMAGE_TYPE_2D, then for each element of pRegions, srcOffsets[0].z must be 0 and srcOffsets[1].z must be 1

  • VUID-vkCmdBlitImage-dstOffset-00248
    For each element of pRegions, dstOffsets[0].x and dstOffsets[1].x must both be greater than or equal to 0 and less than or equal to the width of the specified dstSubresource of dstImage

  • VUID-vkCmdBlitImage-dstOffset-00249
    For each element of pRegions, dstOffsets[0].y and dstOffsets[1].y must both be greater than or equal to 0 and less than or equal to the height of the specified dstSubresource of dstImage

  • VUID-vkCmdBlitImage-dstImage-00250
    If dstImage is of type VK_IMAGE_TYPE_1D, then for each element of pRegions, dstOffsets[0].y must be 0 and dstOffsets[1].y must be 1

  • VUID-vkCmdBlitImage-dstOffset-00251
    For each element of pRegions, dstOffsets[0].z and dstOffsets[1].z must both be greater than or equal to 0 and less than or equal to the depth of the specified dstSubresource of dstImage

  • VUID-vkCmdBlitImage-dstImage-00252
    If dstImage is of type VK_IMAGE_TYPE_1D or VK_IMAGE_TYPE_2D, then for each element of pRegions, dstOffsets[0].z must be 0 and dstOffsets[1].z must be 1

Valid Usage (Implicit)
  • VUID-vkCmdBlitImage-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdBlitImage-srcImage-parameter
    srcImage must be a valid VkImage handle

  • VUID-vkCmdBlitImage-srcImageLayout-parameter
    srcImageLayout must be a valid VkImageLayout value

  • VUID-vkCmdBlitImage-dstImage-parameter
    dstImage must be a valid VkImage handle

  • VUID-vkCmdBlitImage-dstImageLayout-parameter
    dstImageLayout must be a valid VkImageLayout value

  • VUID-vkCmdBlitImage-pRegions-parameter
    pRegions must be a valid pointer to an array of regionCount valid VkImageBlit structures

  • VUID-vkCmdBlitImage-filter-parameter
    filter must be a valid VkFilter value

  • VUID-vkCmdBlitImage-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdBlitImage-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support graphics operations

  • VUID-vkCmdBlitImage-renderpass
    This command must only be called outside of a render pass instance

  • VUID-vkCmdBlitImage-videocoding
    This command must only be called outside of a video coding scope

  • VUID-vkCmdBlitImage-regionCount-arraylength
    regionCount must be greater than 0

  • VUID-vkCmdBlitImage-commonparent
    Each of commandBuffer, dstImage, and srcImage must have been created, allocated, or retrieved from the same VkDevice

Host Synchronization
  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type

Primary
Secondary

Outside

Outside

Graphics

Action

The VkImageBlit structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkImageBlit {
    VkImageSubresourceLayers    srcSubresource;
    VkOffset3D                  srcOffsets[2];
    VkImageSubresourceLayers    dstSubresource;
    VkOffset3D                  dstOffsets[2];
} VkImageBlit;
  • srcSubresource is the subresource to blit from.

  • srcOffsets is a pointer to an array of two VkOffset3D structures specifying the bounds of the source region within srcSubresource.

  • dstSubresource is the subresource to blit into.

  • dstOffsets is a pointer to an array of two VkOffset3D structures specifying the bounds of the destination region within dstSubresource.

For each element of the pRegions array, a blit operation is performed for the specified source and destination regions.

Valid Usage
  • VUID-VkImageBlit-aspectMask-00238
    The aspectMask member of srcSubresource and dstSubresource must match

  • VUID-VkImageBlit-layerCount-08800
    If neither of the layerCount members of srcSubresource or dstSubresource are VK_REMAINING_ARRAY_LAYERS, the layerCount members of srcSubresource or dstSubresource must match

  • VUID-VkImageBlit-layerCount-08801
    If one of the layerCount members of srcSubresource or dstSubresource is VK_REMAINING_ARRAY_LAYERS, the other member must be either VK_REMAINING_ARRAY_LAYERS or equal to the arrayLayers member of the VkImageCreateInfo used to create the image minus baseArrayLayer

Valid Usage (Implicit)

A more extensible version of the blit image command is defined below.

To copy regions of a source image into a destination image, potentially performing format conversion, arbitrary scaling, and filtering, call:

// Provided by VK_VERSION_1_3
void vkCmdBlitImage2(
    VkCommandBuffer                             commandBuffer,
    const VkBlitImageInfo2*                     pBlitImageInfo);

or the equivalent command

// Provided by VK_KHR_copy_commands2
void vkCmdBlitImage2KHR(
    VkCommandBuffer                             commandBuffer,
    const VkBlitImageInfo2*                     pBlitImageInfo);
  • commandBuffer is the command buffer into which the command will be recorded.

  • pBlitImageInfo is a pointer to a VkBlitImageInfo2 structure describing the blit parameters.

This command is functionally identical to vkCmdBlitImage, but includes extensible sub-structures that include sType and pNext parameters, allowing them to be more easily extended.

Valid Usage
  • VUID-vkCmdBlitImage2-commandBuffer-01834
    If commandBuffer is an unprotected command buffer and protectedNoFault is not supported, srcImage must not be a protected image

  • VUID-vkCmdBlitImage2-commandBuffer-01835
    If commandBuffer is an unprotected command buffer and protectedNoFault is not supported, dstImage must not be a protected image

  • VUID-vkCmdBlitImage2-commandBuffer-01836
    If commandBuffer is a protected command buffer and protectedNoFault is not supported, dstImage must not be an unprotected image

Valid Usage (Implicit)
  • VUID-vkCmdBlitImage2-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdBlitImage2-pBlitImageInfo-parameter
    pBlitImageInfo must be a valid pointer to a valid VkBlitImageInfo2 structure

  • VUID-vkCmdBlitImage2-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdBlitImage2-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support graphics operations

  • VUID-vkCmdBlitImage2-renderpass
    This command must only be called outside of a render pass instance

  • VUID-vkCmdBlitImage2-videocoding
    This command must only be called outside of a video coding scope

Host Synchronization
  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type

Primary
Secondary

Outside

Outside

Graphics

Action

The VkBlitImageInfo2 structure is defined as:

// Provided by VK_VERSION_1_3
typedef struct VkBlitImageInfo2 {
    VkStructureType        sType;
    const void*            pNext;
    VkImage                srcImage;
    VkImageLayout          srcImageLayout;
    VkImage                dstImage;
    VkImageLayout          dstImageLayout;
    uint32_t               regionCount;
    const VkImageBlit2*    pRegions;
    VkFilter               filter;
} VkBlitImageInfo2;

or the equivalent

// Provided by VK_KHR_copy_commands2
typedef VkBlitImageInfo2 VkBlitImageInfo2KHR;
  • sType is a VkStructureType value identifying this structure.

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

  • srcImage is the source image.

  • srcImageLayout is the layout of the source image subresources for the blit.

  • dstImage is the destination image.

  • dstImageLayout is the layout of the destination image subresources for the blit.

  • regionCount is the number of regions to blit.

  • pRegions is a pointer to an array of VkImageBlit2 structures specifying the regions to blit.

  • filter is a VkFilter specifying the filter to apply if the blits require scaling.

Valid Usage
  • VUID-VkBlitImageInfo2-pRegions-00215
    The source region specified by each element of pRegions must be a region that is contained within srcImage

  • VUID-VkBlitImageInfo2-pRegions-00216
    The destination region specified by each element of pRegions must be a region that is contained within dstImage

  • VUID-VkBlitImageInfo2-pRegions-00217
    The union of all destination regions, specified by the elements of pRegions, must not overlap in memory with any texel that may be sampled during the blit operation

  • VUID-VkBlitImageInfo2-srcImage-01999
    The format features of srcImage must contain VK_FORMAT_FEATURE_BLIT_SRC_BIT

  • VUID-VkBlitImageInfo2-srcImage-06421
    srcImage must not use a format that requires a sampler Y′CBCR conversion

  • VUID-VkBlitImageInfo2-srcImage-00219
    srcImage must have been created with VK_IMAGE_USAGE_TRANSFER_SRC_BIT usage flag

  • VUID-VkBlitImageInfo2-srcImage-00220
    If srcImage is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-VkBlitImageInfo2-srcImageLayout-00221
    srcImageLayout must specify the layout of the image subresources of srcImage specified in pRegions at the time this command is executed on a VkDevice

  • VUID-VkBlitImageInfo2-srcImageLayout-01398
    srcImageLayout must be VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR, VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL or VK_IMAGE_LAYOUT_GENERAL

  • VUID-VkBlitImageInfo2-srcImage-09459
    If srcImage and dstImage are the same, and an elements of pRegions contains the srcSubresource and dstSubresource with matching mipLevel and overlapping array layers, then the srcImageLayout and dstImageLayout must be VK_IMAGE_LAYOUT_GENERAL or VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR

  • VUID-VkBlitImageInfo2-dstImage-02000
    The format features of dstImage must contain VK_FORMAT_FEATURE_BLIT_DST_BIT

  • VUID-VkBlitImageInfo2-dstImage-06422
    dstImage must not use a format that requires a sampler Y′CBCR conversion

  • VUID-VkBlitImageInfo2-dstImage-00224
    dstImage must have been created with VK_IMAGE_USAGE_TRANSFER_DST_BIT usage flag

  • VUID-VkBlitImageInfo2-dstImage-00225
    If dstImage is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-VkBlitImageInfo2-dstImageLayout-00226
    dstImageLayout must specify the layout of the image subresources of dstImage specified in pRegions at the time this command is executed on a VkDevice

  • VUID-VkBlitImageInfo2-dstImageLayout-01399
    dstImageLayout must be VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR, VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL or VK_IMAGE_LAYOUT_GENERAL

  • VUID-VkBlitImageInfo2-srcImage-00229
    If either of srcImage or dstImage was created with a signed integer VkFormat, the other must also have been created with a signed integer VkFormat

  • VUID-VkBlitImageInfo2-srcImage-00230
    If either of srcImage or dstImage was created with an unsigned integer VkFormat, the other must also have been created with an unsigned integer VkFormat

  • VUID-VkBlitImageInfo2-srcImage-00231
    If either of srcImage or dstImage was created with a depth/stencil format, the other must have exactly the same format

  • VUID-VkBlitImageInfo2-srcImage-00232
    If srcImage was created with a depth/stencil format, filter must be VK_FILTER_NEAREST

  • VUID-VkBlitImageInfo2-srcImage-00233
    srcImage must have been created with a samples value of VK_SAMPLE_COUNT_1_BIT

  • VUID-VkBlitImageInfo2-dstImage-00234
    dstImage must have been created with a samples value of VK_SAMPLE_COUNT_1_BIT

  • VUID-VkBlitImageInfo2-filter-02001
    If filter is VK_FILTER_LINEAR, then the format features of srcImage must contain VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT

  • VUID-VkBlitImageInfo2-filter-02002
    If filter is VK_FILTER_CUBIC_EXT, then the format features of srcImage must contain VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_CUBIC_BIT_EXT

  • VUID-VkBlitImageInfo2-filter-00237
    If filter is VK_FILTER_CUBIC_EXT, srcImage must be of type VK_IMAGE_TYPE_2D

  • VUID-VkBlitImageInfo2-srcSubresource-01705
    The srcSubresource.mipLevel member of each element of pRegions must be less than the mipLevels specified in VkImageCreateInfo when srcImage was created

  • VUID-VkBlitImageInfo2-dstSubresource-01706
    The dstSubresource.mipLevel member of each element of pRegions must be less than the mipLevels specified in VkImageCreateInfo when dstImage was created

  • VUID-VkBlitImageInfo2-srcSubresource-01707
    If srcSubresource.layerCount is not VK_REMAINING_ARRAY_LAYERS, srcSubresource.baseArrayLayer + srcSubresource.layerCount of each element of pRegions must be less than or equal to the arrayLayers specified in VkImageCreateInfo when srcImage was created

  • VUID-VkBlitImageInfo2-dstSubresource-01708
    If srcSubresource.layerCount is not VK_REMAINING_ARRAY_LAYERS, dstSubresource.baseArrayLayer + dstSubresource.layerCount of each element of pRegions must be less than or equal to the arrayLayers specified in VkImageCreateInfo when dstImage was created

  • VUID-VkBlitImageInfo2-dstImage-02545
    dstImage and srcImage must not have been created with flags containing VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT

  • VUID-VkBlitImageInfo2-srcImage-00240
    If either srcImage or dstImage is of type VK_IMAGE_TYPE_3D, then for each element of pRegions, srcSubresource.baseArrayLayer and dstSubresource.baseArrayLayer must each be 0, and srcSubresource.layerCount and dstSubresource.layerCount must each be 1

  • VUID-VkBlitImageInfo2-aspectMask-00241
    For each element of pRegions, srcSubresource.aspectMask must specify aspects present in srcImage

  • VUID-VkBlitImageInfo2-aspectMask-00242
    For each element of pRegions, dstSubresource.aspectMask must specify aspects present in dstImage

  • VUID-VkBlitImageInfo2-srcOffset-00243
    For each element of pRegions, srcOffsets[0].x and srcOffsets[1].x must both be greater than or equal to 0 and less than or equal to the width of the specified srcSubresource of srcImage

  • VUID-VkBlitImageInfo2-srcOffset-00244
    For each element of pRegions, srcOffsets[0].y and srcOffsets[1].y must both be greater than or equal to 0 and less than or equal to the height of the specified srcSubresource of srcImage

  • VUID-VkBlitImageInfo2-srcImage-00245
    If srcImage is of type VK_IMAGE_TYPE_1D, then for each element of pRegions, srcOffsets[0].y must be 0 and srcOffsets[1].y must be 1

  • VUID-VkBlitImageInfo2-srcOffset-00246
    For each element of pRegions, srcOffsets[0].z and srcOffsets[1].z must both be greater than or equal to 0 and less than or equal to the depth of the specified srcSubresource of srcImage

  • VUID-VkBlitImageInfo2-srcImage-00247
    If srcImage is of type VK_IMAGE_TYPE_1D or VK_IMAGE_TYPE_2D, then for each element of pRegions, srcOffsets[0].z must be 0 and srcOffsets[1].z must be 1

  • VUID-VkBlitImageInfo2-dstOffset-00248
    For each element of pRegions, dstOffsets[0].x and dstOffsets[1].x must both be greater than or equal to 0 and less than or equal to the width of the specified dstSubresource of dstImage

  • VUID-VkBlitImageInfo2-dstOffset-00249
    For each element of pRegions, dstOffsets[0].y and dstOffsets[1].y must both be greater than or equal to 0 and less than or equal to the height of the specified dstSubresource of dstImage

  • VUID-VkBlitImageInfo2-dstImage-00250
    If dstImage is of type VK_IMAGE_TYPE_1D, then for each element of pRegions, dstOffsets[0].y must be 0 and dstOffsets[1].y must be 1

  • VUID-VkBlitImageInfo2-dstOffset-00251
    For each element of pRegions, dstOffsets[0].z and dstOffsets[1].z must both be greater than or equal to 0 and less than or equal to the depth of the specified dstSubresource of dstImage

  • VUID-VkBlitImageInfo2-dstImage-00252
    If dstImage is of type VK_IMAGE_TYPE_1D or VK_IMAGE_TYPE_2D, then for each element of pRegions, dstOffsets[0].z must be 0 and dstOffsets[1].z must be 1

  • VUID-VkBlitImageInfo2-pRegions-04561
    If any element of pRegions contains VkCopyCommandTransformInfoQCOM in its pNext chain, then srcImage and dstImage must not be block-compressed images

  • VUID-VkBlitImageInfo2KHR-pRegions-06207
    If any element of pRegions contains VkCopyCommandTransformInfoQCOM in its pNext chain, then srcImage must be of type VK_IMAGE_TYPE_2D

  • VUID-VkBlitImageInfo2KHR-pRegions-06208
    If any element of pRegions contains VkCopyCommandTransformInfoQCOM in its pNext chain, then srcImage must not have a multi-planar format

  • VUID-VkBlitImageInfo2-filter-09204
    If filter is VK_FILTER_CUBIC_EXT and if the selectableCubicWeights feature is not enabled then the cubic weights must be VK_CUBIC_FILTER_WEIGHTS_CATMULL_ROM_QCOM

Valid Usage (Implicit)
  • VUID-VkBlitImageInfo2-sType-sType
    sType must be VK_STRUCTURE_TYPE_BLIT_IMAGE_INFO_2

  • VUID-VkBlitImageInfo2-pNext-pNext
    pNext must be NULL or a pointer to a valid instance of VkBlitImageCubicWeightsInfoQCOM

  • VUID-VkBlitImageInfo2-sType-unique
    The sType value of each struct in the pNext chain must be unique

  • VUID-VkBlitImageInfo2-srcImage-parameter
    srcImage must be a valid VkImage handle

  • VUID-VkBlitImageInfo2-srcImageLayout-parameter
    srcImageLayout must be a valid VkImageLayout value

  • VUID-VkBlitImageInfo2-dstImage-parameter
    dstImage must be a valid VkImage handle

  • VUID-VkBlitImageInfo2-dstImageLayout-parameter
    dstImageLayout must be a valid VkImageLayout value

  • VUID-VkBlitImageInfo2-pRegions-parameter
    pRegions must be a valid pointer to an array of regionCount valid VkImageBlit2 structures

  • VUID-VkBlitImageInfo2-filter-parameter
    filter must be a valid VkFilter value

  • VUID-VkBlitImageInfo2-regionCount-arraylength
    regionCount must be greater than 0

  • VUID-VkBlitImageInfo2-commonparent
    Both of dstImage, and srcImage must have been created, allocated, or retrieved from the same VkDevice

If filter is VK_FILTER_CUBIC_EXT and if the pNext chain of VkBlitImageInfo2 includes a VkBlitImageCubicWeightsInfoQCOM structure, then that structure specifies cubic weights are used in the blit. If that structure is not present, then cubic weights are considered to be VK_CUBIC_FILTER_WEIGHTS_CATMULL_ROM_QCOM.

The VkBlitImageCubicWeightsInfoQCOM structure is defined as:

// Provided by VK_QCOM_filter_cubic_weights
typedef struct VkBlitImageCubicWeightsInfoQCOM {
    VkStructureType             sType;
    const void*                 pNext;
    VkCubicFilterWeightsQCOM    cubicWeights;
} VkBlitImageCubicWeightsInfoQCOM;
  • sType is a VkStructureType value identifying this structure.

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

  • cubicWeights is a VkCubicFilterWeightsQCOM value controlling cubic filter weights for the blit.

Valid Usage (Implicit)
  • VUID-VkBlitImageCubicWeightsInfoQCOM-sType-sType
    sType must be VK_STRUCTURE_TYPE_BLIT_IMAGE_CUBIC_WEIGHTS_INFO_QCOM

  • VUID-VkBlitImageCubicWeightsInfoQCOM-cubicWeights-parameter
    cubicWeights must be a valid VkCubicFilterWeightsQCOM value

The VkImageBlit2 structure is defined as:

// Provided by VK_VERSION_1_3
typedef struct VkImageBlit2 {
    VkStructureType             sType;
    const void*                 pNext;
    VkImageSubresourceLayers    srcSubresource;
    VkOffset3D                  srcOffsets[2];
    VkImageSubresourceLayers    dstSubresource;
    VkOffset3D                  dstOffsets[2];
} VkImageBlit2;

or the equivalent

// Provided by VK_KHR_copy_commands2
typedef VkImageBlit2 VkImageBlit2KHR;
  • sType is a VkStructureType value identifying this structure.

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

  • srcSubresource is the subresource to blit from.

  • srcOffsets is a pointer to an array of two VkOffset3D structures specifying the bounds of the source region within srcSubresource.

  • dstSubresource is the subresource to blit into.

  • dstOffsets is a pointer to an array of two VkOffset3D structures specifying the bounds of the destination region within dstSubresource.

For each element of the pRegions array, a blit operation is performed for the specified source and destination regions.

Valid Usage
  • VUID-VkImageBlit2-aspectMask-00238
    The aspectMask member of srcSubresource and dstSubresource must match

  • VUID-VkImageBlit2-layerCount-08800
    If neither of the layerCount members of srcSubresource or dstSubresource are VK_REMAINING_ARRAY_LAYERS, the layerCount members of srcSubresource or dstSubresource must match

  • VUID-VkImageBlit2-layerCount-08801
    If one of the layerCount members of srcSubresource or dstSubresource is VK_REMAINING_ARRAY_LAYERS, the other member must be either VK_REMAINING_ARRAY_LAYERS or equal to the arrayLayers member of the VkImageCreateInfo used to create the image minus baseArrayLayer

Valid Usage (Implicit)
  • VUID-VkImageBlit2-sType-sType
    sType must be VK_STRUCTURE_TYPE_IMAGE_BLIT_2

  • VUID-VkImageBlit2-pNext-pNext
    pNext must be NULL or a pointer to a valid instance of VkCopyCommandTransformInfoQCOM

  • VUID-VkImageBlit2-sType-unique
    The sType value of each struct in the pNext chain must be unique

  • VUID-VkImageBlit2-srcSubresource-parameter
    srcSubresource must be a valid VkImageSubresourceLayers structure

  • VUID-VkImageBlit2-dstSubresource-parameter
    dstSubresource must be a valid VkImageSubresourceLayers structure

For vkCmdBlitImage2, each region copied can include a rotation. To specify a rotated region, add VkCopyCommandTransformInfoQCOM to the pNext chain of VkImageBlit2. For each region with a rotation specified, Image Blits with Scaling and Rotation specifies how coordinates are rotated prior to sampling from the source image. When rotation is specified, the source and destination images must each be 2D images, have a 1x1x1 texel block extent, and only one plane.

Image Blits With Scaling and Rotation

When VkCopyCommandTransformInfoQCOM is in the pNext chain of VkImageBlit2, the specified region is rotated during the blit. The following description of rotated addressing replaces the description in vkCmdBlitImage.

The following code computes rotation of normalized coordinates.

// rotation of normalized coordinates
VkOffset2D RotateNormUV(VkOffset2D in, VkSurfaceTransformFlagBitsKHR flags)
{
    VkOffset2D output;
    switch (flags)
    {
        case VK_SURFACE_TRANSFORM_IDENTITY_BIT_KHR:
            out.x = in.x;
            out.y = in.y;
            break;
        case VK_SURFACE_TRANSFORM_ROTATE_90_BIT_KHR:
            out.x = in.y;
            out.y = 1.0 - in.x;
            break;
        case VK_SURFACE_TRANSFORM_ROTATE_180_BIT_KHR:
            out.x = 1.0 - in.x;
            out.y = 1.0 - in.y;
            break;
        case VK_SURFACE_TRANSFORM_ROTATE_270_BIT_KHR:
            out.x = 1.0 - in.y;
            out.y = in.x;
            break;
    }
    return out;
}
  • For each destination texel, the integer coordinate of that texel is converted to an unnormalized texture coordinate, using the effective inverse of the equations described in unnormalized to integer conversion:

    ubase = i + ½

    vbase = j + ½

    wbase = k + ½

  • These base coordinates are then offset by the first destination offset:

    uoffset = ubase - xdst0

    voffset = vbase - ydst0

    woffset = wbase - zdst0

    aoffset = a - baseArrayCountdst

  • The UV destination coordinates are scaled by the destination region, rotated, and scaled by the source region.

    udest_scaled = uoffset / (xdst1 - xdst0)

    vdest_scaled = voffset / (ydst1 - ydst0)

    (usrc_scaled, vsrc_scaled) = RotateNormUV(udest_scaled, vdest_scaled, transform)

    uscaled = usrc_scaled × (xSrc1 - xSrc0)

    vscaled = vsrc_scaled × (ySrc1 - ySrc0)

  • The W coordinate is unaffected by rotation. The scale is determined from the ratio of source and destination regions, and applied to the offset coordinate:

    scalew = (zSrc1 - zSrc0) / (zdst1 - zdst0)

    wscaled = woffset × scalew

  • Finally the source offset is added to the scaled source coordinates, to determine the final unnormalized coordinates used to sample from srcImage:

    u = uscaled + xSrc0

    v = vscaled + ySrc0

    w = wscaled + zSrc0

    q = mipLevel

    a = aoffset + baseArrayCountsrc

These coordinates are used to sample from the source image as described for Image Operations, with the filter mode equal to that of filter; a mipmap mode of VK_SAMPLER_MIPMAP_MODE_NEAREST; and an address mode of VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE. Implementations must clamp at the edge of the source image, and may additionally clamp to the edge of the source region.

Resolving Multisample Images

To resolve a multisample color image to a non-multisample color image, call:

// Provided by VK_VERSION_1_0
void vkCmdResolveImage(
    VkCommandBuffer                             commandBuffer,
    VkImage                                     srcImage,
    VkImageLayout                               srcImageLayout,
    VkImage                                     dstImage,
    VkImageLayout                               dstImageLayout,
    uint32_t                                    regionCount,
    const VkImageResolve*                       pRegions);
  • commandBuffer is the command buffer into which the command will be recorded.

  • srcImage is the source image.

  • srcImageLayout is the layout of the source image subresources for the resolve.

  • dstImage is the destination image.

  • dstImageLayout is the layout of the destination image subresources for the resolve.

  • regionCount is the number of regions to resolve.

  • pRegions is a pointer to an array of VkImageResolve structures specifying the regions to resolve.

During the resolve the samples corresponding to each pixel location in the source are converted to a single sample before being written to the destination. If the source formats are floating-point or normalized types, the sample values for each pixel are resolved in an implementation-dependent manner. If the source formats are integer types, a single sample’s value is selected for each pixel.

srcOffset and dstOffset select the initial x, y, and z offsets in texels of the sub-regions of the source and destination image data. extent is the size in texels of the source image to resolve in width, height and depth. Each element of pRegions must be a region that is contained within its corresponding image.

Resolves are done layer by layer starting with baseArrayLayer member of srcSubresource for the source and dstSubresource for the destination. layerCount layers are resolved to the destination image.

Valid Usage
  • VUID-vkCmdResolveImage-commandBuffer-01837
    If commandBuffer is an unprotected command buffer and protectedNoFault is not supported, srcImage must not be a protected image

  • VUID-vkCmdResolveImage-commandBuffer-01838
    If commandBuffer is an unprotected command buffer and protectedNoFault is not supported, dstImage must not be a protected image

  • VUID-vkCmdResolveImage-commandBuffer-01839
    If commandBuffer is a protected command buffer and protectedNoFault is not supported, dstImage must not be an unprotected image

  • VUID-vkCmdResolveImage-pRegions-00255
    The union of all source regions, and the union of all destination regions, specified by the elements of pRegions, must not overlap in memory

  • VUID-vkCmdResolveImage-srcImage-00256
    If srcImage is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-vkCmdResolveImage-srcImage-00257
    srcImage must have a sample count equal to any valid sample count value other than VK_SAMPLE_COUNT_1_BIT

  • VUID-vkCmdResolveImage-dstImage-00258
    If dstImage is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-vkCmdResolveImage-dstImage-00259
    dstImage must have a sample count equal to VK_SAMPLE_COUNT_1_BIT

  • VUID-vkCmdResolveImage-srcImageLayout-00260
    srcImageLayout must specify the layout of the image subresources of srcImage specified in pRegions at the time this command is executed on a VkDevice

  • VUID-vkCmdResolveImage-srcImageLayout-01400
    srcImageLayout must be VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR, VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL or VK_IMAGE_LAYOUT_GENERAL

  • VUID-vkCmdResolveImage-dstImageLayout-00262
    dstImageLayout must specify the layout of the image subresources of dstImage specified in pRegions at the time this command is executed on a VkDevice

  • VUID-vkCmdResolveImage-dstImageLayout-01401
    dstImageLayout must be VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR, VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL or VK_IMAGE_LAYOUT_GENERAL

  • VUID-vkCmdResolveImage-dstImage-02003
    The format features of dstImage must contain VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT

  • VUID-vkCmdResolveImage-linearColorAttachment-06519
    If the linearColorAttachment feature is enabled and the image is created with VK_IMAGE_TILING_LINEAR, the format features of dstImage must contain VK_FORMAT_FEATURE_2_LINEAR_COLOR_ATTACHMENT_BIT_NV

  • VUID-vkCmdResolveImage-srcImage-01386
    srcImage and dstImage must have been created with the same image format

  • VUID-vkCmdResolveImage-srcSubresource-01709
    The srcSubresource.mipLevel member of each element of pRegions must be less than the mipLevels specified in VkImageCreateInfo when srcImage was created

  • VUID-vkCmdResolveImage-dstSubresource-01710
    The dstSubresource.mipLevel member of each element of pRegions must be less than the mipLevels specified in VkImageCreateInfo when dstImage was created

  • VUID-vkCmdResolveImage-srcSubresource-01711
    If srcSubresource.layerCount is not VK_REMAINING_ARRAY_LAYERS, srcSubresource.baseArrayLayer + srcSubresource.layerCount of each element of pRegions must be less than or equal to the arrayLayers specified in VkImageCreateInfo when srcImage was created

  • VUID-vkCmdResolveImage-dstSubresource-01712
    If dstSubresource.layerCount is not VK_REMAINING_ARRAY_LAYERS, dstSubresource.baseArrayLayer + dstSubresource.layerCount of each element of pRegions must be less than or equal to the arrayLayers specified in VkImageCreateInfo when dstImage was created

  • VUID-vkCmdResolveImage-dstImage-02546
    dstImage and srcImage must not have been created with flags containing VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT

  • VUID-vkCmdResolveImage-srcImage-04446
    If dstImage is of type VK_IMAGE_TYPE_3D, then for each element of pRegions, srcSubresource.layerCount must be 1

  • VUID-vkCmdResolveImage-srcImage-04447
    If dstImage is of type VK_IMAGE_TYPE_3D, then for each element of pRegions, dstSubresource.baseArrayLayer must be 0 and dstSubresource.layerCount must be 1

  • VUID-vkCmdResolveImage-srcOffset-00269
    For each element of pRegions, srcOffset.x and (extent.width + srcOffset.x) must both be greater than or equal to 0 and less than or equal to the width of the specified srcSubresource of srcImage

  • VUID-vkCmdResolveImage-srcOffset-00270
    For each element of pRegions, srcOffset.y and (extent.height + srcOffset.y) must both be greater than or equal to 0 and less than or equal to the height of the specified srcSubresource of srcImage

  • VUID-vkCmdResolveImage-srcImage-00271
    If srcImage is of type VK_IMAGE_TYPE_1D, then for each element of pRegions, srcOffset.y must be 0 and extent.height must be 1

  • VUID-vkCmdResolveImage-srcOffset-00272
    For each element of pRegions, srcOffset.z and (extent.depth + srcOffset.z) must both be greater than or equal to 0 and less than or equal to the depth of the specified srcSubresource of srcImage

  • VUID-vkCmdResolveImage-srcImage-00273
    If srcImage is of type VK_IMAGE_TYPE_1D or VK_IMAGE_TYPE_2D, then for each element of pRegions, srcOffset.z must be 0 and extent.depth must be 1

  • VUID-vkCmdResolveImage-dstOffset-00274
    For each element of pRegions, dstOffset.x and (extent.width + dstOffset.x) must both be greater than or equal to 0 and less than or equal to the width of the specified dstSubresource of dstImage

  • VUID-vkCmdResolveImage-dstOffset-00275
    For each element of pRegions, dstOffset.y and (extent.height + dstOffset.y) must both be greater than or equal to 0 and less than or equal to the height of the specified dstSubresource of dstImage

  • VUID-vkCmdResolveImage-dstImage-00276
    If dstImage is of type VK_IMAGE_TYPE_1D, then for each element of pRegions, dstOffset.y must be 0 and extent.height must be 1

  • VUID-vkCmdResolveImage-dstOffset-00277
    For each element of pRegions, dstOffset.z and (extent.depth + dstOffset.z) must both be greater than or equal to 0 and less than or equal to the depth of the specified dstSubresource of dstImage

  • VUID-vkCmdResolveImage-dstImage-00278
    If dstImage is of type VK_IMAGE_TYPE_1D or VK_IMAGE_TYPE_2D, then for each element of pRegions, dstOffset.z must be 0 and extent.depth must be 1

  • VUID-vkCmdResolveImage-srcImage-06762
    srcImage must have been created with VK_IMAGE_USAGE_TRANSFER_SRC_BIT usage flag

  • VUID-vkCmdResolveImage-srcImage-06763
    The format features of srcImage must contain VK_FORMAT_FEATURE_TRANSFER_SRC_BIT

  • VUID-vkCmdResolveImage-dstImage-06764
    dstImage must have been created with VK_IMAGE_USAGE_TRANSFER_DST_BIT usage flag

  • VUID-vkCmdResolveImage-dstImage-06765
    The format features of dstImage must contain VK_FORMAT_FEATURE_TRANSFER_DST_BIT

Valid Usage (Implicit)
  • VUID-vkCmdResolveImage-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdResolveImage-srcImage-parameter
    srcImage must be a valid VkImage handle

  • VUID-vkCmdResolveImage-srcImageLayout-parameter
    srcImageLayout must be a valid VkImageLayout value

  • VUID-vkCmdResolveImage-dstImage-parameter
    dstImage must be a valid VkImage handle

  • VUID-vkCmdResolveImage-dstImageLayout-parameter
    dstImageLayout must be a valid VkImageLayout value

  • VUID-vkCmdResolveImage-pRegions-parameter
    pRegions must be a valid pointer to an array of regionCount valid VkImageResolve structures

  • VUID-vkCmdResolveImage-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdResolveImage-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support graphics operations

  • VUID-vkCmdResolveImage-renderpass
    This command must only be called outside of a render pass instance

  • VUID-vkCmdResolveImage-videocoding
    This command must only be called outside of a video coding scope

  • VUID-vkCmdResolveImage-regionCount-arraylength
    regionCount must be greater than 0

  • VUID-vkCmdResolveImage-commonparent
    Each of commandBuffer, dstImage, and srcImage must have been created, allocated, or retrieved from the same VkDevice

Host Synchronization
  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type

Primary
Secondary

Outside

Outside

Graphics

Action

The VkImageResolve structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkImageResolve {
    VkImageSubresourceLayers    srcSubresource;
    VkOffset3D                  srcOffset;
    VkImageSubresourceLayers    dstSubresource;
    VkOffset3D                  dstOffset;
    VkExtent3D                  extent;
} VkImageResolve;
  • srcSubresource and dstSubresource are VkImageSubresourceLayers structures specifying the image subresources of the images used for the source and destination image data, respectively. Resolve of depth/stencil images is not supported.

  • srcOffset and dstOffset select the initial x, y, and z offsets in texels of the sub-regions of the source and destination image data.

  • extent is the size in texels of the source image to resolve in width, height and depth.

Valid Usage
  • VUID-VkImageResolve-aspectMask-00266
    The aspectMask member of srcSubresource and dstSubresource must only contain VK_IMAGE_ASPECT_COLOR_BIT

  • VUID-VkImageResolve-layerCount-08803
    If neither of the layerCount members of srcSubresource or dstSubresource are VK_REMAINING_ARRAY_LAYERS, the layerCount member of srcSubresource and dstSubresource must match

  • VUID-VkImageResolve-layerCount-08804
    If one of the layerCount members of srcSubresource or dstSubresource is VK_REMAINING_ARRAY_LAYERS, the other member must be either VK_REMAINING_ARRAY_LAYERS or equal to the arrayLayers member of the VkImageCreateInfo used to create the image minus baseArrayLayer

Valid Usage (Implicit)

A more extensible version of the resolve image command is defined below.

To resolve a multisample image to a non-multisample image, call:

// Provided by VK_VERSION_1_3
void vkCmdResolveImage2(
    VkCommandBuffer                             commandBuffer,
    const VkResolveImageInfo2*                  pResolveImageInfo);

or the equivalent command

// Provided by VK_KHR_copy_commands2
void vkCmdResolveImage2KHR(
    VkCommandBuffer                             commandBuffer,
    const VkResolveImageInfo2*                  pResolveImageInfo);
  • commandBuffer is the command buffer into which the command will be recorded.

  • pResolveImageInfo is a pointer to a VkResolveImageInfo2 structure describing the resolve parameters.

This command is functionally identical to vkCmdResolveImage, but includes extensible sub-structures that include sType and pNext parameters, allowing them to be more easily extended.

Valid Usage
  • VUID-vkCmdResolveImage2-commandBuffer-01837
    If commandBuffer is an unprotected command buffer and protectedNoFault is not supported, srcImage must not be a protected image

  • VUID-vkCmdResolveImage2-commandBuffer-01838
    If commandBuffer is an unprotected command buffer and protectedNoFault is not supported, dstImage must not be a protected image

  • VUID-vkCmdResolveImage2-commandBuffer-01839
    If commandBuffer is a protected command buffer and protectedNoFault is not supported, dstImage must not be an unprotected image

Valid Usage (Implicit)
  • VUID-vkCmdResolveImage2-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdResolveImage2-pResolveImageInfo-parameter
    pResolveImageInfo must be a valid pointer to a valid VkResolveImageInfo2 structure

  • VUID-vkCmdResolveImage2-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdResolveImage2-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support graphics operations

  • VUID-vkCmdResolveImage2-renderpass
    This command must only be called outside of a render pass instance

  • VUID-vkCmdResolveImage2-videocoding
    This command must only be called outside of a video coding scope

Host Synchronization
  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type

Primary
Secondary

Outside

Outside

Graphics

Action

The VkResolveImageInfo2 structure is defined as:

// Provided by VK_VERSION_1_3
typedef struct VkResolveImageInfo2 {
    VkStructureType           sType;
    const void*               pNext;
    VkImage                   srcImage;
    VkImageLayout             srcImageLayout;
    VkImage                   dstImage;
    VkImageLayout             dstImageLayout;
    uint32_t                  regionCount;
    const VkImageResolve2*    pRegions;
} VkResolveImageInfo2;

or the equivalent

// Provided by VK_KHR_copy_commands2
typedef VkResolveImageInfo2 VkResolveImageInfo2KHR;
  • sType is a VkStructureType value identifying this structure.

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

  • srcImage is the source image.

  • srcImageLayout is the layout of the source image subresources for the resolve.

  • dstImage is the destination image.

  • dstImageLayout is the layout of the destination image subresources for the resolve.

  • regionCount is the number of regions to resolve.

  • pRegions is a pointer to an array of VkImageResolve2 structures specifying the regions to resolve.

Valid Usage
  • VUID-VkResolveImageInfo2-pRegions-00255
    The union of all source regions, and the union of all destination regions, specified by the elements of pRegions, must not overlap in memory

  • VUID-VkResolveImageInfo2-srcImage-00256
    If srcImage is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-VkResolveImageInfo2-srcImage-00257
    srcImage must have a sample count equal to any valid sample count value other than VK_SAMPLE_COUNT_1_BIT

  • VUID-VkResolveImageInfo2-dstImage-00258
    If dstImage is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-VkResolveImageInfo2-dstImage-00259
    dstImage must have a sample count equal to VK_SAMPLE_COUNT_1_BIT

  • VUID-VkResolveImageInfo2-srcImageLayout-00260
    srcImageLayout must specify the layout of the image subresources of srcImage specified in pRegions at the time this command is executed on a VkDevice

  • VUID-VkResolveImageInfo2-srcImageLayout-01400
    srcImageLayout must be VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR, VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL or VK_IMAGE_LAYOUT_GENERAL

  • VUID-VkResolveImageInfo2-dstImageLayout-00262
    dstImageLayout must specify the layout of the image subresources of dstImage specified in pRegions at the time this command is executed on a VkDevice

  • VUID-VkResolveImageInfo2-dstImageLayout-01401
    dstImageLayout must be VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR, VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL or VK_IMAGE_LAYOUT_GENERAL

  • VUID-VkResolveImageInfo2-dstImage-02003
    The format features of dstImage must contain VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT

  • VUID-VkResolveImageInfo2-linearColorAttachment-06519
    If the linearColorAttachment feature is enabled and the image is created with VK_IMAGE_TILING_LINEAR, the format features of dstImage must contain VK_FORMAT_FEATURE_2_LINEAR_COLOR_ATTACHMENT_BIT_NV

  • VUID-VkResolveImageInfo2-srcImage-01386
    srcImage and dstImage must have been created with the same image format

  • VUID-VkResolveImageInfo2-srcSubresource-01709
    The srcSubresource.mipLevel member of each element of pRegions must be less than the mipLevels specified in VkImageCreateInfo when srcImage was created

  • VUID-VkResolveImageInfo2-dstSubresource-01710
    The dstSubresource.mipLevel member of each element of pRegions must be less than the mipLevels specified in VkImageCreateInfo when dstImage was created

  • VUID-VkResolveImageInfo2-srcSubresource-01711
    If srcSubresource.layerCount is not VK_REMAINING_ARRAY_LAYERS, srcSubresource.baseArrayLayer + srcSubresource.layerCount of each element of pRegions must be less than or equal to the arrayLayers specified in VkImageCreateInfo when srcImage was created

  • VUID-VkResolveImageInfo2-dstSubresource-01712
    If dstSubresource.layerCount is not VK_REMAINING_ARRAY_LAYERS, dstSubresource.baseArrayLayer + dstSubresource.layerCount of each element of pRegions must be less than or equal to the arrayLayers specified in VkImageCreateInfo when dstImage was created

  • VUID-VkResolveImageInfo2-dstImage-02546
    dstImage and srcImage must not have been created with flags containing VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT

  • VUID-VkResolveImageInfo2-srcImage-04446
    If dstImage is of type VK_IMAGE_TYPE_3D, then for each element of pRegions, srcSubresource.layerCount must be 1

  • VUID-VkResolveImageInfo2-srcImage-04447
    If dstImage is of type VK_IMAGE_TYPE_3D, then for each element of pRegions, dstSubresource.baseArrayLayer must be 0 and dstSubresource.layerCount must be 1

  • VUID-VkResolveImageInfo2-srcOffset-00269
    For each element of pRegions, srcOffset.x and (extent.width + srcOffset.x) must both be greater than or equal to 0 and less than or equal to the width of the specified srcSubresource of srcImage

  • VUID-VkResolveImageInfo2-srcOffset-00270
    For each element of pRegions, srcOffset.y and (extent.height + srcOffset.y) must both be greater than or equal to 0 and less than or equal to the height of the specified srcSubresource of srcImage

  • VUID-VkResolveImageInfo2-srcImage-00271
    If srcImage is of type VK_IMAGE_TYPE_1D, then for each element of pRegions, srcOffset.y must be 0 and extent.height must be 1

  • VUID-VkResolveImageInfo2-srcOffset-00272
    For each element of pRegions, srcOffset.z and (extent.depth + srcOffset.z) must both be greater than or equal to 0 and less than or equal to the depth of the specified srcSubresource of srcImage

  • VUID-VkResolveImageInfo2-srcImage-00273
    If srcImage is of type VK_IMAGE_TYPE_1D or VK_IMAGE_TYPE_2D, then for each element of pRegions, srcOffset.z must be 0 and extent.depth must be 1

  • VUID-VkResolveImageInfo2-dstOffset-00274
    For each element of pRegions, dstOffset.x and (extent.width + dstOffset.x) must both be greater than or equal to 0 and less than or equal to the width of the specified dstSubresource of dstImage

  • VUID-VkResolveImageInfo2-dstOffset-00275
    For each element of pRegions, dstOffset.y and (extent.height + dstOffset.y) must both be greater than or equal to 0 and less than or equal to the height of the specified dstSubresource of dstImage

  • VUID-VkResolveImageInfo2-dstImage-00276
    If dstImage is of type VK_IMAGE_TYPE_1D, then for each element of pRegions, dstOffset.y must be 0 and extent.height must be 1

  • VUID-VkResolveImageInfo2-dstOffset-00277
    For each element of pRegions, dstOffset.z and (extent.depth + dstOffset.z) must both be greater than or equal to 0 and less than or equal to the depth of the specified dstSubresource of dstImage

  • VUID-VkResolveImageInfo2-dstImage-00278
    If dstImage is of type VK_IMAGE_TYPE_1D or VK_IMAGE_TYPE_2D, then for each element of pRegions, dstOffset.z must be 0 and extent.depth must be 1

  • VUID-VkResolveImageInfo2-srcImage-06762
    srcImage must have been created with VK_IMAGE_USAGE_TRANSFER_SRC_BIT usage flag

  • VUID-VkResolveImageInfo2-srcImage-06763
    The format features of srcImage must contain VK_FORMAT_FEATURE_TRANSFER_SRC_BIT

  • VUID-VkResolveImageInfo2-dstImage-06764
    dstImage must have been created with VK_IMAGE_USAGE_TRANSFER_DST_BIT usage flag

  • VUID-VkResolveImageInfo2-dstImage-06765
    The format features of dstImage must contain VK_FORMAT_FEATURE_TRANSFER_DST_BIT

Valid Usage (Implicit)
  • VUID-VkResolveImageInfo2-sType-sType
    sType must be VK_STRUCTURE_TYPE_RESOLVE_IMAGE_INFO_2

  • VUID-VkResolveImageInfo2-pNext-pNext
    pNext must be NULL

  • VUID-VkResolveImageInfo2-srcImage-parameter
    srcImage must be a valid VkImage handle

  • VUID-VkResolveImageInfo2-srcImageLayout-parameter
    srcImageLayout must be a valid VkImageLayout value

  • VUID-VkResolveImageInfo2-dstImage-parameter
    dstImage must be a valid VkImage handle

  • VUID-VkResolveImageInfo2-dstImageLayout-parameter
    dstImageLayout must be a valid VkImageLayout value

  • VUID-VkResolveImageInfo2-pRegions-parameter
    pRegions must be a valid pointer to an array of regionCount valid VkImageResolve2 structures

  • VUID-VkResolveImageInfo2-regionCount-arraylength
    regionCount must be greater than 0

  • VUID-VkResolveImageInfo2-commonparent
    Both of dstImage, and srcImage must have been created, allocated, or retrieved from the same VkDevice

The VkImageResolve2 structure is defined as:

// Provided by VK_VERSION_1_3
typedef struct VkImageResolve2 {
    VkStructureType             sType;
    const void*                 pNext;
    VkImageSubresourceLayers    srcSubresource;
    VkOffset3D                  srcOffset;
    VkImageSubresourceLayers    dstSubresource;
    VkOffset3D                  dstOffset;
    VkExtent3D                  extent;
} VkImageResolve2;

or the equivalent

// Provided by VK_KHR_copy_commands2
typedef VkImageResolve2 VkImageResolve2KHR;
  • sType is a VkStructureType value identifying this structure.

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

  • srcSubresource and dstSubresource are VkImageSubresourceLayers structures specifying the image subresources of the images used for the source and destination image data, respectively. Resolve of depth/stencil images is not supported.

  • srcOffset and dstOffset select the initial x, y, and z offsets in texels of the sub-regions of the source and destination image data.

  • extent is the size in texels of the source image to resolve in width, height and depth.

Valid Usage
  • VUID-VkImageResolve2-aspectMask-00266
    The aspectMask member of srcSubresource and dstSubresource must only contain VK_IMAGE_ASPECT_COLOR_BIT

  • VUID-VkImageResolve2-layerCount-08803
    If neither of the layerCount members of srcSubresource or dstSubresource are VK_REMAINING_ARRAY_LAYERS, the layerCount member of srcSubresource and dstSubresource must match

  • VUID-VkImageResolve2-layerCount-08804
    If one of the layerCount members of srcSubresource or dstSubresource is VK_REMAINING_ARRAY_LAYERS, the other member must be either VK_REMAINING_ARRAY_LAYERS or equal to the arrayLayers member of the VkImageCreateInfo used to create the image minus baseArrayLayer

Valid Usage (Implicit)
  • VUID-VkImageResolve2-sType-sType
    sType must be VK_STRUCTURE_TYPE_IMAGE_RESOLVE_2

  • VUID-VkImageResolve2-pNext-pNext
    pNext must be NULL

  • VUID-VkImageResolve2-srcSubresource-parameter
    srcSubresource must be a valid VkImageSubresourceLayers structure

  • VUID-VkImageResolve2-dstSubresource-parameter
    dstSubresource must be a valid VkImageSubresourceLayers structure

Buffer Markers

To write a 32-bit marker value into a buffer as a pipelined operation, call:

// Provided by VK_KHR_synchronization2 with VK_AMD_buffer_marker
void vkCmdWriteBufferMarker2AMD(
    VkCommandBuffer                             commandBuffer,
    VkPipelineStageFlags2                       stage,
    VkBuffer                                    dstBuffer,
    VkDeviceSize                                dstOffset,
    uint32_t                                    marker);
  • commandBuffer is the command buffer into which the command will be recorded.

  • stage specifies the pipeline stage whose completion triggers the marker write.

  • dstBuffer is the buffer where the marker will be written.

  • dstOffset is the byte offset into the buffer where the marker will be written.

  • marker is the 32-bit value of the marker.

The command will write the 32-bit marker value into the buffer only after all preceding commands have finished executing up to at least the specified pipeline stage. This includes the completion of other preceding vkCmdWriteBufferMarker2AMD commands so long as their specified pipeline stages occur either at the same time or earlier than this command’s specified stage.

While consecutive buffer marker writes with the same stage parameter implicitly complete in submission order, memory and execution dependencies between buffer marker writes and other operations must still be explicitly ordered using synchronization commands. The access scope for buffer marker writes falls under the VK_ACCESS_TRANSFER_WRITE_BIT, and the pipeline stages for identifying the synchronization scope must include both stage and VK_PIPELINE_STAGE_TRANSFER_BIT.

Note

Similar to vkCmdWriteTimestamp2, if an implementation is unable to write a marker at any specific pipeline stage, it may instead do so at any logically later stage.

Note

Implementations may only support a limited number of pipelined marker write operations in flight at a given time. Thus an excessive number of marker write operations may degrade command execution performance.

Valid Usage
  • VUID-vkCmdWriteBufferMarker2AMD-stage-03929
    If the geometryShader feature is not enabled, stage must not contain VK_PIPELINE_STAGE_2_GEOMETRY_SHADER_BIT

  • VUID-vkCmdWriteBufferMarker2AMD-stage-03930
    If the tessellationShader feature is not enabled, stage must not contain VK_PIPELINE_STAGE_2_TESSELLATION_CONTROL_SHADER_BIT or VK_PIPELINE_STAGE_2_TESSELLATION_EVALUATION_SHADER_BIT

  • VUID-vkCmdWriteBufferMarker2AMD-stage-03931
    If the conditionalRendering feature is not enabled, stage must not contain VK_PIPELINE_STAGE_2_CONDITIONAL_RENDERING_BIT_EXT

  • VUID-vkCmdWriteBufferMarker2AMD-stage-03932
    If the fragmentDensityMap feature is not enabled, stage must not contain VK_PIPELINE_STAGE_2_FRAGMENT_DENSITY_PROCESS_BIT_EXT

  • VUID-vkCmdWriteBufferMarker2AMD-stage-03933
    If the transformFeedback feature is not enabled, stage must not contain VK_PIPELINE_STAGE_2_TRANSFORM_FEEDBACK_BIT_EXT

  • VUID-vkCmdWriteBufferMarker2AMD-stage-03934
    If the meshShader feature is not enabled, stage must not contain VK_PIPELINE_STAGE_2_MESH_SHADER_BIT_EXT

  • VUID-vkCmdWriteBufferMarker2AMD-stage-03935
    If the taskShader feature is not enabled, stage must not contain VK_PIPELINE_STAGE_2_TASK_SHADER_BIT_EXT

  • VUID-vkCmdWriteBufferMarker2AMD-stage-07316
    If neither the shadingRateImage or attachmentFragmentShadingRate are enabled, stage must not contain VK_PIPELINE_STAGE_2_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR

  • VUID-vkCmdWriteBufferMarker2AMD-stage-04957
    If the subpassShading feature is not enabled, stage must not contain VK_PIPELINE_STAGE_2_SUBPASS_SHADER_BIT_HUAWEI

  • VUID-vkCmdWriteBufferMarker2AMD-stage-04995
    If the invocationMask feature is not enabled, stage must not contain VK_PIPELINE_STAGE_2_INVOCATION_MASK_BIT_HUAWEI

  • VUID-vkCmdWriteBufferMarker2AMD-stage-07946
    If neither the VK_NV_ray_tracing extension or rayTracingPipeline feature are enabled, stage must not contain VK_PIPELINE_STAGE_2_RAY_TRACING_SHADER_BIT_KHR

  • VUID-vkCmdWriteBufferMarker2AMD-synchronization2-03893
    The synchronization2 feature must be enabled

  • VUID-vkCmdWriteBufferMarker2AMD-stage-03894
    stage must include only a single pipeline stage

  • VUID-vkCmdWriteBufferMarker2AMD-stage-03895
    stage must include only stages that are valid for the queue family that was used to create the command pool that commandBuffer was allocated from

  • VUID-vkCmdWriteBufferMarker2AMD-dstOffset-03896
    dstOffset must be less than or equal to the size of dstBuffer minus 4

  • VUID-vkCmdWriteBufferMarker2AMD-dstBuffer-03897
    dstBuffer must have been created with the VK_BUFFER_USAGE_TRANSFER_DST_BIT usage flag

  • VUID-vkCmdWriteBufferMarker2AMD-dstBuffer-03898
    If dstBuffer is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-vkCmdWriteBufferMarker2AMD-dstOffset-03899
    dstOffset must be a multiple of 4

Valid Usage (Implicit)
  • VUID-vkCmdWriteBufferMarker2AMD-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdWriteBufferMarker2AMD-stage-parameter
    stage must be a valid combination of VkPipelineStageFlagBits2 values

  • VUID-vkCmdWriteBufferMarker2AMD-dstBuffer-parameter
    dstBuffer must be a valid VkBuffer handle

  • VUID-vkCmdWriteBufferMarker2AMD-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdWriteBufferMarker2AMD-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support transfer, graphics, or compute operations

  • VUID-vkCmdWriteBufferMarker2AMD-videocoding
    This command must only be called outside of a video coding scope

  • VUID-vkCmdWriteBufferMarker2AMD-commonparent
    Both of commandBuffer, and dstBuffer must have been created, allocated, or retrieved from the same VkDevice

Host Synchronization
  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type

Primary
Secondary

Both

Outside

Transfer
Graphics
Compute

Action

To write a 32-bit marker value into a buffer as a pipelined operation, call:

// Provided by VK_AMD_buffer_marker
void vkCmdWriteBufferMarkerAMD(
    VkCommandBuffer                             commandBuffer,
    VkPipelineStageFlagBits                     pipelineStage,
    VkBuffer                                    dstBuffer,
    VkDeviceSize                                dstOffset,
    uint32_t                                    marker);
  • commandBuffer is the command buffer into which the command will be recorded.

  • pipelineStage is a VkPipelineStageFlagBits value specifying the pipeline stage whose completion triggers the marker write.

  • dstBuffer is the buffer where the marker will be written to.

  • dstOffset is the byte offset into the buffer where the marker will be written to.

  • marker is the 32-bit value of the marker.

The command will write the 32-bit marker value into the buffer only after all preceding commands have finished executing up to at least the specified pipeline stage. This includes the completion of other preceding vkCmdWriteBufferMarkerAMD commands so long as their specified pipeline stages occur either at the same time or earlier than this command’s specified pipelineStage.

While consecutive buffer marker writes with the same pipelineStage parameter are implicitly complete in submission order, memory and execution dependencies between buffer marker writes and other operations must still be explicitly ordered using synchronization commands. The access scope for buffer marker writes falls under the VK_ACCESS_TRANSFER_WRITE_BIT, and the pipeline stages for identifying the synchronization scope must include both pipelineStage and VK_PIPELINE_STAGE_TRANSFER_BIT.

Note

Similar to vkCmdWriteTimestamp, if an implementation is unable to write a marker at any specific pipeline stage, it may instead do so at any logically later stage.

Note

Implementations may only support a limited number of pipelined marker write operations in flight at a given time, thus excessive number of marker write operations may degrade command execution performance.

Valid Usage
  • VUID-vkCmdWriteBufferMarkerAMD-pipelineStage-04074
    pipelineStage must be a valid stage for the queue family that was used to create the command pool that commandBuffer was allocated from

  • VUID-vkCmdWriteBufferMarkerAMD-pipelineStage-04075
    If the geometryShader feature is not enabled, pipelineStage must not be VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT

  • VUID-vkCmdWriteBufferMarkerAMD-pipelineStage-04076
    If the tessellationShader feature is not enabled, pipelineStage must not be VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT or VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT

  • VUID-vkCmdWriteBufferMarkerAMD-pipelineStage-04077
    If the conditionalRendering feature is not enabled, pipelineStage must not be VK_PIPELINE_STAGE_CONDITIONAL_RENDERING_BIT_EXT

  • VUID-vkCmdWriteBufferMarkerAMD-pipelineStage-04078
    If the fragmentDensityMap feature is not enabled, pipelineStage must not be VK_PIPELINE_STAGE_FRAGMENT_DENSITY_PROCESS_BIT_EXT

  • VUID-vkCmdWriteBufferMarkerAMD-pipelineStage-04079
    If the transformFeedback feature is not enabled, pipelineStage must not be VK_PIPELINE_STAGE_TRANSFORM_FEEDBACK_BIT_EXT

  • VUID-vkCmdWriteBufferMarkerAMD-pipelineStage-04080
    If the meshShader feature is not enabled, pipelineStage must not be VK_PIPELINE_STAGE_MESH_SHADER_BIT_EXT

  • VUID-vkCmdWriteBufferMarkerAMD-pipelineStage-07077
    If the taskShader feature is not enabled, pipelineStage must not be VK_PIPELINE_STAGE_TASK_SHADER_BIT_EXT

  • VUID-vkCmdWriteBufferMarkerAMD-shadingRateImage-07314
    If neither the shadingRateImage or attachmentFragmentShadingRate are enabled, pipelineStage must not be VK_PIPELINE_STAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR

  • VUID-vkCmdWriteBufferMarkerAMD-synchronization2-06489
    If the synchronization2 feature is not enabled, pipelineStage must not be VK_PIPELINE_STAGE_NONE

  • VUID-vkCmdWriteBufferMarkerAMD-rayTracingPipeline-07943
    If neither the VK_NV_ray_tracing extension or rayTracingPipeline feature are enabled, pipelineStage must not be VK_PIPELINE_STAGE_RAY_TRACING_SHADER_BIT_KHR

  • VUID-vkCmdWriteBufferMarkerAMD-dstOffset-01798
    dstOffset must be less than or equal to the size of dstBuffer minus 4

  • VUID-vkCmdWriteBufferMarkerAMD-dstBuffer-01799
    dstBuffer must have been created with VK_BUFFER_USAGE_TRANSFER_DST_BIT usage flag

  • VUID-vkCmdWriteBufferMarkerAMD-dstBuffer-01800
    If dstBuffer is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-vkCmdWriteBufferMarkerAMD-dstOffset-01801
    dstOffset must be a multiple of 4

Valid Usage (Implicit)
  • VUID-vkCmdWriteBufferMarkerAMD-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdWriteBufferMarkerAMD-pipelineStage-parameter
    If pipelineStage is not 0, pipelineStage must be a valid VkPipelineStageFlagBits value

  • VUID-vkCmdWriteBufferMarkerAMD-dstBuffer-parameter
    dstBuffer must be a valid VkBuffer handle

  • VUID-vkCmdWriteBufferMarkerAMD-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdWriteBufferMarkerAMD-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support transfer, graphics, or compute operations

  • VUID-vkCmdWriteBufferMarkerAMD-videocoding
    This command must only be called outside of a video coding scope

  • VUID-vkCmdWriteBufferMarkerAMD-commonparent
    Both of commandBuffer, and dstBuffer must have been created, allocated, or retrieved from the same VkDevice

Host Synchronization
  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type

Primary
Secondary

Both

Outside

Transfer
Graphics
Compute

Action