vkCmdCopyImage
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);
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.
Each source region specified by pRegions is copied from the source
image to the destination region of the destination image.
If any of the specified regions in srcImage overlaps in memory with
any of the specified regions in dstImage, values read from those
overlapping regions are undefined:.
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.
If the format of the destination image has a different block extent than the source image (e.g. one is a compressed format), the offset and extent for each of the regions specified is scaled according to the block extents of each format to match in size. 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.
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 maintenance5 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.
Valid Usage
VUID-vkCmdCopyImage-pRegions-00124
The union of all source regions, and the union of all destination
regions, specified by the elements of pRegions, must not overlap
in memory
VUID-vkCmdCopyImage-srcImage-01995
The format features of
srcImage must contain VK_FORMAT_FEATURE_TRANSFER_SRC_BIT
VUID-vkCmdCopyImage-srcImageLayout-00128
srcImageLayout must specify the layout of the image subresources
of srcImage specified in pRegions at the time this command
is executed on a VkDevice
VUID-vkCmdCopyImage-srcImageLayout-01917
srcImageLayout must be
VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR,
VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL, or
VK_IMAGE_LAYOUT_GENERAL
VUID-vkCmdCopyImage-srcImage-09460
If srcImage and dstImage are the same, and any elements of
pRegions contains the srcSubresource and
dstSubresource with matching mipLevel and overlapping array
layers, then the srcImageLayout and dstImageLayout must be
VK_IMAGE_LAYOUT_GENERAL
or VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR
VUID-vkCmdCopyImage-dstImage-01996
The format features of
dstImage must contain VK_FORMAT_FEATURE_TRANSFER_DST_BIT
VUID-vkCmdCopyImage-dstImageLayout-00133
dstImageLayout must specify the layout of the image subresources
of dstImage specified in pRegions at the time this command
is executed on a VkDevice
VUID-vkCmdCopyImage-dstImageLayout-01395
dstImageLayout must be
VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR,
VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL, or
VK_IMAGE_LAYOUT_GENERAL
VUID-vkCmdCopyImage-srcImage-01548
If the VkFormat of each of srcImage and dstImage is
not a multi-planar
format, the
VkFormat of each of srcImage and dstImage must be
size-compatible
VUID-vkCmdCopyImage-None-01549
In a copy to or from a plane of a multi-planar image, the VkFormat of the image and plane must be compatible according to the description of compatible planes for the plane being copied
VUID-vkCmdCopyImage-srcImage-09247
If the VkFormat of each of srcImage and dstImage is a
compressed image format, the formats must
have the same texel block extent
VUID-vkCmdCopyImage-srcImage-00136
The sample count of srcImage and dstImage must match
VUID-vkCmdCopyImage-srcOffset-01783
The srcOffset and extent members of each element of
pRegions must respect the image transfer granularity requirements
of commandBuffer’s command pool’s queue family, as described in
VkQueueFamilyProperties
VUID-vkCmdCopyImage-dstOffset-01784
The dstOffset and extent members of each element of
pRegions must respect the image transfer granularity requirements
of commandBuffer’s command pool’s queue family, as described in
VkQueueFamilyProperties
VUID-vkCmdCopyImage-srcImage-01551
If neither srcImage nor dstImage has a
multi-planar image
format then for each element of pRegions,
srcSubresource.aspectMask and dstSubresource.aspectMaskmust match
VUID-vkCmdCopyImage-srcImage-08713
If srcImage has a multi-planar image format, then for each element of pRegions,
srcSubresource.aspectMask must be a single valid
multi-planar aspect mask bit
VUID-vkCmdCopyImage-dstImage-08714
If dstImage has a multi-planar image format, then for each element of pRegions,
dstSubresource.aspectMask must be a single valid
multi-planar aspect mask bit
VUID-vkCmdCopyImage-srcImage-01556
If srcImage has a
multi-planar image format
and the dstImage does not have a multi-planar image format, then
for each element of pRegions, dstSubresource.aspectMaskmust be VK_IMAGE_ASPECT_COLOR_BIT
VUID-vkCmdCopyImage-dstImage-01557
If dstImage has a
multi-planar image format
and the srcImage does not have a multi-planar image format, then
for each element of pRegions, srcSubresource.aspectMaskmust be VK_IMAGE_ASPECT_COLOR_BIT
VUID-vkCmdCopyImage-apiVersion-07932
If
the [VK_KHR_maintenance1](/extensions/VK_KHR_maintenance1) extension is not enabled,
or
and
either srcImage or dstImage is of type
VK_IMAGE_TYPE_3D, then for each element of pRegions,
srcSubresource.baseArrayLayer and
dstSubresource.baseArrayLayer must both be 0, and
srcSubresource.layerCount and dstSubresource.layerCountmust both be 1
VUID-vkCmdCopyImage-srcImage-04443
If srcImage is of type VK_IMAGE_TYPE_3D, then for each
element of pRegions, srcSubresource.baseArrayLayer must be
0 and srcSubresource.layerCount must be 1
VUID-vkCmdCopyImage-dstImage-04444
If dstImage is of type VK_IMAGE_TYPE_3D, then for each
element of pRegions, dstSubresource.baseArrayLayer must be
0 and dstSubresource.layerCount must be 1
VUID-vkCmdCopyImage-aspectMask-00142
For each element of pRegions, srcSubresource.aspectMaskmust specify aspects present in srcImage
VUID-vkCmdCopyImage-aspectMask-00143
For each element of pRegions, dstSubresource.aspectMaskmust specify aspects present in dstImage
VUID-vkCmdCopyImage-srcOffset-00144
For each element of pRegions, srcOffset.x and
(extent.width + srcOffset.x) must both be
greater than or equal to 0 and less than or equal to the width of the
specified srcSubresource of srcImage
VUID-vkCmdCopyImage-srcOffset-00145
For each element of pRegions, srcOffset.y and
(extent.height + srcOffset.y) must both be
greater than or equal to 0 and less than or equal to the height of the
specified srcSubresource of srcImage
VUID-vkCmdCopyImage-srcImage-00146
If srcImage is of type VK_IMAGE_TYPE_1D, then for each
element of pRegions, srcOffset.y must be 0 and
extent.height must be 1
VUID-vkCmdCopyImage-srcOffset-00147
If srcImage is of type VK_IMAGE_TYPE_3D, then for each
element of pRegions, srcOffset.z and
(extent.depth + srcOffset.z) must both be
greater than or equal to 0 and less than or equal to the depth of the
specified srcSubresource of srcImage
VUID-vkCmdCopyImage-srcImage-01785
If srcImage is of type VK_IMAGE_TYPE_1D, then for each
element of pRegions, srcOffset.z must be 0 and
extent.depth must be 1
VUID-vkCmdCopyImage-dstImage-01786
If dstImage is of type VK_IMAGE_TYPE_1D, then for each
element of pRegions, dstOffset.z must be 0 and
extent.depth must be 1
VUID-vkCmdCopyImage-srcImage-01787
If srcImage is of type VK_IMAGE_TYPE_2D, then for each
element of pRegions, srcOffset.z must be 0
VUID-vkCmdCopyImage-dstImage-01788
If dstImage is of type VK_IMAGE_TYPE_2D, then for each
element of pRegions, dstOffset.z must be 0
VUID-vkCmdCopyImage-apiVersion-07933
If
the [VK_KHR_maintenance1](/extensions/VK_KHR_maintenance1) extension is not enabled,
and
srcImage and dstImage must have the same VkImageType
VUID-vkCmdCopyImage-apiVersion-08969
If
the [VK_KHR_maintenance1](/extensions/VK_KHR_maintenance1) extension is not enabled,
and
srcImage or dstImage is of type VK_IMAGE_TYPE_2D, then
for each element of pRegions, extent.depth must be 1
VUID-vkCmdCopyImage-srcImage-07743
If srcImage and dstImage have a different VkImageType,
and maintenance5 is not enabled,
one must be VK_IMAGE_TYPE_3D and the other must be
VK_IMAGE_TYPE_2D
VUID-vkCmdCopyImage-srcImage-08793
If srcImage and dstImage have the same VkImageType,
for each element of pRegions,
if neither of the layerCount members of srcSubresource or
dstSubresource are VK_REMAINING_ARRAY_LAYERS,
the layerCount members of srcSubresource or
dstSubresource must match
VUID-vkCmdCopyImage-srcImage-08794
If srcImage and dstImage have the same VkImageType,
and one of the layerCount members of srcSubresource or
dstSubresource is VK_REMAINING_ARRAY_LAYERS, the other
member must be either VK_REMAINING_ARRAY_LAYERS or equal to the
arrayLayers member of the VkImageCreateInfo used to create
the image minus baseArrayLayer
VUID-vkCmdCopyImage-srcImage-01790
If srcImage and dstImage are both of type
VK_IMAGE_TYPE_2D, then for each element of pRegions,
extent.depth must be 1
VUID-vkCmdCopyImage-srcImage-01791
If srcImage is of type VK_IMAGE_TYPE_2D, and dstImage
is of type VK_IMAGE_TYPE_3D, then for each element of
pRegions, extent.depth must equal
srcSubresource.layerCount
VUID-vkCmdCopyImage-dstImage-01792
If dstImage is of type VK_IMAGE_TYPE_2D, and srcImage
is of type VK_IMAGE_TYPE_3D, then for each element of
pRegions, extent.depth must equal
dstSubresource.layerCount
VUID-vkCmdCopyImage-dstOffset-00150
For each element of pRegions, dstOffset.x and
(extent.width + dstOffset.x) must both be
greater than or equal to 0 and less than or equal to the width of the
specified dstSubresource of dstImage
VUID-vkCmdCopyImage-dstOffset-00151
For each element of pRegions, dstOffset.y and
(extent.height + dstOffset.y) must both be
greater than or equal to 0 and less than or equal to the height of the
specified dstSubresource of dstImage
VUID-vkCmdCopyImage-dstImage-00152
If dstImage is of type VK_IMAGE_TYPE_1D, then for each
element of pRegions, dstOffset.y must be 0 and
extent.height must be 1
VUID-vkCmdCopyImage-dstOffset-00153
If dstImage is of type VK_IMAGE_TYPE_3D, then for each
element of pRegions, dstOffset.z and
(extent.depth + dstOffset.z) must both be
greater than or equal to 0 and less than or equal to the depth of the
specified dstSubresource of dstImage
VUID-vkCmdCopyImage-pRegions-07278
For each element of pRegions, srcOffset.x must be a
multiple of the texel block extent
width of the VkFormat of srcImage
VUID-vkCmdCopyImage-pRegions-07279
For each element of pRegions, srcOffset.y must be a
multiple of the texel block extent
height of the VkFormat of srcImage
VUID-vkCmdCopyImage-pRegions-07280
For each element of pRegions, srcOffset.z must be a
multiple of the texel block extent
depth of the VkFormat of srcImage
VUID-vkCmdCopyImage-pRegions-07281
For each element of pRegions, dstOffset.x must be a
multiple of the texel block extent
width of the VkFormat of dstImage
VUID-vkCmdCopyImage-pRegions-07282
For each element of pRegions, dstOffset.y must be a
multiple of the texel block extent
height of the VkFormat of dstImage
VUID-vkCmdCopyImage-pRegions-07283
For each element of pRegions, dstOffset.z must be a
multiple of the texel block extent
depth of the VkFormat of dstImage
VUID-vkCmdCopyImage-srcImage-01728
For each element of pRegions, if the sum of srcOffset.x and
extent.width does not equal the width of the subresource specified
by srcSubresource, extent.width must be a multiple of the
texel block extent width of the
VkFormat of srcImage
VUID-vkCmdCopyImage-srcImage-01729
For each element of pRegions, if the sum of srcOffset.y and
extent.height does not equal the height of the subresource
specified by srcSubresource, extent.height must be a
multiple of the texel block extent
height of the VkFormat of srcImage
VUID-vkCmdCopyImage-srcImage-01730
For each element of pRegions, if the sum of srcOffset.z and
extent.depth does not equal the depth of the subresource specified
by srcSubresource, extent.depth must be a multiple of the
texel block extent depth of the
VkFormat of srcImage
VUID-vkCmdCopyImage-dstImage-01732
For each element of pRegions, if the sum of dstOffset.x and
extent.width does not equal the width of the subresource specified
by dstSubresource, extent.width must be a multiple of the
texel block extent width of the
VkFormat of dstImage
VUID-vkCmdCopyImage-dstImage-01733
For each element of pRegions, if the sum of dstOffset.y and
extent.height does not equal the height of the subresource
specified by dstSubresource, extent.height must be a
multiple of the texel block extent
height of the VkFormat of dstImage
VUID-vkCmdCopyImage-dstImage-01734
For each element of pRegions, if the sum of dstOffset.z and
extent.depth does not equal the depth of the subresource specified
by dstSubresource, extent.depth must be a multiple of the
texel block extent depth of the
VkFormat of dstImage
VUID-vkCmdCopyImage-aspect-06662
If the aspect member of any element of pRegions includes any
flag other than VK_IMAGE_ASPECT_STENCIL_BIT or srcImage was
not created with separate stencil
usage,
VK_IMAGE_USAGE_TRANSFER_SRC_BIT must have been included in the
VkImageCreateInfo::usage used to create srcImage
VUID-vkCmdCopyImage-aspect-06663
If the aspect member of any element of pRegions includes any
flag other than VK_IMAGE_ASPECT_STENCIL_BIT or dstImage was
not created with separate stencil
usage,
VK_IMAGE_USAGE_TRANSFER_DST_BIT must have been included in the
VkImageCreateInfo::usage used to create dstImage
VUID-vkCmdCopyImage-aspect-06664
If the aspect member of any element of pRegions includes
VK_IMAGE_ASPECT_STENCIL_BIT, and srcImage was created with
separate stencil usage,
VK_IMAGE_USAGE_TRANSFER_SRC_BIT must have been included in the
VkImageStencilUsageCreateInfo::stencilUsage used to create
srcImage
VUID-vkCmdCopyImage-aspect-06665
If the aspect member of any element of pRegions includes
VK_IMAGE_ASPECT_STENCIL_BIT, and dstImage was created with
separate stencil usage,
VK_IMAGE_USAGE_TRANSFER_DST_BIT must have been included in the
VkImageStencilUsageCreateInfo::stencilUsage used to create
dstImage
VUID-vkCmdCopyImage-srcImage-07966
If srcImage is non-sparse then the image
or the specified disjoint plane
must be bound completely and contiguously to a single
VkDeviceMemory object
VUID-vkCmdCopyImage-srcSubresource-07967
The srcSubresource.mipLevel member of each element of
pRegions must be less than the mipLevels specified in
VkImageCreateInfo when srcImage was created
VUID-vkCmdCopyImage-srcSubresource-07968
If srcSubresource.layerCount is not
VK_REMAINING_ARRAY_LAYERS,
srcSubresource.baseArrayLayer +
srcSubresource.layerCount of each element of pRegionsmust be less than or equal to the arrayLayers specified in
VkImageCreateInfo when srcImage was created
VUID-vkCmdCopyImage-srcImage-07969
srcImage must not have been created with flags
containing VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT
VUID-vkCmdCopyImage-dstImage-07966
If dstImage is non-sparse then the image
or the specified disjoint plane
must be bound completely and contiguously to a single
VkDeviceMemory object
VUID-vkCmdCopyImage-dstSubresource-07967
The dstSubresource.mipLevel member of each element of
pRegions must be less than the mipLevels specified in
VkImageCreateInfo when dstImage was created
VUID-vkCmdCopyImage-dstSubresource-07968
If dstSubresource.layerCount is not
VK_REMAINING_ARRAY_LAYERS,
dstSubresource.baseArrayLayer +
dstSubresource.layerCount of each element of pRegionsmust be less than or equal to the arrayLayers specified in
VkImageCreateInfo when dstImage was created
VUID-vkCmdCopyImage-dstImage-07969
dstImage must not have been created with flags
containing VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT
Valid Usage (Implicit)
VUID-vkCmdCopyImage-commandBuffer-parameter
commandBuffer must be a valid VkCommandBuffer handle
VUID-vkCmdCopyImage-srcImage-parameter
srcImage must be a valid VkImage handle
VUID-vkCmdCopyImage-srcImageLayout-parameter
srcImageLayout must be a valid VkImageLayout value
VUID-vkCmdCopyImage-dstImage-parameter
dstImage must be a valid VkImage handle
VUID-vkCmdCopyImage-dstImageLayout-parameter
dstImageLayout must be a valid VkImageLayout value
VUID-vkCmdCopyImage-pRegions-parameter
pRegions must be a valid pointer to an array of regionCount valid VkImageCopy structures
VUID-vkCmdCopyImage-commandBuffer-recording
commandBuffer must be in the recording state
VUID-vkCmdCopyImage-commandBuffer-cmdpool
The VkCommandPool that commandBuffer was allocated from must support transfer, graphics, or compute operations
VUID-vkCmdCopyImage-renderpass
This command must only be called outside of a render pass instance
VUID-vkCmdCopyImage-videocoding
This command must only be called outside of a video coding scope
VUID-vkCmdCopyImage-regionCount-arraylength
regionCount must be greater than 0
VUID-vkCmdCopyImage-commonparent
Each of commandBuffer, dstImage, and srcImage must have been created, allocated, or retrieved from the same VkDevice
Host Synchronization
- Host access to
commandBuffermust be externally synchronized - Host access to the
VkCommandPoolthatcommandBufferwas allocated from must be externally synchronized ::