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.
vkCmdCopyImage can copy between images with different formats,
provided the formats are compatible as defined below.
To copy data between image objects, call:
void vkCmdCopyImage(
VkCommandBuffer commandBuffer,
VkImage srcImage,
VkImageLayout srcImageLayout,
VkImage dstImage,
VkImageLayout dstImageLayout,
uint32_t regionCount,
const VkImageCopy* pRegions);
commandBuffer is the command buffer into which the command will be
recorded.
srcImage is the source image.
srcImageLayout is the current layout of the source image
subresource.
dstImage is the destination image.
dstImageLayout is the current layout of the destination image
subresource.
regionCount is the number of regions to copy.
pRegions is a pointer to an array of VkImageCopy structures
specifying the regions to copy.
Each region in pRegions is copied from the source image to the same
region of the destination image.
srcImage and dstImage can be the same image or alias the same
memory.
Copies are done layer by layer starting with baseArrayLayer member of
srcSubresource for the source and dstSubresource for the
destination.
layerCount layers are copied to the destination image.
The formats of srcImage and dstImage must be compatible.
Formats are considered compatible if their element size is the same between
both formats.
For example, VK_FORMAT_R8G8B8A8_UNORM is compatible with
VK_FORMAT_R32_UINT because both texels are 4 bytes in size.
Depth/stencil formats must match exactly.
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 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 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 srcImage is compressed, then:
extent.width is not a multiple of the compressed texel block
width, then (extent.width + srcOffset.x) must equal
the image subresource width.
extent.height is not a multiple of the compressed texel block
height, then (extent.height + srcOffset.y) must equal
the image subresource height.
extent.depth is not a multiple of the compressed texel block
depth, then (extent.depth + srcOffset.z) must equal
the image subresource depth.
Similarly, if the dstImage is compressed, then:
extent.width is not a multiple of the compressed texel block
width, then (extent.width + dstOffset.x) must equal
the image subresource width.
extent.height is not a multiple of the compressed texel block
height, then (extent.height + dstOffset.y) must equal
the image subresource height.
extent.depth is not a multiple of the compressed texel block
depth, then (extent.depth + 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.
vkCmdCopyImage can be used to copy image data between multisample
images, but both images must have the same number of samples.
The VkImageCopy structure is defined as:
typedef struct VkImageCopy {
VkImageSubresourceLayers srcSubresource;
VkOffset3D srcOffset;
VkImageSubresourceLayers dstSubresource;
VkOffset3D dstOffset;
VkExtent3D extent;
} VkImageCopy;
srcSubresource and dstSubresource are
VkImageSubresourceLayers structures specifying the image
subresources of the images used for the source and destination image
data, respectively.
srcOffset and dstOffset select the initial x, y, and z
offsets in texels of the sub-regions of the source and destination image
data.
extent is the size in texels of the source image to copy in
width, height and depth.
The VkImageSubresourceLayers structure is defined as:
typedef struct VkImageSubresourceLayers {
VkImageAspectFlags aspectMask;
uint32_t mipLevel;
uint32_t baseArrayLayer;
uint32_t layerCount;
} VkImageSubresourceLayers;
aspectMask is a combination of VkImageAspectFlagBits,
selecting the color, depth and/or stencil aspects to be copied.
mipLevel is the mipmap level to copy from.
baseArrayLayer and layerCount are the starting layer and
number of layers to copy.