xref: /third_party/vk-gl-cts/external/vulkan-docs/src/chapters/copies.adoc

// Copyright 2015-2024 The Khronos Group Inc.
//
// SPDX-License-Identifier: CC-BY-4.0

[[copies]]
= Copy Commands

An application can: copy buffer and image data using several methods
described in this chapter, depending on the type of data transfer.

All copy commands are treated as "`transfer`" operations for the purposes of
synchronization barriers.

All copy commands that have a source format with an X component in its
format description read undefined: values from those bits.

All copy commands that have a destination format with an X component in its
format description write undefined: values to those bits.


[[copies-buffers]]
== Copying Data Between Buffers

[open,refpage='vkCmdCopyBuffer',desc='Copy data between buffer regions',type='protos']
--
:refpage: vkCmdCopyBuffer

To copy data between buffer objects, call:

include::{generated}/api/protos/vkCmdCopyBuffer.adoc[]

  * pname:commandBuffer is the command buffer into which the command will be
    recorded.
  * pname:srcBuffer is the source buffer.
  * pname:dstBuffer is the destination buffer.
  * pname:regionCount is the number of regions to copy.
  * pname:pRegions is a pointer to an array of slink:VkBufferCopy structures
    specifying the regions to copy.

Each source region specified by pname:pRegions is copied from the source
buffer to the destination region of the destination buffer.
If any of the specified regions in pname:srcBuffer overlaps in memory with
any of the specified regions in pname:dstBuffer, values read from those
overlapping regions are undefined:.

.Valid Usage
****
include::{chapters}/commonvalidity/copy_buffer_command_buffer_common.adoc[]
include::{chapters}/commonvalidity/copy_buffer_common.adoc[]
****

include::{generated}/validity/protos/vkCmdCopyBuffer.adoc[]
--

[open,refpage='VkBufferCopy',desc='Structure specifying a buffer copy operation',type='structs']
--
:refpage: VkBufferCopy

The sname:VkBufferCopy structure is defined as:

include::{generated}/api/structs/VkBufferCopy.adoc[]

  * pname:srcOffset is the starting offset in bytes from the start of
    pname:srcBuffer.
  * pname:dstOffset is the starting offset in bytes from the start of
    pname:dstBuffer.
  * pname:size is the number of bytes to copy.

.Valid Usage
****
include::{chapters}/commonvalidity/buffer_copy_common.adoc[]
****

include::{generated}/validity/structs/VkBufferCopy.adoc[]
--

ifdef::VK_VERSION_1_3,VK_KHR_copy_commands2[]
A more extensible version of the copy buffer command is defined below.

[open,refpage='vkCmdCopyBuffer2',desc='Copy data between buffer regions',type='protos',alias='vkCmdCopyBuffer2KHR']
--
:refpage: vkCmdCopyBuffer2

To copy data between buffer objects, call:

ifdef::VK_VERSION_1_3[]
include::{generated}/api/protos/vkCmdCopyBuffer2.adoc[]
endif::VK_VERSION_1_3[]

ifdef::VK_VERSION_1_3+VK_KHR_copy_commands2[or the equivalent command]

ifdef::VK_KHR_copy_commands2[]
include::{generated}/api/protos/vkCmdCopyBuffer2KHR.adoc[]
endif::VK_KHR_copy_commands2[]

  * pname:commandBuffer is the command buffer into which the command will be
    recorded.
  * pname:pCopyBufferInfo is a pointer to a slink:VkCopyBufferInfo2
    structure describing the copy parameters.

Each source region specified by pname:pCopyBufferInfo->pRegions is copied
from the source buffer to the destination region of the destination buffer.
If any of the specified regions in pname:pCopyBufferInfo->srcBuffer overlaps
in memory with any of the specified regions in
pname:pCopyBufferInfo->dstBuffer, values read from those overlapping regions
are undefined:.

.Valid Usage
****
include::{chapters}/commonvalidity/copy_buffer_command_buffer_common.adoc[]
****

include::{generated}/validity/protos/vkCmdCopyBuffer2.adoc[]
--

[open,refpage='VkCopyBufferInfo2',desc='Structure specifying parameters of a buffer copy command',type='structs',alias='VkCopyBufferInfo2KHR']
--
:refpage: VkCopyBufferInfo2

The sname:VkCopyBufferInfo2 structure is defined as:

include::{generated}/api/structs/VkCopyBufferInfo2.adoc[]

ifdef::VK_KHR_copy_commands2[]
or the equivalent

include::{generated}/api/structs/VkCopyBufferInfo2KHR.adoc[]
endif::VK_KHR_copy_commands2[]

  * pname:sType is a elink:VkStructureType value identifying this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:srcBuffer is the source buffer.
  * pname:dstBuffer is the destination buffer.
  * pname:regionCount is the number of regions to copy.
  * pname:pRegions is a pointer to an array of slink:VkBufferCopy2
    structures specifying the regions to copy.

.Valid Usage
****
include::{chapters}/commonvalidity/copy_buffer_common.adoc[]
****

include::{generated}/validity/structs/VkCopyBufferInfo2.adoc[]
--

[open,refpage='VkBufferCopy2',desc='Structure specifying a buffer copy operation',type='structs',alias='VkBufferCopy2KHR']
--
:refpage: VkBufferCopy2

The sname:VkBufferCopy2 structure is defined as:

include::{generated}/api/structs/VkBufferCopy2.adoc[]

ifdef::VK_KHR_copy_commands2[]
or the equivalent

include::{generated}/api/structs/VkBufferCopy2KHR.adoc[]
endif::VK_KHR_copy_commands2[]

  * pname:sType is a elink:VkStructureType value identifying this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:srcOffset is the starting offset in bytes from the start of
    pname:srcBuffer.
  * pname:dstOffset is the starting offset in bytes from the start of
    pname:dstBuffer.
  * pname:size is the number of bytes to copy.

.Valid Usage
****
include::{chapters}/commonvalidity/buffer_copy_common.adoc[]
****

include::{generated}/validity/structs/VkBufferCopy2.adoc[]
--
endif::VK_VERSION_1_3,VK_KHR_copy_commands2[]


[[copies-images]]
== Copying Data Between Images

[open,refpage='vkCmdCopyImage',desc='Copy data between images',type='protos']
--
:refpage: vkCmdCopyImage

To copy data between image objects, call:

include::{generated}/api/protos/vkCmdCopyImage.adoc[]

  * pname:commandBuffer is the command buffer into which the command will be
    recorded.
  * pname:srcImage is the source image.
  * pname:srcImageLayout is the current layout of the source image
    subresource.
  * pname:dstImage is the destination image.
  * pname:dstImageLayout is the current layout of the destination image
    subresource.
  * pname:regionCount is the number of regions to copy.
  * pname:pRegions is a pointer to an array of slink:VkImageCopy structures
    specifying the regions to copy.

Each source region specified by pname:pRegions is copied from the source
image to the destination region of the destination image.
If any of the specified regions in pname:srcImage overlaps in memory with
any of the specified regions in pname:dstImage, values read from those
overlapping regions are undefined:.

ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
<<formats-requiring-sampler-ycbcr-conversion, 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
<<formats-compatible-planes, compatible format for that plane>>, rather than
the format of the multi-planar image.
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]

If the format of the destination image has a different
<<formats-compatibility-classes,block extent>> than the source image (e.g.
one is a compressed format), the offset and extent for each of the regions
specified is <<formats-size-compatibility, 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.

ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[]
Image data can: be copied between images with different image types.
If one image is ename:VK_IMAGE_TYPE_3D and the other image is
ename:VK_IMAGE_TYPE_2D with multiple layers, then each slice is copied to or
from a different layer; pname:depth slices in the 3D image correspond to
pname:layerCount layers in the 2D image, with an effective pname:depth of
`1` used for the 2D image.
ifndef::VK_KHR_maintenance5[]
Other combinations of image types are disallowed.
endif::VK_KHR_maintenance5[]
ifdef::VK_KHR_maintenance5[]
If <<features-maintenance5,pname:maintenance5>> is enabled, all other
combinations are allowed and function as if 1D images are 2D images with a
height of 1.
Otherwise, other combinations of image types are disallowed.
endif::VK_KHR_maintenance5[]
endif::VK_VERSION_1_1,VK_KHR_maintenance1[]

.Valid Usage
****
include::{chapters}/commonvalidity/copy_image_command_buffer_common.adoc[]
include::{chapters}/commonvalidity/copy_image_common.adoc[]

:imageparam: srcImage
:imagesubresource: srcSubresource
include::{chapters}/commonvalidity/copy_anyimage_to_imageany_common.adoc[]

:imageparam: dstImage
:imagesubresource: dstSubresource
include::{chapters}/commonvalidity/copy_anyimage_to_imageany_common.adoc[]
****

include::{generated}/validity/protos/vkCmdCopyImage.adoc[]
--

[open,refpage='VkImageCopy',desc='Structure specifying an image copy operation',type='structs']
--
:refpage: VkImageCopy

The sname:VkImageCopy structure is defined as:

include::{generated}/api/structs/VkImageCopy.adoc[]

  * pname:srcSubresource and pname:dstSubresource are
    slink:VkImageSubresourceLayers structures specifying the image
    subresources of the images used for the source and destination image
    data, respectively.
  * pname:srcOffset and pname:dstOffset select the initial pname:x, pname:y,
    and pname:z offsets in texels of the sub-regions of the source and
    destination image data.
  * pname:extent is the size in texels of the image to copy in pname:width,
    pname:height and pname:depth.

.Valid Usage
****
include::{chapters}/commonvalidity/image_copy_common.adoc[]
****

include::{generated}/validity/structs/VkImageCopy.adoc[]
--

[open,refpage='VkImageSubresourceLayers',desc='Structure specifying an image subresource layers',type='structs']
--
The sname:VkImageSubresourceLayers structure is defined as:

