## 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 containing the values that the depth and stencil image subresource ranges will be cleared to (see https://www.khronos.org/registry/vulkan/specs/1.1-extensions/html/vkspec.html#clears-values below).

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

• pRanges is a pointer to an array of VkImageSubresourceRange structures describing a range of mipmap levels, array layers, and aspects to be cleared, as described in Image Views.

## Description

Valid Usage
• The format features of image must contain VK_FORMAT_FEATURE_TRANSFER_DST_BIT.

• If any element of pRanges.aspect includes VK_IMAGE_ASPECT_STENCIL_BIT, and image was created with separate stencil usage, VK_IMAGE_USAGE_TRANSFER_DST_BIT must have been included in the VkImageStencilUsageCreateInfoEXT::stencilUsage used to create image

• If any element of pRanges.aspect includes VK_IMAGE_ASPECT_STENCIL_BIT, and image was not created with separate stencil usage, VK_IMAGE_USAGE_TRANSFER_DST_BIT must have been included in the VkImageCreateInfo::usage used to create image

• If any element of pRanges.aspect includes VK_IMAGE_ASPECT_DEPTH_BIT, VK_IMAGE_USAGE_TRANSFER_DST_BIT must have been included in the VkImageCreateInfo::usage used to create image

• 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 VkImageSubresourceRange::aspectMask members of the elements of the pRanges array must each only include VK_IMAGE_ASPECT_DEPTH_BIT if the image format has a depth component

• The VkImageSubresourceRange::aspectMask members of the elements of the pRanges array must each only include VK_IMAGE_ASPECT_STENCIL_BIT if the image format has a stencil component

• The VkImageSubresourceRange::baseMipLevel members of the elements of the pRanges array must each be less than the mipLevels specified in VkImageCreateInfo when image was created

• For each VkImageSubresourceRange element of pRanges, if the levelCount member is not VK_REMAINING_MIP_LEVELS, then baseMipLevel + levelCount must be less than the mipLevels specified in VkImageCreateInfo when image was created

• The VkImageSubresourceRange::baseArrayLayer members of the elements of the pRanges array must each be less than the arrayLayers specified in VkImageCreateInfo when image was created

• For each VkImageSubresourceRange element of pRanges, if the layerCount member is not VK_REMAINING_ARRAY_LAYERS, then baseArrayLayer + layerCount must be less than the arrayLayers specified in VkImageCreateInfo when image was created

• image must have a depth/stencil format

• If commandBuffer is an unprotected command buffer, then image must not be a protected image

• If commandBuffer is a protected command buffer, then image must not be an unprotected image

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 valid pointer to a valid VkClearDepthStencilValue structure

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