C Specification

To update buffer data inline in a command buffer, call:

void vkCmdUpdateBuffer(
    VkCommandBuffer                             commandBuffer,
    VkBuffer                                    dstBuffer,
    VkDeviceSize                                dstOffset,
    VkDeviceSize                                dataSize,
    const void*                                 pData);

Parameters

  • 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.

Description

dataSize must be less than or equal to 65536 bytes. For larger updates, applications can use buffer to buffer copies.

Note

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 the user pointer to the command buffer when the command is called.

vkCmdUpdateBuffer is only allowed outside of a render pass. This command is treated as “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
  • dstOffset must be less than the size of dstBuffer

  • dataSize must be less than or equal to the size of dstBuffer minus dstOffset

  • dstBuffer must have been created with VK_BUFFER_USAGE_TRANSFER_DST_BIT usage flag

  • If dstBuffer is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

  • dstOffset must be a multiple of 4

  • dataSize must be less than or equal to 65536

  • dataSize must be a multiple of 4

Valid Usage (Implicit)
  • commandBuffer must be a valid VkCommandBuffer handle

  • dstBuffer must be a valid VkBuffer handle

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

  • commandBuffer must be in the recording state

  • The VkCommandPool that commandBuffer was allocated from must support transfer, graphics, or compute operations

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

  • dataSize must be greater than 0

  • 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

Command Properties
Command Buffer Levels Render Pass Scope Supported Queue Types Pipeline Type

Primary
Secondary

Outside

Transfer
graphics
compute

Transfer

See Also

VkBuffer, VkCommandBuffer, VkDeviceSize

Document Notes

For more information, see the Vulkan Specification at URL

This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.

Copyright (c) 2014-2017 Khronos Group. This work is licensed under a Creative Commons Attribution 4.0 International License.