vkCmdCopyImage(3)

# vkCmdCopyImage(3) Manual Page

## Name

vkCmdCopyImage - Copy data between images

Loading… please wait.

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

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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

- VUID-vkCmdCopyImage-srcImage-01728
  For each element of `pRegions`, if the sum of `srcOffset.x` and `extent.width` does not equal the width of the 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 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 the subresource specified by `srcSubresource`, `extent.depth` must be a multiple of the texel block extent depth of the VkFormat of `srcImage`

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

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

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

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

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

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

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

Valid Usage (Implicit)

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

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

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

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

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

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

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

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

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

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

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

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

Host Synchronization

- Host access to `commandBuffer` must be externally synchronized

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

Command Properties

Command Buffer Levels | Render Pass Scope | Video Coding Scope | Supported Queue Types | Command Type
--- | --- | --- | --- | ---
Primary Secondary | Outside | Outside | Transfer Graphics Compute | Action

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

## Copyright

Copyright 2014-2022 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0