VKCMDCLEARDEPTHSTENC(3)

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

C SPECIFICATION

To clear one or more subranges of a depth/stencil image, call:

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

PARAMETERS

    • commandBuffer is the command buffer into which the command will be recorded.

    • image is the image to be cleared.

    • imageLayout specifies the current layout of the image subresource ranges to be cleared, and must be VK_IMAGE_LAYOUT_GENERAL or VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL.

    • pDepthStencil is a pointer to a VkClearDepthStencilValue structure that contains the values the depth and stencil image subresource ranges will be cleared to (see ??? below).

    • rangeCount is the number of image subresource range structures in pRanges.

    • pRanges points to an array of VkImageSubresourceRange structures that describe a range of mipmap levels, array layers, and aspects to be cleared, as described in Image Views. The aspectMask of each image subresource range in pRanges can include VK_IMAGE_ASPECT_DEPTH_BIT if the image format has a depth component, and VK_IMAGE_ASPECT_STENCIL_BIT if the image format has a stencil component. pDepthStencil is a pointer to a VkClearDepthStencilValue structure that contains the values the image subresource ranges will be cleared to (see ??? below).

DESCRIPTION
Valid Usage

    • image must have been created with VK_IMAGE_USAGE_TRANSFER_DST_BIT usage flag

    • If image is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

    • 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
Valid Usage (Implicit)

    • 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

    • Both of commandBuffer, and image must have been created, allocated, or retrieved from the same VkDevice
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 | Outside | Graphics | Transfer

SEE ALSO

VkClearDepthStencilValue, VkCommandBuffer, VkImage, VkImageLayout, VkImageSubresourceRange

DOCUMENT NOTES

For more information, see the Vulkan Specification at URL

https://www.khronos.org/registry/vulkan/specs/1.0/xhtml/vkspec.html#vkCmdClearDepthStencilImage

This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification,not directly.

COPYRIGHT

Copyright (c) 2014-2016 Khronos Group. This work is licensed under a Creative Commons Attribution 4.0 International License.

AUTHOR

Khronos Group
    Author.