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);
commandBufferis the command buffer into which the command will be recorded.imageis the image to be cleared.imageLayoutspecifies the current layout of the image subresource ranges to be cleared, and must beVK_IMAGE_LAYOUT_GENERALorVK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL.pDepthStencilis 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).rangeCountis the number of image subresource range structures inpRanges.pRangesis 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-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
commandBuffermust be externally synchronized - Host access to the
VkCommandPoolthatcommandBufferwas allocated from must be externally synchronized ::