20. Copy Commands

An application can copy buffer and image data using several methods depending on the type of data transfer. Data can be copied between buffer objects with vkCmdCopyBuffer2KHR and vkCmdCopyBuffer and a portion of an image can be copied to another image with vkCmdCopyImage2KHR and vkCmdCopyImage. Image data can also be copied to and from buffer memory using vkCmdCopyImageToBuffer2KHR, vkCmdCopyImageToBuffer, vkCmdCopyBufferToImage2KHR, and vkCmdCopyBufferToImage. Image data can be blitted (with or without scaling and filtering) with vkCmdBlitImage2KHR and vkCmdBlitImage. Multisampled images can be resolved to a non-multisampled image with vkCmdResolveImage2KHR and vkCmdResolveImage.

20.1. Common Operation

The following valid usage rules apply to all copy commands:

  • Copy commands must be recorded outside of a render pass instance.

  • The set of all bytes bound to all the source regions must not overlap the set of all bytes bound to the destination regions.

  • The set of all bytes bound to each destination region must not overlap the set of all bytes bound to another destination region.

  • Copy regions must be non-empty.

  • Regions must not extend outside the bounds of the buffer or image level, except that regions of compressed images can extend as far as the dimension of the image level rounded up to a complete compressed texel block.

  • Source image subresources must be in either the VK_IMAGE_LAYOUT_GENERAL or VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL layout. Destination image subresources must be in the VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR, VK_IMAGE_LAYOUT_GENERAL or VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL layout. As a consequence, if an image subresource is used as both source and destination of a copy, it must be in the VK_IMAGE_LAYOUT_GENERAL layout.

  • Source images must have VK_FORMAT_FEATURE_TRANSFER_SRC_BIT in their format features.

  • Destination images must have VK_FORMAT_FEATURE_TRANSFER_DST_BIT in their format features.

  • Source buffers must have been created with the VK_BUFFER_USAGE_TRANSFER_SRC_BIT usage bit enabled and destination buffers must have been created with the VK_BUFFER_USAGE_TRANSFER_DST_BIT usage bit enabled.

  • If the stencil aspect of source image is accessed, and the source image was not created with separate stencil usage, the source image must have been created with VK_IMAGE_USAGE_TRANSFER_SRC_BIT set in VkImageCreateInfo::usage

  • If the stencil aspect of destination image is accessed, and the destination image was not created with separate stencil usage, the destination image must have been created with VK_IMAGE_USAGE_TRANSFER_DST_BIT set in VkImageCreateInfo::usage

  • If the stencil aspect of source image is accessed, and the source image was created with separate stencil usage, the source image must have been created with VK_IMAGE_USAGE_TRANSFER_SRC_BIT set in VkImageStencilUsageCreateInfo::stencilUsage

  • If the stencil aspect of destination image is accessed, and the destination image was created with separate stencil usage, the destination image must have been created with VK_IMAGE_USAGE_TRANSFER_DST_BIT set in VkImageStencilUsageCreateInfo::stencilUsage

  • If non-stencil aspects of a source image are accessed, the source image must have been created with VK_IMAGE_USAGE_TRANSFER_SRC_BIT set in VkImageCreateInfo::usage

  • If non-stencil aspects of a source image are accessed, the source image must have been created with VK_IMAGE_USAGE_TRANSFER_DST_BIT set in VkImageCreateInfo::usage

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.

20.2. 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 region in pRegions is copied from the source buffer to the same region of the destination buffer. srcBuffer and dstBuffer can be the same buffer or alias the same memory, but the resulting values are undefined if the copy regions overlap in memory.

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

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

  • VUID-vkCmdCopyBuffer-commandBuffer-01824
    If commandBuffer is a protected command buffer, then 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 Pipeline Type

Primary
Secondary

Outside

Transfer
Graphics
Compute

Transfer

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_KHR_copy_commands2
void vkCmdCopyBuffer2KHR(
    VkCommandBuffer                             commandBuffer,
    const VkCopyBufferInfo2KHR*                 pCopyBufferInfo);
  • commandBuffer is the command buffer into which the command will be recorded.

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

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

Valid Usage
  • VUID-vkCmdCopyBuffer2KHR-commandBuffer-01822
    If commandBuffer is an unprotected command buffer, then srcBuffer must not be a protected buffer

  • VUID-vkCmdCopyBuffer2KHR-commandBuffer-01823
    If commandBuffer is an unprotected command buffer, then dstBuffer must not be a protected buffer

  • VUID-vkCmdCopyBuffer2KHR-commandBuffer-01824
    If commandBuffer is a protected command buffer, then dstBuffer must not be an unprotected buffer

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

  • VUID-vkCmdCopyBuffer2KHR-pCopyBufferInfo-parameter
    pCopyBufferInfo must be a valid pointer to a valid VkCopyBufferInfo2KHR structure

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

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

  • VUID-vkCmdCopyBuffer2KHR-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 Pipeline Type

Primary
Secondary

Outside

Transfer
Graphics
Compute

Transfer

The VkCopyBufferInfo2KHR structure is defined as:

// Provided by VK_KHR_copy_commands2
typedef struct VkCopyBufferInfo2KHR {
    VkStructureType            sType;
    const void*                pNext;
    VkBuffer                   srcBuffer;
    VkBuffer                   dstBuffer;
    uint32_t                   regionCount;
    const VkBufferCopy2KHR*    pRegions;
} VkCopyBufferInfo2KHR;
  • sType is the type of 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 VkBufferCopy2KHR structures specifying the regions to copy.

Members defined by this structure with the same name as parameters in vkCmdCopyBuffer have the identical effect to those parameters; the child structure VkBufferCopy2KHR is a variant of VkBufferCopy which includes sType and pNext parameters, allowing it to be extended.

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

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

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

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

  • VUID-VkCopyBufferInfo2KHR-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-VkCopyBufferInfo2KHR-srcBuffer-00118
    srcBuffer must have been created with VK_BUFFER_USAGE_TRANSFER_SRC_BIT usage flag

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

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

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

Valid Usage (Implicit)
  • VUID-VkCopyBufferInfo2KHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_COPY_BUFFER_INFO_2_KHR

  • VUID-VkCopyBufferInfo2KHR-pNext-pNext
    pNext must be NULL

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

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

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

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

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

The VkBufferCopy2KHR structure is defined as:

// Provided by VK_KHR_copy_commands2
typedef struct VkBufferCopy2KHR {
    VkStructureType    sType;
    const void*        pNext;
    VkDeviceSize       srcOffset;
    VkDeviceSize       dstOffset;
    VkDeviceSize       size;
} VkBufferCopy2KHR;
  • sType is the type of 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-VkBufferCopy2KHR-size-01988
    The size must be greater than 0

Valid Usage (Implicit)
  • VUID-VkBufferCopy2KHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_BUFFER_COPY_2_KHR

  • VUID-VkBufferCopy2KHR-pNext-pNext
    pNext must be NULL

20.3. Copying Data Between Images

vkCmdCopyImage performs image copies in a similar manner to a host memcpy. It does not perform general-purpose conversions such as scaling, resizing, blending, color-space conversion, or format conversions. Rather, it simply copies raw image data. vkCmdCopyImage can copy between images with different formats, provided the formats are compatible as defined below.

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 region in pRegions is copied from the source image to the same region of the destination image. srcImage and dstImage can be the same image or alias the same memory.

The formats of srcImage and dstImage must be compatible. Formats are compatible if they share the same class, as shown in the Compatible Formats table. Depth/stencil formats must match exactly.

If the format of srcImage or dstImage is a multi-planar image format, regions of each plane to be copied must be specified separately using the srcSubresource and dstSubresource members of the VkImageCopy structure. In this case, the aspectMask of the srcSubresource or dstSubresource that refers to the multi-planar image must be VK_IMAGE_ASPECT_PLANE_0_BIT, VK_IMAGE_ASPECT_PLANE_1_BIT, or VK_IMAGE_ASPECT_PLANE_2_BIT. For the purposes of vkCmdCopyImage, each plane of a multi-planar image is treated as having the format listed in Compatible formats of planes of multi-planar formats for the plane identified by the aspectMask of the corresponding subresource. This applies both to VkFormat and to coordinates used in the copy, which correspond to texels in the plane rather than how these texels map to coordinates in the image as a whole.

Note

For example, the VK_IMAGE_ASPECT_PLANE_1_BIT plane of a VK_FORMAT_G8_B8R8_2PLANE_420_UNORM image is compatible with an image of format VK_FORMAT_R8G8_UNORM and (less usefully) with the VK_IMAGE_ASPECT_PLANE_0_BIT plane of an image of format VK_FORMAT_G10X6_B10X6_R10X6_3PLANE_420_UNORM_3PACK16, as each texel is 2 bytes in size.

vkCmdCopyImage allows copying between size-compatible compressed and uncompressed internal formats. Formats are size-compatible if the texel block size of the uncompressed format is equal to the texel block size of the compressed format. Such a copy does not perform on-the-fly compression or decompression. When copying from an uncompressed format to a compressed format, each texel of uncompressed data of the source image is copied as a raw value to the corresponding compressed texel block of the destination image. When copying from a compressed format to an uncompressed format, each compressed texel block of the source image is copied as a raw value to the corresponding texel of uncompressed data in the destination image. Thus, for example, it is legal to copy between a 128-bit uncompressed format and a compressed format which has a 128-bit sized compressed texel block representing 4×4 texels (using 8 bits per texel), or between a 64-bit uncompressed format and a compressed format which has a 64-bit sized compressed texel block representing 4×4 texels (using 4 bits per texel).

When copying between compressed and uncompressed formats the extent members represent the texel dimensions of the source image and not the destination. When copying from a compressed image to an uncompressed image the image texel dimensions written to the uncompressed image will be source extent divided by the compressed texel block dimensions. When copying from an uncompressed image to a compressed image the image texel dimensions written to the compressed image will be the source extent multiplied by the compressed texel block dimensions. In both cases the number of bytes read and the number of bytes written will be identical.

Copying to or from block-compressed images is typically done in multiples of the compressed texel block size. For this reason the extent must be a multiple of the compressed texel block dimension. There is one exception to this rule which is required to handle compressed images created with dimensions that are not a multiple of the compressed texel block dimensions: if the srcImage is compressed, then:

  • If extent.width is not a multiple of the compressed texel block width, then (extent.width + srcOffset.x) must equal the image subresource width.

  • If extent.height is not a multiple of the compressed texel block height, then (extent.height + srcOffset.y) must equal the image subresource height.

  • If extent.depth is not a multiple of the compressed texel block depth, then (extent.depth + srcOffset.z) must equal the image subresource depth.

Similarly, if the dstImage is compressed, then:

  • If extent.width is not a multiple of the compressed texel block width, then (extent.width + dstOffset.x) must equal the image subresource width.

  • If extent.height is not a multiple of the compressed texel block height, then (extent.height + dstOffset.y) must equal the image subresource height.

  • If extent.depth is not a multiple of the compressed texel block depth, then (extent.depth + dstOffset.z) must equal the image subresource depth.