include::{generated}/api/structs/VkImageSubresourceLayers.adoc[]

  * pname:aspectMask is a combination of elink:VkImageAspectFlagBits,
    selecting the color, depth and/or stencil aspects to be copied.
  * pname:mipLevel is the mipmap level to copy
  * pname:baseArrayLayer and pname:layerCount are the starting layer and
    number of layers to copy.

.Valid Usage
****
  * [[VUID-VkImageSubresourceLayers-aspectMask-00167]]
    If pname:aspectMask contains ename:VK_IMAGE_ASPECT_COLOR_BIT, it must:
    not contain either of ename:VK_IMAGE_ASPECT_DEPTH_BIT or
    ename:VK_IMAGE_ASPECT_STENCIL_BIT
  * [[VUID-VkImageSubresourceLayers-aspectMask-00168]]
    pname:aspectMask must: not contain ename:VK_IMAGE_ASPECT_METADATA_BIT
ifdef::VK_EXT_image_drm_format_modifier[]
  * [[VUID-VkImageSubresourceLayers-aspectMask-02247]]
    pname:aspectMask must: not include
    `VK_IMAGE_ASPECT_MEMORY_PLANE__{ibit}__BIT_EXT` for any index _i_
endif::VK_EXT_image_drm_format_modifier[]
  * [[VUID-VkImageSubresourceLayers-layerCount-09243]]
    {empty}
ifdef::VK_KHR_maintenance5[]
    If the <<features-maintenance5, pname:maintenance5>> feature is not
    enabled,
endif::VK_KHR_maintenance5[]
    pname:layerCount must: not be ename:VK_REMAINING_ARRAY_LAYERS
  * [[VUID-VkImageSubresourceLayers-layerCount-01700]]
    If pname:layerCount is not ename:VK_REMAINING_ARRAY_LAYERS, it must: be
    greater than 0
****

include::{generated}/validity/structs/VkImageSubresourceLayers.adoc[]
--

ifdef::VK_VERSION_1_3,VK_KHR_copy_commands2[]
A more extensible version of the copy image command is defined below.

[open,refpage='vkCmdCopyImage2',desc='Copy data between images',type='protos',alias='vkCmdCopyImage2KHR']
--
:refpage: vkCmdCopyImage2

To copy data between image objects, call:

ifdef::VK_VERSION_1_3[]
include::{generated}/api/protos/vkCmdCopyImage2.adoc[]
endif::VK_VERSION_1_3[]

ifdef::VK_VERSION_1_3+VK_KHR_copy_commands2[or the equivalent command]

ifdef::VK_KHR_copy_commands2[]
include::{generated}/api/protos/vkCmdCopyImage2KHR.adoc[]
endif::VK_KHR_copy_commands2[]

  * pname:commandBuffer is the command buffer into which the command will be
    recorded.
  * pname:pCopyImageInfo is a pointer to a slink:VkCopyImageInfo2 structure
    describing the copy parameters.

This command is functionally identical to flink:vkCmdCopyImage, but includes
extensible sub-structures that include pname:sType and pname:pNext
parameters, allowing them to be more easily extended.

.Valid Usage
****
include::{chapters}/commonvalidity/copy_image_command_buffer_common.adoc[]
****

include::{generated}/validity/protos/vkCmdCopyImage2.adoc[]
--


[open,refpage='VkCopyImageInfo2',desc='Structure specifying parameters of an image copy command',type='structs',alias='VkCopyImageInfo2KHR']
--
:refpage: VkCopyImageInfo2

The sname:VkCopyImageInfo2 structure is defined as:

include::{generated}/api/structs/VkCopyImageInfo2.adoc[]

ifdef::VK_KHR_copy_commands2[]
or the equivalent

include::{generated}/api/structs/VkCopyImageInfo2KHR.adoc[]
endif::VK_KHR_copy_commands2[]

  * pname:sType is a elink:VkStructureType value identifying this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:srcImage is the source image.
  * pname:srcImageLayout is the current layout of the source image
    subresource.
  * pname:dstImage is the destination image.
  * pname:dstImageLayout is the current layout of the destination image
    subresource.
  * pname:regionCount is the number of regions to copy.
  * pname:pRegions is a pointer to an array of slink:VkImageCopy2 structures
    specifying the regions to copy.


.Valid Usage
****
include::{chapters}/commonvalidity/copy_image_common.adoc[]

:imageparam: srcImage
:imagesubresource: srcSubresource
include::{chapters}/commonvalidity/copy_anyimage_to_imageany_common.adoc[]

:imageparam: dstImage
:imagesubresource: dstSubresource
include::{chapters}/commonvalidity/copy_anyimage_to_imageany_common.adoc[]
****

include::{generated}/validity/structs/VkCopyImageInfo2.adoc[]
--

[open,refpage='VkImageCopy2',desc='Structure specifying an image copy operation',type='structs',alias='VkImageCopy2KHR']
--
:refpage: VkImageCopy2

The sname:VkImageCopy2 structure is defined as:

include::{generated}/api/structs/VkImageCopy2.adoc[]

ifdef::VK_KHR_copy_commands2[]
or the equivalent

include::{generated}/api/structs/VkImageCopy2KHR.adoc[]
endif::VK_KHR_copy_commands2[]

  * pname:sType is a elink:VkStructureType value identifying this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:srcSubresource and pname:dstSubresource are
    slink:VkImageSubresourceLayers structures specifying the image
    subresources of the images used for the source and destination image
    data, respectively.
  * pname:srcOffset and pname:dstOffset select the initial pname:x, pname:y,
    and pname:z offsets in texels of the sub-regions of the source and
    destination image data.
  * pname:extent is the size in texels of the image to copy in pname:width,
    pname:height and pname:depth.

.Valid Usage
****
include::{chapters}/commonvalidity/image_copy_common.adoc[]
****

include::{generated}/validity/structs/VkImageCopy2.adoc[]
--
endif::VK_VERSION_1_3,VK_KHR_copy_commands2[]


[[copies-buffers-images]]
== Copying Data Between Buffers and Images

Data can: be copied between buffers and images, enabling applications to
load and store data between images and user defined offsets in buffer
memory.

[[copies-buffers-images-addressing]]
When copying between a buffer and an image, whole texel blocks are always
copied; each texel block in the specified extent in the image to be copied
will be written to a region in the buffer, specified according to the
position of the texel block, and the <<formats-compatibility-classes,texel
block extent>> and size of the format being copied.

For a set of coordinates [eq]#(x,y,z,layer)#, where:

  {empty}:: [eq]#x# is in the range [eq]#[pname:imageOffset.x / blockWidth,
            {lceil}(pname:imageOffset.x {plus} pname:imageExtent.width) /
            blockWidth{rceil})#,
  {empty}:: [eq]#y# is in the range [eq]#[pname:imageOffset.y / blockHeight,
            {lceil}(pname:imageOffset.y {plus} pname:imageExtent.height) /
            blockHeight{rceil})#,
  {empty}:: [eq]#z# is in the range [eq]#[pname:imageOffset.z / blockDepth,
            {lceil}(pname:imageOffset.z {plus} pname:imageExtent.depth) /
            blockDepth{rceil})#,
  {empty}:: [eq]#layer# is in the range
            [pname:imageSubresource.baseArrayLayer,
            pname:imageSubresource.baseArrayLayer {plus}
            pname:imageSubresource.layerCount),

and where [eq]#blockWidth#, [eq]#blockHeight#, and [eq]#blockDepth# are the
dimensions of the <<formats-compatibility-classes,texel block extent>> of
the image's format.

For each [eq]#(x,y,z,layer)# coordinate, texels in the image layer selected
by [eq]#layer# are accessed in the following ranges:

  {empty}:: [eq]#[x {times} blockWidth, max( (x {times} blockWidth) {plus}
            blockWidth, imageWidth) )#
  {empty}:: [eq]#[y {times} blockHeight, max( (y {times} blockHeight) {plus}
            blockHeight, imageHeight) )#
  {empty}:: [eq]#[z {times} blockDepth, max( (z {times} blockDepth) {plus}
            blockDepth, imageDepth) )#

where [eq]#imageWidth#, [eq]#imageHeight#, and [eq]#imageDepth# are the
dimensions of the image subresource.

For each [eq]#(x,y,z,layer)# coordinate, bytes in the buffer are accessed at
offsets in the range [eq]#[texelOffset, texelOffset {plus} blockSize)#,
where:

  {empty}:: [eq]#texelOffset = pname:bufferOffset {plus} (x {times}
            blockSize) {plus} (y {times} rowExtent) {plus} (z {times}
            sliceExtent) + (layer {times} layerExtent)#
  {empty}:: [eq]#blockSize# is the size of the block in bytes for the format
  {empty}:: [eq]#rowExtent = max(pname:bufferRowLength,
            {lceil}pname:imageExtent.width / blockWidth{rceil} {times}
            blockSize)#
  {empty}:: [eq]#sliceExtent = max(pname:bufferImageHeight,
            pname:imageExtent.height {times} rowExtent)#
  {empty}:: [eq]#layerExtent = pname:imageExtent.depth {times} sliceExtent#

