C Specification

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

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 ../../html/vkspec.html#features-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
  • srcBuffer must be large enough to contain all buffer locations that are accessed according to Buffer and Image Addressing, for each element of pRegions

  • 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

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

  • srcBuffer must have been created with VK_BUFFER_USAGE_TRANSFER_SRC_BIT usage flag

  • dstImage must use a format that supports VK_FORMAT_FEATURE_TRANSFER_DST_BIT, which is indicated by VkAndroidHardwareBufferFormatPropertiesANDROID::formatFeatures returned by vkGetAndroidHardwareBufferPropertiesANDROID for external format images, or by VkFormatProperties::linearTilingFeatures or VkFormatProperties::optimalTilingFeatures returned by vkGetPhysicalDeviceFormatProperties for non-external format linearly or optimally tiled images, respectively

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

  • dstImage must have been created with VK_IMAGE_USAGE_TRANSFER_DST_BIT usage flag

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

  • dstImage must have a sample count equal to VK_SAMPLE_COUNT_1_BIT

  • dstImageLayout must specify the layout of the image subresources of dstImage specified in pRegions at the time this command is executed on a VkDevice

  • dstImageLayout must be VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL, VK_IMAGE_LAYOUT_GENERAL, or VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR

  • If commandBuffer is an unprotected command buffer, then srcBuffer must not be a protected buffer

  • If commandBuffer is an unprotected command buffer, then dstImage must not be a protected image

  • If commandBuffer is a protected command buffer, then dstImage must not be an unprotected image

  • The imageSubresource.mipLevel member of each element of pRegions must be less than the mipLevels specified in VkImageCreateInfo when dstImage 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 dstImage 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

Valid Usage (Implicit)
  • commandBuffer must be a valid VkCommandBuffer handle

  • srcBuffer must be a valid VkBuffer handle

  • dstImage must be a valid VkImage handle

  • dstImageLayout must be a valid VkImageLayout value

  • 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, 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

Document Notes

For more information, see the Vulkan Specification at URL

This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.

Copyright (c) 2014-2018 Khronos Group. This work is licensed under a Creative Commons Attribution 4.0 International License.