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
-
commandBufferis the command buffer into which the command will be recorded. -
srcImageis the source image. -
srcImageLayoutis the current layout of the source image subresource. -
dstImageis the destination image. -
dstImageLayoutis the current layout of the destination image subresource. -
regionCountis the number of regions to copy. -
pRegionsis a pointer to an array of VkImageCopy structures specifying the regions to copy.
Description
Each source region specified by pRegions is copied from the source
image to the destination region of the destination image.
If any region accesses a depth aspect in dstImage
and the VK_EXT_depth_range_unrestricted extension is not enabled,
values copied from srcImage outside of the range [0,1] will be
written as undefined values to the destination image.
Copy regions for each image must be aligned to a multiple of the texel block extent in each dimension, except at the edges of the image, where region extents must match the edge of the image.
The texels in the images are accessed as follows.
Texels at each coordinate (x,y,z,layer) in a image subresource are accessed, where:
-
x is in the range [offset.x, offset.x + extent.width),
-
y is in the range [offset.y, offset.y + extent.height),
-
z is in the range [offset.z, offset.z + extent.depth),
-
layer is in the range [subresource.baseArrayLayer, subresource.baseArrayLayer + subresource.layerCount)
where for srcImage, offset, extent, and subresource are
srcOffset, extent, and srcSubresource for each region,
respectively.
For dstImage, offset, extent , and subresource are
dstOffset, extent, and dstSubresource for each region,
respectively, where dstOffset and extent are first
size-adjusted if the format of the
destination image has a different block
extent than the format of the source image (e.g. one is a compressed
format).
Multi-planar images can only be copied on a per-plane basis, and the subresources used in each region when copying to or from such images must specify only one plane, though different regions can specify different planes. When copying planes of multi-planar images, the format considered is the compatible format for that plane, rather than the format of the multi-planar image.
Image data can be copied between images with different image types.
If one image is VK_IMAGE_TYPE_3D and the other image is
VK_IMAGE_TYPE_2D with multiple layers, then each slice is copied to or
from a different layer; depth slices in the 3D image correspond to
layerCount layers in the 2D image, with an effective depth of
1 used for the 2D image.
If the maintenance5 feature is enabled, all
other combinations are allowed and function as if 1D images are 2D images
with a height of 1.
Otherwise, other combinations of image types are disallowed.
The memory locations accessed by the source and destination images overlap
if they alias each other, both
srcSubresource and dstSubresource overlap the aliased range, and
any of the following are true:
-
Their contents are not able to be interpreted in consistent ways
-
If the aliased regions are host-accessible, their accessed regions defined above overlap, where the memory locations accessed by the texels of a linear image is according to its VkSubresourceLayout
-
Otherwise, their accessed texel ranges share any of the same texel coordinates
The memory locations of an image overlap if those two ranges share any of the same texel coordinates in the same image aspects.
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.