## C Specification

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

## Parameters

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

## Description

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 either srcImage or dstImage has a multi-planar 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 https://www.khronos.org/registry/vulkan/specs/1.3-extensions/html/vkspec.html#formats-compatible-planes 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 and protectedNoFault is not supported, srcImage must not be a protected image

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

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

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

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

• VUID-vkCmdCopyImage-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-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 srcSubresource.layerCount must be 1

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

For each element of pRegions, srcSubresource.aspectMask must specify aspects present in srcImage

For each element of pRegions, dstSubresource.aspectMask must specify aspects present in dstImage

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Primary
Secondary

Outside

Transfer
Graphics
Compute