Function Prototype

vkCmdClearDepthStencilImage

Fill regions of a combined depth/stencil image
primary / secondary
outside
graphics
action

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);
  • 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 Clear 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.

Valid Usage

VUID-vkCmdClearDepthStencilImage-image-01994

The format features of imagemust contain VK_FORMAT_FEATURE_TRANSFER_DST_BIT

VUID-vkCmdClearDepthStencilImage-pRanges-02658

If the aspect member of any element of pRanges 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 VkImageStencilUsageCreateInfo::stencilUsage used to create image

VUID-vkCmdClearDepthStencilImage-pRanges-02659

If the aspect member of any element of pRanges 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

VUID-vkCmdClearDepthStencilImage-pRanges-02660

If the aspect member of any element of pRanges includes VK_IMAGE_ASPECT_DEPTH_BIT, VK_IMAGE_USAGE_TRANSFER_DST_BITmust have been included in the VkImageCreateInfo::usage used to create image

VUID-vkCmdClearDepthStencilImage-image-00010

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

VUID-vkCmdClearDepthStencilImage-imageLayout-00011

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

VUID-vkCmdClearDepthStencilImage-imageLayout-00012

imageLayout must be either of VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL or VK_IMAGE_LAYOUT_GENERAL

VUID-vkCmdClearDepthStencilImage-aspectMask-02824

The VkImageSubresourceRange::aspectMask member of each element of the pRanges array must not include bits other than VK_IMAGE_ASPECT_DEPTH_BIT or VK_IMAGE_ASPECT_STENCIL_BIT

VUID-vkCmdClearDepthStencilImage-image-02825

If the image’s format does not have a stencil component, then the VkImageSubresourceRange::aspectMask member of each element of the pRanges array must not include the VK_IMAGE_ASPECT_STENCIL_BIT bit

VUID-vkCmdClearDepthStencilImage-image-02826

If the image’s format does not have a depth component, then the VkImageSubresourceRange::aspectMask member of each element of the pRanges array must not include the VK_IMAGE_ASPECT_DEPTH_BIT bit

VUID-vkCmdClearDepthStencilImage-baseMipLevel-01474

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

VUID-vkCmdClearDepthStencilImage-pRanges-01694

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

VUID-vkCmdClearDepthStencilImage-baseArrayLayer-01476

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

VUID-vkCmdClearDepthStencilImage-pRanges-01695

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

VUID-vkCmdClearDepthStencilImage-image-00014

image must have a depth/stencil format

Valid Usage (Implicit)

VUID-vkCmdClearDepthStencilImage-pDepthStencil-parameter

pDepthStencil must be a valid pointer to a valid VkClearDepthStencilValue structure

VUID-vkCmdClearDepthStencilImage-pRanges-parameter

pRanges must be a valid pointer to an array of rangeCount valid VkImageSubresourceRange structures

VUID-vkCmdClearDepthStencilImage-commandBuffer-cmdpool

The VkCommandPool that commandBuffer was allocated from must support graphics operations

VUID-vkCmdClearDepthStencilImage-renderpass

This command must only be called outside of a render pass instance

VUID-vkCmdClearDepthStencilImage-videocoding

This command must only be called outside of a video coding scope

VUID-vkCmdClearDepthStencilImage-commonparent

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