// Copyright 2015-2024 The Khronos Group Inc.
//
// SPDX-License-Identifier: CC-BY-4.0

[[clears]]
= Clear Commands


[[clears-outside]]
== Clearing Images Outside A Render Pass Instance

[open,refpage='vkCmdClearColorImage',desc='Clear regions of a color image',type='protos']
--
To clear one or more subranges of a color image, call:

include::{generated}/api/protos/vkCmdClearColorImage.adoc[]

.Valid Usage
****
ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[]
  * [[VUID-vkCmdClearColorImage-image-01993]]
    The <<resources-image-format-features,format features>> of pname:image must: contain ename:VK_FORMAT_FEATURE_TRANSFER_DST_BIT
endif::VK_VERSION_1_1,VK_KHR_maintenance1[]
  * pname:image must: have been created with ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT usage flag
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
  * [[VUID-vkCmdClearColorImage-image-01545]]
    pname:image must: not use any of the <<formats-requiring-sampler-ycbcr-conversion, formats that require a sampler {YCbCr} conversion>>
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
  * If pname:image is non-sparse then it must: be bound completely and contiguously to a single sname:VkDeviceMemory object
  * [[VUID-vkCmdClearColorImage-imageLayout-00004]]
    pname:imageLayout must: specify the layout of the image subresource ranges of pname:image specified in pname:pRanges at the time this command is executed on a sname:VkDevice
ifndef::VK_KHR_shared_presentable_image[]
  * [[VUID-vkCmdClearColorImage-imageLayout-00005]]
    pname:imageLayout must: be ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL or ename:VK_IMAGE_LAYOUT_GENERAL
endif::VK_KHR_shared_presentable_image[]
ifdef::VK_KHR_shared_presentable_image[]
  * pname:imageLayout must: be ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL, ename:VK_IMAGE_LAYOUT_GENERAL, or ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR
endif::VK_KHR_shared_presentable_image[]
  * [[VUID-vkCmdClearColorImage-aspectMask-02498]]
    The slink:VkImageSubresourceRange::pname:aspectMask members of the
    elements of the pname:pRanges array must: each only include
    ename:VK_IMAGE_ASPECT_COLOR_BIT
  * [[VUID-vkCmdClearColorImage-baseMipLevel-01470]]
    The slink:VkImageSubresourceRange::pname:baseMipLevel members of the
    elements of the pname:pRanges array must: each be less than the
    pname:mipLevels specified in slink:VkImageCreateInfo when pname:image
    was created
  * For each slink:VkImageSubresourceRange element of pname:pRanges, if the
    pname:levelCount member is not ename:VK_REMAINING_MIP_LEVELS, then
    [eq]#pname:baseMipLevel {plus} pname:levelCount# must: be less than or
    equal to the pname:mipLevels specified in slink:VkImageCreateInfo when
    pname:image was created
  * [[VUID-vkCmdClearColorImage-baseArrayLayer-01472]]
    The slink:VkImageSubresourceRange::pname:baseArrayLayer members of the elements of the pname:pRanges array must: each be less than the pname:arrayLayers specified in slink:VkImageCreateInfo when pname:image was created
  * [[VUID-vkCmdClearColorImage-pRanges-01693]]
    For each slink:VkImageSubresourceRange element of pname:pRanges, if the pname:layerCount member is not ename:VK_REMAINING_ARRAY_LAYERS, then
    [eq]#pname:baseArrayLayer {plus} pname:layerCount# must: be less than or equal to the pname:arrayLayers specified in slink:VkImageCreateInfo when
    pname:image was created
  * pname:image must: not have a compressed or depth/stencil format
  * pname:pColor must: be a valid pointer to a slink:VkClearColorValue union
ifdef::VK_VERSION_1_1[]
  * [[VUID-vkCmdClearColorImage-commandBuffer-01805]]
    If pname:commandBuffer is an unprotected command buffer and <<limits-protectedNoFault, pname:protectedNoFault>> is not supported,
    pname:image must: not be a protected image
  * [[VUID-vkCmdClearColorImage-commandBuffer-01806]]
    If pname:commandBuffer is a protected command buffer and <<limits-protectedNoFault, pname:protectedNoFault>> is not supported,
    must: not be an unprotected image
endif::VK_VERSION_1_1[]
****

include::{generated}/validity/protos/vkCmdClearColorImage.adoc[]
--