vkCmdFillBuffer(3)

C Specification

To clear buffer data, call:

// Provided by VK_VERSION_1_0
void vkCmdFillBuffer(
    VkCommandBuffer                             commandBuffer,
    VkBuffer                                    dstBuffer,
    VkDeviceSize                                dstOffset,
    VkDeviceSize                                size,
    uint32_t                                    data);

Parameters

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.

Description

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
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
VUID-vkCmdFillBuffer-commandBuffer-01811
If commandBuffer is an unprotected command buffer and protectedNoFault is not supported, dstBuffer must not be a protected buffer
VUID-vkCmdFillBuffer-commandBuffer-01812
If commandBuffer is a protected command buffer and protectedNoFault is not supported, dstBuffer must not be an unprotected buffer

Valid Usage (Implicit)

VUID-vkCmdFillBuffer-commandBuffer-parameter
commandBuffer must be a valid VkCommandBuffer handle
VUID-vkCmdFillBuffer-dstBuffer-parameter
dstBuffer must be a valid VkBuffer handle
VUID-vkCmdFillBuffer-commandBuffer-recording
commandBuffer must be in the recording state
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-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