Vulkan Logo

18. Clear Commands

18.1. Clearing Images Outside a Render Pass Instance

Color and depth/stencil images can be cleared outside a render pass instance using vkCmdClearColorImage or vkCmdClearDepthStencilImage, respectively. These commands are only allowed outside of a render pass instance.

To clear one or more subranges of a color image, call:

// Provided by VK_VERSION_1_0
void vkCmdClearColorImage(
    VkCommandBuffer                             commandBuffer,
    VkImage                                     image,
    VkImageLayout                               imageLayout,
    const VkClearColorValue*                    pColor,
    uint32_t                                    rangeCount,
    const VkImageSubresourceRange*              pRanges);
  • commandBuffer is the command buffer into which the command will be recorded.

  • image is the image to be cleared.

  • imageLayout specifies the current layout of the image subresource ranges to be cleared, and must be VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR, VK_IMAGE_LAYOUT_GENERAL or VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL.

  • pColor is a pointer to a VkClearColorValue structure containing the values that the image subresource ranges will be cleared to (see Clear Values below).

  • rangeCount is the number of image subresource range structures in pRanges.

  • pRanges is a pointer to an array of VkImageSubresourceRange structures describing a range of mipmap levels, array layers, and aspects to be cleared, as described in Image Views.

Each specified range in pRanges is cleared to the value specified by pColor.

Valid Usage
  • VUID-vkCmdClearColorImage-image-01993
    The format features of image must contain VK_FORMAT_FEATURE_TRANSFER_DST_BIT

  • VUID-vkCmdClearColorImage-image-00002
    image must have been created with VK_IMAGE_USAGE_TRANSFER_DST_BIT usage flag

  • VUID-vkCmdClearColorImage-image-01545
    image must not use any of the formats that require a sampler Y′CBCR conversion

  • VUID-vkCmdClearColorImage-image-00003
    If image is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-vkCmdClearColorImage-imageLayout-00004
    imageLayout must specify the layout of the image subresource ranges of image specified in pRanges at the time this command is executed on a VkDevice

  • VUID-vkCmdClearColorImage-imageLayout-01394
    imageLayout must be VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR, VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL or VK_IMAGE_LAYOUT_GENERAL

  • VUID-vkCmdClearColorImage-aspectMask-02498
    The VkImageSubresourceRange::aspectMask members of the elements of the pRanges array must each only include VK_IMAGE_ASPECT_COLOR_BIT

  • VUID-vkCmdClearColorImage-baseMipLevel-01470
    The VkImageSubresourceRange::baseMipLevel members of the elements of the pRanges array must each be less than the mipLevels specified in VkImageCreateInfo when image was created

  • VUID-vkCmdClearColorImage-pRanges-01692
    For each VkImageSubresourceRange element of pRanges, if the levelCount member is not VK_REMAINING_MIP_LEVELS, then baseMipLevel + levelCount must be less than or equal to the mipLevels specified in VkImageCreateInfo when image was created

  • VUID-vkCmdClearColorImage-baseArrayLayer-01472
    The VkImageSubresourceRange::baseArrayLayer members of the elements of the pRanges array must each be less than the arrayLayers specified in VkImageCreateInfo when image was created

  • VUID-vkCmdClearColorImage-pRanges-01693
    For each VkImageSubresourceRange element of pRanges, if the layerCount member is not VK_REMAINING_ARRAY_LAYERS, then baseArrayLayer + layerCount must be less than or equal to the arrayLayers specified in VkImageCreateInfo when image was created

  • VUID-vkCmdClearColorImage-image-00007
    image must not have a compressed or depth/stencil format

  • VUID-vkCmdClearColorImage-pColor-04961
    pColor must be a valid pointer to a VkClearColorValue union

  • VUID-vkCmdClearColorImage-commandBuffer-01805
    If commandBuffer is an unprotected command buffer and protectedNoFault is not supported, image must not be a protected image

  • VUID-vkCmdClearColorImage-commandBuffer-01806
    If commandBuffer is a protected command buffer and protectedNoFault is not supported, must not be an unprotected image

