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

vkCmdClearAttachments is not affected by the bound pipeline state.

 Note It’s generally advised that attachments are cleared by using the VK_ATTACHMENT_LOAD_OP_CLEAR load operation at the start of rendering, which will be more efficient on some implementations.
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

• 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, then each attachment to be cleared must not be a protected image

• VUID-vkCmdClearAttachments-commandBuffer-02505
If commandBuffer is a protected command buffer, then 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