This allows the last compressed texel block of the image in each non-multiple dimension to be included as a source or destination of the copy.

_422” image formats that are not multi-planar are treated as having a 2×1 compressed texel block for the purposes of these rules.

vkCmdCopyImage can be used to copy image data between multisample images, but both images must have the same number of samples.

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

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

  • VUID-vkCmdCopyImage-commandBuffer-01827
    If commandBuffer is a protected command buffer, then 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-srcImage-00126
    srcImage must have been created with VK_IMAGE_USAGE_TRANSFER_SRC_BIT usage flag

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

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

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

  • VUID-vkCmdCopyImage-dstImage-00131
    dstImage must have been created with VK_IMAGE_USAGE_TRANSFER_DST_BIT usage flag

  • VUID-vkCmdCopyImage-dstImage-01547
    If dstImage is non-sparse then the image or disjoint plane that is the destination of the copy must be bound completely and contiguously to a single VkDeviceMemory object

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

  • 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 compatible, as defined above

  • 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-00136
    The sample count of srcImage and dstImage must match

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

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

  • VUID-vkCmdCopyImage-srcSubresource-01698
    The 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-dstSubresource-01699
    The dstSubresource.baseArrayLayer + dstSubresource.layerCount of each element of pRegions must be less than or equal to the arrayLayers specified in VkImageCreateInfo when dstImage was created

  • VUID-vkCmdCopyImage-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-dstImage-02542
    dstImage and srcImage must not have been created with flags containing VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT

  • 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-01552
    If srcImage has a VkFormat with two planes then for each element of pRegions, srcSubresource.aspectMask must be VK_IMAGE_ASPECT_PLANE_0_BIT or VK_IMAGE_ASPECT_PLANE_1_BIT

  • VUID-vkCmdCopyImage-srcImage-01553
    If srcImage has a VkFormat with three planes then for each element of pRegions, srcSubresource.aspectMask must be VK_IMAGE_ASPECT_PLANE_0_BIT, VK_IMAGE_ASPECT_PLANE_1_BIT, or VK_IMAGE_ASPECT_PLANE_2_BIT

  • VUID-vkCmdCopyImage-dstImage-01554
    If dstImage has a VkFormat with two planes then for each element of pRegions, dstSubresource.aspectMask must be VK_IMAGE_ASPECT_PLANE_0_BIT or VK_IMAGE_ASPECT_PLANE_1_BIT

  • VUID-vkCmdCopyImage-dstImage-01555
    If dstImage has a VkFormat with three planes then for each element of pRegions, dstSubresource.aspectMask must be VK_IMAGE_ASPECT_PLANE_0_BIT, VK_IMAGE_ASPECT_PLANE_1_BIT, or VK_IMAGE_ASPECT_PLANE_2_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-srcImage-04443
    If srcImage is of type VK_IMAGE_TYPE_3D, then for each element of pRegions, srcSubresource.baseArrayLayer must be 0 and 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 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
    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-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
    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-srcImage-01727
    If srcImage is a blocked image, then for each element of pRegions, all members of srcOffset must be a multiple of the corresponding dimensions of the compressed texel block

  • VUID-vkCmdCopyImage-srcImage-01728
    If srcImage is a blocked image, then for each element of pRegions, extent.width must be a multiple of the compressed texel block width or (extent.width + srcOffset.x) must equal the width of the specified srcSubresource of srcImage

  • VUID-vkCmdCopyImage-srcImage-01729
    If srcImage is a blocked image, then for each element of pRegions, extent.height must be a multiple of the compressed texel block height or (extent.height + srcOffset.y) must equal the height of the specified srcSubresource of srcImage

  • VUID-vkCmdCopyImage-srcImage-01730
    If srcImage is a blocked image, then for each element of pRegions, extent.depth must be a multiple of the compressed texel block depth or (extent.depth + srcOffset.z) must equal the depth of the specified srcSubresource of srcImage

  • VUID-vkCmdCopyImage-dstImage-01731
    If dstImage is a blocked image, then for each element of pRegions, all members of dstOffset must be a multiple of the corresponding dimensions of the compressed texel block

  • VUID-vkCmdCopyImage-dstImage-01732
    If dstImage is a blocked image, then for each element of pRegions, extent.width must be a multiple of the compressed texel block width or (extent.width + dstOffset.x) must equal the width of the specified dstSubresource of dstImage

  • VUID-vkCmdCopyImage-dstImage-01733
    If dstImage is a blocked image, then for each element of pRegions, extent.height must be a multiple of the compressed texel block height or (extent.height + dstOffset.y) must equal the height of the specified dstSubresource of dstImage

  • VUID-vkCmdCopyImage-dstImage-01734
    If dstImage is a blocked image, then for each element of pRegions, extent.depth must be a multiple of the compressed texel block depth or (extent.depth + dstOffset.z) must equal the depth of the specified dstSubresource of dstImage

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 Pipeline Type

Primary
Secondary

Outside

Transfer
Graphics
Compute

Transfer

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.

For VK_IMAGE_TYPE_3D images, copies are performed slice by slice starting with the z member of the srcOffset or dstOffset, and copying depth slices. For images with multiple layers, copies are performed layer by layer starting with the baseArrayLayer member of the srcSubresource or dstSubresource and copying layerCount layers. 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.

Copies involving a multi-planar image format specify the region to be copied in terms of the plane to be copied, not the coordinates of the multi-planar image. This means that copies accessing the R/B planes of “_422” format images must fit the copied region within half the width of the parent image, and that copies accessing the R/B planes of “_420” format images must fit the copied region within half the width and height of the parent image.

Valid Usage
  • VUID-VkImageCopy-extent-00140
    The number of slices of the extent (for 3D) or layers of the srcSubresource (for non-3D) must match the number of slices of the extent (for 3D) or layers of the dstSubresource (for non-3D)

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

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

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

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

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

  • VUID-VkImageSubresourceLayers-layerCount-01700
    layerCount 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_KHR_copy_commands2
void vkCmdCopyImage2KHR(
    VkCommandBuffer                             commandBuffer,
    const VkCopyImageInfo2KHR*                  pCopyImageInfo);
  • commandBuffer is the command buffer into which the command will be recorded.

  • pCopyImageInfo is a pointer to a VkCopyImageInfo2KHR 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-vkCmdCopyImage2KHR-commandBuffer-01825
    If commandBuffer is an unprotected command buffer, then srcImage must not be a protected image

  • VUID-vkCmdCopyImage2KHR-commandBuffer-01826
    If commandBuffer is an unprotected command buffer, then dstImage must not be a protected image

  • VUID-vkCmdCopyImage2KHR-commandBuffer-01827
    If commandBuffer is a protected command buffer, then dstImage must not be an unprotected image

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

  • VUID-vkCmdCopyImage2KHR-pCopyImageInfo-parameter
    pCopyImageInfo must be a valid pointer to a valid VkCopyImageInfo2KHR structure

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

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

  • VUID-vkCmdCopyImage2KHR-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 Pipeline Type

Primary
Secondary

Outside

Transfer
Graphics
Compute

Transfer

The VkCopyImageInfo2KHR structure is defined as:

// Provided by VK_KHR_copy_commands2
typedef struct VkCopyImageInfo2KHR {
    VkStructureType           sType;
    const void*               pNext;
    VkImage                   srcImage;
    VkImageLayout             srcImageLayout;
    VkImage                   dstImage;
    VkImageLayout             dstImageLayout;
    uint32_t                  regionCount;
    const VkImageCopy2KHR*    pRegions;
} VkCopyImageInfo2KHR;
  • sType is the type of 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 VkImageCopy2KHR structures specifying the regions to copy.

