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. If any attachment index to be cleared is not backed by an image view, then the clear has no effect.

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

Valid Usage

- VUID-vkCmdClearAttachments-aspectMask-02501
  If the `aspectMask` member of any element of `pAttachments` contains `VK_IMAGE_ASPECT_COLOR_BIT`, then the `colorAttachment` member of that element must either refer to a color attachment which is `VK_ATTACHMENT_UNUSED`, or must be a valid color attachment

- VUID-vkCmdClearAttachments-aspectMask-02502
  If the `aspectMask` member of any element of `pAttachments` contains `VK_IMAGE_ASPECT_DEPTH_BIT`, then the current subpass' depth/stencil attachment must either be `VK_ATTACHMENT_UNUSED`, or must have a depth component

- VUID-vkCmdClearAttachments-aspectMask-02503
  If the `aspectMask` member of any element of `pAttachments` contains `VK_IMAGE_ASPECT_STENCIL_BIT`, then the current subpass' depth/stencil attachment must either be `VK_ATTACHMENT_UNUSED`, or must have a stencil component

- 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-00017
  The layers specified by each element of `pRects` must be contained within every attachment that `pAttachments` refers to

- 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

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-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 | Supported Queue Types
--- | --- | ---
Primary Secondary | Inside | Graphics

## 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-2022 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0