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
12Color and depth/stencil images can: be cleared outside a render pass
13instance using flink:vkCmdClearColorImage or
14flink:vkCmdClearDepthStencilImage, respectively.
15These commands are only allowed outside of a render pass instance.
16
17[open,refpage='vkCmdClearColorImage',desc='Clear regions of a color image',type='protos']
18--
19To clear one or more subranges of a color image, call:
20
21include::{generated}/api/protos/vkCmdClearColorImage.adoc[]
22
23  * pname:commandBuffer is the command buffer into which the command will be
24    recorded.
25  * pname:image is the image to be cleared.
26  * pname:imageLayout specifies the current layout of the image subresource ranges to be cleared, and must: be
27ifdef::VK_KHR_shared_presentable_image[]
28    ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR,
29endif::VK_KHR_shared_presentable_image[]
30    ename:VK_IMAGE_LAYOUT_GENERAL or ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL.
31  * pname:pColor is a pointer to a slink:VkClearColorValue structure containing the values that the image subresource ranges will be cleared to (see <<clears-values>> below).
32  * pname:rangeCount is the number of image subresource range structures in pname:pRanges.
33  * pname:pRanges is a pointer to an array of slink:VkImageSubresourceRange
34    structures describing a range of mipmap levels, array layers, and
35    aspects to be cleared, as described in <<resources-image-views,Image Views>>.
36
37Each specified range in pname:pRanges is cleared to the value specified by
38pname:pColor.
39
40.Valid Usage
41****
42ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[]
43  * [[VUID-vkCmdClearColorImage-image-01993]]
44    The <<resources-image-format-features,format features>> of pname:image must: contain ename:VK_FORMAT_FEATURE_TRANSFER_DST_BIT
45endif::VK_VERSION_1_1,VK_KHR_maintenance1[]
46  * [[VUID-vkCmdClearColorImage-image-00002]]
47    pname:image must: have been created with ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT usage flag
48ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
49  * [[VUID-vkCmdClearColorImage-image-01545]]
50    pname:image must: not use any of the <<formats-requiring-sampler-ycbcr-conversion, formats that require a sampler {YCbCr} conversion>>
51endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
52  * [[VUID-vkCmdClearColorImage-image-00003]]
53    If pname:image is non-sparse then it must: be bound completely and contiguously to a single sname:VkDeviceMemory object
54  * [[VUID-vkCmdClearColorImage-imageLayout-00004]]
55    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
56ifndef::VK_KHR_shared_presentable_image[]
57  * [[VUID-vkCmdClearColorImage-imageLayout-00005]]
58    pname:imageLayout must: be ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL or ename:VK_IMAGE_LAYOUT_GENERAL
59endif::VK_KHR_shared_presentable_image[]
60ifdef::VK_KHR_shared_presentable_image[]
61  * [[VUID-vkCmdClearColorImage-imageLayout-01394]]
62    pname:imageLayout must: be ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL, ename:VK_IMAGE_LAYOUT_GENERAL, or ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR
63endif::VK_KHR_shared_presentable_image[]
64  * [[VUID-vkCmdClearColorImage-aspectMask-02498]]
65    The slink:VkImageSubresourceRange::pname:aspectMask members of the
66    elements of the pname:pRanges array must: each only include
67    ename:VK_IMAGE_ASPECT_COLOR_BIT
68  * [[VUID-vkCmdClearColorImage-baseMipLevel-01470]]
69    The slink:VkImageSubresourceRange::pname:baseMipLevel members of the
70    elements of the pname:pRanges array must: each be less than the
71    pname:mipLevels specified in slink:VkImageCreateInfo when pname:image
72    was created
73  * [[VUID-vkCmdClearColorImage-pRanges-01692]]
74    For each slink:VkImageSubresourceRange element of pname:pRanges, if the
75    pname:levelCount member is not ename:VK_REMAINING_MIP_LEVELS, then
76    [eq]#pname:baseMipLevel {plus} pname:levelCount# must: be less than or
77    equal to the pname:mipLevels specified in slink:VkImageCreateInfo when
78    pname:image was created
79  * [[VUID-vkCmdClearColorImage-baseArrayLayer-01472]]
80    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
81  * [[VUID-vkCmdClearColorImage-pRanges-01693]]
82    For each slink:VkImageSubresourceRange element of pname:pRanges, if the pname:layerCount member is not ename:VK_REMAINING_ARRAY_LAYERS, then
83    [eq]#pname:baseArrayLayer {plus} pname:layerCount# must: be less than or equal to the pname:arrayLayers specified in slink:VkImageCreateInfo when
84    pname:image was created
85  * [[VUID-vkCmdClearColorImage-image-00007]]
86    pname:image must: not have a compressed or depth/stencil format
87  * [[VUID-vkCmdClearColorImage-pColor-04961]]
88    pname:pColor must: be a valid pointer to a slink:VkClearColorValue union
89ifdef::VK_VERSION_1_1[]
90  * [[VUID-vkCmdClearColorImage-commandBuffer-01805]]
91    If pname:commandBuffer is an unprotected command buffer and <<limits-protectedNoFault, pname:protectedNoFault>> is not supported,
92    pname:image must: not be a protected image
93  * [[VUID-vkCmdClearColorImage-commandBuffer-01806]]
94    If pname:commandBuffer is a protected command buffer and
95    <<limits-protectedNoFault, pname:protectedNoFault>> is not supported,
96    must: not be an unprotected image
97endif::VK_VERSION_1_1[]
98****
99
100include::{generated}/validity/protos/vkCmdClearColorImage.adoc[]
101--
102