VKCMDCLEARATTACHMENT(3)

NAME
vkCmdClearAttachments - Clear regions within currently bound framebuffer attachments.

C SPECIFICATION

    void vkCmdClearAttachments(
        VkCommandBuffer                             commandBuffer,
        uint32_t                                    attachmentCount,
        const VkClearAttachment*                    pAttachments,
        uint32_t                                    rectCount,
        const VkClearRect*                          pRects);

PARAMETERS

commandBuffer
    The command buffer into which to insert the command.

attachmentCount
    The number of attachments to clear.

pAttachments
    A pointer to an array of structures describing the attachments to clear and the values to clear them to.

rectCount
    The number of regions within the attachments to clear.

pRects
    A pointer to an array of rectangles defining the regions to clear.

DESCRIPTION

vkCmdClearAttachments clears regions within the attachments associated with the current renderpass. commandBuffer is a handle to the command buffer into which to insert the command. A renderpass must be active on commandBuffer. attachmentCount specifies the number of attachments to clear and pAttachments is a pointer to an array of attachmentCount VkClearAttachment structures, each containing the aspect(s), attachment index and the clear value for each attachment. The definition of VkClearAttachment is:

    typedef struct VkClearAttachment {
        VkImageAspectFlags    aspectMask;
        uint32_t              colorAttachment;
        VkClearValue          clearValue;
    } VkClearAttachment;

aspectMask is a bitfield specifying the aspect or aspects to clear on the referenced attachment. It is constructed from a bitwise combination of the members of the VkImageAspectFlagBits enumeration, the definition of which is:

    typedef enum VkImageAspectFlagBits {
        VK_IMAGE_ASPECT_COLOR_BIT = 0x00000001,
        VK_IMAGE_ASPECT_DEPTH_BIT = 0x00000002,
        VK_IMAGE_ASPECT_STENCIL_BIT = 0x00000004,
        VK_IMAGE_ASPECT_METADATA_BIT = 0x00000008,
    } VkImageAspectFlagBits;

The colorAttachment member of VkClearAttachment specifies the index of the color attachment within the current framebuffer. The clearValue member contains the value to which to clear the attachment. It is an instance of the VkClearValue union, the definition of which is:

    typedef union VkClearValue {
        VkClearColorValue           color;
        VkClearDepthStencilValue    depthStencil;
    } VkClearValue;

If the attachment and aspect referenced by aspectMask and colorAttachment is a color attachment, the values contained in the color field of VkClearValue is used to clear the attachment regions. If the attachment and aspect referenced by aspectMask and colorAttachment is a depth, stencil or depth-stencil attachment, then the depthStencil field of VkClearValue is used to clear the attachment.

The rectCount parameter to vkCmdClearAttachments specifies the number of regions of the attachments to clear. pRects is a pointer to an array of rectCount VkClearRect structures defining those regions. The definition of VkClearRect is:

    typedef struct VkClearRect {
        VkRect2D    rect;
        uint32_t    baseArrayLayer;
        uint32_t    layerCount;
    } VkClearRect;

The rect member of VkClearRect specifies the rectangle, measured in pixels, of the rectangle to clear. baseArrayLayer and layerCount specify the first layer and number of layers to clear and should be used to clear multiple layers in layered attachments.

VALID USAGE

    • commandBuffer must be a valid VkCommandBuffer handle

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

    • pRects must be a 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

    • If the aspectMask member of any given element of pAttachments contains VK_IMAGE_ASPECT_COLOR_BIT, the colorAttachment member of those elements must refer to a valid color attachment in the current subpass

    • The rectangular region specified by a given element of pRects must be contained within the render area of the current render pass instance

    • The layers specified by a given element of pRects must be contained within every attachment that pAttachments refers to

HOST SYNCHRONIZATION

    • Host access to commandBuffer must be externally synchronized

COMMAND PROPERTIES
Command Buffer Levels | Render Pass Scope | Supported Queue Types
Primary Secondary | Inside | GRAPHICS

SEE ALSO

VkClearAttachment, vkCmdBeginRenderPass

COPYRIGHT

Copyright © 2014-2016 Khronos Group. This material may be distributed subject to the terms and conditions set forth in the Open Publication License, v 1.0, 8 June 1999. http://opencontent.org/openpub/.

AUTHOR

Khronos Group
    Author.