17.1. Clearing Images Outside A Render Pass Instance

Color and depth/stencil images can be cleared outside a render pass instance using vkCmdClearColorImage or vkCmdClearDepthStencilImage, respectively. These commands are only allowed outside of a render pass instance.

To clear one or more subranges of a color image, call:

void vkCmdClearColorImage(
VkCommandBuffer                             commandBuffer,
VkImage                                     image,
VkImageLayout                               imageLayout,
const VkClearColorValue*                    pColor,
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.
• pColor is a pointer to a VkClearColorValue structure that contains the values the image subresource ranges will be cleared to (see Section 17.3, “Clear Values” 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 all image subresource ranges must only include VK_IMAGE_ASPECT_COLOR_BIT.

Each specified range in pRanges is cleared to the value specified by pColor.

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 that contains the values the depth and stencil image subresource ranges will be cleared to (see Section 17.3, “Clear Values” 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 Section 17.3, “Clear Values” below).

Clears outside render pass instances are treated as transfer operations for the purposes of memory barriers.