VKCMDCLEARDEPTHSTENC(3)

NAME
vkCmdClearDepthStencilImage - Fill regions of a combined depth-stencil image.

C SPECIFICATION

    void vkCmdClearDepthStencilImage(
        VkCommandBuffer                             commandBuffer,
        VkImage                                     image,
        VkImageLayout                               imageLayout,
        const VkClearDepthStencilValue*             pDepthStencil,
        uint32_t                                    rangeCount,
        const VkImageSubresourceRange*              pRanges);

PARAMETERS

commandBuffer
    The command buffer into which the command is to be placed.

image
    The image containing the regions to be cleared.

imageLayout
    The layout of the image to be cleared.

pDepthStencil
    A pointer to a structure containing the values to clear the image with.

rangeCount
    The number of image regions to clear.

pRanges
    A pointer to an array of rangeCount regions to clear.

DESCRIPTION

vkCmdClearDepthStencilImage clears rangeCount regions of a combined depth-stencil image to the values specified in the structure whose address is given in pDepthStencil. This is a pointer to an instance of the VkClearDepthStencilValue structure, the definition of which is:

    typedef struct VkClearDepthStencilValue {
        float       depth;
        uint32_t    stencil;
    } VkClearDepthStencilValue;

The depth and stencil members contain the value to clear the depth and stencil aspects of the image to, respectively. imageLayout specifies the layout of the image being cleared. pRanges points to an array rangeCount regions of the image are cleared, each of which is described by an instance of the VkImageSubresourceRange structure, the definition of which is:

    typedef struct VkImageSubresourceRange {
        VkImageAspectFlags    aspectMask;
        uint32_t              baseMipLevel;
        uint32_t              levelCount;
        uint32_t              baseArrayLayer;
        uint32_t              layerCount;
    } VkImageSubresourceRange;

VALID USAGE

    • commandBuffer must be a valid VkCommandBuffer handle

    • image must be a valid VkImage handle

    • imageLayout must be a valid VkImageLayout value

    • pDepthStencil must be a pointer to a valid VkClearDepthStencilValue structure

    • pRanges must be a pointer to an array of rangeCount valid VkImageSubresourceRange 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 outside of a render pass instance

    • rangeCount must be greater than 0

    • Each of commandBuffer and image must have been created, allocated or retrieved from the same VkDevice

    • image must have been created with VK_IMAGE_USAGE_TRANSFER_DST_BIT usage flag

    • imageLayout must specify the layout of the image subresource ranges of image specified in pRanges at the time this command is executed on a VkDevice

    • imageLayout must be either of VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL or VK_IMAGE_LAYOUT_GENERAL

    • The image range of any given element of pRanges must be an image subresource range that is contained within image

    • image must have a depth/stencil format

HOST SYNCHRONIZATION

    • Host access to commandBuffer must be externally synchronized

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

NOTES

Although vkCmdClearDepthStencilImage does not generate errors or return a value, enabled validation layers may detect possible error conditions or potentially undefined behavior and report this via some other means.

SEE ALSO

vkCmdClearColorImage

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.