Valid Usage
  • VUID-VkCopyImageInfo2KHR-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-VkCopyImageInfo2KHR-srcImage-01995
    The format features of srcImage must contain VK_FORMAT_FEATURE_TRANSFER_SRC_BIT

  • VUID-VkCopyImageInfo2KHR-srcImage-00126
    srcImage must have been created with VK_IMAGE_USAGE_TRANSFER_SRC_BIT usage flag

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

  • VUID-VkCopyImageInfo2KHR-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-VkCopyImageInfo2KHR-srcImageLayout-01917
    srcImageLayout must be VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL, VK_IMAGE_LAYOUT_GENERAL, or VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR

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

  • VUID-VkCopyImageInfo2KHR-dstImage-00131
    dstImage must have been created with VK_IMAGE_USAGE_TRANSFER_DST_BIT usage flag

  • VUID-VkCopyImageInfo2KHR-dstImage-01547
    If dstImage is non-sparse then the image or disjoint plane that is the destination of the copy must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-VkCopyImageInfo2KHR-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-VkCopyImageInfo2KHR-dstImageLayout-01395
    dstImageLayout must be VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL, VK_IMAGE_LAYOUT_GENERAL, or VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR

  • VUID-VkCopyImageInfo2KHR-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 compatible, as defined above

  • VUID-VkCopyImageInfo2KHR-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-VkCopyImageInfo2KHR-srcImage-00136
    The sample count of srcImage and dstImage must match

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

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

  • VUID-VkCopyImageInfo2KHR-srcSubresource-01698
    The 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-VkCopyImageInfo2KHR-dstSubresource-01699
    The 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-VkCopyImageInfo2KHR-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-VkCopyImageInfo2KHR-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-VkCopyImageInfo2KHR-dstImage-02542
    dstImage and srcImage must not have been created with flags containing VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT

  • VUID-VkCopyImageInfo2KHR-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-VkCopyImageInfo2KHR-srcImage-01552
    If srcImage has a VkFormat with two planes then for each element of pRegions, srcSubresource.aspectMask must be VK_IMAGE_ASPECT_PLANE_0_BIT or VK_IMAGE_ASPECT_PLANE_1_BIT

  • VUID-VkCopyImageInfo2KHR-srcImage-01553
    If srcImage has a VkFormat with three planes then for each element of pRegions, srcSubresource.aspectMask must be VK_IMAGE_ASPECT_PLANE_0_BIT, VK_IMAGE_ASPECT_PLANE_1_BIT, or VK_IMAGE_ASPECT_PLANE_2_BIT

  • VUID-VkCopyImageInfo2KHR-dstImage-01554
    If dstImage has a VkFormat with two planes then for each element of pRegions, dstSubresource.aspectMask must be VK_IMAGE_ASPECT_PLANE_0_BIT or VK_IMAGE_ASPECT_PLANE_1_BIT

  • VUID-VkCopyImageInfo2KHR-dstImage-01555
    If dstImage has a VkFormat with three planes then for each element of pRegions, dstSubresource.aspectMask must be VK_IMAGE_ASPECT_PLANE_0_BIT, VK_IMAGE_ASPECT_PLANE_1_BIT, or VK_IMAGE_ASPECT_PLANE_2_BIT

  • VUID-VkCopyImageInfo2KHR-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-VkCopyImageInfo2KHR-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-VkCopyImageInfo2KHR-srcImage-04443
    If srcImage is of type VK_IMAGE_TYPE_3D, then for each element of pRegions, srcSubresource.baseArrayLayer must be 0 and and srcSubresource.layerCount must be 1

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

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

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

  • VUID-VkCopyImageInfo2KHR-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-VkCopyImageInfo2KHR-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-VkCopyImageInfo2KHR-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-VkCopyImageInfo2KHR-srcOffset-00147
    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-VkCopyImageInfo2KHR-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-VkCopyImageInfo2KHR-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-VkCopyImageInfo2KHR-srcImage-01787
    If srcImage is of type VK_IMAGE_TYPE_2D, then for each element of pRegions, srcOffset.z must be 0

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

  • VUID-VkCopyImageInfo2KHR-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-VkCopyImageInfo2KHR-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-VkCopyImageInfo2KHR-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-VkCopyImageInfo2KHR-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-VkCopyImageInfo2KHR-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-VkCopyImageInfo2KHR-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-VkCopyImageInfo2KHR-dstOffset-00153
    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-VkCopyImageInfo2KHR-srcImage-01727
    If srcImage is a blocked image, then for each element of pRegions, all members of srcOffset must be a multiple of the corresponding dimensions of the compressed texel block

  • VUID-VkCopyImageInfo2KHR-srcImage-01728
    If srcImage is a blocked image, then for each element of pRegions, extent.width must be a multiple of the compressed texel block width or (extent.width + srcOffset.x) must equal the width of the specified srcSubresource of srcImage

  • VUID-VkCopyImageInfo2KHR-srcImage-01729
    If srcImage is a blocked image, then for each element of pRegions, extent.height must be a multiple of the compressed texel block height or (extent.height + srcOffset.y) must equal the height of the specified srcSubresource of srcImage

  • VUID-VkCopyImageInfo2KHR-srcImage-01730
    If srcImage is a blocked image, then for each element of pRegions, extent.depth must be a multiple of the compressed texel block depth or (extent.depth + srcOffset.z) must equal the depth of the specified srcSubresource of srcImage

  • VUID-VkCopyImageInfo2KHR-dstImage-01731
    If dstImage is a blocked image, then for each element of pRegions, all members of dstOffset must be a multiple of the corresponding dimensions of the compressed texel block

  • VUID-VkCopyImageInfo2KHR-dstImage-01732
    If dstImage is a blocked image, then for each element of pRegions, extent.width must be a multiple of the compressed texel block width or (extent.width + dstOffset.x) must equal the width of the specified dstSubresource of dstImage

  • VUID-VkCopyImageInfo2KHR-dstImage-01733
    If dstImage is a blocked image, then for each element of pRegions, extent.height must be a multiple of the compressed texel block height or (extent.height + dstOffset.y) must equal the height of the specified dstSubresource of dstImage

  • VUID-VkCopyImageInfo2KHR-dstImage-01734
    If dstImage is a blocked image, then for each element of pRegions, extent.depth must be a multiple of the compressed texel block depth or (extent.depth + dstOffset.z) must equal the depth of the specified dstSubresource of dstImage

Valid Usage (Implicit)
  • VUID-VkCopyImageInfo2KHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_COPY_IMAGE_INFO_2_KHR

  • VUID-VkCopyImageInfo2KHR-pNext-pNext
    pNext must be NULL

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

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

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

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

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

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

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

The VkImageCopy2KHR structure is defined as:

// Provided by VK_KHR_copy_commands2
typedef struct VkImageCopy2KHR {
    VkStructureType             sType;
    const void*                 pNext;
    VkImageSubresourceLayers    srcSubresource;
    VkOffset3D                  srcOffset;
    VkImageSubresourceLayers    dstSubresource;
    VkOffset3D                  dstOffset;
    VkExtent3D                  extent;
} VkImageCopy2KHR;
  • sType is the type of 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-VkImageCopy2KHR-extent-00140
    The number of slices of the extent (for 3D) or layers of the srcSubresource (for non-3D) must match the number of slices of the extent (for 3D) or layers of the dstSubresource (for non-3D)

Valid Usage (Implicit)
  • VUID-VkImageCopy2KHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_IMAGE_COPY_2_KHR

  • VUID-VkImageCopy2KHR-pNext-pNext
    pNext must be NULL

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

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

20.4. Copying Data Between Buffers and Images

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 region in pRegions is copied from the specified region of the source buffer to the specified region of the destination image.

If the format of dstImage is a multi-planar image format, regions of each plane to be a target of a copy must be specified separately using the pRegions member of the VkBufferImageCopy structure. In this case, the aspectMask of imageSubresource must be VK_IMAGE_ASPECT_PLANE_0_BIT, VK_IMAGE_ASPECT_PLANE_1_BIT, or VK_IMAGE_ASPECT_PLANE_2_BIT. For the purposes of vkCmdCopyBufferToImage, each plane of a multi-planar image is treated as having the format listed in Compatible formats of planes of multi-planar formats for the plane identified by the aspectMask of the corresponding subresource. This applies both to VkFormat and to coordinates used in the copy, which correspond to texels in the plane rather than how these texels map to coordinates in the image as a whole.

Valid Usage
  • VUID-vkCmdCopyBufferToImage-commandBuffer-01828
    If commandBuffer is an unprotected command buffer, then srcBuffer must not be a protected buffer

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

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

  • VUID-vkCmdCopyBufferToImage-pRegions-00172
    The image region specified by each element of pRegions must be a region that is contained within dstImage if the dstImage’s VkFormat is not a multi-planar format, and must be a region that is contained within the plane being copied to if the dstImage’s VkFormat is a multi-planar format

  • 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-dstImage-00178
    If dstImage is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

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

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

  • VUID-vkCmdCopyBufferToImage-imageSubresource-01701
    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-01702
    The 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-imageOffset-01793
    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-dstImage-02543
    dstImage must not have been created with flags containing VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT

  • VUID-vkCmdCopyBufferToImage-commandBuffer-04052
    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-dstImage-04053
    If dstImage has a depth/stencil format, the bufferOffset member of any element of pRegions must be a multiple of 4

  • VUID-vkCmdCopyBufferToImage-commandBuffer-04477
    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-imageOffset-00197
    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 where this refers to the width of the plane of the image involved in the copy in the case of a multi-planar format

  • VUID-vkCmdCopyBufferToImage-imageOffset-00198
    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 where this refers to the height of the plane of the image involved in the copy in the case of a multi-planar format

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

  • VUID-vkCmdCopyBufferToImage-bufferOffset-01559
    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-srcImage-00199
    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-00200
    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-srcImage-00201
    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-bufferRowLength-00203
    If dstImage is a blocked image, for each element of pRegions, bufferRowLength must be a multiple of the compressed texel block width

  • VUID-vkCmdCopyBufferToImage-bufferImageHeight-00204
    If dstImage is a blocked image, for each element of pRegions, bufferImageHeight must be a multiple of the compressed texel block height

  • VUID-vkCmdCopyBufferToImage-imageOffset-00205
    If dstImage is a blocked image, for each element of pRegions, all members of imageOffset must be a multiple of the corresponding dimensions of the compressed texel block

  • VUID-vkCmdCopyBufferToImage-bufferOffset-00206
    If dstImage is a blocked image, for each element of pRegions, bufferOffset must be a multiple of the compressed texel block size in bytes

  • VUID-vkCmdCopyBufferToImage-imageExtent-00207
    If dstImage is a blocked image, for each element of pRegions, imageExtent.width must be a multiple of the compressed texel block width or (imageExtent.width + imageOffset.x) must equal the width of the specified imageSubresource of dstImage

  • VUID-vkCmdCopyBufferToImage-imageExtent-00208
    If dstImage is a blocked image, for each element of pRegions, imageExtent.height must be a multiple of the compressed texel block height or (imageExtent.height + imageOffset.y) must equal the height of the specified imageSubresource of dstImage

  • VUID-vkCmdCopyBufferToImage-imageExtent-00209
    If dstImage is a blocked image, for each element of pRegions, imageExtent.depth must be a multiple of the compressed texel block depth or (imageExtent.depth + imageOffset.z) must equal the depth of the specified imageSubresource of dstImage

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

  • VUID-vkCmdCopyBufferToImage-aspectMask-01560
    If dstImage has a multi-planar format, then for each element of pRegions, imageSubresource.aspectMask must be VK_IMAGE_ASPECT_PLANE_0_BIT, VK_IMAGE_ASPECT_PLANE_1_BIT, or VK_IMAGE_ASPECT_PLANE_2_BIT (with VK_IMAGE_ASPECT_PLANE_2_BIT valid only for image formats with three planes)

  • VUID-vkCmdCopyBufferToImage-baseArrayLayer-00213
    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

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 Pipeline Type

Primary
Secondary

Outside

Transfer
Graphics
Compute

Transfer

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 region in pRegions is copied from the specified region of the source image to the specified region of the destination buffer.

If the VkFormat of srcImage is a multi-planar image format, regions of each plane to be a source of a copy must be specified separately using the pRegions member of the VkBufferImageCopy structure. In this case, the aspectMask of imageSubresource must be VK_IMAGE_ASPECT_PLANE_0_BIT, VK_IMAGE_ASPECT_PLANE_1_BIT, or VK_IMAGE_ASPECT_PLANE_2_BIT. For the purposes of vkCmdCopyBufferToImage, each plane of a multi-planar image is treated as having the format listed in Compatible formats of planes of multi-planar formats for the plane identified by the aspectMask of the corresponding subresource. This applies both to VkFormat and to coordinates used in the copy, which correspond to texels in the plane rather than how these texels map to coordinates in the image as a whole.

