src/chapters/copies.txt

// Copyright 2015-2021 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
depending on the type of data transfer.
Data can: be copied between buffer objects with
ifdef::VK_KHR_copy_commands2[]
fname:vkCmdCopyBuffer2KHR and
endif::VK_KHR_copy_commands2[]
fname:vkCmdCopyBuffer and a portion of an image can: be copied to another
image with
ifdef::VK_KHR_copy_commands2[]
fname:vkCmdCopyImage2KHR and
endif::VK_KHR_copy_commands2[]
fname:vkCmdCopyImage.
Image data can: also be copied to and from buffer memory using
ifndef::VK_KHR_copy_commands2[]
fname:vkCmdCopyImageToBuffer and fname:vkCmdCopyBufferToImage.
endif::VK_KHR_copy_commands2[]
ifdef::VK_KHR_copy_commands2[]
fname:vkCmdCopyImageToBuffer2KHR, fname:vkCmdCopyImageToBuffer,
fname:vkCmdCopyBufferToImage2KHR, and fname:vkCmdCopyBufferToImage.
endif::VK_KHR_copy_commands2[]
Image data can: be blitted (with or without scaling and filtering) with
ifdef::VK_KHR_copy_commands2[]
fname:vkCmdBlitImage2KHR and
endif::VK_KHR_copy_commands2[]
fname:vkCmdBlitImage.
Multisampled images can: be resolved to a non-multisampled image with
ifdef::VK_KHR_copy_commands2[]
fname:vkCmdResolveImage2KHR and
endif::VK_KHR_copy_commands2[]
fname:vkCmdResolveImage.


== Common Operation

The following valid usage rules apply to all copy commands:

  * Copy commands must: be recorded outside of a render pass instance.
  * The set of all bytes bound to all the source regions must: not overlap
    the set of all bytes bound to the destination regions.
  * The set of all bytes bound to each destination region must: not overlap
    the set of all bytes bound to another destination region.
  * Copy regions must: be non-empty.
  * Regions must: not extend outside the bounds of the buffer or image
    level, except that regions of compressed images can: extend as far as
    the dimension of the image level rounded up to a complete compressed
    texel block.
  * Source image subresources must: be in either the
    ename:VK_IMAGE_LAYOUT_GENERAL or
    ename:VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL layout.
    Destination image subresources must: be in the
ifdef::VK_KHR_shared_presentable_image[]
    ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR,
endif::VK_KHR_shared_presentable_image[]
    ename:VK_IMAGE_LAYOUT_GENERAL or
    ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL layout.
    As a consequence, if an image subresource is used as both source and
    destination of a copy, it must: be in the ename:VK_IMAGE_LAYOUT_GENERAL
    layout.
ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[]
  * Source images must: have ename:VK_FORMAT_FEATURE_TRANSFER_SRC_BIT in
    their <<resources-image-format-features,format features>>.
  * Destination images must: have ename:VK_FORMAT_FEATURE_TRANSFER_DST_BIT
    in their <<resources-image-format-features,format features>>.
endif::VK_VERSION_1_1,VK_KHR_maintenance1[]
  * Source buffers must: have been created with the
    ename:VK_BUFFER_USAGE_TRANSFER_SRC_BIT usage bit enabled and destination
    buffers must: have been created with the
    ename:VK_BUFFER_USAGE_TRANSFER_DST_BIT usage bit enabled.
ifndef::VK_VERSION_1_2+VK_EXT_separate_stencil_usage[]
  * Source images must: have been created with
    ename:VK_IMAGE_USAGE_TRANSFER_SRC_BIT set in
    slink:VkImageCreateInfo::pname:usage
  * Destination images must: have been created with
    ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT set in
    slink:VkImageCreateInfo::pname:usage