ifdef::VK_QCOM_rotated_copy_commands[]
[[copies-buffers-images-rotation-addressing]]
If a rotation is specified by slink:VkCopyCommandTransformInfoQCOM, the 2D
region of the image being addressed is rotated around the offset, modifying
the range of [eq]#x# and [eq]#y# coordinates for the image address according
to the specified elink:VkSurfaceTransformFlagBitsKHR:

  * If ename:VK_SURFACE_TRANSFORM_IDENTITY_BIT_KHR is specified, no rotation
    is performed:
      {empty}:: [eq]#x'# is in the same range as [eq]#x#
      {empty}:: [eq]#y'# is in the same range as [eq]#y#
      {empty}:: [eq]#blockWidth' = blockWidth#
      {empty}:: [eq]#blockHeight' = blockHeight#
      {empty}:: [eq]#imageWidth' = imageWidth#
      {empty}:: [eq]#imageHeight' = imageHeight#
  * If ename:VK_SURFACE_TRANSFORM_ROTATE_90_BIT_KHR is specified
      {empty}:: [eq]#x'# is in the range [eq]#[{lceil}(pname:imageOffset.x
                {minus} pname:imageExtent.height) / blockHeight{rceil},
                pname:imageOffset.x {minus} image/ blockHeight)#
      {empty}:: [eq]#y'# is in the range [eq]#[pname:imageOffset.y /
                blockWidth, {lceil}(pname:imageOffset.y {plus}
                pname:imageExtent.width) / blockWidth{rceil})#
      {empty}:: [eq]#blockWidth' = blockHeight#
      {empty}:: [eq]#blockHeight' = blockWidth#
      {empty}:: [eq]#imageWidth' = imageHeight#
      {empty}:: [eq]#imageHeight' = imageWidth#
  * If ename:VK_SURFACE_TRANSFORM_ROTATE_180_BIT_KHR is specified:
      {empty}:: [eq]#x'# is in the range [eq]#[{lceil}(pname:imageOffset.x
                {minus} pname:imageExtent.width) / blockWidth{rceil},
                pname:imageOffset.x / blockWidth)#,
      {empty}:: [eq]#y'# is in the range [eq]#[{lceil}(pname:imageOffset.x
                {plus} pname:imageExtent.height) / blockHeight{rceil},
                pname:imageOffset.x / blockHeight)#,
      {empty}:: [eq]#blockWidth' = blockWidth#
      {empty}:: [eq]#blockHeight' = blockHeight#
      {empty}:: [eq]#imageWidth' = imageWidth#
      {empty}:: [eq]#imageHeight' = imageHeight#
  * If ename:VK_SURFACE_TRANSFORM_ROTATE_270_BIT_KHR is specified:
      {empty}:: [eq]#x# is in the range [eq]#[pname:imageOffset.x /
                blockHeight, {lceil}(pname:imageOffset.x {plus}
                pname:imageExtent.height) / blockHeight{rceil})#
      {empty}:: [eq]#y# is in the range [eq]#[{lceil}(pname:imageOffset.y
                {minus} pname:imageExtent.width) / blockWidth{rceil},
                pname:imageOffset.y / blockWidth)#.
      {empty}:: [eq]#blockWidth' = blockHeight#
      {empty}:: [eq]#blockHeight' = blockWidth#
      {empty}:: [eq]#imageWidth' = imageHeight#
      {empty}:: [eq]#imageHeight' = imageWidth#

When rotation is performed, for each [eq]#(x,y,z,layer)# coordinate, texels
in the image layer selected by [eq]#layer# are instead accessed in the
following ranges:

  {empty}:: [eq]#[x' {times} blockWidth', max( (x' {times} blockWidth')
            {plus} blockWidth', imageWidth') )#
  {empty}:: [eq]#[y' {times} blockHeight', max( (y' {times} blockHeight')
            {plus} blockHeight', imageHeight') )#
  {empty}:: [eq]#[z' {times} blockDepth', max( (z' {times} blockDepth')
            {plus} blockDepth', imageDepth') )#

Buffer addressing calculations are unaffected by this rotation.
endif::VK_QCOM_rotated_copy_commands[]

[[copies-buffers-images-depth-stencil]]
When copying between a buffer and the depth or stencil aspect of an image,
data in the buffer is assumed to be laid out as separate planes rather than
interleaved.
Addressing calculations are thus performed for a different format than the
base image, according to the aspect, as described in the following table:

.Depth/Stencil Aspect Copy Table
[width="95%",cols="1,1,1",options="header"]
|====
^| Base Format ^| Depth Aspect Format ^| Stencil Aspect Format
^| ename:VK_FORMAT_D16_UNORM
^| ename:VK_FORMAT_D16_UNORM
^| -
^| ename:VK_FORMAT_X8_D24_UNORM_PACK32
^| ename:VK_FORMAT_X8_D24_UNORM_PACK32
^| -
^| ename:VK_FORMAT_D32_SFLOAT
^| ename:VK_FORMAT_D32_SFLOAT
^| -
^| ename:VK_FORMAT_S8_UINT
^| -
^| ename:VK_FORMAT_S8_UINT
^| ename:VK_FORMAT_D16_UNORM_S8_UINT
^| ename:VK_FORMAT_D16_UNORM
^| ename:VK_FORMAT_S8_UINT
^| ename:VK_FORMAT_D24_UNORM_S8_UINT
^| ename:VK_FORMAT_X8_D24_UNORM_PACK32
^| ename:VK_FORMAT_S8_UINT
^| ename:VK_FORMAT_D32_SFLOAT_S8_UINT
^| ename:VK_FORMAT_D32_SFLOAT
^| ename:VK_FORMAT_S8_UINT
|====

ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
[[copies-buffers-images-multi-planar]]
When copying between a buffer and any plane of a
<<formats-requiring-sampler-ycbcr-conversion, multi-planar image>>,
addressing calculations are performed using the <<formats-compatible-planes,
compatible format for that plane>>, rather than the format of the
multi-planar image.
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]

Each texel block is copied from one resource to the other according to the
above addressing equations.


[open,refpage='vkCmdCopyBufferToImage',desc='Copy data from a buffer into an image',type='protos']
--
:refpage: vkCmdCopyBufferToImage

To copy data from a buffer object to an image object, call:

include::{generated}/api/protos/vkCmdCopyBufferToImage.adoc[]

  * pname:commandBuffer is the command buffer into which the command will be
    recorded.
  * pname:srcBuffer is the source buffer.
  * pname:dstImage is the destination image.
  * pname:dstImageLayout is the layout of the destination image subresources
    for the copy.
  * pname:regionCount is the number of regions to copy.
  * pname:pRegions is a pointer to an array of slink:VkBufferImageCopy
    structures specifying the regions to copy.

Each source region specified by pname:pRegions is copied from the source
buffer to the destination region of the destination image according to the
<<copies-buffers-images-addressing,addressing calculations>> for each
resource.
If any of the specified regions in pname:srcBuffer overlaps in memory with
any of the specified regions in pname:dstImage, values read from those
overlapping regions are undefined:.
If any region accesses a depth aspect in pname:dstImage
ifdef::VK_EXT_depth_range_unrestricted[]
and the `apiext:VK_EXT_depth_range_unrestricted` extension is not enabled,
endif::VK_EXT_depth_range_unrestricted[]
values copied from pname:srcBuffer outside of the range [eq]#[0,1]# will be
be written as undefined: values to the destination image.

Copy regions for the 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.

:imageparam: dstImage
:imagesubresource: imageSubresource
:imageoffset: imageOffset
:imageextent: imageExtent
:bufferrowlength: bufferRowLength
:bufferimageheight: bufferImageHeight
:regionsparam: pname:pRegions

.Valid Usage
****
include::{chapters}/commonvalidity/copy_anyimage_to_imageany_common.adoc[]
include::{chapters}/commonvalidity/copy_anyimage_to_imageany_no_rotation_common.adoc[]
include::{chapters}/commonvalidity/copy_anyimage_to_imageany_single_sampled_common.adoc[]
include::{chapters}/commonvalidity/copy_buffer_to_image_command_buffer_common.adoc[]
include::{chapters}/commonvalidity/copy_buffer_to_image_common.adoc[]
include::{chapters}/commonvalidity/copy_bufferimage_to_imagebuffer_common.adoc[]
include::{chapters}/commonvalidity/copy_bufferimage_to_imagebuffer_not_both_image_common.adoc[]
include::{chapters}/commonvalidity/copy_bufferimage_to_imagebuffer_buffer_alignment_common.adoc[]
****

include::{generated}/validity/protos/vkCmdCopyBufferToImage.adoc[]
--

[open,refpage='vkCmdCopyImageToBuffer',desc='Copy image data into a buffer',type='protos']
--
:refpage: vkCmdCopyImageToBuffer

To copy data from an image object to a buffer object, call:

include::{generated}/api/protos/vkCmdCopyImageToBuffer.adoc[]

  * pname:commandBuffer is the command buffer into which the command will be
    recorded.
  * pname:srcImage is the source image.
  * pname:srcImageLayout is the layout of the source image subresources for
    the copy.
  * pname:dstBuffer is the destination buffer.
  * pname:regionCount is the number of regions to copy.
  * pname:pRegions is a pointer to an array of slink:VkBufferImageCopy
    structures specifying the regions to copy.

Each source region specified by pname:pRegions is copied from the source
image to the destination region of the destination buffer according to the
<<copies-buffers-images-addressing,addressing calculations>> for each
resource.
If any of the specified regions in pname:srcImage overlaps in memory with
any of the specified regions in pname:dstBuffer, values read from those
overlapping regions are undefined:.

Copy regions for the 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.

:imageparam: srcImage
:imagesubresource: imageSubresource
:imageoffset: imageOffset
:imageextent: imageExtent
:bufferrowlength: bufferRowLength
:bufferimageheight: bufferImageHeight
:regionsparam: pname:pRegions

.Valid Usage
****
include::{chapters}/commonvalidity/copy_anyimage_to_imageany_common.adoc[]
include::{chapters}/commonvalidity/copy_anyimage_to_imageany_no_rotation_common.adoc[]
include::{chapters}/commonvalidity/copy_anyimage_to_imageany_single_sampled_common.adoc[]
include::{chapters}/commonvalidity/copy_image_to_buffer_command_buffer_common.adoc[]
include::{chapters}/commonvalidity/copy_image_to_buffer_common.adoc[]
include::{chapters}/commonvalidity/copy_bufferimage_to_imagebuffer_common.adoc[]
include::{chapters}/commonvalidity/copy_bufferimage_to_imagebuffer_not_both_image_common.adoc[]
include::{chapters}/commonvalidity/copy_bufferimage_to_imagebuffer_buffer_alignment_common.adoc[]
****

include::{generated}/validity/protos/vkCmdCopyImageToBuffer.adoc[]
--

[open,refpage='VkBufferImageCopy',desc='Structure specifying a buffer image copy operation',type='structs']
--
:refpage: VkBufferImageCopy

For both flink:vkCmdCopyBufferToImage and flink:vkCmdCopyImageToBuffer, each
element of pname:pRegions is a structure defined as:

