vkCmdClearAttachments(3)

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

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