1// Copyright 2015-2023 The Khronos Group Inc.
2//
3// SPDX-License-Identifier: CC-BY-4.0
4
5[[clears]]
6= Clear Commands
7
8
9[[clears-outside]]
10== Clearing Images Outside A Render Pass Instance
11
12[open,refpage='vkCmdClearColorImage',desc='Clear regions of a color image',type='protos']
13--
14To clear one or more subranges of a color image, call:
15
16include::{generated}/api/protos/vkCmdClearColorImage.adoc[]
17
18.Valid Usage
19****
20ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[]
21  * [[VUID-vkCmdClearColorImage-image-01993]]
22    The <<resources-image-format-features,format features>> of pname:image must: contain ename:VK_FORMAT_FEATURE_TRANSFER_DST_BIT
23endif::VK_VERSION_1_1,VK_KHR_maintenance1[]
24  * pname:image must: have been created with ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT usage flag
25ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
26  * [[VUID-vkCmdClearColorImage-image-01545]]
27    pname:image must: not use any of the <<formats-requiring-sampler-ycbcr-conversion, formats that require a sampler {YCbCr} conversion>>
28endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
29  * If pname:image is non-sparse then it must: be bound completely and contiguously to a single sname:VkDeviceMemory object
30  * [[VUID-vkCmdClearColorImage-imageLayout-00004]]
31    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
32ifndef::VK_KHR_shared_presentable_image[]
33  * [[VUID-vkCmdClearColorImage-imageLayout-00005]]
34    pname:imageLayout must: be ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL or ename:VK_IMAGE_LAYOUT_GENERAL
35endif::VK_KHR_shared_presentable_image[]
36ifdef::VK_KHR_shared_presentable_image[]
37  * pname:imageLayout must: be ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL, ename:VK_IMAGE_LAYOUT_GENERAL, or ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR
38endif::VK_KHR_shared_presentable_image[]
39  * [[VUID-vkCmdClearColorImage-aspectMask-02498]]
40    The slink:VkImageSubresourceRange::pname:aspectMask members of the
41    elements of the pname:pRanges array must: each only include
42    ename:VK_IMAGE_ASPECT_COLOR_BIT
43  * [[VUID-vkCmdClearColorImage-baseMipLevel-01470]]
44    The slink:VkImageSubresourceRange::pname:baseMipLevel members of the
45    elements of the pname:pRanges array must: each be less than the
46    pname:mipLevels specified in slink:VkImageCreateInfo when pname:image
47    was created
48  * For each slink:VkImageSubresourceRange element of pname:pRanges, if the
49    pname:levelCount member is not ename:VK_REMAINING_MIP_LEVELS, then
50    [eq]#pname:baseMipLevel {plus} pname:levelCount# must: be less than or
51    equal to the pname:mipLevels specified in slink:VkImageCreateInfo when
52    pname:image was created
53  * [[VUID-vkCmdClearColorImage-baseArrayLayer-01472]]
54    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
55  * [[VUID-vkCmdClearColorImage-pRanges-01693]]
56    For each slink:VkImageSubresourceRange element of pname:pRanges, if the pname:layerCount member is not ename:VK_REMAINING_ARRAY_LAYERS, then
57    [eq]#pname:baseArrayLayer {plus} pname:layerCount# must: be less than or equal to the pname:arrayLayers specified in slink:VkImageCreateInfo when
58    pname:image was created
59  * pname:image must: not have a compressed or depth/stencil format
60  * pname:pColor must: be a valid pointer to a slink:VkClearColorValue union
61ifdef::VK_VERSION_1_1[]
62  * [[VUID-vkCmdClearColorImage-commandBuffer-01805]]
63    If pname:commandBuffer is an unprotected command buffer and <<limits-protectedNoFault, pname:protectedNoFault>> is not supported,
64    pname:image must: not be a protected image
65  * [[VUID-vkCmdClearColorImage-commandBuffer-01806]]
66    If pname:commandBuffer is a protected command buffer and <<limits-protectedNoFault, pname:protectedNoFault>> is not supported,
67    must: not be an unprotected image
68endif::VK_VERSION_1_1[]
69****
70
71include::{generated}/validity/protos/vkCmdClearColorImage.adoc[]
72--
73