vkCmdClearDepthStencilImage
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 beVK_IMAGE_LAYOUT_GENERAL
orVK_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 inpRanges
.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 image
must 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_BIT
must 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-commandBuffer-parameter
commandBuffer
must be a valid VkCommandBuffer handle
VUID-vkCmdClearDepthStencilImage-image-parameter
image
must be a valid VkImage handle
VUID-vkCmdClearDepthStencilImage-imageLayout-parameter
imageLayout
must be a valid VkImageLayout value
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-recording
commandBuffer
must be in the recording state
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-rangeCount-arraylength
rangeCount
must be greater than 0
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
thatcommandBuffer
was allocated from must be externally synchronized ::