## C Specification

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

// Provided by VK_VERSION_1_0
void vkCmdClearColorImage(
VkCommandBuffer                             commandBuffer,
VkImage                                     image,
VkImageLayout                               imageLayout,
const VkClearColorValue*                    pColor,
uint32_t                                    rangeCount,
const VkImageSubresourceRange*              pRanges);

## Parameters

• 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 https://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/vkspec.html#clears-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.

## Description

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

Valid Usage
• VUID-vkCmdClearColorImage-image-01993
The format features of image must contain VK_FORMAT_FEATURE_TRANSFER_DST_BIT

• VUID-vkCmdClearColorImage-image-00002
image must have been created with VK_IMAGE_USAGE_TRANSFER_DST_BIT usage flag

• 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_TRANSFER_DST_OPTIMAL, VK_IMAGE_LAYOUT_GENERAL, or VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR

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 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 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, then image must not be a protected image

• VUID-vkCmdClearColorImage-commandBuffer-01806
If commandBuffer is a protected command buffer, then image must not be an unprotected image

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 graphics, or compute operations

• VUID-vkCmdClearColorImage-renderpass
This command must only be called outside of a render pass instance

• 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

Command Properties
Command Buffer Levels Render Pass Scope Supported Queue Types

Primary
Secondary

Outside

Graphics
Compute