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 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 https://www.khronos.org/registry/vulkan/specs/1.2-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

- If `commandBuffer` is an unprotected command buffer, then `srcImage` must not be a protected image

- If `commandBuffer` is an unprotected command buffer, then `dstImage` must not be a protected image

- If `commandBuffer` is a protected command buffer, then `dstImage` must not be an unprotected image

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

- The format features of `srcImage` must contain `VK_FORMAT_FEATURE_TRANSFER_SRC_BIT`

- `srcImage` must have been created with `VK_IMAGE_USAGE_TRANSFER_SRC_BIT` usage flag

- 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

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

- `srcImageLayout` must be `VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL`, `VK_IMAGE_LAYOUT_GENERAL`, or `VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR`

- The format features of `dstImage` must contain `VK_FORMAT_FEATURE_TRANSFER_DST_BIT`

- `dstImage` must have been created with `VK_IMAGE_USAGE_TRANSFER_DST_BIT` usage flag

- 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

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

- `dstImageLayout` must be `VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL`, `VK_IMAGE_LAYOUT_GENERAL`, or `VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR`

- 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

- 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

- The sample count of `srcImage` and `dstImage` must match

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

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

- 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

- 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

- 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

- 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

- `dstImage` and `srcImage` must not have been created with `flags` containing `VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT`

- If neither `srcImage` nor `dstImage` has a multi-planar image format then for each element of `pRegions`, `srcSubresource.aspectMask` and `dstSubresource.aspectMask` must match

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

- 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

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

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

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

- 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

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

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

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

- `commandBuffer` must be a valid VkCommandBuffer handle

- `srcImage` must be a valid VkImage handle

- `srcImageLayout` must be a valid VkImageLayout value

- `dstImage` must be a valid VkImage handle

- `dstImageLayout` must be a valid VkImageLayout value

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

- `commandBuffer` must be in the recording state

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

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

- `regionCount` must be greater than `0`

- 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

## See Also

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 (c) 2014-2020 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0