include::{generated}/api/structs/VkBufferImageCopy.adoc[]

  * pname:bufferOffset is the offset in bytes from the start of the buffer
    object where the image data is copied from or to.
  * pname:bufferRowLength and pname:bufferImageHeight specify in texels a
    subregion of a larger two- or three-dimensional image in buffer memory,
    and control the addressing calculations.
    If either of these values is zero, that aspect of the buffer memory is
    considered to be tightly packed according to the pname:imageExtent.
  * pname:imageSubresource is a slink:VkImageSubresourceLayers used to
    specify the specific image subresources of the image used for the source
    or destination image data.
  * pname:imageOffset selects the initial pname:x, pname:y, pname:z offsets
    in texels of the sub-region of the source or destination image data.
  * pname:imageExtent is the size in texels of the image to copy in
    pname:width, pname:height and pname:depth.

:bufferrowlength: bufferRowLength
:bufferimageheight: bufferImageHeight

.Valid Usage
****
include::{chapters}/commonvalidity/buffer_or_memory_image_copy_common.adoc[]
****

include::{generated}/validity/structs/VkBufferImageCopy.adoc[]
--

ifdef::VK_VERSION_1_3,VK_KHR_copy_commands2[]
More extensible versions of the commands to copy between buffers and images
are defined below.

[open,refpage='vkCmdCopyBufferToImage2',desc='Copy data from a buffer into an image',type='protos',alias='vkCmdCopyBufferToImage2KHR']
--
:refpage: vkCmdCopyBufferToImage2

To copy data from a buffer object to an image object, call:

ifdef::VK_VERSION_1_3[]
include::{generated}/api/protos/vkCmdCopyBufferToImage2.adoc[]
endif::VK_VERSION_1_3[]

ifdef::VK_VERSION_1_3+VK_KHR_copy_commands2[or the equivalent command]

ifdef::VK_KHR_copy_commands2[]
include::{generated}/api/protos/vkCmdCopyBufferToImage2KHR.adoc[]
endif::VK_KHR_copy_commands2[]

  * pname:commandBuffer is the command buffer into which the command will be
    recorded.
  * pname:pCopyBufferToImageInfo is a pointer to a
    slink:VkCopyBufferToImageInfo2 structure describing the copy parameters.

This command is functionally identical to flink:vkCmdCopyBufferToImage, but
includes extensible sub-structures that include pname:sType and pname:pNext
parameters, allowing them to be more easily extended.

:regionsparam: pname:pCopyBufferToImageInfo->pRegions

.Valid Usage
****
include::{chapters}/commonvalidity/copy_buffer_to_image_command_buffer_common.adoc[]
****

include::{generated}/validity/protos/vkCmdCopyBufferToImage2.adoc[]
--

[open,refpage='VkCopyBufferToImageInfo2',desc='Structure specifying parameters of a buffer to image copy command',type='structs',alias='VkCopyBufferToImageInfo2KHR']
--
:refpage: VkCopyBufferToImageInfo2

The sname:VkCopyBufferToImageInfo2 structure is defined as:

include::{generated}/api/structs/VkCopyBufferToImageInfo2.adoc[]

ifdef::VK_KHR_copy_commands2[]
or the equivalent

include::{generated}/api/structs/VkCopyBufferToImageInfo2KHR.adoc[]
endif::VK_KHR_copy_commands2[]

  * pname:sType is a elink:VkStructureType value identifying this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:srcBuffer is the source buffer.
  * pname:dstImage is the destination image.
  * pname:dstImageLayout is the layout of the destination image subresources
    for the copy.
  * pname:regionCount is the number of regions to copy.
  * pname:pRegions is a pointer to an array of slink:VkBufferImageCopy2
    structures specifying the regions to copy.

:imageparam: dstImage
:imagesubresource: imageSubresource
:imageoffset: imageOffset
:imageextent: imageExtent
:bufferrowlength: bufferRowLength
:bufferimageheight: bufferImageHeight
:regionsparam: pname:pRegions

.Valid Usage
****
  * [[VUID-VkCopyBufferToImageInfo2-pRegions-04565]]
    The image region specified by each element of pname:pRegions
ifdef::VK_QCOM_rotated_copy_commands[]
    that does not contain slink:VkCopyCommandTransformInfoQCOM in its
    pname:pNext chain
endif::VK_QCOM_rotated_copy_commands[]
    must: be contained within the specified pname:imageSubresource of
    pname:dstImage
ifdef::VK_QCOM_rotated_copy_commands[]
  * [[VUID-VkCopyBufferToImageInfo2KHR-pRegions-04554]]
    If the image region specified by each element of pname:pRegions contains
    slink:VkCopyCommandTransformInfoQCOM in its pname:pNext chain, the
    rotated destination region as described in
    <<copies-buffers-images-rotation-addressing>> must: be contained within
    pname:dstImage
  * [[VUID-VkCopyBufferToImageInfo2KHR-pRegions-04555]]
    If any element of pname:pRegions contains
    slink:VkCopyCommandTransformInfoQCOM in its pname:pNext chain, then
    pname:dstImage must: have a 1x1x1 <<formats-compatibility-classes,texel
    block extent>>
  * [[VUID-VkCopyBufferToImageInfo2KHR-pRegions-06203]]
    If any element of pname:pRegions contains
    slink:VkCopyCommandTransformInfoQCOM in its pname:pNext chain, then
    pname:dstImage must: be of type ename:VK_IMAGE_TYPE_2D
  * [[VUID-VkCopyBufferToImageInfo2KHR-pRegions-06204]]
    If any element of pname:pRegions contains
    slink:VkCopyCommandTransformInfoQCOM in its pname:pNext chain, then
    pname:dstImage must: not have a
    <<formats-requiring-sampler-ycbcr-conversion, multi-planar format>>
endif::VK_QCOM_rotated_copy_commands[]
include::{chapters}/commonvalidity/copy_buffer_to_image_common.adoc[]
include::{chapters}/commonvalidity/copy_anyimage_to_imageany_common.adoc[]
include::{chapters}/commonvalidity/copy_anyimage_to_imageany_single_sampled_common.adoc[]
include::{chapters}/commonvalidity/copy_bufferimage_to_imagebuffer_common.adoc[]
include::{chapters}/commonvalidity/copy_bufferimage_to_imagebuffer_not_both_image_common.adoc[]
include::{chapters}/commonvalidity/copy_bufferimage_to_imagebuffer_buffer_alignment_common.adoc[]
  * [[VUID-VkCopyBufferToImageInfo2-pRegions-06223]]
    For each element of pname:pRegions not containing
    sname:VkCopyCommandTransformInfoQCOM in its pname:pNext chain,
    pname:imageOffset.x and [eq]#(pname:imageExtent.width {plus}
    pname:imageOffset.x)# must: both be greater than or equal to `0` and
    less than or equal to the width of the specified pname:imageSubresource
    of pname:dstImage
  * [[VUID-VkCopyBufferToImageInfo2-pRegions-06224]]
    For each element of pname:pRegions not containing
    sname:VkCopyCommandTransformInfoQCOM in its pname:pNext chain,
    pname:imageOffset.y and [eq]#(pname:imageExtent.height {plus}
    pname:imageOffset.y)# must: both be greater than or equal to `0` and
    less than or equal to the height of the specified pname:imageSubresource
    of pname:dstImage
****

include::{generated}/validity/structs/VkCopyBufferToImageInfo2.adoc[]
--

[open,refpage='vkCmdCopyImageToBuffer2',desc='Copy image data into a buffer',type='protos',alias='vkCmdCopyImageToBuffer2KHR']
--
:refpage: vkCmdCopyImageToBuffer2

To copy data from an image object to a buffer object, call:

ifdef::VK_VERSION_1_3[]
include::{generated}/api/protos/vkCmdCopyImageToBuffer2.adoc[]
endif::VK_VERSION_1_3[]

ifdef::VK_VERSION_1_3+VK_KHR_copy_commands2[or the equivalent command]

ifdef::VK_KHR_copy_commands2[]
include::{generated}/api/protos/vkCmdCopyImageToBuffer2KHR.adoc[]
endif::VK_KHR_copy_commands2[]

  * pname:commandBuffer is the command buffer into which the command will be
    recorded.
  * pname:pCopyImageToBufferInfo is a pointer to a
    slink:VkCopyImageToBufferInfo2 structure describing the copy parameters.

This command is functionally identical to flink:vkCmdCopyImageToBuffer, but
includes extensible sub-structures that include pname:sType and pname:pNext
parameters, allowing them to be more easily extended.

:regionsparam: pname:pCopyImageToBufferInfo->pRegions

.Valid Usage
****
include::{chapters}/commonvalidity/copy_image_to_buffer_command_buffer_common.adoc[]
****

include::{generated}/validity/protos/vkCmdCopyImageToBuffer2.adoc[]
--

[open,refpage='VkCopyImageToBufferInfo2',desc='Structure specifying parameters of an image to buffer copy command',type='structs',alias='VkCopyImageToBufferInfo2KHR']
--
:refpage: VkCopyImageToBufferInfo2

The sname:VkCopyImageToBufferInfo2 structure is defined as:

include::{generated}/api/structs/VkCopyImageToBufferInfo2.adoc[]

ifdef::VK_KHR_copy_commands2[]
or the equivalent

include::{generated}/api/structs/VkCopyImageToBufferInfo2KHR.adoc[]
endif::VK_KHR_copy_commands2[]

  * pname:sType is a elink:VkStructureType value identifying this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:srcImage is the source image.
  * pname:srcImageLayout is the layout of the source image subresources for
    the copy.
  * pname:dstBuffer is the destination buffer.
  * pname:regionCount is the number of regions to copy.
  * pname:pRegions is a pointer to an array of slink:VkBufferImageCopy2
    structures specifying the regions to copy.

:imageparam: srcImage
:imagesubresource: imageSubresource
:imageoffset: imageOffset
:imageextent: imageExtent
:bufferrowlength: bufferRowLength
:bufferimageheight: bufferImageHeight
:regionsparam: pname:pRegions

