Function Prototype

vkCmdFillBuffer

Fill a region of a buffer with a fixed value
primary / secondary
outside
transfer / graphics / compute
action

To clear buffer data, call:

void vkCmdFillBuffer(
    VkCommandBuffer commandBuffer,
    VkBuffer dstBuffer,
    VkDeviceSize dstOffset,
    VkDeviceSize size,
    uint32_t data);
  • commandBuffer is the command buffer into which the command will be recorded.
  • dstBuffer is the buffer to be filled.
  • dstOffset is the byte offset into the buffer at which to start filling, and must be a multiple of 4.
  • size is the number of bytes to fill, and must be either a multiple of 4, or VK_WHOLE_SIZE to fill the range from offset to the end of the buffer. If VK_WHOLE_SIZE is used and the remaining size of the buffer is not a multiple of 4, then the nearest smaller multiple is used.
  • data is the 4-byte word written repeatedly to the buffer to fill size bytes of data. The data word is written to memory according to the host endianness.

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

Valid Usage

VUID-vkCmdFillBuffer-dstOffset-00024

dstOffset must be less than the size of dstBuffer

VUID-vkCmdFillBuffer-dstOffset-00025

dstOffset must be a multiple of 4

VUID-vkCmdFillBuffer-size-00026

If size is not equal to VK_WHOLE_SIZE, size must be greater than 0

VUID-vkCmdFillBuffer-size-00027

If size is not equal to VK_WHOLE_SIZE, size must be less than or equal to the size of dstBuffer minus dstOffset

VUID-vkCmdFillBuffer-size-00028

If size is not equal to VK_WHOLE_SIZE, size must be a multiple of 4

VUID-vkCmdFillBuffer-dstBuffer-00029

dstBuffer must have been created with VK_BUFFER_USAGE_TRANSFER_DST_BIT usage flag

VUID-vkCmdFillBuffer-apiVersion-07894

If the VK_KHR_maintenance1 extension is not enabled and VkPhysicalDeviceProperties::apiVersion is less than Vulkan 1.1, the VkCommandPool that commandBuffer was allocated from must support graphics or compute operations

VUID-vkCmdFillBuffer-dstBuffer-00031

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

Valid Usage (Implicit)

VUID-vkCmdFillBuffer-dstBuffer-parameter

dstBuffer must be a valid VkBuffer handle

VUID-vkCmdFillBuffer-commandBuffer-cmdpool

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

VUID-vkCmdFillBuffer-renderpass

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

VUID-vkCmdFillBuffer-videocoding

This command must only be called outside of a video coding scope

VUID-vkCmdFillBuffer-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 ::