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 source region specified by pRegions
is copied from the source
buffer to the destination region of the destination image according to the
addressing calculations for each
resource.
If any of the specified regions in srcBuffer
overlaps in memory with
any of the specified regions in dstImage
, values read from those
overlapping regions are undefined.
If any region accesses a depth aspect in dstImage
and the VK_EXT_depth_range_unrestricted
extension is not enabled,
values copied from srcBuffer
outside of the range [0,1] will be
written as undefined values to the destination image.
Copy regions for the image must be aligned to a multiple of the texel block extent in each dimension, except at the edges of the image, where region extents must match the edge of the image.
-
VUID-vkCmdCopyBufferToImage-dstImage-07966
IfdstImage
is non-sparse then the image or the specified disjoint plane must be bound completely and contiguously to a singleVkDeviceMemory
object -
VUID-vkCmdCopyBufferToImage-imageSubresource-07967
TheimageSubresource.mipLevel
member of each element ofpRegions
must be less than themipLevels
specified in VkImageCreateInfo whendstImage
was created -
VUID-vkCmdCopyBufferToImage-imageSubresource-07968
IfimageSubresource.layerCount
is notVK_REMAINING_ARRAY_LAYERS
,imageSubresource.baseArrayLayer
+imageSubresource.layerCount
of each element ofpRegions
must be less than or equal to thearrayLayers
specified in VkImageCreateInfo whendstImage
was created -
VUID-vkCmdCopyBufferToImage-dstImage-07969
dstImage
must not have been created withflags
containingVK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT
-
VUID-vkCmdCopyBufferToImage-imageSubresource-07970
The image region specified by each element ofpRegions
must be contained within the specifiedimageSubresource
ofdstImage
-
VUID-vkCmdCopyBufferToImage-imageSubresource-07971
For each element ofpRegions
,imageOffset.x
and (imageExtent.width
+imageOffset.x
) must both be greater than or equal to0
and less than or equal to the width of the specifiedimageSubresource
ofdstImage
-
VUID-vkCmdCopyBufferToImage-imageSubresource-07972
For each element ofpRegions
,imageOffset.y
and (imageExtent.height
+imageOffset.y
) must both be greater than or equal to0
and less than or equal to the height of the specifiedimageSubresource
ofdstImage
-
VUID-vkCmdCopyBufferToImage-commandBuffer-01828
IfcommandBuffer
is an unprotected command buffer andprotectedNoFault
is not supported,srcBuffer
must not be a protected buffer -
VUID-vkCmdCopyBufferToImage-commandBuffer-01829
IfcommandBuffer
is an unprotected command buffer andprotectedNoFault
is not supported,dstImage
must not be a protected image -
VUID-vkCmdCopyBufferToImage-commandBuffer-01830
IfcommandBuffer
is a protected command buffer andprotectedNoFault
is not supported,dstImage
must not be an unprotected image -
VUID-vkCmdCopyBufferToImage-commandBuffer-07737
If the queue family used to create the VkCommandPool whichcommandBuffer
was allocated from does not supportVK_QUEUE_GRAPHICS_BIT
orVK_QUEUE_COMPUTE_BIT
, thebufferOffset
member of any element ofpRegions
must be a multiple of4
-
VUID-vkCmdCopyBufferToImage-imageOffset-07738
TheimageOffset
andimageExtent
members of each element ofpRegions
must respect the image transfer granularity requirements ofcommandBuffer
’s command pool’s queue family, as described in VkQueueFamilyProperties -
VUID-vkCmdCopyBufferToImage-commandBuffer-07739
If the queue family used to create the VkCommandPool whichcommandBuffer
was allocated from does not supportVK_QUEUE_GRAPHICS_BIT
, for each element ofpRegions
, theaspectMask
member ofimageSubresource
must not beVK_IMAGE_ASPECT_DEPTH_BIT
orVK_IMAGE_ASPECT_STENCIL_BIT
-
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 ofpRegions
-
VUID-vkCmdCopyBufferToImage-pRegions-00173
The union of all source regions, and the union of all destination regions, specified by the elements ofpRegions
, must not overlap in memory -
VUID-vkCmdCopyBufferToImage-srcBuffer-00174
srcBuffer
must have been created withVK_BUFFER_USAGE_TRANSFER_SRC_BIT
usage flag -
VUID-vkCmdCopyBufferToImage-dstImage-01997
The format features ofdstImage
must containVK_FORMAT_FEATURE_TRANSFER_DST_BIT
-
VUID-vkCmdCopyBufferToImage-srcBuffer-00176
IfsrcBuffer
is non-sparse then it must be bound completely and contiguously to a singleVkDeviceMemory
object -
VUID-vkCmdCopyBufferToImage-dstImage-00177
dstImage
must have been created withVK_IMAGE_USAGE_TRANSFER_DST_BIT
usage flag -
VUID-vkCmdCopyBufferToImage-dstImageLayout-00180
dstImageLayout
must specify the layout of the image subresources ofdstImage
specified inpRegions
at the time this command is executed on aVkDevice
-
VUID-vkCmdCopyBufferToImage-dstImageLayout-01396
dstImageLayout
must beVK_IMAGE_LAYOUT_SHARED_PRESENT_KHR
,VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL
, orVK_IMAGE_LAYOUT_GENERAL
-
VUID-vkCmdCopyBufferToImage-pRegions-07931
If VK_EXT_depth_range_unrestricted is not enabled, for each element ofpRegions
whoseimageSubresource
contains a depth aspect, the data insrcBuffer
must be in the range [0,1]
-
VUID-vkCmdCopyBufferToImage-dstImage-07979
IfdstImage
is of typeVK_IMAGE_TYPE_1D
, then for each element ofpRegions
,imageOffset.y
must be0
andimageExtent.height
must be1
-
VUID-vkCmdCopyBufferToImage-imageOffset-09104
For each element ofpRegions
,imageOffset.z
and (imageExtent.depth
+imageOffset.z
) must both be greater than or equal to0
and less than or equal to the depth of the specifiedimageSubresource
ofdstImage
-
VUID-vkCmdCopyBufferToImage-dstImage-07980
IfdstImage
is of typeVK_IMAGE_TYPE_1D
orVK_IMAGE_TYPE_2D
, then for each element ofpRegions
,imageOffset.z
must be0
andimageExtent.depth
must be1
-
VUID-vkCmdCopyBufferToImage-dstImage-07274
For each element ofpRegions
, if VkCopyCommandTransformInfoQCOM::transform
is equal toVK_SURFACE_TRANSFORM_IDENTITY_BIT_KHR
orVK_SURFACE_TRANSFORM_ROTATE_270_BIT_KHR
,imageOffset.x
must be a multiple of the texel block extent width of the VkFormat ofdstImage
-
VUID-vkCmdCopyBufferToImage-imageOffset-10051
For each element ofpRegions
, if VkCopyCommandTransformInfoQCOM::transform
is equal toVK_SURFACE_TRANSFORM_ROTATE_180_BIT_KHR
orVK_SURFACE_TRANSFORM_ROTATE_90_BIT_KHR
, andimageOffset.x
does not equal the width of the subresource specified byimageSubresource
,imageOffset.x
must be a multiple of the texel block extent width of the VkFormat ofdstImage
-
VUID-vkCmdCopyBufferToImage-dstImage-07275
For each element ofpRegions
, if VkCopyCommandTransformInfoQCOM::transform
is equal toVK_SURFACE_TRANSFORM_IDENTITY_BIT_KHR
orVK_SURFACE_TRANSFORM_ROTATE_90_BIT_KHR
,imageOffset.y
must be a multiple of the texel block extent height of the VkFormat ofdstImage
-
VUID-vkCmdCopyBufferToImage-imageOffset-10052
For each element ofpRegions
, if VkCopyCommandTransformInfoQCOM::transform
is equal toVK_SURFACE_TRANSFORM_ROTATE_270_BIT_KHR
orVK_SURFACE_TRANSFORM_ROTATE_180_BIT_KHR
, andimageOffset.y
does not equal the height of the subresource specified byimageSubresource
,imageOffset.y
must be a multiple of the texel block extent height of the VkFormat ofdstImage
-
VUID-vkCmdCopyBufferToImage-dstImage-07276
For each element ofpRegions
,imageOffset.z
must be a multiple of the texel block extent depth of the VkFormat ofdstImage
-
VUID-vkCmdCopyBufferToImage-dstImage-00207
For each element ofpRegions
, if VkCopyCommandTransformInfoQCOM::transform
is equal toVK_SURFACE_TRANSFORM_IDENTITY_BIT_KHR
, the sum ofimageOffset.x
andextent.width
does not equal the width of the subresource specified byimageSubresource
,extent.width
must be a multiple of the texel block extent width of the VkFormat ofdstImage
-
VUID-vkCmdCopyBufferToImage-imageOffset-10053
For each element ofpRegions
, if VkCopyCommandTransformInfoQCOM::transform
is equal toVK_SURFACE_TRANSFORM_ROTATE_90_BIT_KHR
, the difference ofimageOffset.x
andextent.height
must be a multiple of the texel block extent width of the VkFormat ofdstImage
-
VUID-vkCmdCopyBufferToImage-imageOffset-10054
For each element ofpRegions
, if VkCopyCommandTransformInfoQCOM::transform
is equal toVK_SURFACE_TRANSFORM_ROTATE_180_BIT_KHR
, the difference ofimageOffset.x
andextent.width
must be a multiple of the texel block extent width of the VkFormat ofdstImage
-
VUID-vkCmdCopyBufferToImage-imageOffset-10055
For each element ofpRegions
, if VkCopyCommandTransformInfoQCOM::transform
is equal toVK_SURFACE_TRANSFORM_ROTATE_270_BIT_KHR
, the sum ofimageOffset.x
andextent.height
does not equal the width of the subresource specified byimageSubresource
,extent.height
must be a multiple of the texel block extent width of the VkFormat ofdstImage
-
VUID-vkCmdCopyBufferToImage-dstImage-00208
For each element ofpRegions
, if VkCopyCommandTransformInfoQCOM::transform
is equal toVK_SURFACE_TRANSFORM_IDENTITY_BIT_KHR
, and the sum ofimageOffset.y
andextent.height
does not equal the height of the subresource specified byimageSubresource
,extent.height
must be a multiple of the texel block extent height of the VkFormat ofdstImage
-
VUID-vkCmdCopyBufferToImage-imageOffset-10056
For each element ofpRegions
, if VkCopyCommandTransformInfoQCOM::transform
is equal toVK_SURFACE_TRANSFORM_ROTATE_90_BIT_KHR
, the sum ofimageOffset.y
andextent.width
does not equal the height of the subresource specified byimageSubresource
,extent.width
must be a multiple of the texel block extent height of the VkFormat ofdstImage
-
VUID-vkCmdCopyBufferToImage-imageOffset-10057
For each element ofpRegions
, if VkCopyCommandTransformInfoQCOM::transform
is equal toVK_SURFACE_TRANSFORM_ROTATE_180_BIT_KHR
, the difference ofimageOffset.y
andextent.height
must be a multiple of the texel block extent height of the VkFormat ofdstImage
-
VUID-vkCmdCopyBufferToImage-imageOffset-10058
For each element ofpRegions
, if VkCopyCommandTransformInfoQCOM::transform
is equal toVK_SURFACE_TRANSFORM_ROTATE_270_BIT_KHR
, the difference ofimageOffset.y
andextent.width
must be a multiple of the texel block extent height of the VkFormat ofdstImage
-
VUID-vkCmdCopyBufferToImage-dstImage-00209
For each element ofpRegions
, if the sum ofimageOffset.z
andextent.depth
does not equal the depth of the subresource specified bysrcSubresource
,extent.depth
must be a multiple of the texel block extent depth of the VkFormat ofdstImage
-
VUID-vkCmdCopyBufferToImage-imageSubresource-09105
For each element ofpRegions
,imageSubresource.aspectMask
must specify aspects present indstImage
-
VUID-vkCmdCopyBufferToImage-dstImage-07981
IfdstImage
has a multi-planar format, then for each element ofpRegions
,imageSubresource.aspectMask
must be a single valid multi-planar aspect mask bit -
VUID-vkCmdCopyBufferToImage-dstImage-07983
IfdstImage
is of typeVK_IMAGE_TYPE_3D
, for each element ofpRegions
,imageSubresource.baseArrayLayer
must be0
andimageSubresource.layerCount
must be1
-
VUID-vkCmdCopyBufferToImage-bufferRowLength-09106
For each element ofpRegions
,bufferRowLength
must be a multiple of the texel block extent width of the VkFormat ofdstImage
-
VUID-vkCmdCopyBufferToImage-bufferImageHeight-09107
For each element ofpRegions
,bufferImageHeight
must be a multiple of the texel block extent height of the VkFormat ofdstImage
-
VUID-vkCmdCopyBufferToImage-bufferRowLength-09108
For each element ofpRegions
,bufferRowLength
divided by the texel block extent width and then multiplied by the texel block size ofdstImage
must be less than or equal to 231-1
-
VUID-vkCmdCopyBufferToImage-dstImage-07975
IfdstImage
does not have either a depth/stencil format or a multi-planar format, then for each element ofpRegions
,bufferOffset
must be a multiple of the texel block size -
VUID-vkCmdCopyBufferToImage-dstImage-07976
IfdstImage
has a multi-planar format, then for each element ofpRegions
,bufferOffset
must be a multiple of the element size of the compatible format for the format and theaspectMask
of theimageSubresource
as defined in [formats-compatible-planes] -
VUID-vkCmdCopyBufferToImage-dstImage-07978
IfdstImage
has a depth/stencil format, thebufferOffset
member of any element ofpRegions
must be a multiple of4
-
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 ofregionCount
valid VkBufferImageCopy structures -
VUID-vkCmdCopyBufferToImage-commandBuffer-recording
commandBuffer
must be in the recording state -
VUID-vkCmdCopyBufferToImage-commandBuffer-cmdpool
TheVkCommandPool
thatcommandBuffer
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-videocoding
This command must only be called outside of a video coding scope -
VUID-vkCmdCopyBufferToImage-regionCount-arraylength
regionCount
must be greater than0
-
VUID-vkCmdCopyBufferToImage-commonparent
Each ofcommandBuffer
,dstImage
, andsrcBuffer
must have been created, allocated, or retrieved from the same VkDevice
-
Host access to
commandBuffer
must be externally synchronized -
Host access to the
VkCommandPool
thatcommandBuffer
was allocated from must be externally synchronized
Command Buffer Levels | Render Pass Scope | Video Coding Scope | Supported Queue Types | Command Type |
---|---|---|---|---|
Primary |
Outside |
Outside |
Transfer |
Action |
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.