Valid Usage (Implicit)
  • VUID-vkCmdClearColorImage-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdClearColorImage-image-parameter
    image must be a valid VkImage handle

  • VUID-vkCmdClearColorImage-imageLayout-parameter
    imageLayout must be a valid VkImageLayout value

  • VUID-vkCmdClearColorImage-pRanges-parameter
    pRanges must be a valid pointer to an array of rangeCount valid VkImageSubresourceRange structures

  • VUID-vkCmdClearColorImage-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdClearColorImage-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support graphics, or compute operations

  • VUID-vkCmdClearColorImage-renderpass
    This command must only be called outside of a render pass instance

  • VUID-vkCmdClearColorImage-videocoding
    This command must only be called outside of a video coding scope

  • VUID-vkCmdClearColorImage-rangeCount-arraylength
    rangeCount must be greater than 0

  • VUID-vkCmdClearColorImage-commonparent
    Both of commandBuffer, and image 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 Video Coding Scope Supported Queue Types Command Type

Primary
Secondary

Outside

Outside

Graphics
Compute

Action

To clear one or more subranges of a depth/stencil image, call:

// Provided by VK_VERSION_1_0
void vkCmdClearDepthStencilImage(
    VkCommandBuffer                             commandBuffer,
    VkImage                                     image,
    VkImageLayout                               imageLayout,
    const VkClearDepthStencilValue*             pDepthStencil,
    uint32_t                                    rangeCount,
    const VkImageSubresourceRange*              pRanges);
  • commandBuffer is the command buffer into which the command will be recorded.

  • image is the image to be cleared.

  • imageLayout specifies the current layout of the image subresource ranges to be cleared, and must be VK_IMAGE_LAYOUT_GENERAL or VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL.

  • pDepthStencil is a pointer to a VkClearDepthStencilValue structure containing the values that the depth and stencil image subresource ranges will be cleared to (see Clear Values below).

  • rangeCount is the number of image subresource range structures in pRanges.

  • pRanges is a pointer to an array of VkImageSubresourceRange structures describing a range of mipmap levels, array layers, and aspects to be cleared, as described in Image Views.

Valid Usage
  • VUID-vkCmdClearDepthStencilImage-image-01994
    The format features of image must contain VK_FORMAT_FEATURE_TRANSFER_DST_BIT

  • VUID-vkCmdClearDepthStencilImage-pRanges-02658
    If the aspect member of any element of pRanges includes VK_IMAGE_ASPECT_STENCIL_BIT, and image was created with separate stencil usage, VK_IMAGE_USAGE_TRANSFER_DST_BIT must have been included in the VkImageStencilUsageCreateInfo::stencilUsage used to create image

  • VUID-vkCmdClearDepthStencilImage-pRanges-02659
    If the aspect member of any element of pRanges includes VK_IMAGE_ASPECT_STENCIL_BIT, and image was not created with separate stencil usage, VK_IMAGE_USAGE_TRANSFER_DST_BIT must have been included in the VkImageCreateInfo::usage used to create image

  • VUID-vkCmdClearDepthStencilImage-pRanges-02660
    If the aspect member of any element of pRanges includes VK_IMAGE_ASPECT_DEPTH_BIT, VK_IMAGE_USAGE_TRANSFER_DST_BIT must have been included in the VkImageCreateInfo::usage used to create image

  • VUID-vkCmdClearDepthStencilImage-image-00010
    If image is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

  • VUID-vkCmdClearDepthStencilImage-imageLayout-00011
    imageLayout must specify the layout of the image subresource ranges of image specified in pRanges at the time this command is executed on a VkDevice

  • VUID-vkCmdClearDepthStencilImage-imageLayout-00012
    imageLayout must be either of VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL or VK_IMAGE_LAYOUT_GENERAL

  • VUID-vkCmdClearDepthStencilImage-aspectMask-02824
    The VkImageSubresourceRange::aspectMask member of each element of the pRanges array must not include bits other than VK_IMAGE_ASPECT_DEPTH_BIT or VK_IMAGE_ASPECT_STENCIL_BIT

  • VUID-vkCmdClearDepthStencilImage-image-02825
    If the image’s format does not have a stencil component, then the VkImageSubresourceRange::aspectMask member of each element of the pRanges array must not include the VK_IMAGE_ASPECT_STENCIL_BIT bit

  • VUID-vkCmdClearDepthStencilImage-image-02826
    If the image’s format does not have a depth component, then the VkImageSubresourceRange::aspectMask member of each element of the pRanges array must not include the VK_IMAGE_ASPECT_DEPTH_BIT bit

  • VUID-vkCmdClearDepthStencilImage-baseMipLevel-01474
    The VkImageSubresourceRange::baseMipLevel members of the elements of the pRanges array must each be less than the mipLevels specified in VkImageCreateInfo when image was created

  • VUID-vkCmdClearDepthStencilImage-pRanges-01694
    For each VkImageSubresourceRange element of pRanges, if the levelCount member is not VK_REMAINING_MIP_LEVELS, then baseMipLevel + levelCount must be less than or equal to the mipLevels specified in VkImageCreateInfo when image was created

  • VUID-vkCmdClearDepthStencilImage-baseArrayLayer-01476
    The VkImageSubresourceRange::baseArrayLayer members of the elements of the pRanges array must each be less than the arrayLayers specified in VkImageCreateInfo when image was created

  • VUID-vkCmdClearDepthStencilImage-pRanges-01695
    For each VkImageSubresourceRange element of pRanges, if the layerCount member is not VK_REMAINING_ARRAY_LAYERS, then baseArrayLayer + layerCount must be less than or equal to the arrayLayers specified in VkImageCreateInfo when image was created

  • VUID-vkCmdClearDepthStencilImage-image-00014
    image must have a depth/stencil format

  • VUID-vkCmdClearDepthStencilImage-commandBuffer-01807
    If commandBuffer is an unprotected command buffer and protectedNoFault is not supported, image must not be a protected image

  • VUID-vkCmdClearDepthStencilImage-commandBuffer-01808
    If commandBuffer is a protected command buffer and protectedNoFault is not supported, image must not be an unprotected image

