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
-
commandBufferis the command buffer into which the command will be recorded. -
srcImageis the source image. -
srcImageLayoutis the layout of the source image subresources for the copy. -
dstBufferis the destination buffer. -
regionCountis the number of regions to copy. -
pRegionsis 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
IfsrcImageis non-sparse then the image or the specified disjoint plane must be bound completely and contiguously to a singleVkDeviceMemoryobject -
VUID-vkCmdCopyImageToBuffer-imageSubresource-07967
TheimageSubresource.mipLevelmember of each element ofpRegionsmust be less than themipLevelsspecified in VkImageCreateInfo whensrcImagewas created -
VUID-vkCmdCopyImageToBuffer-imageSubresource-07968
IfimageSubresource.layerCountis notVK_REMAINING_ARRAY_LAYERS,imageSubresource.baseArrayLayer+imageSubresource.layerCountof each element ofpRegionsmust be less than or equal to thearrayLayersspecified in VkImageCreateInfo whensrcImagewas created -
VUID-vkCmdCopyImageToBuffer-srcImage-07969
srcImagemust not have been created withflagscontainingVK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT
-
VUID-vkCmdCopyImageToBuffer-imageSubresource-07970
The image region specified by each element ofpRegionsmust be contained within the specifiedimageSubresourceofsrcImage -
VUID-vkCmdCopyImageToBuffer-imageSubresource-07971
For each element ofpRegions,imageOffset.xand (imageExtent.width+imageOffset.x) must both be greater than or equal to0and less than or equal to the width of the specifiedimageSubresourceofsrcImage -
VUID-vkCmdCopyImageToBuffer-imageSubresource-07972
For each element ofpRegions,imageOffset.yand (imageExtent.height+imageOffset.y) must both be greater than or equal to0and less than or equal to the height of the specifiedimageSubresourceofsrcImage
-
VUID-vkCmdCopyImageToBuffer-commandBuffer-01831
IfcommandBufferis an unprotected command buffer andprotectedNoFaultis not supported,srcImagemust not be a protected image -
VUID-vkCmdCopyImageToBuffer-commandBuffer-01832
IfcommandBufferis an unprotected command buffer andprotectedNoFaultis not supported,dstBuffermust not be a protected buffer -
VUID-vkCmdCopyImageToBuffer-commandBuffer-01833
IfcommandBufferis a protected command buffer andprotectedNoFaultis not supported,dstBuffermust not be an unprotected buffer -
VUID-vkCmdCopyImageToBuffer-commandBuffer-07746
If the queue family used to create the VkCommandPool whichcommandBufferwas allocated from does not supportVK_QUEUE_GRAPHICS_BITorVK_QUEUE_COMPUTE_BIT, thebufferOffsetmember of any element ofpRegionsmust be a multiple of4 -
VUID-vkCmdCopyImageToBuffer-imageOffset-07747
TheimageOffsetandimageExtentmembers of each element ofpRegionsmust 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 whichcommandBufferwas allocated from does not supportVK_QUEUE_GRAPHICS_BIT, for each element ofpRegions, theaspectMaskmember ofimageSubresourcemust not beVK_IMAGE_ASPECT_DEPTH_BITorVK_IMAGE_ASPECT_STENCIL_BIT
-
VUID-vkCmdCopyImageToBuffer-pRegions-00183
dstBuffermust 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
srcImagemust have been created withVK_IMAGE_USAGE_TRANSFER_SRC_BITusage flag -
VUID-vkCmdCopyImageToBuffer-srcImage-01998
The format features ofsrcImagemust containVK_FORMAT_FEATURE_TRANSFER_SRC_BIT -
VUID-vkCmdCopyImageToBuffer-dstBuffer-00191
dstBuffermust have been created withVK_BUFFER_USAGE_TRANSFER_DST_BITusage flag -
VUID-vkCmdCopyImageToBuffer-dstBuffer-00192
IfdstBufferis non-sparse then it must be bound completely and contiguously to a singleVkDeviceMemoryobject -
VUID-vkCmdCopyImageToBuffer-srcImageLayout-00189
srcImageLayoutmust specify the layout of the image subresources ofsrcImagespecified inpRegionsat the time this command is executed on aVkDevice -
VUID-vkCmdCopyImageToBuffer-srcImageLayout-01397
srcImageLayoutmust beVK_IMAGE_LAYOUT_SHARED_PRESENT_KHR,VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL, orVK_IMAGE_LAYOUT_GENERAL
-
VUID-vkCmdCopyImageToBuffer-srcImage-07979
IfsrcImageis of typeVK_IMAGE_TYPE_1D, then for each element ofpRegions,imageOffset.ymust be0andimageExtent.heightmust be1 -
VUID-vkCmdCopyImageToBuffer-imageOffset-09104
For each element ofpRegions,imageOffset.zand (imageExtent.depth+imageOffset.z) must both be greater than or equal to0and less than or equal to the depth of the specifiedimageSubresourceofsrcImage -
VUID-vkCmdCopyImageToBuffer-srcImage-07980
IfsrcImageis of typeVK_IMAGE_TYPE_1DorVK_IMAGE_TYPE_2D, then for each element ofpRegions,imageOffset.zmust be0andimageExtent.depthmust be1 -
VUID-vkCmdCopyImageToBuffer-srcImage-07274
For each element ofpRegions, if VkCopyCommandTransformInfoQCOM::transformis equal toVK_SURFACE_TRANSFORM_IDENTITY_BIT_KHRorVK_SURFACE_TRANSFORM_ROTATE_270_BIT_KHR,imageOffset.xmust be a multiple of the texel block extent width of the VkFormat ofsrcImage -
VUID-vkCmdCopyImageToBuffer-imageOffset-10051
For each element ofpRegions, if VkCopyCommandTransformInfoQCOM::transformis equal toVK_SURFACE_TRANSFORM_ROTATE_180_BIT_KHRorVK_SURFACE_TRANSFORM_ROTATE_90_BIT_KHR, andimageOffset.xdoes not equal the width of the subresource specified byimageSubresource,imageOffset.xmust be a multiple of the texel block extent width of the VkFormat ofsrcImage -
VUID-vkCmdCopyImageToBuffer-srcImage-07275
For each element ofpRegions, if VkCopyCommandTransformInfoQCOM::transformis equal toVK_SURFACE_TRANSFORM_IDENTITY_BIT_KHRorVK_SURFACE_TRANSFORM_ROTATE_90_BIT_KHR,imageOffset.ymust be a multiple of the texel block extent height of the VkFormat ofsrcImage -
VUID-vkCmdCopyImageToBuffer-imageOffset-10052
For each element ofpRegions, if VkCopyCommandTransformInfoQCOM::transformis equal toVK_SURFACE_TRANSFORM_ROTATE_270_BIT_KHRorVK_SURFACE_TRANSFORM_ROTATE_180_BIT_KHR, andimageOffset.ydoes not equal the height of the subresource specified byimageSubresource,imageOffset.ymust be a multiple of the texel block extent height of the VkFormat ofsrcImage -
VUID-vkCmdCopyImageToBuffer-srcImage-07276
For each element ofpRegions,imageOffset.zmust be a multiple of the texel block extent depth of the VkFormat ofsrcImage -
VUID-vkCmdCopyImageToBuffer-srcImage-00207
For each element ofpRegions, if VkCopyCommandTransformInfoQCOM::transformis equal toVK_SURFACE_TRANSFORM_IDENTITY_BIT_KHR, the sum ofimageOffset.xandextent.widthdoes not equal the width of the subresource specified byimageSubresource,extent.widthmust be a multiple of the texel block extent width of the VkFormat ofsrcImage -
VUID-vkCmdCopyImageToBuffer-imageOffset-10053
For each element ofpRegions, if VkCopyCommandTransformInfoQCOM::transformis equal toVK_SURFACE_TRANSFORM_ROTATE_90_BIT_KHR, the difference ofimageOffset.xandextent.heightmust be a multiple of the texel block extent width of the VkFormat ofsrcImage -
VUID-vkCmdCopyImageToBuffer-imageOffset-10054
For each element ofpRegions, if VkCopyCommandTransformInfoQCOM::transformis equal toVK_SURFACE_TRANSFORM_ROTATE_180_BIT_KHR, the difference ofimageOffset.xandextent.widthmust be a multiple of the texel block extent width of the VkFormat ofsrcImage -
VUID-vkCmdCopyImageToBuffer-imageOffset-10055
For each element ofpRegions, if VkCopyCommandTransformInfoQCOM::transformis equal toVK_SURFACE_TRANSFORM_ROTATE_270_BIT_KHR, the sum ofimageOffset.xandextent.heightdoes not equal the width of the subresource specified byimageSubresource,extent.heightmust be a multiple of the texel block extent width of the VkFormat ofsrcImage -
VUID-vkCmdCopyImageToBuffer-srcImage-00208
For each element ofpRegions, if VkCopyCommandTransformInfoQCOM::transformis equal toVK_SURFACE_TRANSFORM_IDENTITY_BIT_KHR, and the sum ofimageOffset.yandextent.heightdoes not equal the height of the subresource specified byimageSubresource,extent.heightmust be a multiple of the texel block extent height of the VkFormat ofsrcImage -
VUID-vkCmdCopyImageToBuffer-imageOffset-10056
For each element ofpRegions, if VkCopyCommandTransformInfoQCOM::transformis equal toVK_SURFACE_TRANSFORM_ROTATE_90_BIT_KHR, the sum ofimageOffset.yandextent.widthdoes not equal the height of the subresource specified byimageSubresource,extent.widthmust be a multiple of the texel block extent height of the VkFormat ofsrcImage -
VUID-vkCmdCopyImageToBuffer-imageOffset-10057
For each element ofpRegions, if VkCopyCommandTransformInfoQCOM::transformis equal toVK_SURFACE_TRANSFORM_ROTATE_180_BIT_KHR, the difference ofimageOffset.yandextent.heightmust be a multiple of the texel block extent height of the VkFormat ofsrcImage -
VUID-vkCmdCopyImageToBuffer-imageOffset-10058
For each element ofpRegions, if VkCopyCommandTransformInfoQCOM::transformis equal toVK_SURFACE_TRANSFORM_ROTATE_270_BIT_KHR, the difference ofimageOffset.yandextent.widthmust 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.zandextent.depthdoes not equal the depth of the subresource specified bysrcSubresource,extent.depthmust be a multiple of the texel block extent depth of the VkFormat ofsrcImage -
VUID-vkCmdCopyImageToBuffer-imageSubresource-09105
For each element ofpRegions,imageSubresource.aspectMaskmust specify aspects present insrcImage -
VUID-vkCmdCopyImageToBuffer-srcImage-07981
IfsrcImagehas a multi-planar format, then for each element ofpRegions,imageSubresource.aspectMaskmust be a single valid multi-planar aspect mask bit -
VUID-vkCmdCopyImageToBuffer-srcImage-07983
IfsrcImageis of typeVK_IMAGE_TYPE_3D, for each element ofpRegions,imageSubresource.baseArrayLayermust be0andimageSubresource.layerCountmust be1
-
VUID-vkCmdCopyImageToBuffer-bufferRowLength-09106
For each element ofpRegions,bufferRowLengthmust be a multiple of the texel block extent width of the VkFormat ofsrcImage -
VUID-vkCmdCopyImageToBuffer-bufferImageHeight-09107
For each element ofpRegions,bufferImageHeightmust be a multiple of the texel block extent height of the VkFormat ofsrcImage -
VUID-vkCmdCopyImageToBuffer-bufferRowLength-09108
For each element ofpRegions,bufferRowLengthdivided by the texel block extent width and then multiplied by the texel block size ofsrcImagemust be less than or equal to 231-1
-
VUID-vkCmdCopyImageToBuffer-srcImage-07975
IfsrcImagedoes not have either a depth/stencil format or a multi-planar format, then for each element ofpRegions,bufferOffsetmust be a multiple of the texel block size -
VUID-vkCmdCopyImageToBuffer-srcImage-07976
IfsrcImagehas a multi-planar format, then for each element ofpRegions,bufferOffsetmust be a multiple of the element size of the compatible format for the format and theaspectMaskof theimageSubresourceas defined in [formats-compatible-planes] -
VUID-vkCmdCopyImageToBuffer-srcImage-07978
IfsrcImagehas a depth/stencil format, thebufferOffsetmember of any element ofpRegionsmust be a multiple of4
-
VUID-vkCmdCopyImageToBuffer-commandBuffer-parameter
commandBuffermust be a valid VkCommandBuffer handle -
VUID-vkCmdCopyImageToBuffer-srcImage-parameter
srcImagemust be a valid VkImage handle -
VUID-vkCmdCopyImageToBuffer-srcImageLayout-parameter
srcImageLayoutmust be a valid VkImageLayout value -
VUID-vkCmdCopyImageToBuffer-dstBuffer-parameter
dstBuffermust be a valid VkBuffer handle -
VUID-vkCmdCopyImageToBuffer-pRegions-parameter
pRegionsmust be a valid pointer to an array ofregionCountvalid VkBufferImageCopy structures -
VUID-vkCmdCopyImageToBuffer-commandBuffer-recording
commandBuffermust be in the recording state -
VUID-vkCmdCopyImageToBuffer-commandBuffer-cmdpool
TheVkCommandPoolthatcommandBufferwas 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
regionCountmust be greater than0 -
VUID-vkCmdCopyImageToBuffer-commonparent
Each ofcommandBuffer,dstBuffer, andsrcImagemust have been created, allocated, or retrieved from the same VkDevice
-
Host access to
commandBuffermust be externally synchronized -
Host access to the
VkCommandPoolthatcommandBufferwas 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.