VulkanHub
Function Prototype

vkCmdCopyBufferToImage2

Copy data from a buffer into an image

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

void vkCmdCopyBufferToImage2(
    VkCommandBuffer commandBuffer,
    const VkCopyBufferToImageInfo2* pCopyBufferToImageInfo);

void vkCmdCopyBufferToImage2KHR(
    VkCommandBuffer commandBuffer,
    const VkCopyBufferToImageInfo2* pCopyBufferToImageInfo);
  • commandBuffer is the command buffer into which the command will be recorded.
  • pCopyBufferToImageInfo is a pointer to a VkCopyBufferToImageInfo2 structure describing the copy parameters.

This command is functionally identical to vkCmdCopyBufferToImage, but includes extensible sub-structures that include sType and pNext parameters, allowing them to be more easily extended.

Valid Usage

VUID-vkCmdCopyBufferToImage2-commandBuffer-01828

If commandBuffer is an unprotected command buffer and protectedNoFault is not supported, srcBuffer must not be a protected buffer

VUID-vkCmdCopyBufferToImage2-commandBuffer-01829

If commandBuffer is an unprotected command buffer and protectedNoFault is not supported, dstImage must not be a protected image

VUID-vkCmdCopyBufferToImage2-commandBuffer-01830

If commandBuffer is a protected command buffer and protectedNoFault is not supported, dstImage must not be an unprotected image

VUID-vkCmdCopyBufferToImage2-commandBuffer-07737

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 pCopyBufferToImageInfo→pRegions must be a multiple of 4

VUID-vkCmdCopyBufferToImage2-imageOffset-07738

The imageOffset and imageExtent members of each element of pCopyBufferToImageInfo→pRegions must respect the image transfer granularity requirements of commandBuffer’s command pool’s queue family, as described in VkQueueFamilyProperties

VUID-vkCmdCopyBufferToImage2-commandBuffer-07739

If the queue family used to create the VkCommandPool which commandBuffer was allocated from does not support VK_QUEUE_GRAPHICS_BIT, and the maintenance10 feature is not enabled, for each element of pCopyBufferToImageInfo→pRegions, the aspectMask member of imageSubresource must not be VK_IMAGE_ASPECT_DEPTH_BIT or VK_IMAGE_ASPECT_STENCIL_BIT

VUID-vkCmdCopyBufferToImage2-commandBuffer-11778

If the queue family used to create the VkCommandPool which commandBuffer was allocated from does not support VK_QUEUE_GRAPHICS_BIT but does support VK_QUEUE_COMPUTE_BIT, and in any element of pCopyBufferToImageInfo→pRegions the aspectMask member of imageSubresource is VK_IMAGE_ASPECT_DEPTH_BIT, then the format features of dstImagemust contain VK_FORMAT_FEATURE_2_DEPTH_COPY_ON_COMPUTE_QUEUE_BIT_KHR

VUID-vkCmdCopyBufferToImage2-commandBuffer-11779

If the queue family used to create the VkCommandPool which commandBuffer was allocated from does not support VK_QUEUE_GRAPHICS_BIT and VK_QUEUE_COMPUTE_BIT, but does support VK_QUEUE_TRANSFER_BIT, and in any element of pCopyBufferToImageInfo→pRegions the aspectMask member of imageSubresource is VK_IMAGE_ASPECT_DEPTH_BIT, then the format features of dstImagemust contain VK_FORMAT_FEATURE_2_DEPTH_COPY_ON_TRANSFER_QUEUE_BIT_KHR

VUID-vkCmdCopyBufferToImage2-commandBuffer-11780

If the queue family used to create the VkCommandPool which commandBuffer was allocated from does not support VK_QUEUE_GRAPHICS_BIT but does support VK_QUEUE_COMPUTE_BIT, and in any element of pCopyBufferToImageInfo→pRegions the aspectMask member of imageSubresource is VK_IMAGE_ASPECT_STENCIL_BIT, then the format features of dstImagemust contain VK_FORMAT_FEATURE_2_STENCIL_COPY_ON_COMPUTE_QUEUE_BIT_KHR

VUID-vkCmdCopyBufferToImage2-commandBuffer-11781

If the queue family used to create the VkCommandPool which commandBuffer was allocated from does not support VK_QUEUE_GRAPHICS_BIT and VK_QUEUE_COMPUTE_BIT, but does support VK_QUEUE_TRANSFER_BIT, and in any element of pCopyBufferToImageInfo→pRegions the aspectMask member of imageSubresource is VK_IMAGE_ASPECT_STENCIL_BIT, then the format features of dstImagemust contain VK_FORMAT_FEATURE_2_STENCIL_COPY_ON_TRANSFER_QUEUE_BIT_KHR

Valid Usage (Implicit)

VUID-vkCmdCopyBufferToImage2-commandBuffer-parameter

commandBuffer must be a valid VkCommandBuffer handle

VUID-vkCmdCopyBufferToImage2-pCopyBufferToImageInfo-parameter

pCopyBufferToImageInfo must be a valid pointer to a valid VkCopyBufferToImageInfo2 structure

VUID-vkCmdCopyBufferToImage2-commandBuffer-recording

commandBuffer must be in the recording state

VUID-vkCmdCopyBufferToImage2-commandBuffer-cmdpool

The VkCommandPool that commandBuffer was allocated from must support VK_QUEUE_COMPUTE_BIT, VK_QUEUE_GRAPHICS_BIT, or VK_QUEUE_TRANSFER_BIT operations

VUID-vkCmdCopyBufferToImage2-renderpass

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

VUID-vkCmdCopyBufferToImage2-suspended

This command must not be called between suspended render pass instances

VUID-vkCmdCopyBufferToImage2-videocoding

This command must only be called outside of a video coding scope

Host Synchronization

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