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