Function Prototype

vkCmdUpdateBuffer

Update a buffer's contents from host memory
primary / secondary
outside
transfer / graphics / compute
action

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 least dataSize 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-pData-parameter

pData must be a valid pointer to an array of dataSize bytes

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 that commandBuffer was allocated from must be externally synchronized ::