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 27 ranges to be cleared, and must: be 28ifdef::VK_KHR_shared_presentable_image[] 29 ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR, 30endif::VK_KHR_shared_presentable_image[] 31 ename:VK_IMAGE_LAYOUT_GENERAL or 32 ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL. 33 * pname:pColor is a pointer to a slink:VkClearColorValue structure 34 containing the values that the image subresource ranges will be cleared 35 to (see <<clears-values>> below). 36 * pname:rangeCount is the number of image subresource range structures in 37 pname:pRanges. 38 * pname:pRanges is a pointer to an array of slink:VkImageSubresourceRange 39 structures describing a range of mipmap levels, array layers, and 40 aspects to be cleared, as described in <<resources-image-views,Image 41 Views>>. 42 43Each specified range in pname:pRanges is cleared to the value specified by 44pname:pColor. 45 46.Valid Usage 47**** 48ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[] 49 * [[VUID-vkCmdClearColorImage-image-01993]] 50 The <<resources-image-format-features,format features>> of pname:image 51 must: contain ename:VK_FORMAT_FEATURE_TRANSFER_DST_BIT 52endif::VK_VERSION_1_1,VK_KHR_maintenance1[] 53 * [[VUID-vkCmdClearColorImage-image-00002]] 54 pname:image must: have been created with 55 ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT usage flag 56ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 57 * [[VUID-vkCmdClearColorImage-image-01545]] 58 pname:image must: not use any of the 59 <<formats-requiring-sampler-ycbcr-conversion, formats that require a 60 sampler {YCbCr} conversion>> 61endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 62 * [[VUID-vkCmdClearColorImage-image-00003]] 63 If pname:image is non-sparse then it must: be bound completely and 64 contiguously to a single sname:VkDeviceMemory object 65 * [[VUID-vkCmdClearColorImage-imageLayout-00004]] 66 pname:imageLayout must: specify the layout of the image subresource 67 ranges of pname:image specified in pname:pRanges at the time this 68 command is executed on a sname:VkDevice 69ifndef::VK_KHR_shared_presentable_image[] 70 * [[VUID-vkCmdClearColorImage-imageLayout-00005]] 71 pname:imageLayout must: be ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL or 72 ename:VK_IMAGE_LAYOUT_GENERAL 73endif::VK_KHR_shared_presentable_image[] 74ifdef::VK_KHR_shared_presentable_image[] 75 * [[VUID-vkCmdClearColorImage-imageLayout-01394]] 76 pname:imageLayout must: be ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL, 77 ename:VK_IMAGE_LAYOUT_GENERAL, or 78 ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR 79endif::VK_KHR_shared_presentable_image[] 80 * [[VUID-vkCmdClearColorImage-aspectMask-02498]] 81 The slink:VkImageSubresourceRange::pname:aspectMask members of the 82 elements of the pname:pRanges array must: each only include 83 ename:VK_IMAGE_ASPECT_COLOR_BIT 84 * [[VUID-vkCmdClearColorImage-baseMipLevel-01470]] 85 The slink:VkImageSubresourceRange::pname:baseMipLevel members of the 86 elements of the pname:pRanges array must: each be less than the 87 pname:mipLevels specified in slink:VkImageCreateInfo when pname:image 88 was created 89 * [[VUID-vkCmdClearColorImage-pRanges-01692]] 90 For each slink:VkImageSubresourceRange element of pname:pRanges, if the 91 pname:levelCount member is not ename:VK_REMAINING_MIP_LEVELS, then 92 [eq]#pname:baseMipLevel {plus} pname:levelCount# must: be less than or 93 equal to the pname:mipLevels specified in slink:VkImageCreateInfo when 94 pname:image was created 95 * [[VUID-vkCmdClearColorImage-baseArrayLayer-01472]] 96 The slink:VkImageSubresourceRange::pname:baseArrayLayer members of the 97 elements of the pname:pRanges array must: each be less than the 98 pname:arrayLayers specified in slink:VkImageCreateInfo when pname:image 99 was created 100 * [[VUID-vkCmdClearColorImage-pRanges-01693]] 101 For each slink:VkImageSubresourceRange element of pname:pRanges, if the 102 pname:layerCount member is not ename:VK_REMAINING_ARRAY_LAYERS, then 103 [eq]#pname:baseArrayLayer {plus} pname:layerCount# must: be less than or 104 equal to the pname:arrayLayers specified in slink:VkImageCreateInfo when 105 pname:image was created 106 * [[VUID-vkCmdClearColorImage-image-00007]] 107 pname:image must: not have a compressed or depth/stencil format 108 * [[VUID-vkCmdClearColorImage-pColor-04961]] 109 pname:pColor must: be a valid pointer to a slink:VkClearColorValue union 110ifdef::VK_VERSION_1_1[] 111 * [[VUID-vkCmdClearColorImage-commandBuffer-01805]] 112 If pname:commandBuffer is an unprotected command buffer and 113 <<limits-protectedNoFault, pname:protectedNoFault>> is not supported, 114 pname:image must: not be a protected image 115 * [[VUID-vkCmdClearColorImage-commandBuffer-01806]] 116 If pname:commandBuffer is a protected command buffer and 117 <<limits-protectedNoFault, pname:protectedNoFault>> is not supported, 118 must: not be an unprotected image 119endif::VK_VERSION_1_1[] 120**** 121 122include::{generated}/validity/protos/vkCmdClearColorImage.adoc[] 123-- 124