.Valid Usage
****
  * [[VUID-VkCopyImageToBufferInfo2-pRegions-04566]]
    The image region specified by each element of pname:pRegions
ifdef::VK_QCOM_rotated_copy_commands[]
    that does not contain slink:VkCopyCommandTransformInfoQCOM in its
    pname:pNext chain
endif::VK_QCOM_rotated_copy_commands[]
    must: be contained within the specified pname:imageSubresource of
    pname:srcImage
ifdef::VK_QCOM_rotated_copy_commands[]
  * [[VUID-VkCopyImageToBufferInfo2KHR-pRegions-04557]]
    If the image region specified by each element of pname:pRegions contains
    slink:VkCopyCommandTransformInfoQCOM in its pname:pNext chain, the
    rotated source region as described in
    <<copies-buffers-images-rotation-addressing>> must: be contained within
    pname:srcImage
  * [[VUID-VkCopyImageToBufferInfo2KHR-pRegions-04558]]
    If any element of pname:pRegions contains
    slink:VkCopyCommandTransformInfoQCOM in its pname:pNext chain, then
    pname:srcImage must: have a 1x1x1 <<formats-compatibility-classes,texel
    block extent>>
  * [[VUID-VkCopyImageToBufferInfo2KHR-pRegions-06205]]
    If any element of pname:pRegions contains
    slink:VkCopyCommandTransformInfoQCOM in its pname:pNext chain, then
    pname:srcImage must: be of type ename:VK_IMAGE_TYPE_2D
  * [[VUID-VkCopyImageToBufferInfo2KHR-pRegions-06206]]
    If any element of pname:pRegions contains
    slink:VkCopyCommandTransformInfoQCOM in its pname:pNext chain, then
    pname:srcImage must: not have a
    <<formats-requiring-sampler-ycbcr-conversion, multi-planar format>>
endif::VK_QCOM_rotated_copy_commands[]
include::{chapters}/commonvalidity/copy_image_to_buffer_common.adoc[]
include::{chapters}/commonvalidity/copy_anyimage_to_imageany_common.adoc[]
include::{chapters}/commonvalidity/copy_anyimage_to_imageany_single_sampled_common.adoc[]
include::{chapters}/commonvalidity/copy_bufferimage_to_imagebuffer_common.adoc[]
include::{chapters}/commonvalidity/copy_bufferimage_to_imagebuffer_not_both_image_common.adoc[]
include::{chapters}/commonvalidity/copy_bufferimage_to_imagebuffer_buffer_alignment_common.adoc[]
  * [[VUID-VkCopyImageToBufferInfo2-imageOffset-00197]]
    For each element of pname:pRegions not containing
    sname:VkCopyCommandTransformInfoQCOM in its pname:pNext chain,
    pname:imageOffset.x and [eq]#(pname:imageExtent.width {plus}
    pname:imageOffset.x)# must: both be greater than or equal to `0` and
    less than or equal to the width of the specified pname:imageSubresource
    of pname:srcImage
  * [[VUID-VkCopyImageToBufferInfo2-imageOffset-00198]]
    For each element of pname:pRegions not containing
    sname:VkCopyCommandTransformInfoQCOM in its pname:pNext chain,
    pname:imageOffset.y and [eq]#(pname:imageExtent.height {plus}
    pname:imageOffset.y)# must: both be greater than or equal to `0` and
    less than or equal to the height of the specified pname:imageSubresource
    of pname:srcImage
****

include::{generated}/validity/structs/VkCopyImageToBufferInfo2.adoc[]
--

[open,refpage='VkBufferImageCopy2',desc='Structure specifying a buffer image copy operation',type='structs',alias='VkBufferImageCopy2KHR']
--
:refpage: VkBufferImageCopy2

For both flink:vkCmdCopyBufferToImage2 and flink:vkCmdCopyImageToBuffer2,
each element of pname:pRegions is a structure defined as:

include::{generated}/api/structs/VkBufferImageCopy2.adoc[]

ifdef::VK_KHR_copy_commands2[]
or the equivalent

include::{generated}/api/structs/VkBufferImageCopy2KHR.adoc[]
endif::VK_KHR_copy_commands2[]

  * pname:sType is a elink:VkStructureType value identifying this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:bufferOffset is the offset in bytes from the start of the buffer
    object where the image data is copied from or to.
  * pname:bufferRowLength and pname:bufferImageHeight specify in texels a
    subregion of a larger two- or three-dimensional image in buffer memory,
    and control the addressing calculations.
    If either of these values is zero, that aspect of the buffer memory is
    considered to be tightly packed according to the pname:imageExtent.
  * pname:imageSubresource is a slink:VkImageSubresourceLayers used to
    specify the specific image subresources of the image used for the source
    or destination image data.
  * pname:imageOffset selects the initial pname:x, pname:y, pname:z offsets
    in texels of the sub-region of the source or destination image data.
  * pname:imageExtent is the size in texels of the image to copy in
    pname:width, pname:height and pname:depth.

This structure is functionally identical to slink:VkBufferImageCopy, but
adds pname:sType and pname:pNext parameters, allowing it to be more easily
extended.

:bufferrowlength: bufferRowLength
:bufferimageheight: bufferImageHeight

.Valid Usage
****
include::{chapters}/commonvalidity/buffer_or_memory_image_copy_common.adoc[]
****

include::{generated}/validity/structs/VkBufferImageCopy2.adoc[]
--
endif::VK_VERSION_1_3,VK_KHR_copy_commands2[]

ifdef::VK_QCOM_rotated_copy_commands[]
[open,refpage='VkCopyCommandTransformInfoQCOM',desc='Structure describing transform parameters of rotated copy command',type='structs']
--
The sname:VkCopyCommandTransformInfoQCOM structure is defined as:

include::{generated}/api/structs/VkCopyCommandTransformInfoQCOM.adoc[]

  * pname:sType is a elink:VkStructureType value identifying this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:transform is a elink:VkSurfaceTransformFlagBitsKHR value
    describing the transform to be applied.

Including this structure in the pname:pNext chain of
slink:VkBufferImageCopy2 defines a rotation to be performed when copying
between an image and a buffer.
Including this structure in the pname:pNext chain of slink:VkBlitImageInfo2
defines a rotation to be performed when blitting between two images.
If this structure is not specified in either case, the implementation
behaves as if it was specified with a pname:transform equal to
ename:VK_SURFACE_TRANSFORM_IDENTITY_BIT_KHR.

Specifying a transform for a copy between an image and a buffer
<<copies-buffers-images-rotation-addressing, rotates the region accessed in
the image around the offset>>.
Specifying a transform for a blit performs a similar transform as described
in <<copies-images-scaling-rotation, Image Blits with Scaling and
Rotation>>.

Rotations other than ename:VK_SURFACE_TRANSFORM_IDENTITY_BIT_KHR can: only
be specified for single-plane 2D images with a 1x1x1
<<formats-compatibility-classes,texel block extent>>.

.Valid Usage
****
  * [[VUID-VkCopyCommandTransformInfoQCOM-transform-04560]]
    pname:transform must: be ename:VK_SURFACE_TRANSFORM_IDENTITY_BIT_KHR,
    ename:VK_SURFACE_TRANSFORM_ROTATE_90_BIT_KHR,
    ename:VK_SURFACE_TRANSFORM_ROTATE_180_BIT_KHR, or
    ename:VK_SURFACE_TRANSFORM_ROTATE_270_BIT_KHR
****

include::{generated}/validity/structs/VkCopyCommandTransformInfoQCOM.adoc[]
--
endif::VK_QCOM_rotated_copy_commands[]

ifdef::VK_EXT_host_image_copy[]
include::{chapters}/VK_EXT_host_image_copy/copies.adoc[]
endif::VK_EXT_host_image_copy[]


ifdef::VK_NV_copy_memory_indirect[]
[[indirect-copies]]
== Indirect Copies

An application can use indirect copies when the copy parameters are not
known during the command buffer creation time.

[open,refpage='vkCmdCopyMemoryIndirectNV',desc='Copy data between memory regions',type='protos']
--
To copy data between two memory regions by specifying copy parameters
indirectly in a buffer, call:

include::{generated}/api/protos/vkCmdCopyMemoryIndirectNV.adoc[]

  * pname:commandBuffer is the command buffer into which the command will be
    recorded.
  * pname:copyBufferAddress is the buffer address specifying the copy
    parameters.
    This buffer is laid out in memory as an array of
    slink:VkCopyMemoryIndirectCommandNV structures.
  * pname:copyCount is the number of copies to execute, and can be zero.
  * pname:stride is the stride in bytes between successive sets of copy
    parameters.

Each region read from pname:copyBufferAddress is copied from the source
region to the specified destination region.
The results are undefined: if any of the source and destination regions
overlap in memory.

.Valid Usage
****
  * [[VUID-vkCmdCopyMemoryIndirectNV-None-07653]]
    The <<features-indirectCopy, pname:indirectCopy>> feature must: be
    enabled
  * [[VUID-vkCmdCopyMemoryIndirectNV-copyBufferAddress-07654]]
    pname:copyBufferAddress must: be 4 byte aligned
  * [[VUID-vkCmdCopyMemoryIndirectNV-stride-07655]]
    pname:stride must: be a multiple of `4` and must: be greater than or
    equal to sizeof(sname:VkCopyMemoryIndirectCommandNV)
  * [[VUID-vkCmdCopyMemoryIndirectNV-commandBuffer-07656]]
    The slink:VkCommandPool that pname:commandBuffer was allocated from
    must: support at least one of the
    slink:VkPhysicalDeviceCopyMemoryIndirectPropertiesNV::pname:supportedQueues
****

include::{generated}/validity/protos/vkCmdCopyMemoryIndirectNV.adoc[]
--

[open,refpage='VkCopyMemoryIndirectCommandNV',desc='Structure specifying indirect memory region copy operation',type='structs']
--
The structure describing source and destination memory regions,
sname:VkCopyMemoryIndirectCommandNV is defined as:

