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 texel size in bytes 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 texel
size of the uncompressed format is equal to the compressed texel block size in
bytes 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. 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 and if extent.width
is not a
multiple of the compressed texel block width then (extent.width
srcOffset.x
) must equal the image subresource width, if
extent.height
is not a multiple of the compressed texel block height
then (extent.height
+ srcOffset.y
) must equal the image
subresource height and if 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 and if extent.width
is not a multiple of the compressed
texel block width then (extent.width
+ dstOffset.x
) must equal
the image subresource width, if extent.height
is not a multiple of the
compressed texel block height then (extent.height
+ dstOffset.y
)
must equal the image subresource height and if 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
. 1D images use only x
and width
. 2D images use x
, y
, width
and
height
. 3D images use x
, y
, z
, 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.