Valid Usage
  • VUID-vkCmdCopyImageToBuffer-commandBuffer-01831
    If commandBuffer is an unprotected command buffer, then srcImage must not be a protected image

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

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

  • VUID-vkCmdCopyImageToBuffer-pRegions-00182
    The image region specified by each element of pRegions must be a region that is contained within srcImage if the srcImage’s VkFormat is not a multi-planar format, and must be a region that is contained within the plane being copied if the srcImage’s VkFormat is a multi-planar format

  • 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-srcImage-00187
    If srcImage is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

  • 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-srcImage-00188
    srcImage must have a sample count equal to VK_SAMPLE_COUNT_1_BIT

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

  • VUID-vkCmdCopyImageToBuffer-imageSubresource-01703
    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-01704
    The 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-imageOffset-01794
    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-srcImage-02544
    srcImage must not have been created with flags containing VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT

  • VUID-vkCmdCopyImageToBuffer-commandBuffer-04054
    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-srcImage-04055
    If srcImage has a depth/stencil format, the bufferOffset member of any element of pRegions must be a multiple of 4

  • VUID-vkCmdCopyImageToBuffer-imageOffset-00197
    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 where this refers to the width of the plane of the image involved in the copy in the case of a multi-planar format

  • VUID-vkCmdCopyImageToBuffer-imageOffset-00198
    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 where this refers to the height of the plane of the image involved in the copy in the case of a multi-planar format

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

  • VUID-vkCmdCopyImageToBuffer-bufferOffset-01559
    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-00199
    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-00200
    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-00201
    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-bufferRowLength-00203
    If srcImage is a blocked image, for each element of pRegions, bufferRowLength must be a multiple of the compressed texel block width

  • VUID-vkCmdCopyImageToBuffer-bufferImageHeight-00204
    If srcImage is a blocked image, for each element of pRegions, bufferImageHeight must be a multiple of the compressed texel block height

  • VUID-vkCmdCopyImageToBuffer-imageOffset-00205
    If srcImage is a blocked image, for each element of pRegions, all members of imageOffset must be a multiple of the corresponding dimensions of the compressed texel block

  • VUID-vkCmdCopyImageToBuffer-bufferOffset-00206
    If srcImage is a blocked image, for each element of pRegions, bufferOffset must be a multiple of the compressed texel block size in bytes

  • VUID-vkCmdCopyImageToBuffer-imageExtent-00207
    If srcImage is a blocked image, for each element of pRegions, imageExtent.width must be a multiple of the compressed texel block width or (imageExtent.width + imageOffset.x) must equal the width of the specified imageSubresource of srcImage

  • VUID-vkCmdCopyImageToBuffer-imageExtent-00208
    If srcImage is a blocked image, for each element of pRegions, imageExtent.height must be a multiple of the compressed texel block height or (imageExtent.height + imageOffset.y) must equal the height of the specified imageSubresource of srcImage

  • VUID-vkCmdCopyImageToBuffer-imageExtent-00209
    If srcImage is a blocked image, for each element of pRegions, imageExtent.depth must be a multiple of the compressed texel block depth or (imageExtent.depth + imageOffset.z) must equal the depth of the specified imageSubresource of srcImage

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

  • VUID-vkCmdCopyImageToBuffer-aspectMask-01560
    If srcImage has a multi-planar format, then for each element of pRegions, imageSubresource.aspectMask must be VK_IMAGE_ASPECT_PLANE_0_BIT, VK_IMAGE_ASPECT_PLANE_1_BIT, or VK_IMAGE_ASPECT_PLANE_2_BIT (with VK_IMAGE_ASPECT_PLANE_2_BIT valid only for image formats with three planes)

  • VUID-vkCmdCopyImageToBuffer-baseArrayLayer-00213
    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

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 Pipeline Type

Primary
Secondary

Outside

Transfer
Graphics
Compute

Transfer

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.

When copying to or from a depth or stencil aspect, the data in buffer memory uses a layout that is a (mostly) tightly packed representation of the depth or stencil data. Specifically:

  • data copied to or from the stencil aspect of any depth/stencil format is tightly packed with one VK_FORMAT_S8_UINT value per texel.

  • data copied to or from the depth aspect of a VK_FORMAT_D16_UNORM or VK_FORMAT_D16_UNORM_S8_UINT format is tightly packed with one VK_FORMAT_D16_UNORM value per texel.

  • data copied to or from the depth aspect of a VK_FORMAT_D32_SFLOAT or VK_FORMAT_D32_SFLOAT_S8_UINT format is tightly packed with one VK_FORMAT_D32_SFLOAT value per texel.

  • data copied to or from the depth aspect of a VK_FORMAT_X8_D24_UNORM_PACK32 or VK_FORMAT_D24_UNORM_S8_UINT format is packed with one 32-bit word per texel with the D24 value in the LSBs of the word, and undefined values in the eight MSBs.

Note

To copy both the depth and stencil aspects of a depth/stencil format, two entries in pRegions can be used, where one specifies the depth aspect in imageSubresource, and the other specifies the stencil aspect.

Because depth or stencil aspect buffer to image copies may require format conversions on some implementations, they are not supported on queues that do not support graphics.

When copying to a depth aspect, and the VK_EXT_depth_range_unrestricted extension is not enabled, the data in buffer memory must be in the range [0,1], or the resulting values are undefined.

Copies are done layer by layer starting with image layer baseArrayLayer member of imageSubresource. layerCount layers are copied from the source image or to the destination image.

For purpose of valid usage statements here and in related copy commands, a blocked image is defined as:

  • a image with a single-plane, “_422” format, which is treated as a format with a 2 × 1 compressed texel block, or

  • a compressed image.

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

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

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

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_KHR_copy_commands2
void vkCmdCopyBufferToImage2KHR(
    VkCommandBuffer                             commandBuffer,
    const VkCopyBufferToImageInfo2KHR*          pCopyBufferToImageInfo);
  • commandBuffer is the command buffer into which the command will be recorded.

  • pCopyBufferToImageInfo is a pointer to a VkCopyBufferToImageInfo2KHR 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-vkCmdCopyBufferToImage2KHR-commandBuffer-01828
    If commandBuffer is an unprotected command buffer, then srcBuffer must not be a protected buffer

  • VUID-vkCmdCopyBufferToImage2KHR-commandBuffer-01829
    If commandBuffer is an unprotected command buffer, then dstImage must not be a protected image

  • VUID-vkCmdCopyBufferToImage2KHR-commandBuffer-01830
    If commandBuffer is a protected command buffer, then dstImage must not be an unprotected image

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

  • VUID-vkCmdCopyBufferToImage2KHR-pCopyBufferToImageInfo-parameter
    pCopyBufferToImageInfo must be a valid pointer to a valid VkCopyBufferToImageInfo2KHR structure

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

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

  • VUID-vkCmdCopyBufferToImage2KHR-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 Pipeline Type

Primary
Secondary

Outside

Transfer
Graphics
Compute

Transfer

The VkCopyBufferToImageInfo2KHR structure is defined as:

// Provided by VK_KHR_copy_commands2
typedef struct VkCopyBufferToImageInfo2KHR {
    VkStructureType                 sType;
    const void*                     pNext;
    VkBuffer                        srcBuffer;
    VkImage                         dstImage;
    VkImageLayout                   dstImageLayout;
    uint32_t                        regionCount;
    const VkBufferImageCopy2KHR*    pRegions;
} VkCopyBufferToImageInfo2KHR;
  • sType is the type of 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 VkBufferImageCopy2KHR structures specifying the regions to copy.

Valid Usage
  • VUID-VkCopyBufferToImageInfo2KHR-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-VkCopyBufferToImageInfo2KHR-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-VkCopyBufferToImageInfo2KHR-srcBuffer-00174
    srcBuffer must have been created with VK_BUFFER_USAGE_TRANSFER_SRC_BIT usage flag

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

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

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

  • VUID-VkCopyBufferToImageInfo2KHR-dstImage-00178
    If dstImage is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-VkCopyBufferToImageInfo2KHR-dstImage-00179
    dstImage must have a sample count equal to VK_SAMPLE_COUNT_1_BIT

  • VUID-VkCopyBufferToImageInfo2KHR-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-VkCopyBufferToImageInfo2KHR-dstImageLayout-01396
    dstImageLayout must be VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL, VK_IMAGE_LAYOUT_GENERAL, or VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR

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

  • VUID-VkCopyBufferToImageInfo2KHR-imageSubresource-01702
    The 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-VkCopyBufferToImageInfo2KHR-imageOffset-01793
    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-VkCopyBufferToImageInfo2KHR-dstImage-02543
    dstImage must not have been created with flags containing VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT

  • VUID-VkCopyBufferToImageInfo2KHR-commandBuffer-04052
    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-VkCopyBufferToImageInfo2KHR-dstImage-04053
    If dstImage has a depth/stencil format, the bufferOffset member of any element of pRegions must be a multiple of 4

  • VUID-VkCopyBufferToImageInfo2KHR-commandBuffer-04477
    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-VkCopyBufferToImageInfo2KHR-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 dstImage where this refers to the width of the plane of the image involved in the copy in the case of a multi-planar format

  • VUID-VkCopyBufferToImageInfo2KHR-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 dstImage where this refers to the height of the plane of the image involved in the copy in the case of a multi-planar format

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

  • VUID-VkCopyBufferToImageInfo2KHR-bufferOffset-01559
    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-VkCopyBufferToImageInfo2KHR-srcImage-00199
    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-VkCopyBufferToImageInfo2KHR-imageOffset-00200
    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-VkCopyBufferToImageInfo2KHR-srcImage-00201
    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-VkCopyBufferToImageInfo2KHR-bufferRowLength-00203
    If dstImage is a blocked image, for each element of pRegions, bufferRowLength must be a multiple of the compressed texel block width

  • VUID-VkCopyBufferToImageInfo2KHR-bufferImageHeight-00204
    If dstImage is a blocked image, for each element of pRegions, bufferImageHeight must be a multiple of the compressed texel block height

  • VUID-VkCopyBufferToImageInfo2KHR-imageOffset-00205
    If dstImage is a blocked image, for each element of pRegions, all members of imageOffset must be a multiple of the corresponding dimensions of the compressed texel block

  • VUID-VkCopyBufferToImageInfo2KHR-bufferOffset-00206
    If dstImage is a blocked image, for each element of pRegions, bufferOffset must be a multiple of the compressed texel block size in bytes

  • VUID-VkCopyBufferToImageInfo2KHR-imageExtent-00207
    If dstImage is a blocked image, for each element of pRegions, imageExtent.width must be a multiple of the compressed texel block width or (imageExtent.width + imageOffset.x) must equal the width of the specified imageSubresource of dstImage

  • VUID-VkCopyBufferToImageInfo2KHR-imageExtent-00208
    If dstImage is a blocked image, for each element of pRegions, imageExtent.height must be a multiple of the compressed texel block height or (imageExtent.height + imageOffset.y) must equal the height of the specified imageSubresource of dstImage

  • VUID-VkCopyBufferToImageInfo2KHR-imageExtent-00209
    If dstImage is a blocked image, for each element of pRegions, imageExtent.depth must be a multiple of the compressed texel block depth or (imageExtent.depth + imageOffset.z) must equal the depth of the specified imageSubresource of dstImage

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

  • VUID-VkCopyBufferToImageInfo2KHR-aspectMask-01560
    If dstImage has a multi-planar format, then for each element of pRegions, imageSubresource.aspectMask must be VK_IMAGE_ASPECT_PLANE_0_BIT, VK_IMAGE_ASPECT_PLANE_1_BIT, or VK_IMAGE_ASPECT_PLANE_2_BIT (with VK_IMAGE_ASPECT_PLANE_2_BIT valid only for image formats with three planes)

  • VUID-VkCopyBufferToImageInfo2KHR-baseArrayLayer-00213
    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