include::{generated}/api/structs/VkCopyMemoryIndirectCommandNV.adoc[]

  * pname:srcAddress is the starting address of the source device memory to
    copy from.
  * pname:dstAddress is the starting address of the destination device
    memory to copy to.
  * pname:size is the size of the copy in bytes.

.Valid Usage
****
  * [[VUID-VkCopyMemoryIndirectCommandNV-srcAddress-07657]]
    The pname:srcAddress must: be 4 byte aligned
  * [[VUID-VkCopyMemoryIndirectCommandNV-dstAddress-07658]]
    The pname:dstAddress must: be 4 byte aligned
  * [[VUID-VkCopyMemoryIndirectCommandNV-size-07659]]
    The pname:size must: be 4 byte aligned
****

include::{generated}/validity/structs/VkCopyMemoryIndirectCommandNV.adoc[]
--

[open,refpage='vkCmdCopyMemoryToImageIndirectNV',desc='Copy data from a memory region into an image',type='protos']
--
:refpage: vkCmdCopyMemoryToImageIndirectNV

To copy data from a memory region to an image object by specifying copy
parameters in a buffer, call:

include::{generated}/api/protos/vkCmdCopyMemoryToImageIndirectNV.adoc[]

  * pname:commandBuffer is the command buffer into which the command will be
    recorded.
  * pname:copyBufferAddress is the buffer address specifying the copy
    parameters.
    This buffer is laid out in memory as an array of
    slink:VkCopyMemoryToImageIndirectCommandNV structures.
  * pname:copyCount is the number of copies to execute, and can be zero.
  * pname:stride is the byte stride between successive sets of copy
    parameters.
  * pname:dstImage is the destination image.
  * pname:dstImageLayout is the layout of the destination image subresources
    for the copy.
  * pname:pImageSubresources is a pointer to an array of size
    pname:copyCount of slink:VkImageSubresourceLayers used to specify the
    specific image subresource of the destination image data for that copy.

Each region in pname:copyBufferAddress is copied from the source memory
region to an image region in the destination image.
If the destination image is of type ename:VK_IMAGE_TYPE_3D, the starting
slice and number of slices to copy are specified in
pname:pImageSubresources->baseArrayLayer and
pname:pImageSubresources->layerCount respectively.
The copy must: be performed on a queue that supports indirect copy
operations, see slink:VkPhysicalDeviceCopyMemoryIndirectPropertiesNV.

:imageparam: dstImage

.Valid Usage
****
  * [[VUID-vkCmdCopyMemoryToImageIndirectNV-None-07660]]
    The <<features-indirectCopy, pname:indirectCopy>> feature must: be
    enabled
  * [[VUID-vkCmdCopyMemoryToImageIndirectNV-dstImage-07661]]
    pname:dstImage must: not be a protected image
  * [[VUID-vkCmdCopyMemoryToImageIndirectNV-aspectMask-07662]]
    The pname:aspectMask member for every subresource in
    pname:pImageSubresources must: only have a single bit set
  * [[VUID-vkCmdCopyMemoryToImageIndirectNV-dstImage-07663]]
    The image region specified by each element in sname:copyBufferAddress
    must: be a region that is contained within pname:dstImage
  * [[VUID-vkCmdCopyMemoryToImageIndirectNV-dstImage-07664]]
    pname:dstImage must: have been created with
    ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT usage flag
  * [[VUID-vkCmdCopyMemoryToImageIndirectNV-dstImage-07665]]
    If pname:dstImage is non-sparse then it must: be bound completely and
    contiguously to a single sname:VkDeviceMemory object
include::{chapters}/commonvalidity/copy_anyimage_to_imageany_single_sampled_common.adoc[]
  * [[VUID-vkCmdCopyMemoryToImageIndirectNV-dstImageLayout-07667]]
    pname:dstImageLayout must: specify the layout of the image subresources
    of pname:dstImage at the time this command is executed on a
    sname:VkDevice
  * [[VUID-vkCmdCopyMemoryToImageIndirectNV-dstImageLayout-07669]]
    pname:dstImageLayout must: be
    ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL,
ifdef::VK_KHR_shared_presentable_image[]
    ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR,
endif::VK_KHR_shared_presentable_image[]
    or ename:VK_IMAGE_LAYOUT_GENERAL
  * [[VUID-vkCmdCopyMemoryToImageIndirectNV-mipLevel-07670]]
    The specified pname:mipLevel of each region must: be less than the
    pname:mipLevels specified in slink:VkImageCreateInfo when pname:dstImage
    was created
  * [[VUID-vkCmdCopyMemoryToImageIndirectNV-layerCount-08764]]
    If pname:layerCount is not ename:VK_REMAINING_ARRAY_LAYERS, the
    specified pname:baseArrayLayer {plus} pname:layerCount of each region
    must: be less than or equal to the pname:arrayLayers specified in
    slink:VkImageCreateInfo when pname:dstImage was created
  * [[VUID-vkCmdCopyMemoryToImageIndirectNV-imageOffset-07672]]
    The pname:imageOffset and pname:imageExtent members of each region must:
    respect the image transfer granularity requirements of
    pname:commandBuffer's command pool's queue family, as described in
    slink:VkQueueFamilyProperties
ifdef::VK_EXT_fragment_density_map[]
  * [[VUID-vkCmdCopyMemoryToImageIndirectNV-dstImage-07673]]
    pname:dstImage must: not have been created with pname:flags containing
    ename:VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT
endif::VK_EXT_fragment_density_map[]
  * [[VUID-vkCmdCopyMemoryToImageIndirectNV-commandBuffer-07674]]
    If the queue family used to create the slink:VkCommandPool which
    pname:commandBuffer was allocated from does not support
    ename:VK_QUEUE_GRAPHICS_BIT, for each region, the pname:aspectMask
    member of pname:pImageSubresources must: not be
    ename:VK_IMAGE_ASPECT_DEPTH_BIT or ename:VK_IMAGE_ASPECT_STENCIL_BIT
  * [[VUID-vkCmdCopyMemoryToImageIndirectNV-imageOffset-07675]]
    For each region in sname:copyBufferAddress, pname:imageOffset.y and
    [eq]#(pname:imageExtent.height {plus} pname:imageOffset.y)# must: both
    be greater than or equal to `0` and less than or equal to the height of
    the specified subresource
  * [[VUID-vkCmdCopyMemoryToImageIndirectNV-offset-07676]]
    pname:offset must: be 4 byte aligned
  * [[VUID-vkCmdCopyMemoryToImageIndirectNV-stride-07677]]
    pname:stride must: be a multiple of `4` and must: be greater than or
    equal to sizeof(sname:VkCopyMemoryToImageIndirectCommandNV)
****

include::{generated}/validity/protos/vkCmdCopyMemoryToImageIndirectNV.adoc[]
--

[open,refpage='VkCopyMemoryToImageIndirectCommandNV',desc='Structure specifying indirect buffer image copy operation',type='structs']
--
The sname:VkCopyMemoryToImageIndirectCommandNV is defined as:

include::{generated}/api/structs/VkCopyMemoryToImageIndirectCommandNV.adoc[]

  * pname:srcAddress is the starting address of the source device memory to
    copy from.
  * pname:bufferRowLength and pname:bufferImageHeight specify in texels a
    subregion of a larger two- or three-dimensional image in buffer memory,
    and control the addressing calculations.
    If either of these values is zero, that aspect of the buffer memory is
    considered to be tightly packed according to the pname:imageExtent.
  * pname:imageSubresource is a slink:VkImageSubresourceLayers used to
    specify the specific image subresources of the image used for the
    destination image data, which must: match the values specified in
    pname:pImageSubresources parameter of
    flink:vkCmdCopyMemoryToImageIndirectNV during command recording.
  * pname:imageOffset selects the initial pname:x, pname:y, pname:z offsets
    in texels of the sub-region of the destination image data.
  * pname:imageExtent is the size in texels of the destination image in
    pname:width, pname:height and pname:depth.

.Valid Usage
****
  * [[VUID-VkCopyMemoryToImageIndirectCommandNV-srcAddress-07678]]
    The pname:srcAddress must: be 4 byte aligned
  * [[VUID-VkCopyMemoryToImageIndirectCommandNV-bufferRowLength-07679]]
    pname:bufferRowLength must: be `0`, or greater than or equal to the
    pname:width member of pname:imageExtent
  * [[VUID-VkCopyMemoryToImageIndirectCommandNV-bufferImageHeight-07680]]
    pname:bufferImageHeight must: be `0`, or greater than or equal to the
    pname:height member of pname:imageExtent
  * [[VUID-VkCopyMemoryToImageIndirectCommandNV-imageOffset-07681]]
    pname:imageOffset must: specify a valid offset in the destination image
  * [[VUID-VkCopyMemoryToImageIndirectCommandNV-imageExtent-07682]]
    pname:imageExtent must: specify a valid region in the destination image
    and can be `0`
****

include::{generated}/validity/structs/VkCopyMemoryToImageIndirectCommandNV.adoc[]
--
endif::VK_NV_copy_memory_indirect[]


[[copies-imagescaling]]
== Image Copies With Scaling

[open,refpage='vkCmdBlitImage',desc='Copy regions of an image, potentially performing format conversion,',type='protos']
--
:refpage: vkCmdBlitImage

To copy regions of a source image into a destination image, potentially
performing format conversion, arbitrary scaling, and filtering, call:

include::{generated}/api/protos/vkCmdBlitImage.adoc[]

  * pname:commandBuffer is the command buffer into which the command will be
    recorded.
  * pname:srcImage is the source image.
  * pname:srcImageLayout is the layout of the source image subresources for
    the blit.
  * pname:dstImage is the destination image.
  * pname:dstImageLayout is the layout of the destination image subresources
    for the blit.
  * pname:regionCount is the number of regions to blit.
  * pname:pRegions is a pointer to an array of slink:VkImageBlit structures
    specifying the regions to blit.
  * pname:filter is a elink:VkFilter specifying the filter to apply if the
    blits require scaling.