Valid Usage (Implicit)
  • VUID-vkCmdClearDepthStencilImage-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdClearDepthStencilImage-image-parameter
    image must be a valid VkImage handle

  • VUID-vkCmdClearDepthStencilImage-imageLayout-parameter
    imageLayout must be a valid VkImageLayout value

  • VUID-vkCmdClearDepthStencilImage-pDepthStencil-parameter
    pDepthStencil must be a valid pointer to a valid VkClearDepthStencilValue structure

  • VUID-vkCmdClearDepthStencilImage-pRanges-parameter
    pRanges must be a valid pointer to an array of rangeCount valid VkImageSubresourceRange structures

  • VUID-vkCmdClearDepthStencilImage-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdClearDepthStencilImage-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support graphics operations

  • VUID-vkCmdClearDepthStencilImage-renderpass
    This command must only be called outside of a render pass instance

  • VUID-vkCmdClearDepthStencilImage-videocoding
    This command must only be called outside of a video coding scope

  • VUID-vkCmdClearDepthStencilImage-rangeCount-arraylength
    rangeCount must be greater than 0

  • VUID-vkCmdClearDepthStencilImage-commonparent
    Both of commandBuffer, and image 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 Video Coding Scope Supported Queue Types Command Type

Primary
Secondary

Outside

Outside

Graphics

Action

Clears outside render pass instances are treated as transfer operations for the purposes of memory barriers.

18.2. Clearing Images Inside a Render Pass Instance

To clear one or more regions of color and depth/stencil attachments inside a render pass instance, call:

// Provided by VK_VERSION_1_0
void vkCmdClearAttachments(
    VkCommandBuffer                             commandBuffer,
    uint32_t                                    attachmentCount,
    const VkClearAttachment*                    pAttachments,
    uint32_t                                    rectCount,
    const VkClearRect*                          pRects);
  • commandBuffer is the command buffer into which the command will be recorded.

  • attachmentCount is the number of entries in the pAttachments array.

  • pAttachments is a pointer to an array of VkClearAttachment structures defining the attachments to clear and the clear values to use.

  • rectCount is the number of entries in the pRects array.

  • pRects is a pointer to an array of VkClearRect structures defining regions within each selected attachment to clear.

Unlike other clear commands, vkCmdClearAttachments is not a transfer command. It performs its operations in rasterization order. For color attachments, the operations are executed as color attachment writes, by the VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT stage. For depth/stencil attachments, the operations are executed as depth writes and stencil writes by the VK_PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BIT and VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT stages.

vkCmdClearAttachments is not affected by the bound pipeline state.

Note

It is generally preferable to clear attachments by using the VK_ATTACHMENT_LOAD_OP_CLEAR load operation at the start of rendering, as it is more efficient on some implementations.

If any attachment’s aspectMask to be cleared is not backed by an image view, the clear has no effect on that aspect.