Valid Usage (Implicit)
  • VUID-VkCopyBufferToImageInfo2KHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_COPY_BUFFER_TO_IMAGE_INFO_2_KHR

  • VUID-VkCopyBufferToImageInfo2KHR-pNext-pNext
    pNext must be NULL

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

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

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

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

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

  • VUID-VkCopyBufferToImageInfo2KHR-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_KHR_copy_commands2
void vkCmdCopyImageToBuffer2KHR(
    VkCommandBuffer                             commandBuffer,
    const VkCopyImageToBufferInfo2KHR*          pCopyImageToBufferInfo);
  • commandBuffer is the command buffer into which the command will be recorded.

  • pCopyImageToBufferInfo is a pointer to a vkCmdCopyImageToBuffer2KHR 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-vkCmdCopyImageToBuffer2KHR-commandBuffer-01831
    If commandBuffer is an unprotected command buffer, then srcImage must not be a protected image

  • VUID-vkCmdCopyImageToBuffer2KHR-commandBuffer-01832
    If commandBuffer is an unprotected command buffer, then dstBuffer must not be a protected buffer

  • VUID-vkCmdCopyImageToBuffer2KHR-commandBuffer-01833
    If commandBuffer is a protected command buffer, then dstBuffer must not be an unprotected buffer

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

  • VUID-vkCmdCopyImageToBuffer2KHR-pCopyImageToBufferInfo-parameter
    pCopyImageToBufferInfo must be a valid pointer to a valid VkCopyImageToBufferInfo2KHR structure

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

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

  • VUID-vkCmdCopyImageToBuffer2KHR-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 Pipeline Type

Primary
Secondary

Outside

Transfer
Graphics
Compute

Transfer

The VkCopyImageToBufferInfo2KHR structure is defined as:

// Provided by VK_KHR_copy_commands2
typedef struct VkCopyImageToBufferInfo2KHR {
    VkStructureType                 sType;
    const void*                     pNext;
    VkImage                         srcImage;
    VkImageLayout                   srcImageLayout;
    VkBuffer                        dstBuffer;
    uint32_t                        regionCount;
    const VkBufferImageCopy2KHR*    pRegions;
} VkCopyImageToBufferInfo2KHR;
  • sType is the type of 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 VkBufferImageCopy2KHR structures specifying the regions to copy.

Valid Usage
  • VUID-VkCopyImageToBufferInfo2KHR-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-VkCopyImageToBufferInfo2KHR-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-VkCopyImageToBufferInfo2KHR-srcImage-00186
    srcImage must have been created with VK_IMAGE_USAGE_TRANSFER_SRC_BIT usage flag

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

  • VUID-VkCopyImageToBufferInfo2KHR-srcImage-00187
    If srcImage is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

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

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

  • VUID-VkCopyImageToBufferInfo2KHR-srcImage-00188
    srcImage must have a sample count equal to VK_SAMPLE_COUNT_1_BIT

  • VUID-VkCopyImageToBufferInfo2KHR-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-VkCopyImageToBufferInfo2KHR-srcImageLayout-01397
    srcImageLayout must be VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL, VK_IMAGE_LAYOUT_GENERAL, or VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR

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

  • VUID-VkCopyImageToBufferInfo2KHR-imageSubresource-01704
    The 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-VkCopyImageToBufferInfo2KHR-imageOffset-01794
    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-VkCopyImageToBufferInfo2KHR-srcImage-02544
    srcImage must not have been created with flags containing VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT

  • VUID-VkCopyImageToBufferInfo2KHR-commandBuffer-04054
    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-VkCopyImageToBufferInfo2KHR-srcImage-04055
    If srcImage has a depth/stencil format, the bufferOffset member of any element of pRegions must be a multiple of 4

  • VUID-VkCopyImageToBufferInfo2KHR-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 where this refers to the width of the plane of the image involved in the copy in the case of a multi-planar format

  • VUID-VkCopyImageToBufferInfo2KHR-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 where this refers to the height of the plane of the image involved in the copy in the case of a multi-planar format

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

  • VUID-VkCopyImageToBufferInfo2KHR-bufferOffset-01559
    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-VkCopyImageToBufferInfo2KHR-srcImage-00199
    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-VkCopyImageToBufferInfo2KHR-imageOffset-00200
    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-VkCopyImageToBufferInfo2KHR-srcImage-00201
    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-VkCopyImageToBufferInfo2KHR-bufferRowLength-00203
    If srcImage is a blocked image, for each element of pRegions, bufferRowLength must be a multiple of the compressed texel block width

  • VUID-VkCopyImageToBufferInfo2KHR-bufferImageHeight-00204
    If srcImage is a blocked image, for each element of pRegions, bufferImageHeight must be a multiple of the compressed texel block height

  • VUID-VkCopyImageToBufferInfo2KHR-imageOffset-00205
    If srcImage is a blocked image, for each element of pRegions, all members of imageOffset must be a multiple of the corresponding dimensions of the compressed texel block

  • VUID-VkCopyImageToBufferInfo2KHR-bufferOffset-00206
    If srcImage is a blocked image, for each element of pRegions, bufferOffset must be a multiple of the compressed texel block size in bytes

  • VUID-VkCopyImageToBufferInfo2KHR-imageExtent-00207
    If srcImage is a blocked image, for each element of pRegions, imageExtent.width must be a multiple of the compressed texel block width or (imageExtent.width + imageOffset.x) must equal the width of the specified imageSubresource of srcImage

  • VUID-VkCopyImageToBufferInfo2KHR-imageExtent-00208
    If srcImage is a blocked image, for each element of pRegions, imageExtent.height must be a multiple of the compressed texel block height or (imageExtent.height + imageOffset.y) must equal the height of the specified imageSubresource of srcImage

  • VUID-VkCopyImageToBufferInfo2KHR-imageExtent-00209
    If srcImage is a blocked image, for each element of pRegions, imageExtent.depth must be a multiple of the compressed texel block depth or (imageExtent.depth + imageOffset.z) must equal the depth of the specified imageSubresource of srcImage

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

  • VUID-VkCopyImageToBufferInfo2KHR-aspectMask-01560
    If srcImage has a multi-planar format, then for each element of pRegions, imageSubresource.aspectMask must be VK_IMAGE_ASPECT_PLANE_0_BIT, VK_IMAGE_ASPECT_PLANE_1_BIT, or VK_IMAGE_ASPECT_PLANE_2_BIT (with VK_IMAGE_ASPECT_PLANE_2_BIT valid only for image formats with three planes)

  • VUID-VkCopyImageToBufferInfo2KHR-baseArrayLayer-00213
    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

Valid Usage (Implicit)
  • VUID-VkCopyImageToBufferInfo2KHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_COPY_IMAGE_TO_BUFFER_INFO_2_KHR

  • VUID-VkCopyImageToBufferInfo2KHR-pNext-pNext
    pNext must be NULL

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

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

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

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

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

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

For both vkCmdCopyBufferToImage2KHR and vkCmdCopyImageToBuffer2KHR, each element of pRegions is a structure defined as:

// Provided by VK_KHR_copy_commands2
typedef struct VkBufferImageCopy2KHR {
    VkStructureType             sType;
    const void*                 pNext;
    VkDeviceSize                bufferOffset;
    uint32_t                    bufferRowLength;
    uint32_t                    bufferImageHeight;
    VkImageSubresourceLayers    imageSubresource;
    VkOffset3D                  imageOffset;
    VkExtent3D                  imageExtent;
} VkBufferImageCopy2KHR;
  • sType is the type of 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-VkBufferImageCopy2KHR-bufferRowLength-00195
    bufferRowLength must be 0, or greater than or equal to the width member of imageExtent

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

  • VUID-VkBufferImageCopy2KHR-aspectMask-00212
    The aspectMask member of imageSubresource must only have a single bit set

Valid Usage (Implicit)
  • VUID-VkBufferImageCopy2KHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_BUFFER_IMAGE_COPY_2_KHR

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

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

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

For both vkCmdCopyBufferToImage2KHR and vkCmdCopyImageToBuffer2KHR, each region copied can include a rotation. To specify a region with rotation, add the VkCopyCommandTransformInfoQCOM to the pNext chain of VkBufferImageCopy2KHR. When a rotation is specified, Buffer and Image Addressing with Rotation specifies how coordinates of texels in the source region are rotated by transform to produce texel coordinates in the destination region. When rotation is specified, the source or destination image must be a 2D image and must not be blocked image or multi-planar format.

The VkRenderPassTransformBeginInfoQCOM structure is defined as:

// Provided by VK_QCOM_rotated_copy_commands
typedef struct VkCopyCommandTransformInfoQCOM {
    VkStructureType                  sType;
    const void*                      pNext;
    VkSurfaceTransformFlagBitsKHR    transform;
} VkCopyCommandTransformInfoQCOM;
  • sType is the type of this structure.

  • pNext is NULL or a pointer to an extension-specific structure.

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

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

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

20.4.1. Buffer and Image Addressing

Pseudocode for image/buffer addressing of uncompressed formats is:

rowLength = region->bufferRowLength;
if (rowLength == 0)
    rowLength = region->imageExtent.width;

imageHeight = region->bufferImageHeight;
if (imageHeight == 0)
    imageHeight = region->imageExtent.height;

texelBlockSize = <texel block size of the format of the src/dstImage>;

address of (x,y,z) = region->bufferOffset + (((z * imageHeight) + y) * rowLength + x) * texelBlockSize;

where x,y,z range from (0,0,0) to region->imageExtent.{width,height,depth}.

Note that imageOffset does not affect addressing calculations for buffer memory. Instead, bufferOffset can be used to select the starting address in buffer memory.

For block-compressed formats, all parameters are still specified in texels rather than compressed texel blocks, but the addressing math operates on whole compressed texel blocks. Pseudocode for compressed copy addressing is:

rowLength = region->bufferRowLength;
if (rowLength == 0)
    rowLength = region->imageExtent.width;

imageHeight = region->bufferImageHeight;
if (imageHeight == 0)
    imageHeight = region->imageExtent.height;

compressedTexelBlockSizeInBytes = <compressed texel block size taken from the src/dstImage>;
rowLength /= compressedTexelBlockWidth;
imageHeight /= compressedTexelBlockHeight;

address of (x,y,z) = region->bufferOffset + (((z * imageHeight) + y) * rowLength + x) * compressedTexelBlockSizeInBytes;

where x,y,z range from (0,0,0) to region->imageExtent.{width/compressedTexelBlockWidth,height/compressedTexelBlockHeight,depth/compressedTexelBlockDepth}.

Copying to or from block-compressed images is typically done in multiples of the compressed texel block size. For this reason the imageExtent must be a multiple of the compressed texel block dimension. There is one exception to this rule which is required to handle compressed images created with dimensions that are not a multiple of the compressed texel block dimensions:

  • If imageExtent.width is not a multiple of the compressed texel block width, then (imageExtent.width + imageOffset.x) must equal the image subresource width.

  • If imageExtent.height is not a multiple of the compressed texel block height, then (imageExtent.height + imageOffset.y) must equal the image subresource height.

  • If imageExtent.depth is not a multiple of the compressed texel block depth, then (imageExtent.depth + imageOffset.z) must equal the image subresource depth.