endif::VK_VERSION_1_2+VK_EXT_separate_stencil_usage[]
ifdef::VK_VERSION_1_2,VK_EXT_separate_stencil_usage[]
  * If the stencil aspect of source image is accessed, and the source image
    was not created with <<VkImageStencilUsageCreateInfo,separate stencil
    usage>>, the source image must: have been created with
    ename:VK_IMAGE_USAGE_TRANSFER_SRC_BIT set in
    slink:VkImageCreateInfo::pname:usage
  * If the stencil aspect of destination image is accessed, and the
    destination image was not created with
    <<VkImageStencilUsageCreateInfo,separate stencil usage>>, the
    destination image must: have been created with
    ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT set in
    slink:VkImageCreateInfo::pname:usage
  * If the stencil aspect of source image is accessed, and the source image
    was created with <<VkImageStencilUsageCreateInfo,separate stencil
    usage>>, the source image must: have been created with
    ename:VK_IMAGE_USAGE_TRANSFER_SRC_BIT set in
    slink:VkImageStencilUsageCreateInfo::pname:stencilUsage
  * If the stencil aspect of destination image is accessed, and the
    destination image was created with
    <<VkImageStencilUsageCreateInfo,separate stencil usage>>, the
    destination image must: have been created with
    ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT set in
    slink:VkImageStencilUsageCreateInfo::pname:stencilUsage
  * If non-stencil aspects of a source image are accessed, the source image
    must: have been created with ename:VK_IMAGE_USAGE_TRANSFER_SRC_BIT set
    in slink:VkImageCreateInfo::pname:usage
  * If non-stencil aspects of a destination image are accessed, the
    destination image must: have been created with
    ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT set in
    slink:VkImageCreateInfo::pname:usage
endif::VK_VERSION_1_2,VK_EXT_separate_stencil_usage[]

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.txt[]

  * 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 region in pname:pRegions is copied from the source buffer to the same
region of the destination buffer.
pname:srcBuffer and pname:dstBuffer can: be the same buffer or alias the
same memory, but the resulting values are undefined: if the copy regions
overlap in memory.

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

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

[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.txt[]

  * 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.txt[]
****

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

ifdef::VK_KHR_copy_commands2[]

A more extensible version of the copy buffer command is defined below.

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

To copy data between buffer objects, call:

include::{generated}/api/protos/vkCmdCopyBuffer2KHR.txt[]

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

This command is functionally identical to flink:vkCmdCopyBuffer, 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_buffer_command_buffer_common.txt[]
****

include::{generated}/validity/protos/vkCmdCopyBuffer2KHR.txt[]
--

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

The sname:VkCopyBufferInfo2KHR structure is defined as:

include::{generated}/api/structs/VkCopyBufferInfo2KHR.txt[]

  * pname:sType is the type of 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:VkBufferCopy2KHR
    structures specifying the regions to copy.

Members defined by this structure with the same name as parameters in
flink:vkCmdCopyBuffer have the identical effect to those parameters; the
child structure slink:VkBufferCopy2KHR is a variant of slink:VkBufferCopy
which includes pname:sType and pname:pNext parameters, allowing it to be
extended.

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

include::{generated}/validity/structs/VkCopyBufferInfo2KHR.txt[]
--

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

The sname:VkBufferCopy2KHR structure is defined as:

include::{generated}/api/structs/VkBufferCopy2KHR.txt[]

  * pname:sType is the type of 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.txt[]
****

include::{generated}/validity/structs/VkBufferCopy2KHR.txt[]
--

endif::VK_KHR_copy_commands2[]


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

fname:vkCmdCopyImage performs image copies in a similar manner to a host
memcpy.
It does not perform general-purpose conversions such as scaling, resizing,
blending, color-space conversion, or format conversions.
Rather, it simply copies raw image data.
fname:vkCmdCopyImage can: copy between images with different formats,
provided the formats are compatible as defined below.

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

To copy data between image objects, call:

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

  * 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 region in pname:pRegions is copied from the source image to the same
region of the destination image.
pname:srcImage and pname:dstImage can: be the same image or alias the same
memory.

[[copies-images-format-compatibility]]
The formats of pname:srcImage and pname:dstImage must: be compatible.
Formats are compatible if they share the same class, as shown in the
<<formats-compatibility,Compatible Formats>> table.
Depth/stencil formats must: match exactly.

ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
If either pname:srcImage or pname:dstImage has a
<<formats-requiring-sampler-ycbcr-conversion, _multi-planar_ format>>,
regions of each plane to be copied must: be specified separately using the
pname:srcSubresource and pname:dstSubresource members of the
slink:VkImageCopy structure.
In this case, the pname:aspectMask of the pname:srcSubresource or
pname:dstSubresource that refers to the multi-planar image must: be
ename:VK_IMAGE_ASPECT_PLANE_0_BIT, ename:VK_IMAGE_ASPECT_PLANE_1_BIT, or
ename:VK_IMAGE_ASPECT_PLANE_2_BIT.
For the purposes of fname:vkCmdCopyImage, each plane of a multi-planar image
is treated as having the format listed in <<formats-compatible-planes>> for
the plane identified by the pname:aspectMask of the corresponding
subresource.
This applies both to elink:VkFormat and to coordinates used in the copy,
which correspond to texels in the _plane_ rather than how these texels map
to coordinates in the image as a whole.

[NOTE]
.Note
====
For example, the ename:VK_IMAGE_ASPECT_PLANE_1_BIT plane of a
ename:VK_FORMAT_G8_B8R8_2PLANE_420_UNORM image is compatible with an image
of format ename:VK_FORMAT_R8G8_UNORM and (less usefully) with the
ename:VK_IMAGE_ASPECT_PLANE_0_BIT plane of an image of format
ename:VK_FORMAT_G10X6_B10X6_R10X6_3PLANE_420_UNORM_3PACK16, as each texel is
2 bytes in size.
====
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]

