// Copyright (c) 2015-2017 The Khronos Group Inc.
// Copyright notice at https://www.khronos.org/registry/speccopyright.html

[[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 fname:vkCmdCopyBuffer and a
portion of an image can: be copied to another image with
fname:vkCmdCopyImage.
Image data can: also be copied to and from buffer memory using
fname:vkCmdCopyImageToBuffer and fname:vkCmdCopyBufferToImage.
Image data can: be blitted (with or without scaling and filtering) with
fname:vkCmdBlitImage.
Multisampled images can: be resolved to a non-multisampled image with
fname:vkCmdResolveImage.


== Common Operation

Some rules for valid operation are common to all copy commands:

  * Copy commands must: be recorded outside of a render pass instance.
  * For non-sparse resources, the union of the source regions in a given
    buffer or image must: not overlap the union of the destination regions
    in the same buffer or image.
  * For sparse resources, the set of bytes used by all the source regions
    must: not intersect the set of bytes used by all the destination
    regions.
  * 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_KHR_maintenance1[]
  * Source images must: use a format that supports
    ename:VK_FORMAT_FEATURE_TRANSFER_SRC_BIT_KHR, which is indicated by
    sname:VkFormatProperties::pname:linearTilingFeatures (for linearly tiled
    images) or sname:VkFormatProperties::pname:optimalTilingFeatures (for
    optimally tiled images) - as returned by
    flink:vkGetPhysicalDeviceFormatProperties.
  * Destination images must: use a format that supports
    ename:VK_FORMAT_FEATURE_TRANSFER_DST_BIT_KHR, which is indicated by
    sname:VkFormatProperties::pname:linearTilingFeatures (for linearly tiled
    images) or sname:VkFormatProperties::pname:optimalTilingFeatures (for
    optimally tiled images) - as returned by
    flink:vkGetPhysicalDeviceFormatProperties.
endif::VK_KHR_maintenance1[]
  * Source images must: have been created with the
    ename:VK_IMAGE_USAGE_TRANSFER_SRC_BIT usage bit enabled and destination
    images must: have been created with the
    ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT usage bit enabled.
  * 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.

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


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

// refBegin vkCmdCopyBuffer Copy data between buffer regions

To copy data between buffer objects, call:

include::../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 result is undefined if the copy regions overlap in
memory.

.Valid Usage
****
  * [[VUID-vkCmdCopyBuffer-size-00112]]
    The pname:size member of a given element of pname:pRegions must: be
    greater than `0`
  * [[VUID-vkCmdCopyBuffer-srcOffset-00113]]
    The pname:srcOffset member of a given element of pname:pRegions must: be
    less than the size of pname:srcBuffer
  * [[VUID-vkCmdCopyBuffer-dstOffset-00114]]
    The pname:dstOffset member of a given element of pname:pRegions must: be
    less than the size of pname:dstBuffer
  * [[VUID-vkCmdCopyBuffer-size-00115]]
    The pname:size member of a given element of pname:pRegions must: be less
    than or equal to the size of pname:srcBuffer minus pname:srcOffset
  * [[VUID-vkCmdCopyBuffer-size-00116]]
    The pname:size member of a given element of pname:pRegions must: be less
    than or equal to the size of pname:dstBuffer minus pname:dstOffset
  * [[VUID-vkCmdCopyBuffer-pRegions-00117]]
    The union of the source regions, and the union of the destination
    regions, specified by the elements of pname:pRegions, must: not overlap
    in memory
  * [[VUID-vkCmdCopyBuffer-srcBuffer-00118]]
    pname:srcBuffer must: have been created with
    ename:VK_BUFFER_USAGE_TRANSFER_SRC_BIT usage flag
  * [[VUID-vkCmdCopyBuffer-srcBuffer-00119]]
    If pname:srcBuffer is non-sparse then it must: be bound completely and
    contiguously to a single sname:VkDeviceMemory object
  * [[VUID-vkCmdCopyBuffer-dstBuffer-00120]]
    pname:dstBuffer must: have been created with
    ename:VK_BUFFER_USAGE_TRANSFER_DST_BIT usage flag
  * [[VUID-vkCmdCopyBuffer-dstBuffer-00121]]
    If pname:dstBuffer is non-sparse then it must: be bound completely and
    contiguously to a single sname:VkDeviceMemory object
****

include::../validity/protos/vkCmdCopyBuffer.txt[]

// refBegin VkBufferCopy Structure specifying a buffer copy operation

The sname:VkBufferCopy structure is defined as:

include::../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.

include::../validity/structs/VkBufferCopy.txt[]


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

// refBegin vkCmdCopyImage Copy data between images

To copy data between image objects, call:

include::../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 considered compatible if their element size is the same between
both formats.
For example, ename:VK_FORMAT_R8G8B8A8_UNORM is compatible with
ename:VK_FORMAT_R32_UINT because both texels are 4 bytes in size.
Depth/stencil formats must: match exactly.

fname:vkCmdCopyImage allows copying between size-compatible compressed and
uncompressed internal formats.
Formats are size-compatible if the element size of the uncompressed format
is equal to the element size (compressed 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 4x4 texels (using 8 bits per texel), or between a 64-bit
uncompressed format and a compressed format which has a 64-bit sized
compressed texel block representing 4x4 texels (using 4 bits per texel).

When copying between compressed and uncompressed formats the 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 + 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 + 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 + 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 + 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 + 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 + 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.

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

.Valid Usage
****
  * [[VUID-vkCmdCopyImage-pRegions-00122]]
    The source region specified by a given element of pname:pRegions must:
    be a region that is contained within pname:srcImage
  * [[VUID-vkCmdCopyImage-pRegions-00123]]
    The destination region specified by a given element of pname:pRegions
    must: be a region that is contained within pname:dstImage
  * [[VUID-vkCmdCopyImage-pRegions-00124]]
    The union of all source regions, and the union of all destination
    regions, specified by the elements of pname:pRegions, must: not overlap
    in memory
ifdef::VK_KHR_maintenance1[]
  * [[VUID-vkCmdCopyImage-srcImage-00125]]
    pname:srcImage must: use a format that supports
    ename:VK_FORMAT_FEATURE_TRANSFER_SRC_BIT_KHR, which is indicated by
    sname:VkFormatProperties::pname:linearTilingFeatures (for linearly tiled
    images) or sname:VkFormatProperties::pname:optimalTilingFeatures (for
    optimally tiled images) - as returned by
    flink:vkGetPhysicalDeviceFormatProperties
endif::VK_KHR_maintenance1[]
  * [[VUID-vkCmdCopyImage-srcImage-00126]]
    pname:srcImage must: have been created with
    ename:VK_IMAGE_USAGE_TRANSFER_SRC_BIT usage flag
  * [[VUID-vkCmdCopyImage-srcImage-00127]]
    If pname:srcImage is non-sparse then it must: be bound completely and
    contiguously to a single sname:VkDeviceMemory object
  * [[VUID-vkCmdCopyImage-srcImageLayout-00128]]
    pname:srcImageLayout must: specify the layout of the image subresources
    of pname:srcImage specified in pname:pRegions at the time this command
    is executed on a sname:VkDevice
  * [[VUID-vkCmdCopyImage-srcImageLayout-00129]]
    pname:srcImageLayout must: be
ifdef::VK_KHR_shared_presentable_image[]
    ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR,
endif::VK_KHR_shared_presentable_image[]
    ename:VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL or
    ename:VK_IMAGE_LAYOUT_GENERAL
ifdef::VK_KHR_maintenance1[]
  * [[VUID-vkCmdCopyImage-dstImage-00130]]
    pname:dstImage must: use a format that supports
    ename:VK_FORMAT_FEATURE_TRANSFER_DST_BIT_KHR, which is indicated by
    sname:VkFormatProperties::pname:linearTilingFeatures (for linearly tiled
    images) or sname:VkFormatProperties::pname:optimalTilingFeatures (for
    optimally tiled images) - as returned by
    flink:vkGetPhysicalDeviceFormatProperties
endif::VK_KHR_maintenance1[]
  * [[VUID-vkCmdCopyImage-dstImage-00131]]
    pname:dstImage must: have been created with
    ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT usage flag
  * [[VUID-vkCmdCopyImage-dstImage-00132]]
    If pname:dstImage is non-sparse then it must: be bound completely and
    contiguously to a single sname:VkDeviceMemory object
  * [[VUID-vkCmdCopyImage-dstImageLayout-00133]]
    pname:dstImageLayout must: specify the layout of the image subresources
    of pname:dstImage specified in pname:pRegions at the time this command
    is executed on a sname:VkDevice
  * [[VUID-vkCmdCopyImage-dstImageLayout-00134]]
    pname:dstImageLayout must: be
ifdef::VK_KHR_shared_presentable_image[]
    ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR,
endif::VK_KHR_shared_presentable_image[]
    ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL or
    ename:VK_IMAGE_LAYOUT_GENERAL
  * [[VUID-vkCmdCopyImage-srcImage-00135]]
    The elink:VkFormat of each of pname:srcImage and pname:dstImage must: be
    compatible, as defined <<copies-images-format-compatibility, below>>
  * [[VUID-vkCmdCopyImage-srcImage-00136]]
    The sample count of pname:srcImage and pname:dstImage must: match
****

include::../validity/protos/vkCmdCopyImage.txt[]

// refBegin VkImageCopy Structure specifying an image copy operation

The sname:VkImageCopy structure is defined as:

include::../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 x, y, and 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 copy in
    pname:width, pname:height and pname:depth.

ifdef::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_KHR_maintenance1[]
ifndef::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_KHR_maintenance1[]

.Valid Usage
****
  * [[VUID-VkImageCopy-aspectMask-00137]]
    The pname:aspectMask member of pname:srcSubresource and
    pname:dstSubresource must: match
ifndef::VK_KHR_maintenance1[]
  * [[VUID-VkImageCopy-layerCount-00138]]
    The pname:layerCount member of pname:srcSubresource and
    pname:dstSubresource must: match
  * [[VUID-VkImageCopy-srcImage-00139]]
    If either of the calling command's pname:srcImage or pname:dstImage
    parameters are of elink:VkImageType ename:VK_IMAGE_TYPE_3D, the
    pname:baseArrayLayer and pname:layerCount members of both
    pname:srcSubresource and pname:dstSubresource must: be `0` and `1`,
    respectively
endif::VK_KHR_maintenance1[]
ifdef::VK_KHR_maintenance1[]
  * [[VUID-VkImageCopy-extent-00140]]
    The number of slices of the pname:extent (for 3D) or layers of the
    pname:srcSubresource (for non-3D) must: match the number of slices of
    the pname:extent (for 3D) or layers of the pname:dstSubresource (for
    non-3D)
  * [[VUID-VkImageCopy-srcImage-00141]]
    If either of the calling command's pname:srcImage or pname:dstImage
    parameters are of elink:VkImageType ename:VK_IMAGE_TYPE_3D, the
    pname:baseArrayLayer and pname:layerCount members of the corresponding
    subresource must: be `0` and `1`, respectively
endif::VK_KHR_maintenance1[]
  * [[VUID-VkImageCopy-aspectMask-00142]]
    The pname:aspectMask member of pname:srcSubresource must: specify
    aspects present in the calling command's pname:srcImage
  * [[VUID-VkImageCopy-aspectMask-00143]]
    The pname:aspectMask member of pname:dstSubresource must: specify
    aspects present in the calling command's pname:dstImage
  * [[VUID-VkImageCopy-srcOffset-00144]]
    pname:srcOffset.x and (pname:extent.width + pname:srcOffset.x) must:
    both be greater than or equal to `0` and less than or equal to the
    source image subresource width
  * [[VUID-VkImageCopy-srcOffset-00145]]
    pname:srcOffset.y and (pname:extent.height + pname:srcOffset.y) must:
    both be greater than or equal to `0` and less than or equal to the
    source image subresource height
  * [[VUID-VkImageCopy-srcImage-00146]]
    If the calling command's pname:srcImage is of type
    ename:VK_IMAGE_TYPE_1D, then pname:srcOffset.y must: be `0` and
    pname:extent.height must: be `1`.
  * [[VUID-VkImageCopy-srcOffset-00147]]
    pname:srcOffset.z and (pname:extent.depth + pname:srcOffset.z) must:
    both be greater than or equal to `0` and less than or equal to the
    source image subresource depth
  * [[VUID-VkImageCopy-srcImage-00148]]
    If the calling command's pname:srcImage is of type
    ename:VK_IMAGE_TYPE_1D or ename:VK_IMAGE_TYPE_2D, then pname:srcOffset.z
    must: be `0` and pname:extent.depth must: be `1`.
  * [[VUID-VkImageCopy-srcSubresource-00149]]
    pname:srcSubresource.baseArrayLayer must: be less than and
    (pname:srcSubresource.layerCount + pname:srcSubresource.baseArrayLayer)
    must: be less than or equal to the number of layers in the source image
  * [[VUID-VkImageCopy-dstOffset-00150]]
    pname:dstOffset.x and (pname:extent.width + pname:dstOffset.x) must:
    both be greater than or equal to `0` and less than or equal to the
    destination image subresource width
  * [[VUID-VkImageCopy-dstOffset-00151]]
    pname:dstOffset.y and (pname:extent.height + pname:dstOffset.y) must:
    both be greater than or equal to `0` and less than or equal to the
    destination image subresource height
  * [[VUID-VkImageCopy-dstImage-00152]]
    If the calling command's pname:dstImage is of type
    ename:VK_IMAGE_TYPE_1D, then pname:dstOffset.y must: be `0` and
    pname:extent.height must: be `1`.
  * [[VUID-VkImageCopy-dstOffset-00153]]
    pname:dstOffset.z and (pname:extent.depth + pname:dstOffset.z) must:
    both be greater than or equal to `0` and less than or equal to the
    destination image subresource depth
  * [[VUID-VkImageCopy-dstImage-00154]]
    If the calling command's pname:dstImage is of type
    ename:VK_IMAGE_TYPE_1D or ename:VK_IMAGE_TYPE_2D, then pname:dstOffset.z
    must: be `0` and pname:extent.depth must: be `1`.
  * [[VUID-VkImageCopy-dstSubresource-00155]]
    pname:dstSubresource.baseArrayLayer must: be less than and
    (pname:dstSubresource.layerCount + pname:dstSubresource.baseArrayLayer)
    must: be less than or equal to the number of layers in the destination
    image
  * [[VUID-VkImageCopy-srcOffset-00157]]
    If the calling command's pname:srcImage is a compressed format image,
    all members of pname:srcOffset must: be a multiple of the corresponding
    dimensions of the compressed texel block
  * [[VUID-VkImageCopy-extent-00158]]
    If the calling command's pname:srcImage is a compressed format image,
    pname:extent.width must: be a multiple of the compressed texel block
    width or (pname:extent.width + pname:srcOffset.x) must: equal the source
    image subresource width
  * [[VUID-VkImageCopy-extent-00159]]
    If the calling command's pname:srcImage is a compressed format image,
    pname:extent.height must: be a multiple of the compressed texel block
    height or (pname:extent.height + pname:srcOffset.y) must: equal the
    source image subresource height
  * [[VUID-VkImageCopy-extent-00160]]
    If the calling command's pname:srcImage is a compressed format image,
    pname:extent.depth must: be a multiple of the compressed texel block
    depth or (pname:extent.depth + pname:srcOffset.z) must: equal the source
    image subresource depth
  * [[VUID-VkImageCopy-dstOffset-00162]]
    If the calling command's pname:dstImage is a compressed format image,
    all members of pname:dstOffset must: be a multiple of the corresponding
    dimensions of the compressed texel block
  * [[VUID-VkImageCopy-extent-00163]]
    If the calling command's pname:dstImage is a compressed format image,
    pname:extent.width must: be a multiple of the compressed texel block
    width or (pname:extent.width + pname:dstOffset.x) must: equal the
    destination image subresource width
  * [[VUID-VkImageCopy-extent-00164]]
    If the calling command's pname:dstImage is a compressed format image,
    pname:extent.height must: be a multiple of the compressed texel block
    height or (pname:extent.height + pname:dstOffset.y) must: equal the
    destination image subresource height
  * [[VUID-VkImageCopy-extent-00165]]
    If the calling command's pname:dstImage is a compressed format image,
    pname:extent.depth must: be a multiple of the compressed texel block
    depth or (pname:extent.depth + pname:dstOffset.z) must: equal the
    destination image subresource depth
  * [[VUID-VkImageCopy-srcOffset-00166]]
    pname:srcOffset, pname:dstOffset, and pname:extent must: respect the
    image transfer granularity requirements of the queue family that it will
    be submitted against, as described in
    <<devsandqueues-physical-device-enumeration,Physical Device
    Enumeration>>
****

include::../validity/structs/VkImageCopy.txt[]

// refBegin VkImageSubresourceLayers Structure specifying a image subresource layers

The sname:VkImageSubresourceLayers structure is defined as:

include::../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 from.
  * 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
  * [[VUID-VkImageSubresourceLayers-mipLevel-00169]]
    pname:mipLevel must: be less than the pname:mipLevels specified in
    slink:VkImageCreateInfo when the image was created
  * [[VUID-VkImageSubresourceLayers-baseArrayLayer-00170]]
    [eq]#(pname:baseArrayLayer + pname:layerCount)# must: be less than or
    equal to the pname:arrayLayers specified in slink:VkImageCreateInfo when
    the image was created
****

include::../validity/structs/VkImageSubresourceLayers.txt[]


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

// refBegin vkCmdCopyBufferToImage Copy data from a buffer into an image

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

include::../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.

.Valid Usage
****
  * [[VUID-vkCmdCopyBufferToImage-pRegions-00171]]
    The buffer region specified by a given element of pname:pRegions must:
    be a region that is contained within pname:srcBuffer
  * [[VUID-vkCmdCopyBufferToImage-pRegions-00172]]
    The image region specified by a given element of pname:pRegions must: be
    a region that is contained within pname:dstImage
  * [[VUID-vkCmdCopyBufferToImage-pRegions-00173]]
    The union of all source regions, and the union of all destination
    regions, specified by the elements of pname:pRegions, must: not overlap
    in memory
  * [[VUID-vkCmdCopyBufferToImage-srcBuffer-00174]]
    pname:srcBuffer must: have been created with
    ename:VK_BUFFER_USAGE_TRANSFER_SRC_BIT usage flag
ifdef::VK_KHR_maintenance1[]
  * [[VUID-vkCmdCopyBufferToImage-dstImage-00175]]
    pname:dstImage must: use a format that supports
    ename:VK_FORMAT_FEATURE_TRANSFER_DST_BIT_KHR, which is indicated by
    sname:VkFormatProperties::pname:linearTilingFeatures (for linearly tiled
    images) or sname:VkFormatProperties::pname:optimalTilingFeatures (for
    optimally tiled images) - as returned by
    flink:vkGetPhysicalDeviceFormatProperties
endif::VK_KHR_maintenance1[]
  * [[VUID-vkCmdCopyBufferToImage-srcBuffer-00176]]
    If pname:srcBuffer is non-sparse then it must: be bound completely and
    contiguously to a single sname:VkDeviceMemory object
  * [[VUID-vkCmdCopyBufferToImage-dstImage-00177]]
    pname:dstImage must: have been created with
    ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT usage flag
  * [[VUID-vkCmdCopyBufferToImage-dstImage-00178]]
    If pname:dstImage is non-sparse then it must: be bound completely and
    contiguously to a single sname:VkDeviceMemory object
  * [[VUID-vkCmdCopyBufferToImage-dstImage-00179]]
    pname:dstImage must: have a sample count equal to
    ename:VK_SAMPLE_COUNT_1_BIT
  * [[VUID-vkCmdCopyBufferToImage-dstImageLayout-00180]]
    pname:dstImageLayout must: specify the layout of the image subresources
    of pname:dstImage specified in pname:pRegions at the time this command
    is executed on a sname:VkDevice
  * [[VUID-vkCmdCopyBufferToImage-dstImageLayout-00181]]
    pname:dstImageLayout must: be
ifdef::VK_KHR_shared_presentable_image[]
    ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR,
endif::VK_KHR_shared_presentable_image[]
    ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL or
    ename:VK_IMAGE_LAYOUT_GENERAL
****

include::../validity/protos/vkCmdCopyBufferToImage.txt[]

// refBegin vkCmdCopyImageToBuffer Copy image data into a buffer

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

include::../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.

.Valid Usage
****
  * [[VUID-vkCmdCopyImageToBuffer-pRegions-00182]]
    The image region specified by a given element of pname:pRegions must: be
    a region that is contained within pname:srcImage
  * [[VUID-vkCmdCopyImageToBuffer-pRegions-00183]]
    The buffer region specified by a given element of pname:pRegions must:
    be a region that is contained within pname:dstBuffer
  * [[VUID-vkCmdCopyImageToBuffer-pRegions-00184]]
    The union of all source regions, and the union of all destination
    regions, specified by the elements of pname:pRegions, must: not overlap
    in memory
ifdef::VK_KHR_maintenance1[]
  * [[VUID-vkCmdCopyImageToBuffer-srcImage-00185]]
    pname:srcImage must: use a format that supports
    ename:VK_FORMAT_FEATURE_TRANSFER_SRC_BIT_KHR, which is indicated by
    sname:VkFormatProperties::pname:linearTilingFeatures (for linearly tiled
    images) or sname:VkFormatProperties::pname:optimalTilingFeatures (for
    optimally tiled images) - as returned by
    flink:vkGetPhysicalDeviceFormatProperties
endif::VK_KHR_maintenance1[]
  * [[VUID-vkCmdCopyImageToBuffer-srcImage-00186]]
    pname:srcImage must: have been created with
    ename:VK_IMAGE_USAGE_TRANSFER_SRC_BIT usage flag
  * [[VUID-vkCmdCopyImageToBuffer-srcImage-00187]]
    If pname:srcImage is non-sparse then it must: be bound completely and
    contiguously to a single sname:VkDeviceMemory object
  * [[VUID-vkCmdCopyImageToBuffer-srcImage-00188]]
    pname:srcImage must: have a sample count equal to
    ename:VK_SAMPLE_COUNT_1_BIT
  * [[VUID-vkCmdCopyImageToBuffer-srcImageLayout-00189]]
    pname:srcImageLayout must: specify the layout of the image subresources
    of pname:srcImage specified in pname:pRegions at the time this command
    is executed on a sname:VkDevice
  * [[VUID-vkCmdCopyImageToBuffer-srcImageLayout-00190]]
    pname:srcImageLayout must: be
ifdef::VK_KHR_shared_presentable_image[]
    ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR,
endif::VK_KHR_shared_presentable_image[]
    ename:VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL or
    ename:VK_IMAGE_LAYOUT_GENERAL
  * [[VUID-vkCmdCopyImageToBuffer-dstBuffer-00191]]
    pname:dstBuffer must: have been created with
    ename:VK_BUFFER_USAGE_TRANSFER_DST_BIT usage flag
  * [[VUID-vkCmdCopyImageToBuffer-dstBuffer-00192]]
    If pname:dstBuffer is non-sparse then it must: be bound completely and
    contiguously to a single sname:VkDeviceMemory object
****

include::../validity/protos/vkCmdCopyImageToBuffer.txt[]

// refBegin VkBufferImageCopy Structure specifying a buffer image copy operation

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

include::../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 the data in
    buffer memory as a subregion of a larger two- or three-dimensional
    image, and control the addressing calculations of data in buffer memory.
    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 x, y, 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, the data in buffer memory must: be in the
the range [eq]#[0,1]# or undefined results occur.

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.

.Valid Usage
****
  * [[VUID-VkBufferImageCopy-bufferOffset-00193]]
    If the the calling command's sname:VkImage parameter's format is not a
    depth/stencil format, then pname:bufferOffset must: be a multiple of the
    format's element size
  * [[VUID-VkBufferImageCopy-bufferOffset-00194]]
    pname:bufferOffset must: be a multiple of `4`
  * [[VUID-VkBufferImageCopy-bufferRowLength-00195]]
    pname:bufferRowLength must: be `0`, or greater than or equal to the
    pname:width member of pname:imageExtent
  * [[VUID-VkBufferImageCopy-bufferImageHeight-00196]]
    pname:bufferImageHeight must: be `0`, or greater than or equal to the
    pname:height member of pname:imageExtent
  * [[VUID-VkBufferImageCopy-imageOffset-00197]]
    pname:imageOffset.x and (pname:imageExtent.width + pname:imageOffset.x)
    must: both be greater than or equal to `0` and less than or equal to the
    image subresource width
  * [[VUID-VkBufferImageCopy-imageOffset-00198]]
    pname:imageOffset.y and (imageExtent.height + pname:imageOffset.y) must:
    both be greater than or equal to `0` and less than or equal to the image
    subresource height
  * [[VUID-VkBufferImageCopy-srcImage-00199]]
    If the calling command's pname:srcImage (flink:vkCmdCopyImageToBuffer)
    or pname:dstImage (flink:vkCmdCopyBufferToImage) is of type
    ename:VK_IMAGE_TYPE_1D, then pname:imageOffset.y must: be `0` and
    pname:imageExtent.height must: be `1`.
  * [[VUID-VkBufferImageCopy-imageOffset-00200]]
    pname:imageOffset.z and (imageExtent.depth + pname:imageOffset.z) must:
    both be greater than or equal to `0` and less than or equal to the image
    subresource depth
  * [[VUID-VkBufferImageCopy-srcImage-00201]]
    If the calling command's pname:srcImage (flink:vkCmdCopyImageToBuffer)
    or pname:dstImage (flink:vkCmdCopyBufferToImage) is of type
    ename:VK_IMAGE_TYPE_1D or ename:VK_IMAGE_TYPE_2D, then
    pname:imageOffset.z must: be `0` and pname:imageExtent.depth must: be
    `1`.
  * [[VUID-VkBufferImageCopy-bufferRowLength-00203]]
    If the calling command's sname:VkImage parameter is a compressed format
    image, pname:bufferRowLength must: be a multiple of the compressed texel
    block width
  * [[VUID-VkBufferImageCopy-bufferImageHeight-00204]]
    If the calling command's sname:VkImage parameter is a compressed format
    image, pname:bufferImageHeight must: be a multiple of the compressed
    texel block height
  * [[VUID-VkBufferImageCopy-imageOffset-00205]]
    If the calling command's sname:VkImage parameter is a compressed format
    image, all members of pname:imageOffset must: be a multiple of the
    corresponding dimensions of the compressed texel block
  * [[VUID-VkBufferImageCopy-bufferOffset-00206]]
    If the calling command's sname:VkImage parameter is a compressed format
    image, pname:bufferOffset must: be a multiple of the compressed texel
    block size in bytes
  * [[VUID-VkBufferImageCopy-imageExtent-00207]]
    If the calling command's sname:VkImage parameter is a compressed format
    image, pname:imageExtent.width must: be a multiple of the compressed
    texel block width or (pname:imageExtent.width + pname:imageOffset.x)
    must: equal the image subresource width
  * [[VUID-VkBufferImageCopy-imageExtent-00208]]
    If the calling command's sname:VkImage parameter is a compressed format
    image, pname:imageExtent.height must: be a multiple of the compressed
    texel block height or (pname:imageExtent.height + pname:imageOffset.y)
    must: equal the image subresource height
  * [[VUID-VkBufferImageCopy-imageExtent-00209]]
    If the calling command's sname:VkImage parameter is a compressed format
    image, pname:imageExtent.depth must: be a multiple of the compressed
    texel block depth or (pname:imageExtent.depth + pname:imageOffset.z)
    must: equal the image subresource depth
  * [[VUID-VkBufferImageCopy-bufferOffset-00210]]
    pname:bufferOffset, pname:bufferRowLength, pname:bufferImageHeight and
    all members of pname:imageOffset and pname:imageExtent must: respect the
    image transfer granularity requirements of the queue family that it will
    be submitted against, as described in
    <<devsandqueues-physical-device-enumeration,Physical Device
    Enumeration>>
  * [[VUID-VkBufferImageCopy-aspectMask-00211]]
    The pname:aspectMask member of pname:imageSubresource must: specify
    aspects present in the calling command's sname:VkImage parameter
  * [[VUID-VkBufferImageCopy-aspectMask-00212]]
    The pname:aspectMask member of pname:imageSubresource must: only have a
    single bit set
  * [[VUID-VkBufferImageCopy-baseArrayLayer-00213]]
    If the calling command's sname:VkImage parameter is of elink:VkImageType
    ename:VK_IMAGE_TYPE_3D, the pname:baseArrayLayer and pname:layerCount
    members of pname:imageSubresource must: be `0` and `1`, respectively
  * [[VUID-VkBufferImageCopy-None-00214]]
    When copying to the depth aspect of an image subresource, the data in
    the source buffer must: be in the range [eq]#[0,1]#
****

include::../validity/structs/VkBufferImageCopy.txt[]

Pseudocode for image/buffer addressing is:

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

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

elementSize = <element size of the format of the src/dstImage>;

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

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-compression 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 /= compressedTexelBlockWidth;
imageHeight /= 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 + 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 + 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.


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

// refBegin vkCmdBlitImage Copy regions of an image, potentially performing format conversion,

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

include::../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>>:
    :: [eq]#u~base~ = i + {onehalf}#
    :: [eq]#v~base~ = j + {onehalf}#
    :: [eq]#w~base~ = k + {onehalf}#
    * These base coordinates are then offset by the first destination
      offset:
    :: [eq]#u~offset~ = u~base~ - x~dst0~#
    :: [eq]#v~offset~ = v~base~ - y~dst0~#
    :: [eq]#w~offset~ = w~base~ - z~dst0~#
    :: [eq]#a~offset~ = a - pname:baseArrayCount~dst~#
    * The scale is determined from the source and destination regions, and
      applied to the offset coordinates:
    :: [eq]#scale_u = (x~src1~ - x~src0~) / (x~dst1~ - x~dst0~)#
    :: [eq]#scale_v = (y~src1~ - y~src0~) / (y~dst1~ - y~dst0~)#
    :: [eq]#scale_w = (z~src1~ - z~src0~) / (z~dst1~ - z~dst0~)#
    :: [eq]#u~scaled~ = u~offset~ * scale~u~#
    :: [eq]#v~scaled~ = v~offset~ * scale~v~#
    :: [eq]#w~scaled~ = w~offset~ * scale~w~#
    * Finally the source offset is added to the scaled coordinates, to
      determine the final unnormalized coordinates used to sample from
      pname:srcImage: +
    :: [eq]#u = u~scaled~ + x~src0~#
    :: [eq]#v = v~scaled~ + y~src0~#
    :: [eq]#w = w~scaled~ + z~src0~#
    :: [eq]#q = pname:mipLevel#
    :: [eq]#a = a~offset~ + 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.

3D textures are blitted slice by slice.
Slices in the source region bounded by pname:srcOffsets[0].pname:z and
pname:srcOffsets[1].pname:z are copied to slices in the destination region
bounded by pname:dstOffsets[0].pname:z and pname:dstOffsets[1].pname:z.
For each destination slice, a source z coordinate is linearly interpolated
between pname:srcOffsets[0].pname:z and pname:srcOffsets[1].pname: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.
If pname:filter parameter is ename:VK_FILTER_NEAREST then value sampled from
the source image is taken from the single nearest slice (with undefined
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
****
  * [[VUID-vkCmdBlitImage-pRegions-00215]]
    The source region specified by a given element of pname:pRegions must:
    be a region that is contained within pname:srcImage
  * [[VUID-vkCmdBlitImage-pRegions-00216]]
    The destination region specified by a given element of pname:pRegions
    must: be a region that is contained within pname:dstImage
  * [[VUID-vkCmdBlitImage-pRegions-00217]]
    The union of all destination regions, specified by the elements of
    pname:pRegions, must: not overlap in memory with any texel that may: be
    sampled during the blit operation
  * [[VUID-vkCmdBlitImage-srcImage-00218]]
    pname:srcImage must: use a format that supports
    ename:VK_FORMAT_FEATURE_BLIT_SRC_BIT, which is indicated by
    sname:VkFormatProperties::pname:linearTilingFeatures (for linearly tiled
    images) or sname:VkFormatProperties::pname:optimalTilingFeatures (for
    optimally tiled images) - as returned by
    fname:vkGetPhysicalDeviceFormatProperties
  * [[VUID-vkCmdBlitImage-srcImage-00219]]
    pname:srcImage must: have been created with
    ename:VK_IMAGE_USAGE_TRANSFER_SRC_BIT usage flag
  * [[VUID-vkCmdBlitImage-srcImage-00220]]
    If pname:srcImage is non-sparse then it must: be bound completely and
    contiguously to a single sname:VkDeviceMemory object
  * [[VUID-vkCmdBlitImage-srcImageLayout-00221]]
    pname:srcImageLayout must: specify the layout of the image subresources
    of pname:srcImage specified in pname:pRegions at the time this command
    is executed on a sname:VkDevice
  * [[VUID-vkCmdBlitImage-srcImageLayout-00222]]
    pname:srcImageLayout must: be
ifdef::VK_KHR_shared_presentable_image[]
    ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR,
endif::VK_KHR_shared_presentable_image[]
    ename:VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL or
    ename:VK_IMAGE_LAYOUT_GENERAL
  * [[VUID-vkCmdBlitImage-dstImage-00223]]
    pname:dstImage must: use a format that supports
    ename:VK_FORMAT_FEATURE_BLIT_DST_BIT, which is indicated by
    sname:VkFormatProperties::pname:linearTilingFeatures (for linearly tiled
    images) or sname:VkFormatProperties::pname:optimalTilingFeatures (for
    optimally tiled images) - as returned by
    fname:vkGetPhysicalDeviceFormatProperties
  * [[VUID-vkCmdBlitImage-dstImage-00224]]
    pname:dstImage must: have been created with
    ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT usage flag
  * [[VUID-vkCmdBlitImage-dstImage-00225]]
    If pname:dstImage is non-sparse then it must: be bound completely and
    contiguously to a single sname:VkDeviceMemory object
  * [[VUID-vkCmdBlitImage-dstImageLayout-00226]]
    pname:dstImageLayout must: specify the layout of the image subresources
    of pname:dstImage specified in pname:pRegions at the time this command
    is executed on a sname:VkDevice
  * [[VUID-vkCmdBlitImage-dstImageLayout-00227]]
    pname:dstImageLayout must: be
ifdef::VK_KHR_shared_presentable_image[]
    ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR,
endif::VK_KHR_shared_presentable_image[]
    ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL or
    ename:VK_IMAGE_LAYOUT_GENERAL
  * [[VUID-vkCmdBlitImage-srcImage-00228]]
    The sample count of pname:srcImage and pname:dstImage must: both be
    equal to ename:VK_SAMPLE_COUNT_1_BIT
  * [[VUID-vkCmdBlitImage-srcImage-00229]]
    If either of pname:srcImage or pname:dstImage was created with a signed
    integer elink:VkFormat, the other must: also have been created with a
    signed integer elink:VkFormat
  * [[VUID-vkCmdBlitImage-srcImage-00230]]
    If either of pname:srcImage or pname:dstImage was created with an
    unsigned integer elink:VkFormat, the other must: also have been created
    with an unsigned integer elink:VkFormat
  * [[VUID-vkCmdBlitImage-srcImage-00231]]
    If either of pname:srcImage or pname:dstImage was created with a
    depth/stencil format, the other must: have exactly the same format
  * [[VUID-vkCmdBlitImage-srcImage-00232]]
    If pname:srcImage was created with a depth/stencil format, pname:filter
    must: be ename:VK_FILTER_NEAREST
  * [[VUID-vkCmdBlitImage-srcImage-00233]]
    pname:srcImage must: have been created with a pname:samples value of
    ename:VK_SAMPLE_COUNT_1_BIT
  * [[VUID-vkCmdBlitImage-dstImage-00234]]
    pname:dstImage must: have been created with a pname:samples value of
    ename:VK_SAMPLE_COUNT_1_BIT
  * [[VUID-vkCmdBlitImage-filter-00235]]
    If pname:filter is ename:VK_FILTER_LINEAR, pname:srcImage must: be of a
    format which supports linear filtering, as specified by the
    ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT flag in
    sname:VkFormatProperties::pname:linearTilingFeatures (for a linear
    image) or sname:VkFormatProperties::pname:optimalTilingFeatures(for an
    optimally tiled image) returned by
    fname:vkGetPhysicalDeviceFormatProperties
ifdef::VK_IMG_filter_cubic[]
  * [[VUID-vkCmdBlitImage-filter-00236]]
    If pname:filter is ename:VK_FILTER_CUBIC_IMG, pname:srcImage must: be of
    a format which supports cubic filtering, as specified by the
    ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_CUBIC_BIT_IMG flag in
    sname:VkFormatProperties::pname:linearTilingFeatures (for a linear
    image) or sname:VkFormatProperties::pname:optimalTilingFeatures(for an
    optimally tiled image) returned by
    fname:vkGetPhysicalDeviceFormatProperties
  * [[VUID-vkCmdBlitImage-filter-00237]]
    If pname:filter is ename:VK_FILTER_CUBIC_IMG, pname:srcImage must: have
    a elink:VkImageType of ename:VK_IMAGE_TYPE_3D
endif::VK_IMG_filter_cubic[]
****

include::../validity/protos/vkCmdBlitImage.txt[]

// refBegin VkImageBlit Structure specifying an image blit operation

The sname:VkImageBlit structure is defined as:

include::../api/structs/VkImageBlit.txt[]

  * pname:srcSubresource is the subresource to blit from.
  * pname:srcOffsets is 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 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
the specified source and destination regions.

.Valid Usage
****
  * [[VUID-VkImageBlit-aspectMask-00238]]
    The pname:aspectMask member of pname:srcSubresource and
    pname:dstSubresource must: match
  * [[VUID-VkImageBlit-layerCount-00239]]
    The pname:layerCount member of pname:srcSubresource and
    pname:dstSubresource must: match
  * [[VUID-VkImageBlit-srcImage-00240]]
    If either of the calling command's pname:srcImage or pname:dstImage
    parameters are of elink:VkImageType ename:VK_IMAGE_TYPE_3D, the
    pname:baseArrayLayer and pname:layerCount members of both
    pname:srcSubresource and pname:dstSubresource must: be `0` and `1`,
    respectively
  * [[VUID-VkImageBlit-aspectMask-00241]]
    The pname:aspectMask member of pname:srcSubresource must: specify
    aspects present in the calling command's pname:srcImage
  * [[VUID-VkImageBlit-aspectMask-00242]]
    The pname:aspectMask member of pname:dstSubresource must: specify
    aspects present in the calling command's pname:dstImage
  * [[VUID-VkImageBlit-srcOffset-00243]]
    pname:srcOffset[0].pname:x and pname:srcOffset[1].pname:x must: both be
    greater than or equal to `0` and less than or equal to the source image
    subresource width
  * [[VUID-VkImageBlit-srcOffset-00244]]
    pname:srcOffset[0].pname:y and pname:srcOffset[1].pname:y must: both be
    greater than or equal to `0` and less than or equal to the source image
    subresource height
  * [[VUID-VkImageBlit-srcImage-00245]]
    If the calling command's pname:srcImage is of type
    ename:VK_IMAGE_TYPE_1D, then pname:srcOffset[0].y must: be `0` and
    pname:srcOffset[1].y must: be `1`.
  * [[VUID-VkImageBlit-srcOffset-00246]]
    pname:srcOffset[0].pname:z and pname:srcOffset[1].pname:z must: both be
    greater than or equal to `0` and less than or equal to the source image
    subresource depth
  * [[VUID-VkImageBlit-srcImage-00247]]
    If the calling command's pname:srcImage is of type
    ename:VK_IMAGE_TYPE_1D or ename:VK_IMAGE_TYPE_2D, then
    pname:srcOffset[0].z must: be `0` and pname:srcOffset[1].z must: be `1`.
  * [[VUID-VkImageBlit-dstOffset-00248]]
    pname:dstOffset[0].pname:x and pname:dstOffset[1].pname:x must: both be
    greater than or equal to `0` and less than or equal to the destination
    image subresource width
  * [[VUID-VkImageBlit-dstOffset-00249]]
    pname:dstOffset[0].pname:y and pname:dstOffset[1].pname:y must: both be
    greater than or equal to `0` and less than or equal to the destination
    image subresource height
  * [[VUID-VkImageBlit-dstImage-00250]]
    If the calling command's pname:dstImage is of type
    ename:VK_IMAGE_TYPE_1D, then pname:dstOffset[0].y must: be `0` and
    pname:dstOffset[1].y must: be `1`.
  * [[VUID-VkImageBlit-dstOffset-00251]]
    pname:dstOffset[0].pname:z and pname:dstOffset[1].pname:z must: both be
    greater than or equal to `0` and less than or equal to the destination
    image subresource depth
  * [[VUID-VkImageBlit-dstImage-00252]]
    If the calling command's pname:dstImage is of type
    ename:VK_IMAGE_TYPE_1D or ename:VK_IMAGE_TYPE_2D, then
    pname:dstOffset[0].z must: be `0` and pname:dstOffset[1].z must: be `1`.
****

include::../validity/structs/VkImageBlit.txt[]


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

// refBegin vkCmdResolveImage Resolve regions of an image

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

include::../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 x, y, and 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.

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
****
  * [[VUID-vkCmdResolveImage-pRegions-00253]]
    The source region specified by a given element of pname:pRegions must:
    be a region that is contained within pname:srcImage
  * [[VUID-vkCmdResolveImage-pRegions-00254]]
    The destination region specified by a given element of pname:pRegions
    must: be a region that is contained within pname:dstImage
  * [[VUID-vkCmdResolveImage-pRegions-00255]]
    The union of all source regions, and the union of all destination
    regions, specified by the elements of pname:pRegions, must: not overlap
    in memory
  * [[VUID-vkCmdResolveImage-srcImage-00256]]
    If pname:srcImage is non-sparse then it must: be bound completely and
    contiguously to a single sname:VkDeviceMemory object
  * [[VUID-vkCmdResolveImage-srcImage-00257]]
    pname:srcImage must: have a sample count equal to any valid sample count
    value other than ename:VK_SAMPLE_COUNT_1_BIT
  * [[VUID-vkCmdResolveImage-dstImage-00258]]
    If pname:dstImage is non-sparse then it must: be bound completely and
    contiguously to a single sname:VkDeviceMemory object
  * [[VUID-vkCmdResolveImage-dstImage-00259]]
    pname:dstImage must: have a sample count equal to
    ename:VK_SAMPLE_COUNT_1_BIT
  * [[VUID-vkCmdResolveImage-srcImageLayout-00260]]
    pname:srcImageLayout must: specify the layout of the image subresources
    of pname:srcImage specified in pname:pRegions at the time this command
    is executed on a sname:VkDevice
  * [[VUID-vkCmdResolveImage-srcImageLayout-00261]]
    pname:srcImageLayout must: be
ifdef::VK_KHR_shared_presentable_image[]
    ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR,
endif::VK_KHR_shared_presentable_image[]
    ename:VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL or
    ename:VK_IMAGE_LAYOUT_GENERAL
  * [[VUID-vkCmdResolveImage-dstImageLayout-00262]]
    pname:dstImageLayout must: specify the layout of the image subresources
    of pname:dstImage specified in pname:pRegions at the time this command
    is executed on a sname:VkDevice
  * [[VUID-vkCmdResolveImage-dstImageLayout-00263]]
    pname:dstImageLayout must: be
ifdef::VK_KHR_shared_presentable_image[]
    ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR,
endif::VK_KHR_shared_presentable_image[]
    ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL or
    ename:VK_IMAGE_LAYOUT_GENERAL
  * [[VUID-vkCmdResolveImage-dstImage-00264]]
    If pname:dstImage was created with pname:tiling equal to
    ename:VK_IMAGE_TILING_LINEAR, pname:dstImage must: have been created
    with a pname:format that supports being a color attachment, as specified
    by the ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT flag in
    sname:VkFormatProperties::pname:linearTilingFeatures returned by
    fname:vkGetPhysicalDeviceFormatProperties
  * [[VUID-vkCmdResolveImage-dstImage-00265]]
    If pname:dstImage was created with pname:tiling equal to
    ename:VK_IMAGE_TILING_OPTIMAL, pname:dstImage must: have been created
    with a pname:format that supports being a color attachment, as specified
    by the ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT flag in
    sname:VkFormatProperties::pname:optimalTilingFeatures returned by
    fname:vkGetPhysicalDeviceFormatProperties
****

include::../validity/protos/vkCmdResolveImage.txt[]

// refBegin VkImageResolve Structure specifying an image resolve operation

The sname:VkImageResolve structure is defined as:

include::../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 x, y, and 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
****
  * [[VUID-VkImageResolve-aspectMask-00266]]
    The pname:aspectMask member of pname:srcSubresource and
    pname:dstSubresource must: only contain ename:VK_IMAGE_ASPECT_COLOR_BIT
  * [[VUID-VkImageResolve-layerCount-00267]]
    The pname:layerCount member of pname:srcSubresource and
    pname:dstSubresource must: match
  * [[VUID-VkImageResolve-srcImage-00268]]
    If either of the calling command's pname:srcImage or pname:dstImage
    parameters are of elink:VkImageType ename:VK_IMAGE_TYPE_3D, the
    pname:baseArrayLayer and pname:layerCount members of both
    pname:srcSubresource and pname:dstSubresource must: be `0` and `1`,
    respectively
  * [[VUID-VkImageResolve-srcOffset-00269]]
    pname:srcOffset.x and (pname:extent.width + pname:srcOffset.x) must:
    both be greater than or equal to `0` and less than or equal to the
    source image subresource width
  * [[VUID-VkImageResolve-srcOffset-00270]]
    pname:srcOffset.y and (pname:extent.height + pname:srcOffset.y) must:
    both be greater than or equal to `0` and less than or equal to the
    source image subresource height
  * [[VUID-VkImageResolve-srcImage-00271]]
    If the calling command's pname:srcImage is of type
    ename:VK_IMAGE_TYPE_1D, then pname:srcOffset.y must: be `0` and
    pname:extent.height must: be `1`.
  * [[VUID-VkImageResolve-srcOffset-00272]]
    pname:srcOffset.z and (pname:extent.depth + pname:srcOffset.z) must:
    both be greater than or equal to `0` and less than or equal to the
    source image subresource depth
  * [[VUID-VkImageResolve-srcImage-00273]]
    If the calling command's pname:srcImage is of type
    ename:VK_IMAGE_TYPE_1D or ename:VK_IMAGE_TYPE_2D, then pname:srcOffset.z
    must: be `0` and pname:extent.depth must: be `1`.
  * [[VUID-VkImageResolve-dstOffset-00274]]
    pname:dstOffset.x and (pname:extent.width + pname:dstOffset.x) must:
    both be greater than or equal to `0` and less than or equal to the
    destination image subresource width
  * [[VUID-VkImageResolve-dstOffset-00275]]
    pname:dstOffset.y and (pname:extent.height + pname:dstOffset.y) must:
    both be greater than or equal to `0` and less than or equal to the
    destination image subresource height
  * [[VUID-VkImageResolve-dstImage-00276]]
    If the calling command's pname:dstImage is of type
    ename:VK_IMAGE_TYPE_1D, then pname:dstOffset.y must: be `0` and
    pname:extent.height must: be `1`.
  * [[VUID-VkImageResolve-dstOffset-00277]]
    pname:dstOffset.z and (pname:extent.depth + pname:dstOffset.z) must:
    both be greater than or equal to `0` and less than or equal to the
    destination image subresource depth
  * [[VUID-VkImageResolve-dstImage-00278]]
    If the calling command's pname:dstImage is of type
    ename:VK_IMAGE_TYPE_1D or ename:VK_IMAGE_TYPE_2D, then pname:dstOffset.z
    must: be `0` and pname:extent.depth must: be `1`.
****

include::../validity/structs/VkImageResolve.txt[]

