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
23    must: contain ename:VK_FORMAT_FEATURE_TRANSFER_DST_BIT
24endif::VK_VERSION_1_1,VK_KHR_maintenance1[]
25  * [[VUID-vkCmdClearColorImage-image-10000]]
26    pname:image must: have been created with
27    ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT usage flag
28ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
29  * [[VUID-vkCmdClearColorImage-image-01545]]
30    pname:image must: not use any of the
31    <<formats-requiring-sampler-ycbcr-conversion, formats that require a
32    sampler {YCbCr} conversion>>
33endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
34  * [[VUID-vkCmdClearColorImage-image-10001]]
35    If pname:image is non-sparse then it must: be bound completely and
36    contiguously to a single sname:VkDeviceMemory object
37  * [[VUID-vkCmdClearColorImage-imageLayout-00004]]
38    pname:imageLayout must: specify the layout of the image subresource
39    ranges of pname:image specified in pname:pRanges at the time this
40    command is executed on a sname:VkDevice
41ifndef::VK_KHR_shared_presentable_image[]
42  * [[VUID-vkCmdClearColorImage-imageLayout-00005]]
43    pname:imageLayout must: be ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL or
44    ename:VK_IMAGE_LAYOUT_GENERAL
45endif::VK_KHR_shared_presentable_image[]
46ifdef::VK_KHR_shared_presentable_image[]
47  * [[VUID-vkCmdClearColorImage-imageLayout-10002]]
48    pname:imageLayout must: be ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL,
49    ename:VK_IMAGE_LAYOUT_GENERAL, or
50    ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR
51endif::VK_KHR_shared_presentable_image[]
52  * [[VUID-vkCmdClearColorImage-aspectMask-02498]]
53    The slink:VkImageSubresourceRange::pname:aspectMask members of the
54    elements of the pname:pRanges array must: each only include
55    ename:VK_IMAGE_ASPECT_COLOR_BIT
56  * [[VUID-vkCmdClearColorImage-baseMipLevel-01470]]
57    The slink:VkImageSubresourceRange::pname:baseMipLevel members of the
58    elements of the pname:pRanges array must: each be less than the
59    pname:mipLevels specified in slink:VkImageCreateInfo when pname:image
60    was created
61  * [[VUID-vkCmdClearColorImage-pRanges-10003]]
62    For each slink:VkImageSubresourceRange element of pname:pRanges, if the
63    pname:levelCount member is not ename:VK_REMAINING_MIP_LEVELS, then
64    [eq]#pname:baseMipLevel {plus} pname:levelCount# must: be less than or
65    equal to the pname:mipLevels specified in slink:VkImageCreateInfo when
66    pname:image was created
67  * [[VUID-vkCmdClearColorImage-baseArrayLayer-01472]]
68    The slink:VkImageSubresourceRange::pname:baseArrayLayer members of the
69    elements of the pname:pRanges array must: each be less than the
70    pname:arrayLayers specified in slink:VkImageCreateInfo when pname:image
71    was created
72  * [[VUID-vkCmdClearColorImage-pRanges-01693]]
73    For each slink:VkImageSubresourceRange element of pname:pRanges, if the
74    pname:layerCount member is not ename:VK_REMAINING_ARRAY_LAYERS, then
75    [eq]#pname:baseArrayLayer {plus} pname:layerCount# must: be less than or
76    equal to the pname:arrayLayers specified in slink:VkImageCreateInfo when
77    pname:image was created
78  * [[VUID-vkCmdClearColorImage-image-10004]]
79    pname:image must: not have a compressed or depth/stencil format
80  * [[VUID-vkCmdClearColorImage-pColor-10005]]
81    pname:pColor must: be a valid pointer to a slink:VkClearColorValue union
82ifdef::VK_VERSION_1_1[]
83  * [[VUID-vkCmdClearColorImage-commandBuffer-01805]]
84    If pname:commandBuffer is an unprotected command buffer and
85    <<limits-protectedNoFault, pname:protectedNoFault>> is not supported,
86    pname:image must: not be a protected image
87  * [[VUID-vkCmdClearColorImage-commandBuffer-01806]]
88    If pname:commandBuffer is a protected command buffer and
89    <<limits-protectedNoFault, pname:protectedNoFault>> is not supported,
90    must: not be an unprotected image
91endif::VK_VERSION_1_1[]
92****
93
94include::{generated}/validity/protos/vkCmdClearColorImage.adoc[]
95--
96