vkCmdCopyImage(3)

Name

vkCmdCopyImage - Copy data between images

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 source region specified by pRegions is copied from the source image to the destination region of the destination image. If any of the specified regions in srcImage overlaps in memory with any of the specified regions in dstImage, values read from those overlapping regions are undefined. If any region accesses a depth aspect in dstImage and the VK_EXT_depth_range_unrestricted extension is not enabled, values copied from srcBuffer outside of the range [0,1] will be written as undefined values to the destination image.

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

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

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

Valid Usage

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  • VUID-vkCmdCopyImage-pRegions-12201
    For each element of pRegions where srcSubresource.aspectMask and dstSubresource.aspectMask each contain at least one of VK_IMAGE_ASPECT_DEPTH_BIT or VK_IMAGE_ASPECT_STENCIL_BIT, srcSubresource.aspectMask and dstSubresource.aspectMask must match

  • VUID-vkCmdCopyImage-srcSubresource-10214
    If srcSubresource.aspectMask is VK_IMAGE_ASPECT_COLOR_BIT, then dstSubresource.aspectMask must not contain both VK_IMAGE_ASPECT_DEPTH_BIT and VK_IMAGE_ASPECT_STENCIL_BIT

  • VUID-vkCmdCopyImage-dstSubresource-10215
    If dstSubresource.aspectMask is VK_IMAGE_ASPECT_COLOR_BIT, then srcSubresource.aspectMask must not contain both VK_IMAGE_ASPECT_DEPTH_BIT and VK_IMAGE_ASPECT_STENCIL_BIT

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

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

  • VUID-vkCmdCopyImage-srcImage-01556
    If srcImage has a multi-planar 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 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-srcSubresource-10211
    If srcSubresource.aspectMask is VK_IMAGE_ASPECT_COLOR_BIT and dstSubresource.aspectMask is VK_IMAGE_ASPECT_DEPTH_BIT or VK_IMAGE_ASPECT_STENCIL_BIT, then the VkFormat values of srcImage and dstImage must be compatible according to the list of compatible depth-stencil and color formats

  • VUID-vkCmdCopyImage-srcSubresource-10212
    If srcSubresource.aspectMask is VK_IMAGE_ASPECT_DEPTH_BIT or VK_IMAGE_ASPECT_STENCIL_BIT and dstSubresource.aspectMask is VK_IMAGE_ASPECT_COLOR_BIT, then the VkFormat values of srcImage and dstImage must be compatible according to the list of compatible depth-stencil and color formats

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

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

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

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

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

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

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

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

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

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

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

  • VUID-vkCmdCopyImage-srcImage-10907
    If either the VkFormat of each of srcImage and dstImage is not a compressed image format, and dstImage is of type VK_IMAGE_TYPE_1D, then for each element of pRegions, extent.depth must be 1

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

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

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

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

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

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

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

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

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

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

  • VUID-vkCmdCopyImage-dstOffset-00150
    For each element of pRegions, dstOffset.x and (extent.width + dstOffset.x), where extent is adjusted for size-compatibility, 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), where extent is adjusted for size-compatibility, 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

  • VUID-vkCmdCopyImage-srcImage-10908
    If either the VkFormat of each of srcImage and dstImage is not a compressed image format, and dstImage is of type VK_IMAGE_TYPE_1D, then for each element of pRegions, extent.height must be 1, where extent is adjusted for size-compatibility

  • 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), where extent is adjusted for size-compatibility, must both be greater than or equal to 0 and less than or equal to the depth of the specified dstSubresource of dstImage

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

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

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

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

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

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

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

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

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

  • VUID-vkCmdCopyImage-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, srcImage must have been created with the VK_IMAGE_USAGE_TRANSFER_SRC_BIT usage flag set

  • 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, dstImage must have been created with the VK_IMAGE_USAGE_TRANSFER_DST_BIT usage flag set

  • 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, srcImage must have been created with the VK_IMAGE_USAGE_TRANSFER_SRC_BIT usage flag set

  • 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, srcImage must have been created with the VK_IMAGE_USAGE_TRANSFER_DST_BIT usage flag set

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

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

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

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

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

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

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

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

Valid Usage (Implicit)

  • VUID-vkCmdCopyImage-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

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

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

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

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

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

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

  • VUID-vkCmdCopyImage-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support VK_QUEUE_COMPUTE_BIT, VK_QUEUE_GRAPHICS_BIT, or VK_QUEUE_TRANSFER_BIT operations

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

  • VUID-vkCmdCopyImage-suspended
    This command must not be called between suspended render pass instances

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

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

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

Host Synchronization

  • Host access to commandBuffer must be externally synchronized

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

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

Primary
Secondary

Outside

Outside

VK_QUEUE_COMPUTE_BIT
VK_QUEUE_GRAPHICS_BIT
VK_QUEUE_TRANSFER_BIT

Action
Conditional Rendering

vkCmdCopyImage is not affected by conditional rendering

See Also

VK_VERSION_1_0, VkCommandBuffer, VkImage, VkImageCopy, VkImageLayout

Document Notes

For more information, see the Vulkan Specification.

This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.