VkImageCopy(3)

# VkImageCopy(3) Manual Page

## Name

VkImageCopy - Structure specifying an image copy operation

Loading... please wait.

## C Specification

The `VkImageCopy` structure is defined as:

    typedef struct VkImageCopy {
        VkImageSubresourceLayers    srcSubresource;
        VkOffset3D                  srcOffset;
        VkImageSubresourceLayers    dstSubresource;
        VkOffset3D                  dstOffset;
        VkExtent3D                  extent;
    } VkImageCopy;

## Members

- `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 image to copy in `width`, `height` and `depth`.

## Description

For `VK_IMAGE_TYPE_3D` images, copies are performed slice by slice starting with the `z` member of the `srcOffset` or `dstOffset`, and copying `depth` slices. For images with multiple layers, copies are performed layer by layer starting with the `baseArrayLayer` member of the `srcSubresource` or `dstSubresource` and copying `layerCount` layers. 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.

Copies involving a multi-planar image format specify the region to be copied in terms of the plane to be copied, not the coordinates of the multi-planar image. This means that copies accessing the R/B planes of “`_422`” format images must fit the copied region within half the `width` of the parent image, and that copies accessing the R/B planes of “`_420`” format images must fit the copied region within half the `width` and `height` of the parent image.

Valid Usage

- If neither the calling command’s `srcImage` nor the calling command’s `dstImage` has a multi-planar image format then the `aspectMask` member of `srcSubresource` and `dstSubresource` must match

- If the calling command’s `srcImage` has a VkFormat with two planes then the `srcSubresource` `aspectMask` must be `VK_IMAGE_ASPECT_PLANE_0_BIT` or `VK_IMAGE_ASPECT_PLANE_1_BIT`

- If the calling command’s `srcImage` has a VkFormat with three planes then the `srcSubresource` `aspectMask` must be `VK_IMAGE_ASPECT_PLANE_0_BIT`, `VK_IMAGE_ASPECT_PLANE_1_BIT`, or `VK_IMAGE_ASPECT_PLANE_2_BIT`

- If the calling command’s `dstImage` has a VkFormat with two planes then the `dstSubresource` `aspectMask` must be `VK_IMAGE_ASPECT_PLANE_0_BIT` or `VK_IMAGE_ASPECT_PLANE_1_BIT`

- If the calling command’s `dstImage` has a VkFormat with three planes then the `dstSubresource` `aspectMask` must be `VK_IMAGE_ASPECT_PLANE_0_BIT`, `VK_IMAGE_ASPECT_PLANE_1_BIT`, or `VK_IMAGE_ASPECT_PLANE_2_BIT`

- If the calling command’s `srcImage` has a multi-planar image format and the `dstImage` does not have a multi-planar image format, the `dstSubresource` `aspectMask` must be `VK_IMAGE_ASPECT_COLOR_BIT`

- If the calling command’s `dstImage` has a multi-planar image format and the `srcImage` does not have a multi-planar image format, the `srcSubresource` `aspectMask` must be `VK_IMAGE_ASPECT_COLOR_BIT`

- The number of slices of the `extent` (for 3D) or layers of the `srcSubresource` (for non-3D) must match the number of slices of the `extent` (for 3D) or layers of the `dstSubresource` (for non-3D)

- If either of the calling command’s `srcImage` or `dstImage` parameters are of VkImageType `VK_IMAGE_TYPE_3D`, the `baseArrayLayer` and `layerCount` members of the corresponding subresource must be `0` and `1`, respectively

- The `aspectMask` member of `srcSubresource` must specify aspects present in the calling command’s `srcImage`

- The `aspectMask` member of `dstSubresource` must specify aspects present in the calling command’s `dstImage`

- `srcOffset.x` and (`extent.width` + `srcOffset.x`) must both be greater than or equal to `0` and less than or equal to the source image subresource width

- `srcOffset.y` and (`extent.height` + `srcOffset.y`) must both be greater than or equal to `0` and less than or equal to the source image subresource height

- If the calling command’s `srcImage` is of type `VK_IMAGE_TYPE_1D`, then `srcOffset.y` must be `0` and `extent.height` must be `1`

- `srcOffset.z` and (`extent.depth` + `srcOffset.z`) must both be greater than or equal to `0` and less than or equal to the source image subresource depth

- If the calling command’s `srcImage` is of type `VK_IMAGE_TYPE_1D`, then `srcOffset.z` must be `0` and `extent.depth` must be `1`

- If the calling command’s `dstImage` is of type `VK_IMAGE_TYPE_1D`, then `dstOffset.z` must be `0` and `extent.depth` must be `1`

- If the calling command’s `srcImage` is of type `VK_IMAGE_TYPE_2D`, then `srcOffset.z` must be `0`

- If the calling command’s `dstImage` is of type `VK_IMAGE_TYPE_2D`, then `dstOffset.z` must be `0`

- If both `srcImage` and `dstImage` are of type `VK_IMAGE_TYPE_2D` then `extent.depth` must be `1`

- If the calling command’s `srcImage` is of type `VK_IMAGE_TYPE_2D`, and the `dstImage` is of type `VK_IMAGE_TYPE_3D`, then `extent.depth` must equal to the `layerCount` member of `srcSubresource`

- If the calling command’s `dstImage` is of type `VK_IMAGE_TYPE_2D`, and the `srcImage` is of type `VK_IMAGE_TYPE_3D`, then `extent.depth` must equal to the `layerCount` member of `dstSubresource`

- `dstOffset.x` and (`extent.width` + `dstOffset.x`) must both be greater than or equal to `0` and less than or equal to the destination image subresource width

- `dstOffset.y` and (`extent.height` + `dstOffset.y`) must both be greater than or equal to `0` and less than or equal to the destination image subresource height

- If the calling command’s `dstImage` is of type `VK_IMAGE_TYPE_1D`, then `dstOffset.y` must be `0` and `extent.height` must be `1`

- `dstOffset.z` and (`extent.depth` + `dstOffset.z`) must both be greater than or equal to `0` and less than or equal to the destination image subresource depth

- If the calling command’s `srcImage` is a compressed image, or a single-plane, “`_422`” image format, all members of `srcOffset` must be a multiple of the corresponding dimensions of the compressed texel block

- If the calling command’s `srcImage` is a compressed image, or a single-plane, “`_422`” image format, `extent.width` must be a multiple of the compressed texel block width or (`extent.width` + `srcOffset.x`) must equal the source image subresource width

- If the calling command’s `srcImage` is a compressed image, or a single-plane, “`_422`” image format, `extent.height` must be a multiple of the compressed texel block height or (`extent.height` + `srcOffset.y`) must equal the source image subresource height

- If the calling command’s `srcImage` is a compressed image, or a single-plane, “`_422`” image format, `extent.depth` must be a multiple of the compressed texel block depth or (`extent.depth` + `srcOffset.z`) must equal the source image subresource depth

- If the calling command’s `dstImage` is a compressed format image, or a single-plane, “`_422`” image format, all members of `dstOffset` must be a multiple of the corresponding dimensions of the compressed texel block

- If the calling command’s `dstImage` is a compressed format image, or a single-plane, “`_422`” image format, `extent.width` must be a multiple of the compressed texel block width or (`extent.width` + `dstOffset.x`) must equal the destination image subresource width

- If the calling command’s `dstImage` is a compressed format image, or a single-plane, “`_422`” image format, `extent.height` must be a multiple of the compressed texel block height or (`extent.height` + `dstOffset.y`) must equal the destination image subresource height

- If the calling command’s `dstImage` is a compressed format image, or a single-plane, “`_422`” image format, `extent.depth` must be a multiple of the compressed texel block depth or (`extent.depth` + `dstOffset.z`) must equal the destination image subresource depth

Valid Usage (Implicit)

- `srcSubresource` must be a valid VkImageSubresourceLayers structure

- `dstSubresource` must be a valid VkImageSubresourceLayers structure

## See Also

VkExtent3D, VkImageSubresourceLayers, VkOffset3D, vkCmdCopyImage

## 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 Khronos Group. This work is licensed under a Creative Commons Attribution 4.0 International License.