Vulkan Logo

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

19.1. 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-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 Supported Queue Types Command Type

Primary
Secondary

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

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 Supported Queue Types Command Type

Primary
Secondary

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

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

  • 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_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 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 and VkPhysicalDeviceProperties::apiVersion is less than Vulkan 1.1, srcImage and dstImage must have the same VkImageType

  • VUID-vkCmdCopyImage-apiVersion-08969
    If 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, 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, the layerCount members of srcSubresource or dstSubresource must match

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

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-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 Supported Queue Types Command Type

Primary
Secondary

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 and VkPhysicalDeviceProperties::apiVersion is less than Vulkan 1.1, the aspectMask member of srcSubresource and dstSubresource must match

  • VUID-VkImageCopy-apiVersion-07941
    If 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-layerCount-09243
    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);
  • 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

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 Supported Queue Types Command Type

Primary
Secondary

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

  • 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_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 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 and VkPhysicalDeviceProperties::apiVersion is less than Vulkan 1.1, srcImage and dstImage must have the same VkImageType

  • VUID-VkCopyImageInfo2-apiVersion-08969
    If 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, 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, the layerCount members of srcSubresource or dstSubresource must match

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

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;
  • 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 and VkPhysicalDeviceProperties::apiVersion is less than Vulkan 1.1, the aspectMask member of srcSubresource and dstSubresource must match

  • VUID-VkImageCopy2-apiVersion-07941
    If 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

19.3. Copying Data Between Buffers and Images

Data can be copied between buffers and images, enabling applications to load and store data between images and user 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

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 19. 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 values copied from srcBuffer outside of the range [0,1] will be 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
    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-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_TRANSFER_DST_OPTIMAL, or VK_IMAGE_LAYOUT_GENERAL

  • VUID-vkCmdCopyBufferToImage-pRegions-07931
    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-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 Supported Queue Types Command Type

Primary
Secondary

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
    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-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_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-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 Supported Queue Types Command Type

Primary
Secondary

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

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 Supported Queue Types Command Type

Primary
Secondary

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;
  • 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-04565
    The image region specified by each element of pRegions must be contained within the specified imageSubresource of dstImage

  • 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_TRANSFER_DST_OPTIMAL, or VK_IMAGE_LAYOUT_GENERAL

  • VUID-VkCopyBufferToImageInfo2-pRegions-07931
    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
    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-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);
  • 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

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 Supported Queue Types Command Type

Primary
Secondary

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;
  • 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-04566
    The image region specified by each element of pRegions must be contained within the specified imageSubresource of srcImage

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

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

19.4. 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-00222
    srcImageLayout must be 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

  • 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-00227
    dstImageLayout must be 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-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
    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
    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-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-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 Supported Queue Types Command Type

Primary
Secondary

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
    The layerCount members of srcSubresource or dstSubresource must match

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

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 Supported Queue Types Command Type

Primary
Secondary

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;
  • 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-00222
    srcImageLayout must be 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

  • 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-00227
    dstImageLayout must be 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-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
    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
    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-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

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

  • 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

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;
  • 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
    The layerCount members of srcSubresource or dstSubresource must match

Valid Usage (Implicit)
  • VUID-VkImageBlit2-sType-sType
    sType must be VK_STRUCTURE_TYPE_IMAGE_BLIT_2

  • VUID-VkImageBlit2-pNext-pNext
    pNext must be NULL

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

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

19.5. 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_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_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-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
    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
    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-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-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 Supported Queue Types Command Type

Primary
Secondary

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
    The layerCount member of srcSubresource and dstSubresource must match

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

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 Supported Queue Types Command Type

Primary
Secondary

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;
  • 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_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_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-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
    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
    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-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;
  • 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
    The layerCount member of srcSubresource and dstSubresource must match

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