vkCmdClearAttachments(3)

# vkCmdClearAttachments(3) Manual Page

## Name

vkCmdClearAttachments - Clear regions within bound framebuffer attachments

Loading… please wait.

## C Specification

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

## Parameters

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

## Description

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

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

## See Also

VK_VERSION_1_0, VkClearAttachment, VkClearRect, VkCommandBuffer

## Document Notes

For more information, see the Vulkan Specification

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

## Copyright

Copyright 2014-2023 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0