This allows the last compressed texel block of the image in each non-multiple dimension to be included as a source or destination of the copy.

20.4.2. Buffer and Image Addressing with Rotation

When VkCopyCommandTransformInfoQCOM is in the pNext chain of VkBufferImageCopy2KHR, a rotated copy is specified. For both vkCmdCopyImageToBuffer2KHR and vkCmdCopyBufferToImage2KHR, a rotation is applied to the region used for image accesses, but a non-rotated region is used for buffer accesses. In the case of rotated vkCmdCopyImageToBuffer2KHR, the source image region is rotated. In the case of rotated vkCmdCopyBufferToImage2KHR, the destination image region is rotated.

For a rotated copy, The following description of rotated addressing replaces the description in Buffer and Image Addressing.

The following code computes rotation of unnormalized coordinates.

// Forward rotation of unnormalized coordinates
VkOffset2D RotateUV(VkOffset2D in, VkSurfaceTransformFlagBitsKHR flags)
{
    VkOffset2D output;
    switch (flags)
    {
        case VK_SURFACE_TRANSFORM_IDENTITY_BIT_KHR:
            out.x = in.x;
            out.y = in.y;
            break;
        case VK_SURFACE_TRANSFORM_ROTATE_90_BIT_KHR:
            out.x = -in.y;
            out.y = in.x;
            break;
        case VK_SURFACE_TRANSFORM_ROTATE_180_BIT_KHR:
            out.x = -in.x;
            out.y = -in.y;
            break;
        case VK_SURFACE_TRANSFORM_ROTATE_270_BIT_KHR:
            out.x = in.y;
            out.y = -in.x;
            break;
    }
    return out;
}

Pseudocode for image/buffer addressing of uncompressed formats with rotation is:

rowLength = region->bufferRowLength;
if (rowLength == 0)
    rowLength = region->imageExtent.width;

imageHeight = region->bufferImageHeight;
if (imageHeight == 0)
    imageHeight = region->imageExtent.height;

texelBlockSize = <texel block size of the format of the src/dstImage>;

// Buffer addressing is unaffected by rotation:
address of (x,y,z) = region->bufferOffset + (((z * imageHeight) + y) * rowLength + x) * texelBlockSize;

// When copying from buffer to image, the source buffer coordinates x,y,z range from (0,0,0) to
// region->imageExtent.{width,height,depth}.  The source extent is rotated by the specified
// VK_SURFACE_TRANSFORM, centered on the imageOffset, to define a rotated destination region.
// For each source buffer texel with coordinates (x,y) the rotated destination image texel has
// coordinates (x',y') defined as:
(x',y')= RotateUV(x,y) + ImageOffset.{x,y}

// When copying from image to buffer, the the destination buffer coordinates x,y,z range from (0,0,0) to
// region->imageExtent.{width,height,depth}.  The destination extent is rotated by the specified
//  VK_SURFACE_TRANSFORM, centered on the imageOffset, to define a rotated source region.  For each destination
// buffer texel with coordinates (x,y) the rotated source image texel has coordinates (x',y') defined as:
(x',y')= RotateUV(x,y) + ImageOffset.{x,y}

Note that imageOffset does not affect addressing calculations for buffer memory. Instead, bufferOffset can be used to select the starting address in buffer memory.

