VkCopyImageInfo2(3)

# VkCopyImageInfo2(3) Manual Page

## Name

VkCopyImageInfo2 - Structure specifying parameters of an image copy command

Loading… please wait.

## C Specification

The `VkCopyImageInfo2` structure is defined as:

    // Provided by VK_VERSION_1_3
    typedef struct VkCopyImageInfo2 {
        VkStructureType        sType;
        const void*            pNext;
        VkImage                srcImage;
        VkImageLayout          srcImageLayout;
        VkImage                dstImage;
        VkImageLayout          dstImageLayout;
        uint32_t               regionCount;
        const VkImageCopy2*    pRegions;
    } VkCopyImageInfo2;

or the equivalent

    // Provided by VK_KHR_copy_commands2
    typedef VkCopyImageInfo2 VkCopyImageInfo2KHR;

## Members

- `sType` is the type of this structure.

- `pNext` is `NULL` or a pointer to a structure extending this structure.

- `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 VkImageCopy2 structures specifying the regions to copy.

## Description

Valid Usage

- VUID-VkCopyImageInfo2-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-VkCopyImageInfo2-srcImage-01995
  The format features of `srcImage` must contain `VK_FORMAT_FEATURE_TRANSFER_SRC_BIT`

- VUID-VkCopyImageInfo2-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-VkCopyImageInfo2-srcImageLayout-01917
  `srcImageLayout` must be `VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL`, `VK_IMAGE_LAYOUT_GENERAL`, or `VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR`

- VUID-VkCopyImageInfo2-dstImage-01996
  The format features of `dstImage` must contain `VK_FORMAT_FEATURE_TRANSFER_DST_BIT`

- VUID-VkCopyImageInfo2-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-VkCopyImageInfo2-dstImageLayout-01395
  `dstImageLayout` must be `VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL`, `VK_IMAGE_LAYOUT_GENERAL`, or `VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR`

- VUID-VkCopyImageInfo2-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-VkCopyImageInfo2-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-VkCopyImageInfo2-srcImage-00136
  The sample count of `srcImage` and `dstImage` must match

- VUID-VkCopyImageInfo2-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-VkCopyImageInfo2-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-VkCopyImageInfo2-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-VkCopyImageInfo2-srcImage-08713
  If `srcImage` has a multi-planar image format, then for each element of `pRegions`, `srcSubresource.aspectMask` must be a single valid multi-planar aspect mask

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

- VUID-VkCopyImageInfo2-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-VkCopyImageInfo2-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-VkCopyImageInfo2-apiVersion-07932
  If the VK_KHR_maintenance1 extension is not enabled, 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 each be `0`, and `srcSubresource.layerCount` and `dstSubresource.layerCount` must each be `1`

- VUID-VkCopyImageInfo2-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-VkCopyImageInfo2-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-VkCopyImageInfo2-aspectMask-00142
  For each element of `pRegions`, `srcSubresource.aspectMask` must specify aspects present in `srcImage`

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

- VUID-VkCopyImageInfo2-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-VkCopyImageInfo2-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-VkCopyImageInfo2-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-VkCopyImageInfo2-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-VkCopyImageInfo2-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-VkCopyImageInfo2-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-VkCopyImageInfo2-srcImage-01787
  If `srcImage` is of type `VK_IMAGE_TYPE_2D`, then for each element of `pRegions`, `srcOffset.z` must be `0`

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

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

- VUID-VkCopyImageInfo2-srcImage-07743
  If `srcImage` and `dstImage` have a different VkImageType, one must be `VK_IMAGE_TYPE_3D` and the other must be `VK_IMAGE_TYPE_2D`

- VUID-VkCopyImageInfo2-srcImage-07744
  If `srcImage` and `dstImage` have the same VkImageType, the `layerCount` member of `srcSubresource` and `dstSubresource` in each element of `pRegions` must match

- VUID-VkCopyImageInfo2-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-VkCopyImageInfo2-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-VkCopyImageInfo2-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-VkCopyImageInfo2-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-VkCopyImageInfo2-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-VkCopyImageInfo2-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-VkCopyImageInfo2-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-VkCopyImageInfo2-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-VkCopyImageInfo2-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-VkCopyImageInfo2-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-VkCopyImageInfo2-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-VkCopyImageInfo2-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-VkCopyImageInfo2-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-VkCopyImageInfo2-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-VkCopyImageInfo2-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-VkCopyImageInfo2-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-VkCopyImageInfo2-dstImage-01732
  For each element of `pRegions`, if the sum of `dstOffset.x` and `extent.width` does not equal the width of the subresource specified by `dstSubresource`, `extent.width` must be a multiple of the texel block extent width of the VkFormat of `dstImage`

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

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

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

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

- VUID-VkCopyImageInfo2-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-VkCopyImageInfo2-srcSubresource-07968
  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-VkCopyImageInfo2-srcImage-07969
  `srcImage` must not have been created with `flags` containing `VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT`

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

- VUID-VkCopyImageInfo2-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-VkCopyImageInfo2-dstSubresource-07968
  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-VkCopyImageInfo2-dstImage-07969
  `dstImage` must not have been created with `flags` containing `VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT`

Valid Usage (Implicit)

- VUID-VkCopyImageInfo2-sType-sType
  `sType` must be `VK_STRUCTURE_TYPE_COPY_IMAGE_INFO_2`

- VUID-VkCopyImageInfo2-pNext-pNext
  `pNext` must be `NULL`

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

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

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

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

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

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

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

## See Also

VK_KHR_copy_commands2, VK_VERSION_1_3, VkImage, VkImageCopy2, VkImageLayout, VkStructureType, vkCmdCopyImage2, vkCmdCopyImage2KHR

## 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-2023 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0