VulkanHub
Function Prototype

vkCmdClearColorImage

Clear regions of a color image

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_SHARED_PRESENT_KHR, VK_IMAGE_LAYOUT_GENERAL or VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL.
  • pColor is a pointer to a VkClearColorValue structure containing the values that the 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.

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

Valid Usage

VUID-vkCmdClearColorImage-image-01993

The format features of imagemust contain VK_FORMAT_FEATURE_TRANSFER_DST_BIT

VUID-vkCmdClearColorImage-image-00002

image must have been created with the VK_IMAGE_USAGE_TRANSFER_DST_BIT usage flag set

VUID-vkCmdClearColorImage-image-01545

image must not use any of the formats that require a sampler Y′CBCR conversion

VUID-vkCmdClearColorImage-image-00003

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

VUID-vkCmdClearColorImage-imageLayout-00004

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-vkCmdClearColorImage-imageLayout-01394

imageLayout must be VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR, VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL or VK_IMAGE_LAYOUT_GENERAL

VUID-vkCmdClearColorImage-aspectMask-02498

The VkImageSubresourceRange::aspectMask members of the elements of the pRanges array must each only include VK_IMAGE_ASPECT_COLOR_BIT

VUID-vkCmdClearColorImage-baseMipLevel-01470

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-vkCmdClearColorImage-pRanges-01692

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-vkCmdClearColorImage-baseArrayLayer-01472

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-vkCmdClearColorImage-pRanges-01693

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-vkCmdClearColorImage-image-00007

image must not have a compressed or depth/stencil format

VUID-vkCmdClearColorImage-pColor-04961

pColor must be a valid pointer to a VkClearColorValue union

VUID-vkCmdClearColorImage-commandBuffer-01805

If commandBuffer is an unprotected command buffer and protectedNoFault is not supported, image must not be a protected image

VUID-vkCmdClearColorImage-commandBuffer-01806

If commandBuffer is a protected command buffer and protectedNoFault is not supported, must not be an unprotected image

VUID-vkCmdClearColorImage-image-09678

If image’s format has components other than R and G, it must not have a 64-bit component width

Valid Usage (Implicit)

VUID-vkCmdClearColorImage-commandBuffer-parameter

commandBuffer must be a valid VkCommandBuffer handle

VUID-vkCmdClearColorImage-image-parameter

image must be a valid VkImage handle

VUID-vkCmdClearColorImage-imageLayout-parameter

imageLayout must be a valid VkImageLayout value

VUID-vkCmdClearColorImage-pRanges-parameter

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

VUID-vkCmdClearColorImage-commandBuffer-recording

commandBuffer must be in the recording state

VUID-vkCmdClearColorImage-commandBuffer-cmdpool

The VkCommandPool that commandBuffer was allocated from must support VK_QUEUE_COMPUTE_BIT, or VK_QUEUE_GRAPHICS_BIT operations

VUID-vkCmdClearColorImage-renderpass

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

VUID-vkCmdClearColorImage-suspended

This command must not be called between suspended render pass instances

VUID-vkCmdClearColorImage-videocoding

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

VUID-vkCmdClearColorImage-rangeCount-arraylength

rangeCount must be greater than 0

VUID-vkCmdClearColorImage-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