20.5. 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, unscaled 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, then srcImage must not be a protected image

  • VUID-vkCmdBlitImage-commandBuffer-01835
    If commandBuffer is an unprotected command buffer, then dstImage must not be a protected image

  • VUID-vkCmdBlitImage-commandBuffer-01836
    If commandBuffer is a protected command buffer, then 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-01561
    srcImage must not use a format listed in Formats requiring sampler Y′CBCR conversion for VK_IMAGE_ASPECT_COLOR_BIT image views

  • VUID-vkCmdBlitImage-srcImage-00219
    srcImage must have been created with VK_IMAGE_USAGE_TRANSFER_SRC_BIT usage flag

  • VUID-vkCmdBlitImage-srcImage-00220
    If srcImage is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

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

  • VUID-vkCmdBlitImage-srcImageLayout-01398
    srcImageLayout must be VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR, VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL or VK_IMAGE_LAYOUT_GENERAL

  • VUID-vkCmdBlitImage-dstImage-02000
    The format features of dstImage must contain VK_FORMAT_FEATURE_BLIT_DST_BIT

  • VUID-vkCmdBlitImage-dstImage-01562
    dstImage must not use a format listed in Formats requiring sampler Y′CBCR conversion for VK_IMAGE_ASPECT_COLOR_BIT image views

  • VUID-vkCmdBlitImage-dstImage-00224
    dstImage must have been created with VK_IMAGE_USAGE_TRANSFER_DST_BIT usage flag

  • VUID-vkCmdBlitImage-dstImage-00225
    If dstImage is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

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

  • VUID-vkCmdBlitImage-dstImageLayout-01399
    dstImageLayout must be VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR, VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL or VK_IMAGE_LAYOUT_GENERAL

  • VUID-vkCmdBlitImage-srcImage-00229
    If either of srcImage or dstImage was created with a signed integer VkFormat, the other must also have been created with a signed integer VkFormat

  • VUID-vkCmdBlitImage-srcImage-00230
    If either of srcImage or dstImage was created with an unsigned integer VkFormat, the other must also have been created with an unsigned integer VkFormat

  • VUID-vkCmdBlitImage-srcImage-00231
    If either of srcImage or dstImage was created with a depth/stencil format, the other must have exactly the same format

  • VUID-vkCmdBlitImage-srcImage-00232
    If srcImage was created with a depth/stencil format, filter must be VK_FILTER_NEAREST

  • VUID-vkCmdBlitImage-srcImage-00233
    srcImage must have been created with a samples value of VK_SAMPLE_COUNT_1_BIT

  • VUID-vkCmdBlitImage-dstImage-00234
    dstImage must have been created with a samples value of VK_SAMPLE_COUNT_1_BIT

  • VUID-vkCmdBlitImage-filter-02001
    If filter is VK_FILTER_LINEAR, then the format features of srcImage must contain VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT

  • VUID-vkCmdBlitImage-filter-02002
    If filter is VK_FILTER_CUBIC_EXT, then the format features of srcImage must contain VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_CUBIC_BIT_EXT

  • VUID-vkCmdBlitImage-filter-00237
    If filter is VK_FILTER_CUBIC_EXT, srcImage must be of type VK_IMAGE_TYPE_2D

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

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

  • VUID-vkCmdBlitImage-srcSubresource-01707
    The 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
    The dstSubresource.baseArrayLayer + dstSubresource.layerCount of each element of pRegions must be less than or equal to the arrayLayers specified in VkImageCreateInfo when dstImage was created

  • VUID-vkCmdBlitImage-dstImage-02545
    dstImage and srcImage must not have been created with flags containing VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT

  • VUID-vkCmdBlitImage-srcImage-00240
    If either srcImage or dstImage is of type VK_IMAGE_TYPE_3D, then for each element of pRegions, srcSubresource.baseArrayLayer and dstSubresource.baseArrayLayer must each be 0, and srcSubresource.layerCount and dstSubresource.layerCount must each be 1.

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

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

  • VUID-vkCmdBlitImage-srcOffset-00243
    For each element of pRegions, srcOffset[0].x and srcOffset[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, srcOffset[0].y and srcOffset[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, srcOffset[0].y must be 0 and srcOffset[1].y must be 1

  • VUID-vkCmdBlitImage-srcOffset-00246
    For each element of pRegions, srcOffset[0].z and srcOffset[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, srcOffset[0].z must be 0 and srcOffset[1].z must be 1

  • VUID-vkCmdBlitImage-dstOffset-00248
    For each element of pRegions, dstOffset[0].x and dstOffset[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, dstOffset[0].y and dstOffset[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, dstOffset[0].y must be 0 and dstOffset[1].y must be 1

  • VUID-vkCmdBlitImage-dstOffset-00251
    For each element of pRegions, dstOffset[0].z and dstOffset[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, dstOffset[0].z must be 0 and dstOffset[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 Pipeline Type

Primary
Secondary

Outside

Graphics

Transfer

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 the specified source and destination regions.

Valid Usage
  • VUID-VkImageBlit-aspectMask-00238
    The aspectMask member of srcSubresource and dstSubresource must match

  • VUID-VkImageBlit-layerCount-00239
    The layerCount member of srcSubresource and 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_KHR_copy_commands2
void vkCmdBlitImage2KHR(
    VkCommandBuffer                             commandBuffer,
    const VkBlitImageInfo2KHR*                  pBlitImageInfo);
  • commandBuffer is the command buffer into which the command will be recorded.

  • pBlitImageInfo is a pointer to a VkBlitImageInfo2KHR 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-vkCmdBlitImage2KHR-commandBuffer-01834
    If commandBuffer is an unprotected command buffer, then srcImage must not be a protected image

  • VUID-vkCmdBlitImage2KHR-commandBuffer-01835
    If commandBuffer is an unprotected command buffer, then dstImage must not be a protected image

  • VUID-vkCmdBlitImage2KHR-commandBuffer-01836
    If commandBuffer is a protected command buffer, then dstImage must not be an unprotected image

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

  • VUID-vkCmdBlitImage2KHR-pBlitImageInfo-parameter
    pBlitImageInfo must be a valid pointer to a valid VkBlitImageInfo2KHR structure

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

  • VUID-vkCmdBlitImage2KHR-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support graphics operations

  • VUID-vkCmdBlitImage2KHR-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 Pipeline Type

Primary
Secondary

Outside

Graphics

Transfer

The VkBlitImageInfo2KHR structure is defined as:

// Provided by VK_KHR_copy_commands2
typedef struct VkBlitImageInfo2KHR {
    VkStructureType           sType;
    const void*               pNext;
    VkImage                   srcImage;
    VkImageLayout             srcImageLayout;
    VkImage                   dstImage;
    VkImageLayout             dstImageLayout;
    uint32_t                  regionCount;
    const VkImageBlit2KHR*    pRegions;
    VkFilter                  filter;
} VkBlitImageInfo2KHR;
  • sType is the type of 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 VkImageBlit2KHR structures specifying the regions to blit.

  • filter is a VkFilter specifying the filter to apply if the blits require scaling.

Valid Usage
  • VUID-VkBlitImageInfo2KHR-pRegions-00215
    The source region specified by each element of pRegions must be a region that is contained within srcImage

  • VUID-VkBlitImageInfo2KHR-pRegions-00216
    The destination region specified by each element of pRegions must be a region that is contained within dstImage

  • VUID-VkBlitImageInfo2KHR-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-VkBlitImageInfo2KHR-srcImage-01999
    The format features of srcImage must contain VK_FORMAT_FEATURE_BLIT_SRC_BIT

  • VUID-VkBlitImageInfo2KHR-srcImage-01561
    srcImage must not use a format listed in Formats requiring sampler Y′CBCR conversion for VK_IMAGE_ASPECT_COLOR_BIT image views

  • VUID-VkBlitImageInfo2KHR-srcImage-00219
    srcImage must have been created with VK_IMAGE_USAGE_TRANSFER_SRC_BIT usage flag

  • VUID-VkBlitImageInfo2KHR-srcImage-00220
    If srcImage is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-VkBlitImageInfo2KHR-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-VkBlitImageInfo2KHR-srcImageLayout-01398
    srcImageLayout must be VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR, VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL or VK_IMAGE_LAYOUT_GENERAL

  • VUID-VkBlitImageInfo2KHR-dstImage-02000
    The format features of dstImage must contain VK_FORMAT_FEATURE_BLIT_DST_BIT

  • VUID-VkBlitImageInfo2KHR-dstImage-01562
    dstImage must not use a format listed in Formats requiring sampler Y′CBCR conversion for VK_IMAGE_ASPECT_COLOR_BIT image views

  • VUID-VkBlitImageInfo2KHR-dstImage-00224
    dstImage must have been created with VK_IMAGE_USAGE_TRANSFER_DST_BIT usage flag

  • VUID-VkBlitImageInfo2KHR-dstImage-00225
    If dstImage is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-VkBlitImageInfo2KHR-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-VkBlitImageInfo2KHR-dstImageLayout-01399
    dstImageLayout must be VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR, VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL or VK_IMAGE_LAYOUT_GENERAL

  • VUID-VkBlitImageInfo2KHR-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-VkBlitImageInfo2KHR-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-VkBlitImageInfo2KHR-srcImage-00231
    If either of srcImage or dstImage was created with a depth/stencil format, the other must have exactly the same format

  • VUID-VkBlitImageInfo2KHR-srcImage-00232
    If srcImage was created with a depth/stencil format, filter must be VK_FILTER_NEAREST

  • VUID-VkBlitImageInfo2KHR-srcImage-00233
    srcImage must have been created with a samples value of VK_SAMPLE_COUNT_1_BIT

  • VUID-VkBlitImageInfo2KHR-dstImage-00234
    dstImage must have been created with a samples value of VK_SAMPLE_COUNT_1_BIT

  • VUID-VkBlitImageInfo2KHR-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-VkBlitImageInfo2KHR-filter-02002
    If filter is VK_FILTER_CUBIC_EXT, then the format features of srcImage must contain VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_CUBIC_BIT_EXT

  • VUID-VkBlitImageInfo2KHR-filter-00237
    If filter is VK_FILTER_CUBIC_EXT, srcImage must be of type VK_IMAGE_TYPE_2D

  • VUID-VkBlitImageInfo2KHR-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-VkBlitImageInfo2KHR-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-VkBlitImageInfo2KHR-srcSubresource-01707
    The 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-VkBlitImageInfo2KHR-dstSubresource-01708
    The 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-VkBlitImageInfo2KHR-dstImage-02545
    dstImage and srcImage must not have been created with flags containing VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT

  • VUID-VkBlitImageInfo2KHR-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-VkBlitImageInfo2KHR-aspectMask-00241
    For each element of pRegions, srcSubresource.aspectMask must specify aspects present in srcImage

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

  • VUID-VkBlitImageInfo2KHR-srcOffset-00243
    For each element of pRegions, srcOffset[0].x and srcOffset[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-VkBlitImageInfo2KHR-srcOffset-00244
    For each element of pRegions, srcOffset[0].y and srcOffset[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-VkBlitImageInfo2KHR-srcImage-00245
    If srcImage is of type VK_IMAGE_TYPE_1D, then for each element of pRegions, srcOffset[0].y must be 0 and srcOffset[1].y must be 1

  • VUID-VkBlitImageInfo2KHR-srcOffset-00246
    For each element of pRegions, srcOffset[0].z and srcOffset[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-VkBlitImageInfo2KHR-srcImage-00247
    If srcImage is of type VK_IMAGE_TYPE_1D or VK_IMAGE_TYPE_2D, then for each element of pRegions, srcOffset[0].z must be 0 and srcOffset[1].z must be 1

  • VUID-VkBlitImageInfo2KHR-dstOffset-00248
    For each element of pRegions, dstOffset[0].x and dstOffset[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-VkBlitImageInfo2KHR-dstOffset-00249
    For each element of pRegions, dstOffset[0].y and dstOffset[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-VkBlitImageInfo2KHR-dstImage-00250
    If dstImage is of type VK_IMAGE_TYPE_1D, then for each element of pRegions, dstOffset[0].y must be 0 and dstOffset[1].y must be 1

  • VUID-VkBlitImageInfo2KHR-dstOffset-00251
    For each element of pRegions, dstOffset[0].z and dstOffset[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-VkBlitImageInfo2KHR-dstImage-00252
    If dstImage is of type VK_IMAGE_TYPE_1D or VK_IMAGE_TYPE_2D, then for each element of pRegions, dstOffset[0].z must be 0 and dstOffset[1].z must be 1

  • VUID-VkBlitImageInfo2KHR-pRegions-04561
    If any element of pRegions contains VkCopyCommandTransformInfoQCOM in its pNext chain, then srcImage and dstImage must not be a block-compressed image.

  • VUID-VkBlitImageInfo2KHR-pRegions-04562
    If any element of pRegions contains VkCopyCommandTransformInfoQCOM in its pNext chain, then the srcImage must be of type VK_IMAGE_TYPE_2D and must not be a multi-planar format.

Valid Usage (Implicit)
  • VUID-VkBlitImageInfo2KHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_BLIT_IMAGE_INFO_2_KHR

  • VUID-VkBlitImageInfo2KHR-pNext-pNext
    pNext must be NULL

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

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

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

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

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

  • VUID-VkBlitImageInfo2KHR-filter-parameter
    filter must be a valid VkFilter value

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

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

The VkImageBlit2KHR structure is defined as:

// Provided by VK_KHR_copy_commands2
typedef struct VkImageBlit2KHR {
    VkStructureType             sType;
    const void*                 pNext;
    VkImageSubresourceLayers    srcSubresource;
    VkOffset3D                  srcOffsets[2];
    VkImageSubresourceLayers    dstSubresource;
    VkOffset3D                  dstOffsets[2];
} VkImageBlit2KHR;
  • sType is the type of 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-VkImageBlit2KHR-aspectMask-00238
    The aspectMask member of srcSubresource and dstSubresource must match

  • VUID-VkImageBlit2KHR-layerCount-00239
    The layerCount member of srcSubresource and dstSubresource must match

Valid Usage (Implicit)
  • VUID-VkImageBlit2KHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_IMAGE_BLIT_2_KHR

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

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

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

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

For vkCmdBlitImage2KHR, each region copied can include a rotation. To specify a rotated region, add VkCopyCommandTransformInfoQCOM to the pNext chain of VkImageBlit2KHR. For each region with a rotation specified, Image Blits with Scaling and Rotation specifies how coordinates are rotated prior to sampling from the source image. When rotation is specified, the source and destination images must be a 2D image and must not be blocked image or multi-planar format.

 <<formats-requiring-sampler-ycbcr-conversion,_multi-planar_ image>>,
or specify a destination <<blocked-image, blocked image>>.

20.5.1. Image Blits with Scaling and Rotation

When VkCopyCommandTransformInfoQCOM is in the pNext chain of VkImageBlit2KHR, the specified region is rotated during the blit. The following description of rotated addressing replaces the description in vkCmdBlitImage.

The following code computes rotation of normalized coordinates.

// rotation of normalized coordinates
VkOffset2D RotateNormUV(VkOffset2D in, VkSurfaceTransformFlagBitsKHR flags)
{
    VkOffset2D output;
    switch (flags)
    {
        case VK_SURFACE_TRANSFORM_IDENTITY_BIT_KHR:
            out.x = in.x;
            out.y = in.y;
            break;
        case VK_SURFACE_TRANSFORM_ROTATE_90_BIT_KHR:
            out.x = in.y;
            out.y = 1.0 - in.x;
            break;
        case VK_SURFACE_TRANSFORM_ROTATE_180_BIT_KHR:
            out.x = 1.0 - in.x;
            out.y = 1.0 - in.y;
            break;
        case VK_SURFACE_TRANSFORM_ROTATE_270_BIT_KHR:
            out.x = 1.0 - in.y;
            out.y = in.x;
            break;
    }
    return out;
}
  • For each destination texel, the integer coordinate of that texel is converted to an unnormalized texture coordinate, using the effective inverse of the equations described in unnormalized to integer conversion:

    ubase = i + ½

    vbase = j + ½

    wbase = k + ½

  • These base coordinates are then offset by the first destination offset:

    uoffset = ubase - xdst0

    voffset = vbase - ydst0

    woffset = wbase - zdst0

    aoffset = a - baseArrayCountdst

  • The UV destination coordinates are scaled by the destination region, rotated, and scaled by the source region.

    udest_scaled = uoffset / (xdst1 - xdst0)

    vdest_scaled = voffset / (ydst1 - ydst0)

    (usrc_scaled, vsrc_scaled) = RotateNormUV(udest_scaled, vdest_scaled, transform)

    uscaled = usrc_scaled * (xSrc1 - xSrc0)

    vscaled = vsrc_scaled * (ySrc1 - ySrc0)

  • The W coordinate is unaffected by rotation. The scale is determined from the ratio of source and destination regions, and applied to the offset coordinate:

    scalew = (zSrc1 - zSrc0) / (zdst1 - zdst0)

    wscaled = woffset * scalew

  • Finally the source offset is added to the scaled source coordinates, to determine the final unnormalized coordinates used to sample from srcImage:

    u = uscaled + xSrc0

    v = vscaled + ySrc0

    w = wscaled + zSrc0

    q = mipLevel

    a = aoffset + baseArrayCountsrc

These coordinates are used to sample from the source image, as described 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.

20.6. 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, then srcImage must not be a protected image

  • VUID-vkCmdResolveImage-commandBuffer-01838
    If commandBuffer is an unprotected command buffer, then dstImage must not be a protected image

  • VUID-vkCmdResolveImage-commandBuffer-01839
    If commandBuffer is a protected command buffer, then dstImage must not be an unprotected image

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

  • VUID-vkCmdResolveImage-srcImage-00256
    If srcImage is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-vkCmdResolveImage-srcImage-00257
    srcImage must have a sample count equal to any valid sample count value other than VK_SAMPLE_COUNT_1_BIT

  • VUID-vkCmdResolveImage-dstImage-00258
    If dstImage is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-vkCmdResolveImage-dstImage-00259
    dstImage must have a sample count equal to VK_SAMPLE_COUNT_1_BIT

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

  • VUID-vkCmdResolveImage-srcImageLayout-01400
    srcImageLayout must be VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR, VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL or VK_IMAGE_LAYOUT_GENERAL

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

  • VUID-vkCmdResolveImage-dstImageLayout-01401
    dstImageLayout must be VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR, VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL or VK_IMAGE_LAYOUT_GENERAL

  • VUID-vkCmdResolveImage-dstImage-02003
    The format features of dstImage must contain VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT

  • VUID-vkCmdResolveImage-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
    The 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
    The dstSubresource.baseArrayLayer + dstSubresource.layerCount of each element of pRegions must be less than or equal to the arrayLayers specified in VkImageCreateInfo when dstImage was created

  • VUID-vkCmdResolveImage-dstImage-02546
    dstImage and srcImage must not have been created with flags containing VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT

  • VUID-vkCmdResolveImage-srcImage-04446
    If either srcImage or dstImage are of type VK_IMAGE_TYPE_3D, then for each element of pRegions, srcSubresource.baseArrayLayer must be 0 and srcSubresource.layerCount must be 1

  • VUID-vkCmdResolveImage-srcImage-04447
    If either srcImage or dstImage are 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

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 Pipeline Type

Primary
Secondary

Outside

Graphics

Transfer

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

Valid Usage (Implicit)

20.7. Buffer Markers

To write a 32-bit marker value into a buffer as a pipelined operation, call:

// Provided by VK_AMD_buffer_marker
void vkCmdWriteBufferMarkerAMD(
    VkCommandBuffer                             commandBuffer,
    VkPipelineStageFlagBits                     pipelineStage,
    VkBuffer                                    dstBuffer,
    VkDeviceSize                                dstOffset,
    uint32_t                                    marker);
  • commandBuffer is the command buffer into which the command will be recorded.

  • pipelineStage is one of the VkPipelineStageFlagBits values, specifying the pipeline stage whose completion triggers the marker write.

  • dstBuffer is the buffer where the marker will be written to.

  • dstOffset is the byte offset into the buffer where the marker will be written to.

  • marker is the 32-bit value of the marker.

The command will write the 32-bit marker value into the buffer only after all preceding commands have finished executing up to at least the specified pipeline stage. This includes the completion of other preceding vkCmdWriteBufferMarkerAMD commands so long as their specified pipeline stages occur either at the same time or earlier than this command’s specified pipelineStage.

While consecutive buffer marker writes with the same pipelineStage parameter are implicitly complete in submission order, memory and execution dependencies between buffer marker writes and other operations must still be explicitly ordered using synchronization commands. The access scope for buffer marker writes falls under the VK_ACCESS_TRANSFER_WRITE_BIT, and the pipeline stages for identifying the synchronization scope must include both pipelineStage and VK_PIPELINE_STAGE_TRANSFER_BIT.

Note

Similar to vkCmdWriteTimestamp, if an implementation is unable to write a marker at any specific pipeline stage, it may instead do so at any logically later stage.

Note

Implementations may only support a limited number of pipelined marker write operations in flight at a given time, thus excessive number of marker write operations may degrade command execution performance.

Valid Usage
  • VUID-vkCmdWriteBufferMarkerAMD-pipelineStage-04074
    pipelineStage must be a valid stage for the queue family that was used to create the command pool that commandBuffer was allocated from

  • VUID-vkCmdWriteBufferMarkerAMD-pipelineStage-04075
    If the geometry shaders feature is not enabled, pipelineStage must not be VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT

  • VUID-vkCmdWriteBufferMarkerAMD-pipelineStage-04076
    If the tessellation shaders feature is not enabled, pipelineStage must not be VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT or VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT

  • VUID-vkCmdWriteBufferMarkerAMD-pipelineStage-04077
    If the conditional rendering feature is not enabled, pipelineStage must not be VK_PIPELINE_STAGE_CONDITIONAL_RENDERING_BIT_EXT

  • VUID-vkCmdWriteBufferMarkerAMD-pipelineStage-04078
    If the fragment density map feature is not enabled, pipelineStage must not be VK_PIPELINE_STAGE_FRAGMENT_DENSITY_PROCESS_BIT_EXT

  • VUID-vkCmdWriteBufferMarkerAMD-pipelineStage-04079
    If the transform feedback feature is not enabled, pipelineStage must not be VK_PIPELINE_STAGE_TRANSFORM_FEEDBACK_BIT_EXT

  • VUID-vkCmdWriteBufferMarkerAMD-pipelineStage-04080
    If the mesh shaders feature is not enabled, pipelineStage must not be VK_PIPELINE_STAGE_MESH_SHADER_BIT_NV or VK_PIPELINE_STAGE_TASK_SHADER_BIT_NV

  • VUID-vkCmdWriteBufferMarkerAMD-pipelineStage-04081
    If the shading rate image feature is not enabled, pipelineStage must not be VK_PIPELINE_STAGE_SHADING_RATE_IMAGE_BIT_NV

  • VUID-vkCmdWriteBufferMarkerAMD-dstOffset-01798
    dstOffset must be less than or equal to the size of dstBuffer minus 4

  • VUID-vkCmdWriteBufferMarkerAMD-dstBuffer-01799
    dstBuffer must have been created with VK_BUFFER_USAGE_TRANSFER_DST_BIT usage flag

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

  • VUID-vkCmdWriteBufferMarkerAMD-dstOffset-01801
    dstOffset must be a multiple of 4

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

  • VUID-vkCmdWriteBufferMarkerAMD-pipelineStage-parameter
    pipelineStage must be a valid VkPipelineStageFlagBits value

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

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

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

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

Host Synchronization
  • Host access to commandBuffer must be externally synchronized

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

Command Properties
Command Buffer Levels Render Pass Scope Supported Queue Types Pipeline Type

Primary
Secondary

Both

Transfer
Graphics
Compute

Transfer

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_KHR_copy_commands2
void vkCmdResolveImage2KHR(
    VkCommandBuffer                             commandBuffer,
    const VkResolveImageInfo2KHR*               pResolveImageInfo);
  • commandBuffer is the command buffer into which the command will be recorded.

  • pResolveImageInfo is a pointer to a VkResolveImageInfo2KHR 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-vkCmdResolveImage2KHR-commandBuffer-01837
    If commandBuffer is an unprotected command buffer, then srcImage must not be a protected image

  • VUID-vkCmdResolveImage2KHR-commandBuffer-01838
    If commandBuffer is an unprotected command buffer, then dstImage must not be a protected image

  • VUID-vkCmdResolveImage2KHR-commandBuffer-01839
    If commandBuffer is a protected command buffer, then dstImage must not be an unprotected image

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

  • VUID-vkCmdResolveImage2KHR-pResolveImageInfo-parameter
    pResolveImageInfo must be a valid pointer to a valid VkResolveImageInfo2KHR structure

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

  • VUID-vkCmdResolveImage2KHR-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support graphics operations

  • VUID-vkCmdResolveImage2KHR-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 Pipeline Type

Primary
Secondary

Outside

Graphics

Transfer

The VkResolveImageInfo2KHR structure is defined as:

// Provided by VK_KHR_copy_commands2
typedef struct VkResolveImageInfo2KHR {
    VkStructureType              sType;
    const void*                  pNext;
    VkImage                      srcImage;
    VkImageLayout                srcImageLayout;
    VkImage                      dstImage;
    VkImageLayout                dstImageLayout;
    uint32_t                     regionCount;
    const VkImageResolve2KHR*    pRegions;
} VkResolveImageInfo2KHR;
  • sType is the type of 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 VkImageResolve2KHR structures specifying the regions to resolve.

Valid Usage
  • VUID-VkResolveImageInfo2KHR-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-VkResolveImageInfo2KHR-srcImage-00256
    If srcImage is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-VkResolveImageInfo2KHR-srcImage-00257
    srcImage must have a sample count equal to any valid sample count value other than VK_SAMPLE_COUNT_1_BIT

  • VUID-VkResolveImageInfo2KHR-dstImage-00258
    If dstImage is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-VkResolveImageInfo2KHR-dstImage-00259
    dstImage must have a sample count equal to VK_SAMPLE_COUNT_1_BIT

  • VUID-VkResolveImageInfo2KHR-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-VkResolveImageInfo2KHR-srcImageLayout-01400
    srcImageLayout must be VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR, VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL or VK_IMAGE_LAYOUT_GENERAL

  • VUID-VkResolveImageInfo2KHR-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-VkResolveImageInfo2KHR-dstImageLayout-01401
    dstImageLayout must be VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR, VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL or VK_IMAGE_LAYOUT_GENERAL

  • VUID-VkResolveImageInfo2KHR-dstImage-02003
    The format features of dstImage must contain VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT

  • VUID-VkResolveImageInfo2KHR-srcImage-01386
    srcImage and dstImage must have been created with the same image format

  • VUID-VkResolveImageInfo2KHR-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-VkResolveImageInfo2KHR-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-VkResolveImageInfo2KHR-srcSubresource-01711
    The 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-VkResolveImageInfo2KHR-dstSubresource-01712
    The 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-VkResolveImageInfo2KHR-dstImage-02546
    dstImage and srcImage must not have been created with flags containing VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT

  • VUID-VkResolveImageInfo2KHR-srcImage-04446
    If either srcImage or dstImage are of type VK_IMAGE_TYPE_3D, then for each element of pRegions, srcSubresource.baseArrayLayer must be 0 and srcSubresource.layerCount must be 1

  • VUID-VkResolveImageInfo2KHR-srcImage-04447
    If either srcImage or dstImage are of type VK_IMAGE_TYPE_3D, then for each element of pRegions, dstSubresource.baseArrayLayer must be 0 and dstSubresource.layerCount must be 1

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

Valid Usage (Implicit)
  • VUID-VkResolveImageInfo2KHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_RESOLVE_IMAGE_INFO_2_KHR

  • VUID-VkResolveImageInfo2KHR-pNext-pNext
    pNext must be NULL

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

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

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

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

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

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

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

The VkImageResolve2KHR structure is defined as:

// Provided by VK_KHR_copy_commands2
typedef struct VkImageResolve2KHR {
    VkStructureType             sType;
    const void*                 pNext;
    VkImageSubresourceLayers    srcSubresource;
    VkOffset3D                  srcOffset;
    VkImageSubresourceLayers    dstSubresource;
    VkOffset3D                  dstOffset;
    VkExtent3D                  extent;
} VkImageResolve2KHR;
  • sType is the type of 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-VkImageResolve2KHR-aspectMask-00266
    The aspectMask member of srcSubresource and dstSubresource must only contain VK_IMAGE_ASPECT_COLOR_BIT

  • VUID-VkImageResolve2KHR-layerCount-00267
    The layerCount member of srcSubresource and dstSubresource must match

Valid Usage (Implicit)
  • VUID-VkImageResolve2KHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_IMAGE_RESOLVE_2_KHR

  • VUID-VkImageResolve2KHR-pNext-pNext
    pNext must be NULL

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

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