vkCmdUpdateBuffer
To update buffer data inline in a command buffer, call:
void vkCmdUpdateBuffer(
VkCommandBuffer commandBuffer,
VkBuffer dstBuffer,
VkDeviceSize dstOffset,
VkDeviceSize dataSize,
const void* pData);
commandBufferis the command buffer into which the command will be recorded.dstBufferis a handle to the buffer to be updated.dstOffsetis the byte offset into the buffer to start updating, and must be a multiple of 4.dataSizeis the number of bytes to update, and must be a multiple of 4.pDatais a pointer to the source data for the buffer update, and must be at leastdataSizebytes 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 should only be used for very small
amounts of data, and is why it is limited to at most 65536 bytes.
Applications can work around this restriction by issuing multiple
vkCmdUpdateBuffer commands to different ranges of the same buffer, but
doing so is not recommended.
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
commandBuffermust be externally synchronized - Host access to the
VkCommandPoolthatcommandBufferwas allocated from must be externally synchronized ::