[[copies-images-format-size-compatibility]]
fname:vkCmdCopyImage allows copying between _size-compatible_ compressed and
uncompressed internal formats.
Formats are size-compatible if the texel block size of the uncompressed
format is equal to the texel block size of the compressed format.
Such a copy does not perform on-the-fly compression or decompression.
When copying from an uncompressed format to a compressed format, each texel
of uncompressed data of the source image is copied as a raw value to the
corresponding compressed texel block of the destination image.
When copying from a compressed format to an uncompressed format, each
compressed texel block of the source image is copied as a raw value to the
corresponding texel of uncompressed data in the destination image.
Thus, for example, it is legal to copy between a 128-bit uncompressed format
and a compressed format which has a 128-bit sized compressed texel block
representing 4{times}4 texels (using 8 bits per texel), or between a 64-bit
uncompressed format and a compressed format which has a 64-bit sized
compressed texel block representing 4{times}4 texels (using 4 bits per
texel).

When copying between compressed and uncompressed formats the pname:extent
members represent the texel dimensions of the source image and not the
destination.
When copying from a compressed image to an uncompressed image the image
texel dimensions written to the uncompressed image will be source extent
divided by the compressed texel block dimensions.
When copying from an uncompressed image to a compressed image the image
texel dimensions written to the compressed image will be the source extent
multiplied by the compressed texel block dimensions.
In both cases the number of bytes read and the number of bytes written will
be identical.

Copying to or from block-compressed images is typically done in multiples of
the compressed texel block size.
For this reason the pname:extent must: be a multiple of the compressed texel
block dimension.
There is one exception to this rule which is required: to handle compressed
images created with dimensions that are not a multiple of the compressed
texel block dimensions: if the pname:srcImage is compressed, then:

  * If pname:extent.width is not a multiple of the compressed texel block
    width, then [eq]#(pname:extent.width {plus} pname:srcOffset.x)# must:
    equal the image subresource width.
  * If pname:extent.height is not a multiple of the compressed texel block
    height, then [eq]#(pname:extent.height {plus} pname:srcOffset.y)# must:
    equal the image subresource height.
  * If pname:extent.depth is not a multiple of the compressed texel block
    depth, then [eq]#(pname:extent.depth {plus} pname:srcOffset.z)# must:
    equal the image subresource depth.

Similarly, if the pname:dstImage is compressed, then:

  * If pname:extent.width is not a multiple of the compressed texel block
    width, then [eq]#(pname:extent.width {plus} pname:dstOffset.x)# must:
    equal the image subresource width.
  * If pname:extent.height is not a multiple of the compressed texel block
    height, then [eq]#(pname:extent.height {plus} pname:dstOffset.y)# must:
    equal the image subresource height.
  * If pname:extent.depth is not a multiple of the compressed texel block
    depth, then [eq]#(pname:extent.depth {plus} pname:dstOffset.z)# must:
    equal the image subresource depth.