If an attachment being cleared refers to an image view created with an aspectMask equal to one of VK_IMAGE_ASPECT_PLANE_0_BIT, VK_IMAGE_ASPECT_PLANE_1_BIT or VK_IMAGE_ASPECT_PLANE_2_BIT, it is considered to be VK_IMAGE_ASPECT_COLOR_BIT for purposes of this command, and must be cleared with the VK_IMAGE_ASPECT_COLOR_BIT aspect as specified by image view creation.

Valid Usage
  • VUID-vkCmdClearAttachments-aspectMask-07884
    If the current render pass instance does not use dynamic rendering, and the aspectMask member of any element of pAttachments contains VK_IMAGE_ASPECT_DEPTH_BIT, the current subpass instance’s depth-stencil attachment must be either VK_ATTACHMENT_UNUSED or the attachment format must contain a depth component

  • VUID-vkCmdClearAttachments-aspectMask-07885
    If the current render pass instance does not use dynamic rendering, and the aspectMask member of any element of pAttachments contains VK_IMAGE_ASPECT_STENCIL_BIT, the current subpass instance’s depth-stencil attachment must be either VK_ATTACHMENT_UNUSED or the attachment format must contain a stencil component

  • VUID-vkCmdClearAttachments-aspectMask-07271
    If the aspectMask member of any element of pAttachments contains VK_IMAGE_ASPECT_COLOR_BIT, the colorAttachment must be a valid color attachment index in the current render pass instance

  • VUID-vkCmdClearAttachments-rect-02682
    The rect member of each element of pRects must have an extent.width greater than 0

  • VUID-vkCmdClearAttachments-rect-02683
    The rect member of each element of pRects must have an extent.height greater than 0

  • VUID-vkCmdClearAttachments-pRects-00016
    The rectangular region specified by each element of pRects must be contained within the render area of the current render pass instance

  • VUID-vkCmdClearAttachments-pRects-06937
    The layers specified by each element of pRects must be contained within every attachment that pAttachments refers to, i.e. for each element of pRects, VkClearRect::baseArrayLayer + VkClearRect::layerCount must be less than or equal to the number of layers rendered to in the current render pass instance

  • VUID-vkCmdClearAttachments-layerCount-01934
    The layerCount member of each element of pRects must not be 0

  • VUID-vkCmdClearAttachments-commandBuffer-02504
    If commandBuffer is an unprotected command buffer and protectedNoFault is not supported, each attachment to be cleared must not be a protected image

  • VUID-vkCmdClearAttachments-commandBuffer-02505
    If commandBuffer is a protected command buffer and protectedNoFault is not supported, each attachment to be cleared must not be an unprotected image

  • VUID-vkCmdClearAttachments-baseArrayLayer-00018
    If the render pass instance this is recorded in uses multiview, then baseArrayLayer must be zero and layerCount must be one

  • VUID-vkCmdClearAttachments-colorAttachment-09503
    The colorAttachment member of each element of pAttachments must not identify a color attachment that is currently mapped to VK_ATTACHMENT_UNUSED in commandBuffer via VkRenderingAttachmentLocationInfoKHR

Valid Usage (Implicit)
  • VUID-vkCmdClearAttachments-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdClearAttachments-pAttachments-parameter
    pAttachments must be a valid pointer to an array of attachmentCount valid VkClearAttachment structures

  • VUID-vkCmdClearAttachments-pRects-parameter
    pRects must be a valid pointer to an array of rectCount VkClearRect structures

  • VUID-vkCmdClearAttachments-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdClearAttachments-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support graphics operations

  • VUID-vkCmdClearAttachments-renderpass
    This command must only be called inside of a render pass instance

  • VUID-vkCmdClearAttachments-videocoding
    This command must only be called outside of a video coding scope

  • VUID-vkCmdClearAttachments-attachmentCount-arraylength
    attachmentCount must be greater than 0

  • VUID-vkCmdClearAttachments-rectCount-arraylength
    rectCount must be greater than 0

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 Video Coding Scope Supported Queue Types Command Type

Primary
Secondary

Inside

Outside

Graphics

Action

The VkClearRect structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkClearRect {
    VkRect2D    rect;
    uint32_t    baseArrayLayer;
    uint32_t    layerCount;
} VkClearRect;
  • rect is the two-dimensional region to be cleared.

  • baseArrayLayer is the first layer to be cleared.

  • layerCount is the number of layers to clear.

The layers [baseArrayLayer, baseArrayLayer + layerCount) counting from the base layer of the attachment image view are cleared.