fname:vkCmdBlitImage must: not be used for multisampled source or
destination images.
Use flink:vkCmdResolveImage for this purpose.

As the sizes of the source and destination extents can: differ in any
dimension, texels in the source extent are scaled and filtered to the
destination extent.
Scaling occurs via the following operations:

  * For each destination texel, the integer coordinate of that texel is
    converted to an unnormalized texture coordinate, using the effective
    inverse of the equations described in
    <<textures-unnormalized-to-integer, unnormalized to integer
    conversion>>:
  {empty}:: [eq]#u~base~ = i {plus} {onehalf}#
  {empty}:: [eq]#v~base~ = j {plus} {onehalf}#
  {empty}:: [eq]#w~base~ = k {plus} {onehalf}#
  * These base coordinates are then offset by the first destination offset:
  {empty}:: [eq]#u~offset~ = u~base~ - x~dst0~#
  {empty}:: [eq]#v~offset~ = v~base~ - y~dst0~#
  {empty}:: [eq]#w~offset~ = w~base~ - z~dst0~#
  {empty}:: [eq]#a~offset~ = a - pname:baseArrayCount~dst~#
  * The scale is determined from the source and destination regions, and
    applied to the offset coordinates:
  {empty}:: [eq]#scale~u~ = (x~src1~ - x~src0~) / (x~dst1~ - x~dst0~)#
  {empty}:: [eq]#scale~v~ = (y~src1~ - y~src0~) / (y~dst1~ - y~dst0~)#
  {empty}:: [eq]#scale~w~ = (z~src1~ - z~src0~) / (z~dst1~ - z~dst0~)#
  {empty}:: [eq]#u~scaled~ = u~offset~ {times} scale~u~#
  {empty}:: [eq]#v~scaled~ = v~offset~ {times} scale~v~#
  {empty}:: [eq]#w~scaled~ = w~offset~ {times} scale~w~#
  * Finally the source offset is added to the scaled coordinates, to
    determine the final unnormalized coordinates used to sample from
    pname:srcImage:
  {empty}:: [eq]#u = u~scaled~ {plus} x~src0~#
  {empty}:: [eq]#v = v~scaled~ {plus} y~src0~#
  {empty}:: [eq]#w = w~scaled~ {plus} z~src0~#
  {empty}:: [eq]#q = pname:mipLevel#
  {empty}:: [eq]#a = a~offset~ {plus} pname:baseArrayCount~src~#

These coordinates are used to sample from the source image, as described in
<<textures, Image Operations chapter>>, with the filter mode equal to that
of pname:filter, a mipmap mode of ename:VK_SAMPLER_MIPMAP_MODE_NEAREST and
an address mode of ename:VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE.
Implementations must: clamp at the edge of the source image, and may:
additionally clamp to the edge of the source region.

[NOTE]
.Note
====
Due to allowable rounding errors in the generation of the source texture
coordinates, it is not always possible to guarantee exactly which source
texels will be sampled for a given blit.
As rounding errors are implementation-dependent, the exact results of a
blitting operation are also implementation-dependent.
====

Blits are done layer by layer starting with the pname:baseArrayLayer member
of pname:srcSubresource for the source and pname:dstSubresource for the
destination.
pname:layerCount layers are blitted to the destination image.

When blitting 3D textures, slices in the destination region bounded by
pname:dstOffsets[0].z and pname:dstOffsets[1].z are sampled from slices in
the source region bounded by pname:srcOffsets[0].z and
pname:srcOffsets[1].z.
If the pname:filter parameter is ename:VK_FILTER_LINEAR then the value
sampled from the source image is taken by doing linear filtering using the
interpolated *z* coordinate represented by *w* in the previous equations.
If the pname:filter parameter is ename:VK_FILTER_NEAREST then the value
sampled from the source image is taken from the single nearest slice, with
an implementation-dependent arithmetic rounding mode.

The following filtering and conversion rules apply:

  * Integer formats can: only be converted to other integer formats with the
    same signedness.
  * No format conversion is supported between depth/stencil images.
    The formats must: match.
  * Format conversions on unorm, snorm, scaled and packed float formats of
    the copied aspect of the image are performed by first converting the
    pixels to float values.
  * For sRGB source formats, nonlinear RGB values are converted to linear
    representation prior to filtering.
  * After filtering, the float values are first clamped and then cast to the
    destination image format.
    In case of sRGB destination format, linear RGB values are converted to
    nonlinear representation before writing the pixel to the image.

Signed and unsigned integers are converted by first clamping to the
representable range of the destination format, then casting the value.

.Valid Usage
****
include::{chapters}/commonvalidity/blit_image_command_buffer_common.adoc[]
include::{chapters}/commonvalidity/blit_image_common.adoc[]
****

include::{generated}/validity/protos/vkCmdBlitImage.adoc[]
--

[open,refpage='VkImageBlit',desc='Structure specifying an image blit operation',type='structs']
--
:refpage: VkImageBlit

The sname:VkImageBlit structure is defined as:

include::{generated}/api/structs/VkImageBlit.adoc[]

  * pname:srcSubresource is the subresource to blit from.
  * pname:srcOffsets is a pointer to an array of two slink:VkOffset3D
    structures specifying the bounds of the source region within
    pname:srcSubresource.
  * pname:dstSubresource is the subresource to blit into.
  * pname:dstOffsets is a pointer to an array of two slink:VkOffset3D
    structures specifying the bounds of the destination region within
    pname:dstSubresource.

For each element of the pname:pRegions array, a blit operation is performed
for the specified source and destination regions.

.Valid Usage
****
include::{chapters}/commonvalidity/image_blit_common.adoc[]
****

include::{generated}/validity/structs/VkImageBlit.adoc[]
--

ifdef::VK_VERSION_1_3,VK_KHR_copy_commands2[]
A more extensible version of the blit image command is defined below.

[open,refpage='vkCmdBlitImage2',desc='Copy regions of an image, potentially performing format conversion,',type='protos',alias='vkCmdBlitImage2KHR']
--
:refpage: vkCmdBlitImage2

To copy regions of a source image into a destination image, potentially
performing format conversion, arbitrary scaling, and filtering, call:

ifdef::VK_VERSION_1_3[]
include::{generated}/api/protos/vkCmdBlitImage2.adoc[]
endif::VK_VERSION_1_3[]

ifdef::VK_VERSION_1_3+VK_KHR_copy_commands2[or the equivalent command]

ifdef::VK_KHR_copy_commands2[]
include::{generated}/api/protos/vkCmdBlitImage2KHR.adoc[]
endif::VK_KHR_copy_commands2[]

  * pname:commandBuffer is the command buffer into which the command will be
    recorded.
  * pname:pBlitImageInfo is a pointer to a slink:VkBlitImageInfo2 structure
    describing the blit parameters.

This command is functionally identical to flink:vkCmdBlitImage, but includes
extensible sub-structures that include pname:sType and pname:pNext
parameters, allowing them to be more easily extended.

.Valid Usage
****
include::{chapters}/commonvalidity/blit_image_command_buffer_common.adoc[]
****

include::{generated}/validity/protos/vkCmdBlitImage2.adoc[]
--

[open,refpage='VkBlitImageInfo2',desc='Structure specifying parameters of blit image command',type='structs',alias='VkBlitImageInfo2KHR']
--
:refpage: VkBlitImageInfo2

The sname:VkBlitImageInfo2 structure is defined as:

include::{generated}/api/structs/VkBlitImageInfo2.adoc[]

ifdef::VK_KHR_copy_commands2[]
or the equivalent

include::{generated}/api/structs/VkBlitImageInfo2KHR.adoc[]
endif::VK_KHR_copy_commands2[]

  * pname:sType is a elink:VkStructureType value identifying this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:srcImage is the source image.
  * pname:srcImageLayout is the layout of the source image subresources for
    the blit.
  * pname:dstImage is the destination image.
  * pname:dstImageLayout is the layout of the destination image subresources
    for the blit.
  * pname:regionCount is the number of regions to blit.
  * pname:pRegions is a pointer to an array of slink:VkImageBlit2 structures
    specifying the regions to blit.
  * pname:filter is a elink:VkFilter specifying the filter to apply if the
    blits require scaling.

.Valid Usage
****
include::{chapters}/commonvalidity/blit_image_common.adoc[]
ifdef::VK_QCOM_rotated_copy_commands[]
  * [[VUID-VkBlitImageInfo2-pRegions-04561]]
    If any element of pname:pRegions contains
    slink:VkCopyCommandTransformInfoQCOM in its pname:pNext chain, then
    pname:srcImage and pname:dstImage must: not be block-compressed images
  * [[VUID-VkBlitImageInfo2KHR-pRegions-06207]]
    If any element of pname:pRegions contains
    slink:VkCopyCommandTransformInfoQCOM in its pname:pNext chain, then
    pname:srcImage must: be of type ename:VK_IMAGE_TYPE_2D
  * [[VUID-VkBlitImageInfo2KHR-pRegions-06208]]
    If any element of pname:pRegions contains
    slink:VkCopyCommandTransformInfoQCOM in its pname:pNext chain, then
    pname:srcImage must: not have a
    <<formats-requiring-sampler-ycbcr-conversion, multi-planar format>>
endif::VK_QCOM_rotated_copy_commands[]
ifdef::VK_QCOM_filter_cubic_weights[]
  * [[VUID-VkBlitImageInfo2-filter-09204]]
    If pname:filter is ename:VK_FILTER_CUBIC_EXT and if the
    <<features-filter-cubic-weight-selection,selectableCubicWeights>>
    feature is not enabled then the cubic weights must: be
    ename:VK_CUBIC_FILTER_WEIGHTS_CATMULL_ROM_QCOM
endif::VK_QCOM_filter_cubic_weights[]
****

include::{generated}/validity/structs/VkBlitImageInfo2.adoc[]
--

ifdef::VK_QCOM_filter_cubic_weights[]