This allows the last compressed texel block of the image in each
non-multiple dimension to be included as a source or destination of the
copy.

ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
"`etext:_422`" image formats that are not
<<formats-requiring-sampler-ycbcr-conversion,_multi-planar_>> are treated as
having a 2{times}1 compressed texel block for the purposes of these rules.
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]

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

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

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

[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.txt[]

  * 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.

ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[]
For ename:VK_IMAGE_TYPE_3D images, copies are performed slice by slice
starting with the pname:z member of the pname:srcOffset or pname:dstOffset,
and copying pname:depth slices.
For images with multiple layers, copies are performed layer by layer
starting with the pname:baseArrayLayer member of the pname:srcSubresource or
pname:dstSubresource and copying pname:layerCount layers.
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.
endif::VK_VERSION_1_1,VK_KHR_maintenance1[]
ifndef::VK_VERSION_1_1,VK_KHR_maintenance1[]
Copies 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 copied to the destination image.
endif::VK_VERSION_1_1,VK_KHR_maintenance1[]

ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
Copies involving a <<formats-requiring-sampler-ycbcr-conversion,
multi-planar image format>> specify the region to be copied in terms of the
_plane_ to be copied, not the coordinates of the multi-planar image.
This means that copies accessing the R/B planes of "`etext:_422`" format
images must: fit the copied region within half the pname:width of the parent
image, and that copies accessing the R/B planes of "`etext:_420`" format
images must: fit the copied region within half the pname:width and
pname:height of the parent image.
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]

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

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

[open,refpage='VkImageSubresourceLayers',desc='Structure specifying an image subresource layers',type='structs']
--

The sname:VkImageSubresourceLayers structure is defined as:

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

  * 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-01700]]
    pname:layerCount must: be greater than 0
****

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

ifdef::VK_KHR_copy_commands2[]

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

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

To copy data between image objects, call:

include::{generated}/api/protos/vkCmdCopyImage2KHR.txt[]

  * pname:commandBuffer is the command buffer into which the command will be
    recorded.
  * pname:pCopyImageInfo is a pointer to a slink:VkCopyImageInfo2KHR
    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.txt[]
****

include::{generated}/validity/protos/vkCmdCopyImage2KHR.txt[]
--


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

The sname:VkCopyImageInfo2KHR structure is defined as:

include::{generated}/api/structs/VkCopyImageInfo2KHR.txt[]

  * pname:sType is the type of 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:VkImageCopy2KHR
    structures specifying the regions to copy.


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

include::{generated}/validity/structs/VkCopyImageInfo2KHR.txt[]
--

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

The sname:VkImageCopy2KHR structure is defined as:

include::{generated}/api/structs/VkImageCopy2KHR.txt[]

  * pname:sType is the type of 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.txt[]
****

include::{generated}/validity/structs/VkImageCopy2KHR.txt[]
--

endif::VK_KHR_copy_commands2[]


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

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

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

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

  * 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 region in pname:pRegions is copied from the specified region of the
source buffer to the specified region of the destination image.

ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
If pname:dstImage has a
<<formats-requiring-sampler-ycbcr-conversion,multi-planar format>>, regions
of each plane to be a target of a copy must: be specified separately using
the pname:pRegions member of the slink:VkBufferImageCopy structure.
In this case, the pname:aspectMask of pname:imageSubresource must: be
ename:VK_IMAGE_ASPECT_PLANE_0_BIT, ename:VK_IMAGE_ASPECT_PLANE_1_BIT, or
ename:VK_IMAGE_ASPECT_PLANE_2_BIT.
For the purposes of fname:vkCmdCopyBufferToImage, each plane of a
multi-planar image is treated as having the format listed in
<<formats-compatible-planes>> for the plane identified by the
pname:aspectMask of the corresponding subresource.
This applies both to elink:VkFormat and to coordinates used in the copy,
which correspond to texels in the _plane_ rather than how these texels map
to coordinates in the image as a whole.
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]

.Valid Usage
****
include::{chapters}/commonvalidity/copy_buffer_to_image_command_buffer_common.txt[]
  * [[VUID-vkCmdCopyBufferToImage-pRegions-06217]]
    The image region specified by each element of pname:pRegions must: be
    contained within the specified pname:imageSubresource of pname:dstImage
