vkCmdCopyBufferToImage(3)

# vkCmdCopyBufferToImage(3) Manual Page

## Name

vkCmdCopyBufferToImage - Copy data from a buffer into an image

Loading… please wait.

## C Specification

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

    // Provided by VK_VERSION_1_0
    void vkCmdCopyBufferToImage(
        VkCommandBuffer                             commandBuffer,
        VkBuffer                                    srcBuffer,
        VkImage                                     dstImage,
        VkImageLayout                               dstImageLayout,
        uint32_t                                    regionCount,
        const VkBufferImageCopy*                    pRegions);

## Parameters

- `commandBuffer` is the command buffer into which the command will be recorded.

- `srcBuffer` is the source buffer.

- `dstImage` is the destination image.

- `dstImageLayout` is the layout of the destination image subresources for the copy.

- `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 buffer to the specified region of the destination image.

If the format of `dstImage` is a multi-planar image format, regions of each plane to be a target 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.2-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-vkCmdCopyBufferToImage-commandBuffer-01828
  If `commandBuffer` is an unprotected command buffer, then `srcBuffer` must not be a protected buffer

- VUID-vkCmdCopyBufferToImage-commandBuffer-01829
  If `commandBuffer` is an unprotected command buffer, then `dstImage` must not be a protected image

- VUID-vkCmdCopyBufferToImage-commandBuffer-01830
  If `commandBuffer` is a protected command buffer, then `dstImage` must not be an unprotected image

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

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

- VUID-vkCmdCopyBufferToImage-pRegions-00173
  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-vkCmdCopyBufferToImage-srcBuffer-00174
  `srcBuffer` must have been created with `VK_BUFFER_USAGE_TRANSFER_SRC_BIT` usage flag

- VUID-vkCmdCopyBufferToImage-dstImage-01997
  The format features of `dstImage` must contain `VK_FORMAT_FEATURE_TRANSFER_DST_BIT`

- VUID-vkCmdCopyBufferToImage-srcBuffer-00176
  If `srcBuffer` is non-sparse then it must be bound completely and contiguously to a single `VkDeviceMemory` object

- VUID-vkCmdCopyBufferToImage-dstImage-00177
  `dstImage` must have been created with `VK_IMAGE_USAGE_TRANSFER_DST_BIT` usage flag

- VUID-vkCmdCopyBufferToImage-dstImage-00178
  If `dstImage` is non-sparse then it must be bound completely and contiguously to a single `VkDeviceMemory` object

- VUID-vkCmdCopyBufferToImage-dstImage-00179
  `dstImage` must have a sample count equal to `VK_SAMPLE_COUNT_1_BIT`

- VUID-vkCmdCopyBufferToImage-dstImageLayout-00180
  `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-vkCmdCopyBufferToImage-dstImageLayout-01396
  `dstImageLayout` must be `VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL`, `VK_IMAGE_LAYOUT_GENERAL`, or `VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR`

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

- VUID-vkCmdCopyBufferToImage-imageSubresource-01702
  The `imageSubresource.baseArrayLayer` + `imageSubresource.layerCount` of each element of `pRegions` must be less than or equal to the `arrayLayers` specified in VkImageCreateInfo when `dstImage` was created

- VUID-vkCmdCopyBufferToImage-imageOffset-01793
  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-vkCmdCopyBufferToImage-dstImage-02543
  `dstImage` must not have been created with `flags` containing `VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT`

- VUID-vkCmdCopyBufferToImage-commandBuffer-04477
  If the queue family used to create the VkCommandPool which `commandBuffer` was allocated from does not support `VK_QUEUE_GRAPHICS_BIT`, for each element of `pRegions`, the `aspectMask` member of `imageSubresource` must not be `VK_IMAGE_ASPECT_DEPTH_BIT` or `VK_IMAGE_ASPECT_STENCIL_BIT`.

- VUID-vkCmdCopyBufferToImage-imageOffset-00197
  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 `dstImage` where this refers to the width of the plane of the image involved in the copy in the case of a multi-planar format

- VUID-vkCmdCopyBufferToImage-imageOffset-00198
  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 `dstImage` where this refers to the height of the plane of the image involved in the copy in the case of a multi-planar format

- VUID-vkCmdCopyBufferToImage-bufferOffset-01558
  If `dstImage` 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-vkCmdCopyBufferToImage-bufferOffset-01559
  If `dstImage` 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-vkCmdCopyBufferToImage-srcImage-00199
  If `dstImage` 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-vkCmdCopyBufferToImage-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 `dstImage`

- VUID-vkCmdCopyBufferToImage-srcImage-00201
  If `dstImage` 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-vkCmdCopyBufferToImage-bufferRowLength-00203
  If `dstImage` is a blocked image, for each element of `pRegions`, `bufferRowLength` must be a multiple of the compressed texel block width

- VUID-vkCmdCopyBufferToImage-bufferImageHeight-00204
  If `dstImage` is a blocked image, for each element of `pRegions`, `bufferImageHeight` must be a multiple of the compressed texel block height

- VUID-vkCmdCopyBufferToImage-imageOffset-00205
  If `dstImage` 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-vkCmdCopyBufferToImage-bufferOffset-00206
  If `dstImage` is a blocked image, for each element of `pRegions`, `bufferOffset` must be a multiple of the compressed texel block size in bytes

- VUID-vkCmdCopyBufferToImage-imageExtent-00207
  If `dstImage` 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 `dstImage`

- VUID-vkCmdCopyBufferToImage-imageExtent-00208
  If `dstImage` 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 `dstImage`

- VUID-vkCmdCopyBufferToImage-imageExtent-00209
  If `dstImage` 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 `dstImage`

- VUID-vkCmdCopyBufferToImage-aspectMask-00211
  For each element of `pRegions`, `imageSubresource.aspectMask` must specify aspects present in `dstImage`

- VUID-vkCmdCopyBufferToImage-aspectMask-01560
  If `dstImage` 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-vkCmdCopyBufferToImage-baseArrayLayer-00213
  If `dstImage` is of type `VK_IMAGE_TYPE_3D`, for each element of `pRegions`, `imageSubresource.baseArrayLayer` must be `0` and `imageSubresource.layerCount` must be `1`

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

- VUID-vkCmdCopyBufferToImage-pRegions-04726
  If `dstImage` 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 `dstImage` must be less than or equal to 231-1

- VUID-vkCmdCopyBufferToImage-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-vkCmdCopyBufferToImage-srcImage-04053
  If `dstImage` has a depth/stencil format, the `bufferOffset` member of any element of `pRegions` must be a multiple of `4`

Valid Usage (Implicit)

- VUID-vkCmdCopyBufferToImage-commandBuffer-parameter
  `commandBuffer` must be a valid VkCommandBuffer handle

- VUID-vkCmdCopyBufferToImage-srcBuffer-parameter
  `srcBuffer` must be a valid VkBuffer handle

- VUID-vkCmdCopyBufferToImage-dstImage-parameter
  `dstImage` must be a valid VkImage handle

- VUID-vkCmdCopyBufferToImage-dstImageLayout-parameter
  `dstImageLayout` must be a valid VkImageLayout value

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

- VUID-vkCmdCopyBufferToImage-commandBuffer-recording
  `commandBuffer` must be in the recording state

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

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

- VUID-vkCmdCopyBufferToImage-regionCount-arraylength
  `regionCount` must be greater than `0`

- VUID-vkCmdCopyBufferToImage-commonparent
  Each of `commandBuffer`, `dstImage`, and `srcBuffer` 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 2014-2021 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0