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