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 region in pRegions is copied from the specified region of the source image to the specified region of the destination buffer.

If srcImage has a multi-planar format, regions of each plane to be a source of a copy must be specified separately using the pRegions member of the VkBufferImageCopy structure. In this case, the aspectMask of imageSubresource 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 vkCmdCopyBufferToImage, 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.

Valid Usage

  • VUID-vkCmdCopyImageToBuffer-commandBuffer-01831
    If commandBuffer is an unprotected command buffer and protectedNoFault is not supported, srcImage must not be a protected image

  • VUID-vkCmdCopyImageToBuffer-commandBuffer-01832
    If commandBuffer is an unprotected command buffer and protectedNoFault is not supported, dstBuffer must not be a protected buffer

  • VUID-vkCmdCopyImageToBuffer-commandBuffer-01833
    If commandBuffer is a protected command buffer and protectedNoFault is not supported, dstBuffer must not be an unprotected buffer

  • VUID-vkCmdCopyImageToBuffer-pRegions-06220
    The image region specified by each element of pRegions must be contained within the specified imageSubresource of srcImage

  • 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 of pRegions

  • VUID-vkCmdCopyImageToBuffer-pRegions-00184
    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-vkCmdCopyImageToBuffer-srcImage-00186
    srcImage must have been created with VK_IMAGE_USAGE_TRANSFER_SRC_BIT usage flag

  • VUID-vkCmdCopyImageToBuffer-srcImage-01998
    The format features of srcImage must contain VK_FORMAT_FEATURE_TRANSFER_SRC_BIT

  • VUID-vkCmdCopyImageToBuffer-srcImage-00187
    If srcImage is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-vkCmdCopyImageToBuffer-dstBuffer-00191
    dstBuffer must have been created with VK_BUFFER_USAGE_TRANSFER_DST_BIT usage flag

  • VUID-vkCmdCopyImageToBuffer-dstBuffer-00192
    If dstBuffer is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-vkCmdCopyImageToBuffer-srcImage-00188
    srcImage must have a sample count equal to VK_SAMPLE_COUNT_1_BIT

  • VUID-vkCmdCopyImageToBuffer-srcImageLayout-00189
    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-vkCmdCopyImageToBuffer-srcImageLayout-01397
    srcImageLayout must be VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL, VK_IMAGE_LAYOUT_GENERAL, or VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR

  • VUID-vkCmdCopyImageToBuffer-imageSubresource-01703
    The imageSubresource.mipLevel member of each element of pRegions must be less than the mipLevels specified in VkImageCreateInfo when srcImage was created

  • VUID-vkCmdCopyImageToBuffer-imageSubresource-01704
    The imageSubresource.baseArrayLayer + imageSubresource.layerCount of each element of pRegions must be less than or equal to the arrayLayers specified in VkImageCreateInfo when srcImage was created

  • VUID-vkCmdCopyImageToBuffer-imageOffset-01794
    The imageOffset and imageExtent 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-vkCmdCopyImageToBuffer-srcImage-02544
    srcImage must not have been created with flags containing VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT

  • VUID-vkCmdCopyImageToBuffer-pRegions-06221
    For each element of pRegions, imageOffset.x and (imageExtent.width + imageOffset.x) must both be greater than or equal to 0 and less than or equal to the width of the specified imageSubresource of srcImage

  • VUID-vkCmdCopyImageToBuffer-pRegions-06222
    For each element of pRegions, imageOffset.y and (imageExtent.height + imageOffset.y) must both be greater than or equal to 0 and less than or equal to the height of the specified imageSubresource of srcImage

  • VUID-vkCmdCopyImageToBuffer-bufferOffset-01558
    If srcImage does not have either a depth/stencil or a multi-planar format, then for each element of pRegions, bufferOffset must be a multiple of the format’s texel block size

  • VUID-vkCmdCopyImageToBuffer-bufferOffset-01559
    If srcImage has a multi-planar format, then for each element of pRegions, bufferOffset must be a multiple of the element size of the compatible format for the format and the aspectMask of the imageSubresource as defined in [formats-compatible-planes]

  • VUID-vkCmdCopyImageToBuffer-srcImage-00199
    If srcImage is of type VK_IMAGE_TYPE_1D, then for each element of pRegions, imageOffset.y must be 0 and imageExtent.height must be 1

  • VUID-vkCmdCopyImageToBuffer-imageOffset-00200
    For each element of pRegions, imageOffset.z and (imageExtent.depth + imageOffset.z) must both be greater than or equal to 0 and less than or equal to the depth of the specified imageSubresource of srcImage

  • VUID-vkCmdCopyImageToBuffer-srcImage-00201
    If srcImage is of type VK_IMAGE_TYPE_1D or VK_IMAGE_TYPE_2D, then for each element of pRegions, imageOffset.z must be 0 and imageExtent.depth must be 1

  • VUID-vkCmdCopyImageToBuffer-bufferRowLength-00203
    If srcImage is a blocked image, for each element of pRegions, bufferRowLength must be a multiple of the compressed texel block width

  • VUID-vkCmdCopyImageToBuffer-bufferImageHeight-00204
    If srcImage is a blocked image, for each element of pRegions, bufferImageHeight must be a multiple of the compressed texel block height

  • VUID-vkCmdCopyImageToBuffer-imageOffset-00205
    If srcImage is a blocked image, for each element of pRegions, all members of imageOffset must be a multiple of the corresponding dimensions of the compressed texel block

  • VUID-vkCmdCopyImageToBuffer-bufferOffset-00206
    If srcImage is a blocked image, for each element of pRegions, bufferOffset must be a multiple of the compressed texel block size in bytes

  • VUID-vkCmdCopyImageToBuffer-imageExtent-00207
    If srcImage is a blocked image, for each element of pRegions, imageExtent.width must be a multiple of the compressed texel block width or (imageExtent.width + imageOffset.x) must equal the width of the specified imageSubresource of srcImage

  • VUID-vkCmdCopyImageToBuffer-imageExtent-00208
    If srcImage is a blocked image, for each element of pRegions, imageExtent.height must be a multiple of the compressed texel block height or (imageExtent.height + imageOffset.y) must equal the height of the specified imageSubresource of srcImage

  • VUID-vkCmdCopyImageToBuffer-imageExtent-00209
    If srcImage is a blocked image, for each element of pRegions, imageExtent.depth must be a multiple of the compressed texel block depth or (imageExtent.depth + imageOffset.z) must equal the depth of the specified imageSubresource of srcImage

  • VUID-vkCmdCopyImageToBuffer-aspectMask-00211
    For each element of pRegions, imageSubresource.aspectMask must specify aspects present in srcImage

  • VUID-vkCmdCopyImageToBuffer-aspectMask-01560
    If srcImage has a multi-planar format, then for each element of pRegions, imageSubresource.aspectMask must be VK_IMAGE_ASPECT_PLANE_0_BIT, VK_IMAGE_ASPECT_PLANE_1_BIT, or VK_IMAGE_ASPECT_PLANE_2_BIT (with VK_IMAGE_ASPECT_PLANE_2_BIT valid only for image formats with three planes)

  • VUID-vkCmdCopyImageToBuffer-baseArrayLayer-00213
    If srcImage is of type VK_IMAGE_TYPE_3D, for each element of pRegions, imageSubresource.baseArrayLayer must be 0 and imageSubresource.layerCount must be 1

  • VUID-vkCmdCopyImageToBuffer-pRegions-04725
    If srcImage is not a blocked image, for each element of pRegions, bufferRowLength multiplied by the texel block size of srcImage must be less than or equal to 231-1

  • VUID-vkCmdCopyImageToBuffer-pRegions-04726
    If srcImage is a blocked image, for each element of pRegions, bufferRowLength divided by the compressed texel block width and then multiplied by the texel block size of srcImage must be less than or equal to 231-1

  • VUID-vkCmdCopyImageToBuffer-commandBuffer-04052
    If the queue family used to create the VkCommandPool which commandBuffer was allocated from does not support VK_QUEUE_GRAPHICS_BIT or VK_QUEUE_COMPUTE_BIT, the bufferOffset member of any element of pRegions must be a multiple of 4

  • VUID-vkCmdCopyImageToBuffer-srcImage-04053
    If srcImage has a depth/stencil format, the bufferOffset member of any element of pRegions must be a multiple of 4

Valid Usage (Implicit)

  • 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 of regionCount valid VkBufferImageCopy structures

  • VUID-vkCmdCopyImageToBuffer-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdCopyImageToBuffer-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer 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-regionCount-arraylength
    regionCount must be greater than 0

  • VUID-vkCmdCopyImageToBuffer-commonparent
    Each of commandBuffer, dstBuffer, and srcImage must have been created, allocated, or retrieved from the same VkDevice

Host Synchronization

  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Supported Queue Types

Primary
Secondary

Outside

Transfer
Graphics
Compute

See Also

VK_VERSION_1_0, VkBuffer, VkBufferImageCopy, VkCommandBuffer, VkImage, VkImageLayout

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.

Copyright

Copyright 2014-2022 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0