The VkClearAttachment structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkClearAttachment {
    VkImageAspectFlags    aspectMask;
    uint32_t              colorAttachment;
    VkClearValue          clearValue;
} VkClearAttachment;
  • aspectMask is a mask selecting the color, depth and/or stencil aspects of the attachment to be cleared.

  • colorAttachment is only meaningful if VK_IMAGE_ASPECT_COLOR_BIT is set in aspectMask, in which case it is an index into the currently bound color attachments.

  • clearValue is the color or depth/stencil value to clear the attachment to, as described in Clear Values below.

Valid Usage
  • VUID-VkClearAttachment-aspectMask-00019
    If aspectMask includes VK_IMAGE_ASPECT_COLOR_BIT, it must not include VK_IMAGE_ASPECT_DEPTH_BIT or VK_IMAGE_ASPECT_STENCIL_BIT

  • VUID-VkClearAttachment-aspectMask-00020
    aspectMask must not include VK_IMAGE_ASPECT_METADATA_BIT

Valid Usage (Implicit)
  • VUID-VkClearAttachment-aspectMask-parameter
    aspectMask must be a valid combination of VkImageAspectFlagBits values

  • VUID-VkClearAttachment-aspectMask-requiredbitmask
    aspectMask must not be 0

18.3. Clear Values

The VkClearColorValue structure is defined as:

// Provided by VK_VERSION_1_0
typedef union VkClearColorValue {
    float       float32[4];
    int32_t     int32[4];
    uint32_t    uint32[4];
} VkClearColorValue;
  • float32 are the color clear values when the format of the image or attachment is one of the numeric formats with a numeric type that is floating-point. Floating point values are automatically converted to the format of the image, with the clear value being treated as linear if the image is sRGB.

  • int32 are the color clear values when the format of the image or attachment has a numeric type that is signed integer (SINT). Signed integer values are converted to the format of the image by casting to the smaller type (with negative 32-bit values mapping to negative values in the smaller type). If the integer clear value is not representable in the target type (e.g. would overflow in conversion to that type), the clear value is undefined.

  • uint32 are the color clear values when the format of the image or attachment has a numeric type that is unsigned integer (UINT). Unsigned integer values are converted to the format of the image by casting to the integer type with fewer bits.

The four array elements of the clear color map to R, G, B, and A components of image formats, in order.

If the image has more than one sample, the same value is written to all samples for any pixels being cleared.

The VkClearDepthStencilValue structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkClearDepthStencilValue {
    float       depth;
    uint32_t    stencil;
} VkClearDepthStencilValue;
  • depth is the clear value for the depth aspect of the depth/stencil attachment. It is a floating-point value which is automatically converted to the attachment’s format.

  • stencil is the clear value for the stencil aspect of the depth/stencil attachment. It is a 32-bit integer value which is converted to the attachment’s format by taking the appropriate number of LSBs.

Valid Usage

The VkClearValue union is defined as:

// Provided by VK_VERSION_1_0
typedef union VkClearValue {
    VkClearColorValue           color;
    VkClearDepthStencilValue    depthStencil;
} VkClearValue;
  • color specifies the color image clear values to use when clearing a color image or attachment.

  • depthStencil specifies the depth and stencil clear values to use when clearing a depth/stencil image or attachment.

This union is used where part of the API requires either color or depth/stencil clear values, depending on the attachment, and defines the initial clear values in the VkRenderPassBeginInfo structure.

18.4. Filling Buffers

To clear buffer data, call:

// Provided by VK_VERSION_1_0
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

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

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type

Primary
Secondary

Outside

Outside

Transfer
Graphics
Compute

Action

18.5. Updating Buffers

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

// Provided by VK_VERSION_1_0
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.

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

  • VUID-vkCmdUpdateBuffer-commandBuffer-01813
    If commandBuffer is an unprotected command buffer and protectedNoFault is not supported, dstBuffer must not be a protected buffer

  • VUID-vkCmdUpdateBuffer-commandBuffer-01814
    If commandBuffer is a protected command buffer and protectedNoFault is not supported, dstBuffer must not be an unprotected buffer

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 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 Video Coding Scope Supported Queue Types Command Type

Primary
Secondary

Outside

Outside

Transfer
Graphics
Compute

Action

Note

The pData parameter was of type uint32_t* instead of void* prior to version 1.0.19 of the Specification and VK_HEADER_VERSION 19 of the Vulkan Header Files. This was a historical anomaly, as the source data may be of other types.