C Specification
To copy data from an image object to a buffer object, call:
// Provided by VK_VERSION_1_0
void vkCmdCopyImageToBuffer(
VkCommandBuffer commandBuffer,
VkImage srcImage,
VkImageLayout srcImageLayout,
VkBuffer dstBuffer,
uint32_t regionCount,
const VkBufferImageCopy* pRegions);
Parameters
-
commandBuffer
is the command buffer into which the command will be recorded. -
srcImage
is the source image. -
srcImageLayout
is the layout of the source image subresources for the copy. -
dstBuffer
is the destination buffer. -
regionCount
is the number of regions to copy. -
pRegions
is a pointer to an array of VkBufferImageCopy 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 buffer according to the
addressing calculations for each
resource.
If any of the specified regions in srcImage
overlaps in memory with
any of the specified regions in dstBuffer
, values read from those
overlapping regions are undefined.
Copy regions for the 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.
-
VUID-vkCmdCopyImageToBuffer-srcImage-07966
IfsrcImage
is non-sparse then the image or the specified disjoint plane must be bound completely and contiguously to a singleVkDeviceMemory
object -
VUID-vkCmdCopyImageToBuffer-imageSubresource-07967
TheimageSubresource.mipLevel
member of each element ofpRegions
must be less than themipLevels
specified in VkImageCreateInfo whensrcImage
was created -
VUID-vkCmdCopyImageToBuffer-imageSubresource-07968
IfimageSubresource.layerCount
is notVK_REMAINING_ARRAY_LAYERS
,imageSubresource.baseArrayLayer
+imageSubresource.layerCount
of each element ofpRegions
must be less than or equal to thearrayLayers
specified in VkImageCreateInfo whensrcImage
was created -
VUID-vkCmdCopyImageToBuffer-srcImage-07969
srcImage
must not have been created withflags
containingVK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT
-
VUID-vkCmdCopyImageToBuffer-imageSubresource-07970
The image region specified by each element ofpRegions
must be contained within the specifiedimageSubresource
ofsrcImage
-
VUID-vkCmdCopyImageToBuffer-imageSubresource-07971
For each element ofpRegions
,imageOffset.x
and (imageExtent.width
+imageOffset.x
) must both be greater than or equal to0
and less than or equal to the width of the specifiedimageSubresource
ofsrcImage
-
VUID-vkCmdCopyImageToBuffer-imageSubresource-07972
For each element ofpRegions
,imageOffset.y
and (imageExtent.height
+imageOffset.y
) must both be greater than or equal to0
and less than or equal to the height of the specifiedimageSubresource
ofsrcImage
-
VUID-vkCmdCopyImageToBuffer-commandBuffer-01831
IfcommandBuffer
is an unprotected command buffer andprotectedNoFault
is not supported,srcImage
must not be a protected image -
VUID-vkCmdCopyImageToBuffer-commandBuffer-01832
IfcommandBuffer
is an unprotected command buffer andprotectedNoFault
is not supported,dstBuffer
must not be a protected buffer -
VUID-vkCmdCopyImageToBuffer-commandBuffer-01833
IfcommandBuffer
is a protected command buffer andprotectedNoFault
is not supported,dstBuffer
must not be an unprotected buffer -
VUID-vkCmdCopyImageToBuffer-commandBuffer-07746
If the queue family used to create the VkCommandPool whichcommandBuffer
was allocated from does not supportVK_QUEUE_GRAPHICS_BIT
orVK_QUEUE_COMPUTE_BIT
, thebufferOffset
member of any element ofpRegions
must be a multiple of4
-
VUID-vkCmdCopyImageToBuffer-imageOffset-07747
TheimageOffset
andimageExtent
members of each element ofpRegions
must respect the image transfer granularity requirements ofcommandBuffer
’s command pool’s queue family, as described in VkQueueFamilyProperties -
VUID-vkCmdCopyImageToBuffer-commandBuffer-10216
If the queue family used to create the VkCommandPool whichcommandBuffer
was allocated from does not supportVK_QUEUE_GRAPHICS_BIT
, for each element ofpRegions
, theaspectMask
member ofimageSubresource
must not beVK_IMAGE_ASPECT_DEPTH_BIT
orVK_IMAGE_ASPECT_STENCIL_BIT
-
VUID-vkCmdCopyImageToBuffer-pRegions-00183
dstBuffer
must be large enough to contain all buffer locations that are accessed according to Buffer and Image Addressing, for each element ofpRegions
-
VUID-vkCmdCopyImageToBuffer-pRegions-00184
The union of all source regions, and the union of all destination regions, specified by the elements ofpRegions
, must not overlap in memory -
VUID-vkCmdCopyImageToBuffer-srcImage-00186
srcImage
must have been created withVK_IMAGE_USAGE_TRANSFER_SRC_BIT
usage flag -
VUID-vkCmdCopyImageToBuffer-srcImage-01998
The format features ofsrcImage
must containVK_FORMAT_FEATURE_TRANSFER_SRC_BIT
-
VUID-vkCmdCopyImageToBuffer-dstBuffer-00191
dstBuffer
must have been created withVK_BUFFER_USAGE_TRANSFER_DST_BIT
usage flag -
VUID-vkCmdCopyImageToBuffer-dstBuffer-00192
IfdstBuffer
is non-sparse then it must be bound completely and contiguously to a singleVkDeviceMemory
object -
VUID-vkCmdCopyImageToBuffer-srcImageLayout-00189
srcImageLayout
must specify the layout of the image subresources ofsrcImage
specified inpRegions
at the time this command is executed on aVkDevice
-
VUID-vkCmdCopyImageToBuffer-srcImageLayout-01397
srcImageLayout
must beVK_IMAGE_LAYOUT_SHARED_PRESENT_KHR
,VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL
, orVK_IMAGE_LAYOUT_GENERAL
-
VUID-vkCmdCopyImageToBuffer-srcImage-07979
IfsrcImage
is of typeVK_IMAGE_TYPE_1D
, then for each element ofpRegions
,imageOffset.y
must be0
andimageExtent.height
must be1
-
VUID-vkCmdCopyImageToBuffer-imageOffset-09104
For each element ofpRegions
,imageOffset.z
and (imageExtent.depth
+imageOffset.z
) must both be greater than or equal to0
and less than or equal to the depth of the specifiedimageSubresource
ofsrcImage
-
VUID-vkCmdCopyImageToBuffer-srcImage-07980
IfsrcImage
is of typeVK_IMAGE_TYPE_1D
orVK_IMAGE_TYPE_2D
, then for each element ofpRegions
,imageOffset.z
must be0
andimageExtent.depth
must be1
-
VUID-vkCmdCopyImageToBuffer-srcImage-07274
For each element ofpRegions
, if VkCopyCommandTransformInfoQCOM::transform
is equal toVK_SURFACE_TRANSFORM_IDENTITY_BIT_KHR
orVK_SURFACE_TRANSFORM_ROTATE_270_BIT_KHR
,imageOffset.x
must be a multiple of the texel block extent width of the VkFormat ofsrcImage
-
VUID-vkCmdCopyImageToBuffer-imageOffset-10051
For each element ofpRegions
, if VkCopyCommandTransformInfoQCOM::transform
is equal toVK_SURFACE_TRANSFORM_ROTATE_180_BIT_KHR
orVK_SURFACE_TRANSFORM_ROTATE_90_BIT_KHR
, andimageOffset.x
does not equal the width of the subresource specified byimageSubresource
,imageOffset.x
must be a multiple of the texel block extent width of the VkFormat ofsrcImage
-
VUID-vkCmdCopyImageToBuffer-srcImage-07275
For each element ofpRegions
, if VkCopyCommandTransformInfoQCOM::transform
is equal toVK_SURFACE_TRANSFORM_IDENTITY_BIT_KHR
orVK_SURFACE_TRANSFORM_ROTATE_90_BIT_KHR
,imageOffset.y
must be a multiple of the texel block extent height of the VkFormat ofsrcImage
-
VUID-vkCmdCopyImageToBuffer-imageOffset-10052
For each element ofpRegions
, if VkCopyCommandTransformInfoQCOM::transform
is equal toVK_SURFACE_TRANSFORM_ROTATE_270_BIT_KHR
orVK_SURFACE_TRANSFORM_ROTATE_180_BIT_KHR
, andimageOffset.y
does not equal the height of the subresource specified byimageSubresource
,imageOffset.y
must be a multiple of the texel block extent height of the VkFormat ofsrcImage
-
VUID-vkCmdCopyImageToBuffer-srcImage-07276
For each element ofpRegions
,imageOffset.z
must be a multiple of the texel block extent depth of the VkFormat ofsrcImage
-
VUID-vkCmdCopyImageToBuffer-srcImage-00207
For each element ofpRegions
, if VkCopyCommandTransformInfoQCOM::transform
is equal toVK_SURFACE_TRANSFORM_IDENTITY_BIT_KHR
, the sum ofimageOffset.x
andextent.width
does not equal the width of the subresource specified byimageSubresource
,extent.width
must be a multiple of the texel block extent width of the VkFormat ofsrcImage
-
VUID-vkCmdCopyImageToBuffer-imageOffset-10053
For each element ofpRegions
, if VkCopyCommandTransformInfoQCOM::transform
is equal toVK_SURFACE_TRANSFORM_ROTATE_90_BIT_KHR
, the difference ofimageOffset.x
andextent.height
must be a multiple of the texel block extent width of the VkFormat ofsrcImage
-
VUID-vkCmdCopyImageToBuffer-imageOffset-10054
For each element ofpRegions
, if VkCopyCommandTransformInfoQCOM::transform
is equal toVK_SURFACE_TRANSFORM_ROTATE_180_BIT_KHR
, the difference ofimageOffset.x
andextent.width
must be a multiple of the texel block extent width of the VkFormat ofsrcImage
-
VUID-vkCmdCopyImageToBuffer-imageOffset-10055
For each element ofpRegions
, if VkCopyCommandTransformInfoQCOM::transform
is equal toVK_SURFACE_TRANSFORM_ROTATE_270_BIT_KHR
, the sum ofimageOffset.x
andextent.height
does not equal the width of the subresource specified byimageSubresource
,extent.height
must be a multiple of the texel block extent width of the VkFormat ofsrcImage
-
VUID-vkCmdCopyImageToBuffer-srcImage-00208
For each element ofpRegions
, if VkCopyCommandTransformInfoQCOM::transform
is equal toVK_SURFACE_TRANSFORM_IDENTITY_BIT_KHR
, and the sum ofimageOffset.y
andextent.height
does not equal the height of the subresource specified byimageSubresource
,extent.height
must be a multiple of the texel block extent height of the VkFormat ofsrcImage
-
VUID-vkCmdCopyImageToBuffer-imageOffset-10056
For each element ofpRegions
, if VkCopyCommandTransformInfoQCOM::transform
is equal toVK_SURFACE_TRANSFORM_ROTATE_90_BIT_KHR
, the sum ofimageOffset.y
andextent.width
does not equal the height of the subresource specified byimageSubresource
,extent.width
must be a multiple of the texel block extent height of the VkFormat ofsrcImage
-
VUID-vkCmdCopyImageToBuffer-imageOffset-10057
For each element ofpRegions
, if VkCopyCommandTransformInfoQCOM::transform
is equal toVK_SURFACE_TRANSFORM_ROTATE_180_BIT_KHR
, the difference ofimageOffset.y
andextent.height
must be a multiple of the texel block extent height of the VkFormat ofsrcImage
-
VUID-vkCmdCopyImageToBuffer-imageOffset-10058
For each element ofpRegions
, if VkCopyCommandTransformInfoQCOM::transform
is equal toVK_SURFACE_TRANSFORM_ROTATE_270_BIT_KHR
, the difference ofimageOffset.y
andextent.width
must be a multiple of the texel block extent height of the VkFormat ofsrcImage
-
VUID-vkCmdCopyImageToBuffer-srcImage-00209
For each element ofpRegions
, if the sum ofimageOffset.z
andextent.depth
does not equal the depth of the subresource specified bysrcSubresource
,extent.depth
must be a multiple of the texel block extent depth of the VkFormat ofsrcImage
-
VUID-vkCmdCopyImageToBuffer-imageSubresource-09105
For each element ofpRegions
,imageSubresource.aspectMask
must specify aspects present insrcImage
-
VUID-vkCmdCopyImageToBuffer-srcImage-07981
IfsrcImage
has a multi-planar format, then for each element ofpRegions
,imageSubresource.aspectMask
must be a single valid multi-planar aspect mask bit -
VUID-vkCmdCopyImageToBuffer-srcImage-07983
IfsrcImage
is of typeVK_IMAGE_TYPE_3D
, for each element ofpRegions
,imageSubresource.baseArrayLayer
must be0
andimageSubresource.layerCount
must be1
-
VUID-vkCmdCopyImageToBuffer-bufferRowLength-09106
For each element ofpRegions
,bufferRowLength
must be a multiple of the texel block extent width of the VkFormat ofsrcImage
-
VUID-vkCmdCopyImageToBuffer-bufferImageHeight-09107
For each element ofpRegions
,bufferImageHeight
must be a multiple of the texel block extent height of the VkFormat ofsrcImage
-
VUID-vkCmdCopyImageToBuffer-bufferRowLength-09108
For each element ofpRegions
,bufferRowLength
divided by the texel block extent width and then multiplied by the texel block size ofsrcImage
must be less than or equal to 231-1
-
VUID-vkCmdCopyImageToBuffer-srcImage-07975
IfsrcImage
does not have either a depth/stencil format or a multi-planar format, then for each element ofpRegions
,bufferOffset
must be a multiple of the texel block size -
VUID-vkCmdCopyImageToBuffer-srcImage-07976
IfsrcImage
has a multi-planar format, then for each element ofpRegions
,bufferOffset
must be a multiple of the element size of the compatible format for the format and theaspectMask
of theimageSubresource
as defined in [formats-compatible-planes] -
VUID-vkCmdCopyImageToBuffer-srcImage-07978
IfsrcImage
has a depth/stencil format, thebufferOffset
member of any element ofpRegions
must be a multiple of4
-
VUID-vkCmdCopyImageToBuffer-commandBuffer-parameter
commandBuffer
must be a valid VkCommandBuffer handle -
VUID-vkCmdCopyImageToBuffer-srcImage-parameter
srcImage
must be a valid VkImage handle -
VUID-vkCmdCopyImageToBuffer-srcImageLayout-parameter
srcImageLayout
must be a valid VkImageLayout value -
VUID-vkCmdCopyImageToBuffer-dstBuffer-parameter
dstBuffer
must be a valid VkBuffer handle -
VUID-vkCmdCopyImageToBuffer-pRegions-parameter
pRegions
must be a valid pointer to an array ofregionCount
valid VkBufferImageCopy structures -
VUID-vkCmdCopyImageToBuffer-commandBuffer-recording
commandBuffer
must be in the recording state -
VUID-vkCmdCopyImageToBuffer-commandBuffer-cmdpool
TheVkCommandPool
thatcommandBuffer
was allocated from must support transfer, graphics, or compute operations -
VUID-vkCmdCopyImageToBuffer-renderpass
This command must only be called outside of a render pass instance -
VUID-vkCmdCopyImageToBuffer-videocoding
This command must only be called outside of a video coding scope -
VUID-vkCmdCopyImageToBuffer-regionCount-arraylength
regionCount
must be greater than0
-
VUID-vkCmdCopyImageToBuffer-commonparent
Each ofcommandBuffer
,dstBuffer
, andsrcImage
must have been created, allocated, or retrieved from the same VkDevice
-
Host access to
commandBuffer
must be externally synchronized -
Host access to the
VkCommandPool
thatcommandBuffer
was allocated from must be externally synchronized
Command Buffer Levels | Render Pass Scope | Video Coding Scope | Supported Queue Types | Command Type |
---|---|---|---|---|
Primary |
Outside |
Outside |
Transfer |
Action |
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.