vkCmdUpdateBuffer
To update buffer data inline in a command buffer, call:
void vkCmdUpdateBuffer(
VkCommandBuffer commandBuffer,
VkBuffer dstBuffer,
VkDeviceSize dstOffset,
VkDeviceSize dataSize,
const void* pData);
commandBuffer
is the command buffer into which the command will be recorded.dstBuffer
is a handle to the buffer to be updated.dstOffset
is the byte offset into the buffer to start updating, and must be a multiple of 4.dataSize
is the number of bytes to update, and must be a multiple of 4.pData
is a pointer to the source data for the buffer update, and must be at leastdataSize
bytes in size.
dataSize
must be less than or equal to 65536 bytes.
For larger updates, applications can use buffer to buffer
copies.
Buffer updates performed with vkCmdUpdateBuffer
first copy the data
into command buffer memory when the command is recorded (which requires
additional storage and may incur an additional allocation), and then copy
the data from the command buffer into dstBuffer
when the command is
executed on a device.
The additional cost of this functionality compared to buffer to buffer copies means it is only recommended for very small amounts of data, and is why it is limited to only 65536 bytes.
Applications can work around this by issuing multiple
vkCmdUpdateBuffer
commands to different ranges of the same buffer, but
it is strongly recommended that they should not.
The source data is copied from pData
to the command buffer when the
command is called.
vkCmdUpdateBuffer
is only allowed outside of a render pass.
This command is treated as a transfer
operation for the purposes of
synchronization barriers.
The VK_BUFFER_USAGE_TRANSFER_DST_BIT
must be specified in usage
of VkBufferCreateInfo in order for the buffer to be compatible with
vkCmdUpdateBuffer
.
Valid Usage
VUID-vkCmdUpdateBuffer-dstOffset-00032
dstOffset
must be less than the size of dstBuffer
VUID-vkCmdUpdateBuffer-dataSize-00033
dataSize
must be less than or equal to the size of
dstBuffer
minus dstOffset
VUID-vkCmdUpdateBuffer-dstBuffer-00034
dstBuffer
must have been created with
VK_BUFFER_USAGE_TRANSFER_DST_BIT
usage flag
VUID-vkCmdUpdateBuffer-dstBuffer-00035
If dstBuffer
is non-sparse then it must be bound completely and
contiguously to a single VkDeviceMemory
object
VUID-vkCmdUpdateBuffer-dstOffset-00036
dstOffset
must be a multiple of 4
VUID-vkCmdUpdateBuffer-dataSize-00037
dataSize
must be less than or equal to 65536
VUID-vkCmdUpdateBuffer-dataSize-00038
dataSize
must be a multiple of 4
Valid Usage (Implicit)
VUID-vkCmdUpdateBuffer-commandBuffer-parameter
commandBuffer
must be a valid VkCommandBuffer handle
VUID-vkCmdUpdateBuffer-dstBuffer-parameter
dstBuffer
must be a valid VkBuffer handle
VUID-vkCmdUpdateBuffer-pData-parameter
pData
must be a valid pointer to an array of dataSize
bytes
VUID-vkCmdUpdateBuffer-commandBuffer-recording
commandBuffer
must be in the recording state
VUID-vkCmdUpdateBuffer-commandBuffer-cmdpool
The VkCommandPool
that commandBuffer
was allocated from must support transfer, graphics, or compute operations
VUID-vkCmdUpdateBuffer-renderpass
This command must only be called outside of a render pass instance
VUID-vkCmdUpdateBuffer-videocoding
This command must only be called outside of a video coding scope
VUID-vkCmdUpdateBuffer-dataSize-arraylength
dataSize
must be greater than 0
VUID-vkCmdUpdateBuffer-commonparent
Both of commandBuffer
, and dstBuffer
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
thatcommandBuffer
was allocated from must be externally synchronized ::