include::{chapters}/commonvalidity/copy_buffer_to_image_common.txt[]
  * [[VUID-vkCmdCopyBufferToImage-pRegions-06218]]
    For each element of pname:pRegions, 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-vkCmdCopyBufferToImage-pRegions-06219]]
    For each element of pname:pRegions, 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::{chapters}/commonvalidity/copy_bufferimage_to_imagebuffer_common.txt[]
****

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

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

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

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

  * 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 region in pname:pRegions is copied from the specified region of the
source image to the specified region of the destination buffer.

ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
If pname:srcImage has a <<formats-requiring-sampler-ycbcr-conversion,
multi-planar format>>, regions of each plane to be a source of a copy must:
be specified separately using the pname:pRegions member of the
slink:VkBufferImageCopy structure.
In this case, the pname:aspectMask of pname:imageSubresource must: be
ename:VK_IMAGE_ASPECT_PLANE_0_BIT, ename:VK_IMAGE_ASPECT_PLANE_1_BIT, or
ename:VK_IMAGE_ASPECT_PLANE_2_BIT.
For the purposes of fname:vkCmdCopyBufferToImage, each plane of a
multi-planar image is treated as having the format listed in
<<formats-compatible-planes>> for the plane identified by the
pname:aspectMask of the corresponding subresource.
This applies both to elink:VkFormat and to coordinates used in the copy,
which correspond to texels in the _plane_ rather than how these texels map
to coordinates in the image as a whole.
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]

.Valid Usage
****
include::{chapters}/commonvalidity/copy_image_to_buffer_command_buffer_common.txt[]
  * [[VUID-vkCmdCopyImageToBuffer-pRegions-06220]]
    The image region specified by each element of pname:pRegions must: be
    contained within the specified pname:imageSubresource of pname:srcImage
include::{chapters}/commonvalidity/copy_image_to_buffer_common.txt[]
  * [[VUID-vkCmdCopyImageToBuffer-pRegions-06221]]
    For each element of pname:pRegions, 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-vkCmdCopyImageToBuffer-pRegions-06222]]
    For each element of pname:pRegions, pname:imageOffset.y and
    [eq]#(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::{chapters}/commonvalidity/copy_bufferimage_to_imagebuffer_common.txt[]
****

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

