vkCmdCopyImageToBuffer(3)

# vkCmdCopyImageToBuffer(3) Manual Page

## Name

vkCmdCopyImageToBuffer - Copy image data into a buffer

## C Specification

To copy data from an image object to a buffer object, call:

    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 the VkFormat of `srcImage` is a multi-planar image 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.1-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

- The image region specified by each element of `pRegions` must be a region that is contained within `srcImage` if the `srcImage`’s VkFormat is not a multi-planar format, and must be a region that is contained within the plane being copied if the `srcImage`’s VkFormat is a multi-planar format

- `dstBuffer` must be large enough to contain all buffer locations that are accessed according to Buffer and Image Addressing, for each element of `pRegions`

- The union of all source regions, and the union of all destination regions, specified by the elements of `pRegions`, must not overlap in memory

- The format features of `srcImage` must contain `VK_FORMAT_FEATURE_TRANSFER_SRC_BIT`.

- `srcImage` must have been created with `VK_IMAGE_USAGE_TRANSFER_SRC_BIT` usage flag

- If `srcImage` is non-sparse then it must be bound completely and contiguously to a single `VkDeviceMemory` object

- `srcImage` must have a sample count equal to `VK_SAMPLE_COUNT_1_BIT`

- `srcImageLayout` must specify the layout of the image subresources of `srcImage` specified in `pRegions` at the time this command is executed on a `VkDevice`

- `srcImageLayout` must be `VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR`, `VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL` or `VK_IMAGE_LAYOUT_GENERAL`

- `dstBuffer` must have been created with `VK_BUFFER_USAGE_TRANSFER_DST_BIT` usage flag

- If `dstBuffer` is non-sparse then it must be bound completely and contiguously to a single `VkDeviceMemory` object

- If `commandBuffer` is an unprotected command buffer, then `srcImage` must not be a protected image

- If `commandBuffer` is an unprotected command buffer, then `dstBuffer` must not be a protected buffer

- If `commandBuffer` is a protected command buffer, then `dstBuffer` must not be an unprotected buffer

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

- 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

- 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

- `srcImage` must not have been created with `flags` containing `VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT`

Valid Usage (Implicit)

- `commandBuffer` must be a valid `VkCommandBuffer` handle

- `srcImage` must be a valid `VkImage` handle

- `srcImageLayout` must be a valid VkImageLayout value

- `dstBuffer` must be a valid `VkBuffer` handle

- `pRegions` must be a valid pointer to an array of `regionCount` valid `VkBufferImageCopy` structures

- `commandBuffer` must be in the recording state

- The `VkCommandPool` that `commandBuffer` was allocated from must support transfer, graphics, or compute operations

- This command must only be called outside of a render pass instance

- `regionCount` must be greater than `0`

- 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 | Pipeline Type
--- | --- | --- | ---
Primary Secondary | Outside | Transfer Graphics Compute | Transfer

## See Also

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 (c) 2014-2019 Khronos Group. This work is licensed under a Creative Commons Attribution 4.0 International License.