If pname:filter is ename:VK_FILTER_CUBIC_EXT and if the pname:pNext chain of
slink:VkBlitImageInfo2 includes a sname:VkBlitImageCubicWeightsInfoQCOM
structure, then that structure specifies cubic weights are used in the blit.
If that structure is not present, then cubic weights are considered to be
ename:VK_CUBIC_FILTER_WEIGHTS_CATMULL_ROM_QCOM.

[open,refpage='VkBlitImageCubicWeightsInfoQCOM',desc='Structure specifying image blit cubic weight info',type='structs',alias='VkImageBlit2KHR']
--
:refpage: VkBlitImageCubicWeightsInfoQCOM

The sname:VkBlitImageCubicWeightsInfoQCOM structure is defined as:

include::{generated}/api/structs/VkBlitImageCubicWeightsInfoQCOM.adoc[]

  * pname:sType is a elink:VkStructureType value identifying this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:cubicWeights is a elink:VkCubicFilterWeightsQCOM value controlling
    cubic filter weights for the blit.

include::{generated}/validity/structs/VkBlitImageCubicWeightsInfoQCOM.adoc[]
--

endif::VK_QCOM_filter_cubic_weights[]


[open,refpage='VkImageBlit2',desc='Structure specifying an image blit operation',type='structs',alias='VkImageBlit2KHR']
--
:refpage: VkImageBlit2

The sname:VkImageBlit2 structure is defined as:

include::{generated}/api/structs/VkImageBlit2.adoc[]

ifdef::VK_KHR_copy_commands2[]
or the equivalent

include::{generated}/api/structs/VkImageBlit2KHR.adoc[]
endif::VK_KHR_copy_commands2[]

  * pname:sType is a elink:VkStructureType value identifying this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:srcSubresource is the subresource to blit from.
  * pname:srcOffsets is a pointer to an array of two slink:VkOffset3D
    structures specifying the bounds of the source region within
    pname:srcSubresource.
  * pname:dstSubresource is the subresource to blit into.
  * pname:dstOffsets is a pointer to an array of two slink:VkOffset3D
    structures specifying the bounds of the destination region within
    pname:dstSubresource.

For each element of the pname:pRegions array, a blit operation is performed
for the specified source and destination regions.

.Valid Usage
****
include::{chapters}/commonvalidity/image_blit_common.adoc[]
****

include::{generated}/validity/structs/VkImageBlit2.adoc[]
--

ifdef::VK_QCOM_rotated_copy_commands[]
For flink:vkCmdBlitImage2, each region copied can include a rotation.
To specify a rotated region, add slink:VkCopyCommandTransformInfoQCOM to the
pname:pNext chain of slink:VkImageBlit2.
For each region with a rotation specified,
<<copies-images-scaling-rotation,Image Blits with Scaling and Rotation>>
specifies how coordinates are rotated prior to sampling from the source
image.
When rotation is specified, the source and destination images must: each be
2D images, have a 1x1x1 <<formats-compatibility-classes,texel block
extent>>, and only one plane.
endif::VK_QCOM_rotated_copy_commands[]
endif::VK_VERSION_1_3,VK_KHR_copy_commands2[]

ifdef::VK_QCOM_rotated_copy_commands[]
include::{chapters}/VK_QCOM_rotated_copies/rotated_addressing_blits.adoc[]
endif::VK_QCOM_rotated_copy_commands[]


[[copies-resolve]]
== Resolving Multisample Images

[open,refpage='vkCmdResolveImage',desc='Resolve regions of an image',type='protos']
--
:refpage: vkCmdResolveImage

To resolve a multisample color image to a non-multisample color image, call:

include::{generated}/api/protos/vkCmdResolveImage.adoc[]

  * pname:commandBuffer is the command buffer into which the command will be
    recorded.
  * pname:srcImage is the source image.
  * pname:srcImageLayout is the layout of the source image subresources for
    the resolve.
  * pname:dstImage is the destination image.
  * pname:dstImageLayout is the layout of the destination image subresources
    for the resolve.
  * pname:regionCount is the number of regions to resolve.
  * pname:pRegions is a pointer to an array of slink:VkImageResolve
    structures specifying the regions to resolve.

During the resolve the samples corresponding to each pixel location in the
source are converted to a single sample before being written to the
destination.
If the source formats are floating-point or normalized types, the sample
values for each pixel are resolved in an implementation-dependent manner.
If the source formats are integer types, a single sample's value is selected
for each pixel.

pname:srcOffset and pname:dstOffset select the initial pname:x, pname:y, and
pname:z offsets in texels of the sub-regions of the source and destination
image data.
pname:extent is the size in texels of the source image to resolve in
pname:width, pname:height and pname:depth.
Each element of pname:pRegions must: be a region that is contained within
its corresponding image.

Resolves are done layer by layer starting with pname:baseArrayLayer member
of pname:srcSubresource for the source and pname:dstSubresource for the
destination.
pname:layerCount layers are resolved to the destination image.

.Valid Usage
****
include::{chapters}/commonvalidity/resolve_image_command_buffer_common.adoc[]
include::{chapters}/commonvalidity/resolve_image_common.adoc[]
****

include::{generated}/validity/protos/vkCmdResolveImage.adoc[]
--

[open,refpage='VkImageResolve',desc='Structure specifying an image resolve operation',type='structs']
--
:refpage: VkImageResolve

The sname:VkImageResolve structure is defined as:

include::{generated}/api/structs/VkImageResolve.adoc[]

  * pname:srcSubresource and pname:dstSubresource are
    slink:VkImageSubresourceLayers structures specifying the image
    subresources of the images used for the source and destination image
    data, respectively.
    Resolve of depth/stencil images is not supported.
  * pname:srcOffset and pname:dstOffset select the initial pname:x, pname:y,
    and pname:z offsets in texels of the sub-regions of the source and
    destination image data.
  * pname:extent is the size in texels of the source image to resolve in
    pname:width, pname:height and pname:depth.

.Valid Usage
****
include::{chapters}/commonvalidity/image_resolve_common.adoc[]
****

include::{generated}/validity/structs/VkImageResolve.adoc[]
--

ifdef::VK_VERSION_1_3,VK_KHR_copy_commands2[]

A more extensible version of the resolve image command is defined below.

[open,refpage='vkCmdResolveImage2',desc='Resolve regions of an image',type='protos',alias='vkCmdResolveImage2KHR']
--
:refpage: vkCmdResolveImage2

To resolve a multisample image to a non-multisample image, call:

ifdef::VK_VERSION_1_3[]
include::{generated}/api/protos/vkCmdResolveImage2.adoc[]
endif::VK_VERSION_1_3[]

ifdef::VK_VERSION_1_3+VK_KHR_copy_commands2[or the equivalent command]

ifdef::VK_KHR_copy_commands2[]
include::{generated}/api/protos/vkCmdResolveImage2KHR.adoc[]
endif::VK_KHR_copy_commands2[]

  * pname:commandBuffer is the command buffer into which the command will be
    recorded.
  * pname:pResolveImageInfo is a pointer to a slink:VkResolveImageInfo2
    structure describing the resolve parameters.

This command is functionally identical to flink:vkCmdResolveImage, but
includes extensible sub-structures that include pname:sType and pname:pNext
parameters, allowing them to be more easily extended.


.Valid Usage
****
include::{chapters}/commonvalidity/resolve_image_command_buffer_common.adoc[]
****

include::{generated}/validity/protos/vkCmdResolveImage2.adoc[]
--

[open,refpage='VkResolveImageInfo2',desc='Structure specifying parameters of resolve image command',type='structs',alias='VkResolveImageInfo2KHR']
--
:refpage: VkResolveImageInfo2

The sname:VkResolveImageInfo2 structure is defined as:

include::{generated}/api/structs/VkResolveImageInfo2.adoc[]

ifdef::VK_KHR_copy_commands2[]
or the equivalent

include::{generated}/api/structs/VkResolveImageInfo2KHR.adoc[]
endif::VK_KHR_copy_commands2[]

  * pname:sType is a elink:VkStructureType value identifying this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:srcImage is the source image.
  * pname:srcImageLayout is the layout of the source image subresources for
    the resolve.
  * pname:dstImage is the destination image.
  * pname:dstImageLayout is the layout of the destination image subresources
    for the resolve.
  * pname:regionCount is the number of regions to resolve.
  * pname:pRegions is a pointer to an array of slink:VkImageResolve2
    structures specifying the regions to resolve.

.Valid Usage
****
include::{chapters}/commonvalidity/resolve_image_common.adoc[]
****

include::{generated}/validity/structs/VkResolveImageInfo2.adoc[]
--

[open,refpage='VkImageResolve2',desc='Structure specifying an image resolve operation',type='structs',alias='VkImageResolve2KHR']
--
:refpage: VkImageResolve2

The sname:VkImageResolve2 structure is defined as:

include::{generated}/api/structs/VkImageResolve2.adoc[]

ifdef::VK_KHR_copy_commands2[]
or the equivalent

include::{generated}/api/structs/VkImageResolve2KHR.adoc[]
endif::VK_KHR_copy_commands2[]

  * pname:sType is a elink:VkStructureType value identifying this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:srcSubresource and pname:dstSubresource are
    slink:VkImageSubresourceLayers structures specifying the image
    subresources of the images used for the source and destination image
    data, respectively.
    Resolve of depth/stencil images is not supported.
  * pname:srcOffset and pname:dstOffset select the initial pname:x, pname:y,
    and pname:z offsets in texels of the sub-regions of the source and
    destination image data.
  * pname:extent is the size in texels of the source image to resolve in
    pname:width, pname:height and pname:depth.

.Valid Usage
****
include::{chapters}/commonvalidity/image_resolve_common.adoc[]
****

include::{generated}/validity/structs/VkImageResolve2.adoc[]
--
endif::VK_VERSION_1_3,VK_KHR_copy_commands2[]

ifdef::VK_KHR_object_refresh[]
include::{chapters}/VK_KHR_object_refresh/copies.adoc[]
endif::VK_KHR_object_refresh[]

ifdef::VK_AMD_buffer_marker[]
include::{chapters}/VK_AMD_buffer_marker/copies.adoc[]
endif::VK_AMD_buffer_marker[]