Author: The Khronos® Vulkan Working Group

# Vulkan® 1.4.309 - A Specification (with all registered extensions)

The Khronos® Vulkan Working Group
version 1.4.309, 2025-03-27 13:53:44Z
from git branch: makepkg commit: 5a38e1f41285241a29f6428978aae6d1cf13fd16

Loading… please wait.

Search:

## 19. Clear Commands

### 19.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

- VUID-vkCmdClearColorImage-image-09678
  If `image`’s format has components other than R and G, it must not have a 64-bit component width

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.

### 19.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.

If the render pass has a fragment density map attachment, clears follow the operations of fragment density maps as if each clear region was a primitive which generates fragments. The clear color is applied to all pixels inside each fragment’s area regardless if the pixels lie outside of the clear region. Clears may have a different set of supported fragment areas than draws.

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 VkRenderingAttachmentLocationInfo

- VUID-vkCmdClearAttachments-aspectMask-09298
  If the subpass this is recorded in performs an external format resolve, the `aspectMask` member of any element of `pAttachments` must not include `VK_IMAGE_ASPECT_PLANE_i_BIT` for any index i

- VUID-vkCmdClearAttachments-None-09679
  If the attachment format has components other than R and G, it must not have a 64-bit component width

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

- VUID-VkClearAttachment-aspectMask-02246
  `aspectMask` must not include `VK_IMAGE_ASPECT_MEMORY_PLANE_i_BIT_EXT` for any index i

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`

### 19.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.

If the image or attachment format has a 64-bit component width, the first 2 array elements of each of the arrays above are reinterpreted as a single 64-bit element for the R component. The next 2 array elements are used in the same way for the G component. In other words, the union behaves as if it had the following additional members:

    double float64[2];
    int64_t int64[2];
    uint64_t uint64[2];

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

- VUID-VkClearDepthStencilValue-depth-00022
  Unless the `VK_EXT_depth_range_unrestricted` extension is enabled `depth` must be between `0.0` and `1.0`, inclusive

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.

### 19.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

### 19.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 should only be used for very small amounts of data, and is why it is limited to at most 65536 bytes. Applications can work around this restriction by issuing multiple `vkCmdUpdateBuffer` commands to different ranges of the same buffer, but doing so is not recommended.

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`

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