C Specification
To copy data between image objects, call:
// Provided by VK_VERSION_1_0
void vkCmdCopyImage(
VkCommandBuffer commandBuffer,
VkImage srcImage,
VkImageLayout srcImageLayout,
VkImage dstImage,
VkImageLayout dstImageLayout,
uint32_t regionCount,
const VkImageCopy* pRegions);
Parameters
-
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.
Description
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.
The formats of srcImage
and dstImage
must be compatible.
Formats are compatible if they share the same class, as shown in the
Compatible Formats table.
Depth/stencil formats must match exactly.
If either srcImage
or dstImage
has a
multi-planar format,
regions of each plane to be copied must be specified separately using the
srcSubresource
and dstSubresource
members of the
VkImageCopy structure.
In this case, the aspectMask
of the srcSubresource
or
dstSubresource
that refers to the multi-planar image must be
VK_IMAGE_ASPECT_PLANE_0_BIT
, VK_IMAGE_ASPECT_PLANE_1_BIT
, or
VK_IMAGE_ASPECT_PLANE_2_BIT
.
For the purposes of vkCmdCopyImage
, each plane of a multi-planar image
is treated as having the format listed in https://www.khronos.org/registry/vulkan/specs/1.3-extensions/html/vkspec.html#formats-compatible-planes for
the plane identified by the aspectMask
of the corresponding
subresource.
This applies both to 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
For example, the |
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×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×4 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:
-
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. -
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, then:
-
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. -
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.
“_422
” image formats that are not
multi-planar are treated as
having a 2×1 compressed texel block for the purposes of these rules.
vkCmdCopyImage
can be used to copy image data between multisample
images, but both images must have the same number of samples.
Document Notes
For more information, see the Vulkan Specification
This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.