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

    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.

Copies are done layer by layer starting with `baseArrayLayer` member of `srcSubresource` for the source and `dstSubresource` for the destination. `layerCount` layers are copied to the destination image.

The formats of `srcImage` and `dstImage` must be compatible. Formats are considered compatible if their texel size in bytes is the same between both formats. For example, `VK_FORMAT_R8G8B8A8_UNORM` is compatible with `VK_FORMAT_R32_UINT` because both texels are 4 bytes in size. Depth/stencil formats must match exactly.

`vkCmdCopyImage` allows copying between size-compatible compressed and uncompressed internal formats. Formats are size-compatible if the texel size of the uncompressed format is equal to the compressed texel block size in bytes 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 4x4 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 4x4 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. 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 and 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 and 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 and 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 and 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.

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

The `VkImageCopy` structure is defined as:

    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 source image to copy in `width`, `height` and `depth`. 1D images use only `x` and `width`. 2D images use `x`, `y`, `width` and `height`. 3D images use `x`, `y`, `z`, `width`, `height` and `depth`.

The `VkImageSubresourceLayers` structure is defined as:

    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.