vkCmdClearAttachments(3)

# vkCmdClearAttachments(3) Manual Page

## Name

vkCmdClearAttachments - Clear regions within bound framebuffer attachments

## C Specification

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

    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 to be cleared in the current subpass is `VK_ATTACHMENT_UNUSED`, then the clear has no effect on that attachment.

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

`vkCmdClearAttachments` can clear multiple regions of each attachment used in the current subpass of a render pass instance. This command must be called only inside a render pass instance, and implicitly selects the images to clear based on the current framebuffer attachments and the command parameters.

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 executes as a drawing command, rather than a transfer command, with writes performed by it executing in rasterization order. Clears to color attachments are executed as color attachment writes, by the `VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT` stage. Clears to depth/stencil attachments 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.

Valid Usage

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

- 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

- 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

- The `rect` member of each element of `pRects` must have an `extent.width` greater than `0`

- The `rect` member of each element of `pRects` must have an `extent.height` greater than `0`

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

- The layers specified by each element of `pRects` must be contained within every attachment that `pAttachments` refers to

- The `layerCount` member of each element of `pRects` must not be `0`

- If `commandBuffer` is an unprotected command buffer, then each attachment to be cleared must not be a protected image.

- If `commandBuffer` is a protected command buffer, then each attachment to be cleared must not be an unprotected image.

- If the render pass instance this is recorded in uses multiview, then `baseArrayLayer` must be zero and `layerCount` must be one.

Valid Usage (Implicit)

- `commandBuffer` must be a valid `VkCommandBuffer` handle

- `pAttachments` must be a valid pointer to an array of `attachmentCount` valid `VkClearAttachment` structures

- `pRects` must be a valid pointer to an array of `rectCount` `VkClearRect` structures

- `commandBuffer` must be in the recording state

- The `VkCommandPool` that `commandBuffer` was allocated from must support graphics operations

- This command must only be called inside of a render pass instance

- `attachmentCount` must be greater than `0`

- `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 | Pipeline Type
--- | --- | --- | ---
Primary Secondary | Inside | Graphics | Graphics

## See Also

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 (c) 2014-2019 Khronos Group. This work is licensed under a Creative Commons Attribution 4.0 International License.