[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.txt[]

  * 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.

When copying to or from a depth or stencil aspect, the data in buffer memory
uses a layout that is a (mostly) tightly packed representation of the depth
or stencil data.
Specifically:

  * data copied to or from the stencil aspect of any depth/stencil format is
    tightly packed with one ename:VK_FORMAT_S8_UINT value per texel.
  * data copied to or from the depth aspect of a ename:VK_FORMAT_D16_UNORM
    or ename:VK_FORMAT_D16_UNORM_S8_UINT format is tightly packed with one
    ename:VK_FORMAT_D16_UNORM value per texel.
  * data copied to or from the depth aspect of a ename:VK_FORMAT_D32_SFLOAT
    or ename:VK_FORMAT_D32_SFLOAT_S8_UINT format is tightly packed with one
    ename:VK_FORMAT_D32_SFLOAT value per texel.
  * data copied to or from the depth aspect of a
    ename:VK_FORMAT_X8_D24_UNORM_PACK32 or ename:VK_FORMAT_D24_UNORM_S8_UINT
    format is packed with one 32-bit word per texel with the D24 value in
    the LSBs of the word, and undefined: values in the eight MSBs.

[NOTE]
.Note
====
To copy both the depth and stencil aspects of a depth/stencil format, two
entries in pname:pRegions can: be used, where one specifies the depth aspect
in pname:imageSubresource, and the other specifies the stencil aspect.
====

Because depth or stencil aspect buffer to image copies may: require format
conversions on some implementations, they are not supported on queues that
do not support graphics.

When copying to a depth aspect,
ifdef::VK_EXT_depth_range_unrestricted[]
and the `apiext:VK_EXT_depth_range_unrestricted` extension is not enabled,
endif::VK_EXT_depth_range_unrestricted[]
the data in buffer memory must: be in the range [eq]#[0,1]#, or the
resulting values are undefined:.

Copies are done layer by layer starting with image layer
pname:baseArrayLayer member of pname:imageSubresource.
pname:layerCount layers are copied from the source image or to the
destination image.

[[blocked-image]]
For purpose of valid usage statements here and in related copy commands, a
_blocked image_ is defined as:

ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
  * an image with a _single-plane_, "`etext:_422`" format, which is treated
    as a format with a 2 {times} 1 compressed texel block, or
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
  * a compressed image.

.Valid Usage
****
include::{chapters}/commonvalidity/buffer_image_copy_common.txt[]
****

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

ifdef::VK_KHR_copy_commands2[]

More extensible versions of the commands to copy between buffers and images
are defined below.

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

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

include::{generated}/api/protos/vkCmdCopyBufferToImage2KHR.txt[]

  * pname:commandBuffer is the command buffer into which the command will be
    recorded.
  * pname:pCopyBufferToImageInfo is a pointer to a
    slink:VkCopyBufferToImageInfo2KHR 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.

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

include::{generated}/validity/protos/vkCmdCopyBufferToImage2KHR.txt[]
--

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

The sname:VkCopyBufferToImageInfo2KHR structure is defined as:

include::{generated}/api/structs/VkCopyBufferToImageInfo2KHR.txt[]

  * pname:sType is the type of 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:VkBufferImageCopy2KHR
    structures specifying the regions to copy.

.Valid Usage
****
ifndef::VK_QCOM_rotated_copy_commands[]
  * [[VUID-VkCopyBufferToImageInfo2KHR-pRegions-00172]]
    The image region specified by each element of pname:pRegions must: be
    contained within the specified pname:imageSubresource of pname:dstImage
endif::VK_QCOM_rotated_copy_commands[]
ifdef::VK_QCOM_rotated_copy_commands[]
  * [[VUID-VkCopyBufferToImageInfo2KHR-pRegions-04565]]
    If the image region specified by each element of pname:pRegions does not
    contain slink:VkCopyCommandTransformInfoQCOM in its pname:pNext chain,
    it must: be a region that is contained within the specified
    pname:imageSubresource of pname:dstImage
  * [[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: not be a <<blocked-image,blocked image>>
  * [[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.txt[]
  * [[VUID-VkCopyBufferToImageInfo2KHR-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-VkCopyBufferToImageInfo2KHR-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::{chapters}/commonvalidity/copy_bufferimage_to_imagebuffer_common.txt[]
****

include::{generated}/validity/structs/VkCopyBufferToImageInfo2KHR.txt[]
--

[open,refpage='vkCmdCopyImageToBuffer2KHR',desc='Copy image data into a buffer',type='protos']
--
:refpage: vkCmdCopyImageToBuffer2KHR
:imageparam: pname:srcImage

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

include::{generated}/api/protos/vkCmdCopyImageToBuffer2KHR.txt[]

  * pname:commandBuffer is the command buffer into which the command will be
    recorded.
  * pname:pCopyImageToBufferInfo is a pointer to a
    slink:VkCopyImageToBufferInfo2KHR 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.


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

include::{generated}/validity/protos/vkCmdCopyImageToBuffer2KHR.txt[]
--

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

The sname:VkCopyImageToBufferInfo2KHR structure is defined as:

include::{generated}/api/structs/VkCopyImageToBufferInfo2KHR.txt[]

  * pname:sType is the type of 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:VkBufferImageCopy2KHR
    structures specifying the regions to copy.

.Valid Usage
****
ifndef::VK_QCOM_rotated_copy_commands[]
  * [[VUID-VkCopyImageToBufferInfo2KHR-pRegions-00182]]
    The image region specified by each element of pname:pRegions must: be
    contained within the specified pname:imageSubresource of pname:srcImage
endif::VK_QCOM_rotated_copy_commands[]
ifdef::VK_QCOM_rotated_copy_commands[]
  * [[VUID-VkCopyImageToBufferInfo2KHR-pRegions-04566]]
    If the image region specified by each element of pname:pRegions does not
    contain slink:VkCopyCommandTransformInfoQCOM in its pname:pNext chain,
    it must: be contained within the specified pname:imageSubresource of
    pname:srcImage
  * [[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: not be a <<blocked-image,blocked image>>
  * [[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.txt[]
  * [[VUID-VkCopyImageToBufferInfo2KHR-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-VkCopyImageToBufferInfo2KHR-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::{chapters}/commonvalidity/copy_bufferimage_to_imagebuffer_common.txt[]
****

include::{generated}/validity/structs/VkCopyImageToBufferInfo2KHR.txt[]
--

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

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

include::{generated}/api/structs/VkBufferImageCopy2KHR.txt[]

  * pname:sType is the type of 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.

.Valid Usage
****
include::{chapters}/commonvalidity/buffer_image_copy_common.txt[]
****

include::{generated}/validity/structs/VkBufferImageCopy2KHR.txt[]
--
endif::VK_KHR_copy_commands2[]

ifdef::VK_QCOM_rotated_copy_commands[]
For both flink:vkCmdCopyBufferToImage2KHR and
flink:vkCmdCopyImageToBuffer2KHR, each region copied can include a rotation.
To specify a region with rotation, add the
slink:VkCopyCommandTransformInfoQCOM to the pname:pNext chain of
slink:VkBufferImageCopy2KHR.
When a rotation is specified, <<copies-buffers-images-rotation-addressing,
Buffer and Image Addressing with Rotation>> specifies how coordinates of
texels in the source region are rotated by pname:transform to produce texel
coordinates in the destination region.
When rotation is specified, the source and destination images must: each be
2D images.
They must: not be <<blocked-image,blocked images>> or have a
<<formats-requiring-sampler-ycbcr-conversion, multi-planar format>>.

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

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

  * pname:sType is the type of 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.

.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.txt[]
--

endif::VK_QCOM_rotated_copy_commands[]


[[copies-buffers-images-addressing]]
=== Buffer and Image Addressing

Pseudocode for image/buffer addressing of uncompressed formats is:

[source,c]
---------------------------------------------------
rowLength = region->bufferRowLength;
if (rowLength == 0)
    rowLength = region->imageExtent.width;

imageHeight = region->bufferImageHeight;
if (imageHeight == 0)
    imageHeight = region->imageExtent.height;

texelBlockSize = <texel block size of the format of the src/dstImage>;

address of (x,y,z) = region->bufferOffset + (((z * imageHeight) + y) * rowLength + x) * texelBlockSize;

where x,y,z range from (0,0,0) to region->imageExtent.{width,height,depth}.
---------------------------------------------------

Note that pname:imageOffset does not affect addressing calculations for
buffer memory.
Instead, pname:bufferOffset can: be used to select the starting address in
buffer memory.

For block-compressed formats, all parameters are still specified in texels
rather than compressed texel blocks, but the addressing math operates on
whole compressed texel blocks.
Pseudocode for compressed copy addressing is:

[source,c]
---------------------------------------------------
rowLength = region->bufferRowLength;
if (rowLength == 0)
    rowLength = region->imageExtent.width;

imageHeight = region->bufferImageHeight;
if (imageHeight == 0)
    imageHeight = region->imageExtent.height;

compressedTexelBlockSizeInBytes = <compressed texel block size taken from the src/dstImage>;
rowLength = (rowLength + compressedTexelBlockWidth - 1) / compressedTexelBlockWidth;
imageHeight = (imageHeight + compressedTexelBlockHeight - 1) / compressedTexelBlockHeight;

address of (x,y,z) = region->bufferOffset + (((z * imageHeight) + y) * rowLength + x) * compressedTexelBlockSizeInBytes;

where x,y,z range from (0,0,0) to region->imageExtent.{width/compressedTexelBlockWidth,height/compressedTexelBlockHeight,depth/compressedTexelBlockDepth}.
---------------------------------------------------

Copying to or from block-compressed images is typically done in multiples of
the compressed texel block size.
For this reason the pname:imageExtent must: be a multiple of the compressed
texel block dimension.
There is one exception to this rule which is required: to handle compressed
images created with dimensions that are not a multiple of the compressed
texel block dimensions:

  * If pname:imageExtent.width is not a multiple of the compressed texel
    block width, then [eq]#(pname:imageExtent.width {plus}
    pname:imageOffset.x)# must: equal the image subresource width.
  * If pname:imageExtent.height is not a multiple of the compressed texel
    block height, then [eq]#(pname:imageExtent.height {plus}
    pname:imageOffset.y)# must: equal the image subresource height.
  * If pname:imageExtent.depth is not a multiple of the compressed texel
    block depth, then [eq]#(pname:imageExtent.depth {plus}
    pname:imageOffset.z)# must: equal the image subresource depth.

This allows the last compressed texel block of the image in each
non-multiple dimension to be included as a source or destination of the
copy.

ifdef::VK_QCOM_rotated_copy_commands[]
include::{chapters}/VK_QCOM_rotated_copies/rotated_addressing_copies.txt[]
endif::VK_QCOM_rotated_copy_commands[]


[[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.txt[]

  * 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, unscaled 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.txt[]
include::{chapters}/commonvalidity/blit_image_common.txt[]
****

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

[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.txt[]

  * 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.txt[]
****

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

ifdef::VK_KHR_copy_commands2[]

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

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

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

include::{generated}/api/protos/vkCmdBlitImage2KHR.txt[]

  * pname:commandBuffer is the command buffer into which the command will be
    recorded.
  * pname:pBlitImageInfo is a pointer to a slink:VkBlitImageInfo2KHR
    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.txt[]
****

include::{generated}/validity/protos/vkCmdBlitImage2KHR.txt[]
--

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

The sname:VkBlitImageInfo2KHR structure is defined as:

include::{generated}/api/structs/VkBlitImageInfo2KHR.txt[]

  * pname:sType is the type of 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:VkImageBlit2KHR
    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.txt[]
ifdef::VK_QCOM_rotated_copy_commands[]
  * [[VUID-VkBlitImageInfo2KHR-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[]
****

include::{generated}/validity/structs/VkBlitImageInfo2KHR.txt[]
--

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

The sname:VkImageBlit2KHR structure is defined as:

include::{generated}/api/structs/VkImageBlit2KHR.txt[]

  * pname:sType is the type of 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.txt[]
****

include::{generated}/validity/structs/VkImageBlit2KHR.txt[]
--

ifdef::VK_QCOM_rotated_copy_commands[]
For flink:vkCmdBlitImage2KHR, each region copied can include a rotation.
To specify a rotated region, add slink:VkCopyCommandTransformInfoQCOM to the
pname:pNext chain of slink:VkImageBlit2KHR.
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.
They must: not be <<blocked-image,blocked images>> or have a
<<formats-requiring-sampler-ycbcr-conversion, multi-planar format>>.
endif::VK_QCOM_rotated_copy_commands[]

endif::VK_KHR_copy_commands2[]

ifdef::VK_QCOM_rotated_copy_commands[]
include::{chapters}/VK_QCOM_rotated_copies/rotated_addressing_blits.txt[]
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.txt[]

  * 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.txt[]
include::{chapters}/commonvalidity/resolve_image_common.txt[]
****

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

[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.txt[]

  * 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.txt[]
****

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

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

ifdef::VK_KHR_copy_commands2[]

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

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

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

include::{generated}/api/protos/vkCmdResolveImage2KHR.txt[]

  * pname:commandBuffer is the command buffer into which the command will be
    recorded.
  * pname:pResolveImageInfo is a pointer to a slink:VkResolveImageInfo2KHR
    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.txt[]
****

include::{generated}/validity/protos/vkCmdResolveImage2KHR.txt[]
--

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

The sname:VkResolveImageInfo2KHR structure is defined as:

include::{generated}/api/structs/VkResolveImageInfo2KHR.txt[]

  * pname:sType is the type of 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:VkImageResolve2KHR
    structures specifying the regions to resolve.

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

include::{generated}/validity/structs/VkResolveImageInfo2KHR.txt[]
--

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

The sname:VkImageResolve2KHR structure is defined as:

include::{generated}/api/structs/VkImageResolve2KHR.txt[]

  * pname:sType is the type of 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.txt[]
****

include::{generated}/validity/structs/VkImageResolve2KHR.txt[]
--

endif::VK_KHR_copy_commands2[]