| // Copyright 2015-2023 The Khronos Group Inc. |
| // |
| // SPDX-License-Identifier: CC-BY-4.0 |
| |
| [[clears]] |
| = Clear Commands |
| |
| |
| [[clears-outside]] |
| == Clearing Images Outside A Render Pass Instance |
| |
| Color and depth/stencil images can: be cleared outside a render pass |
| instance using flink:vkCmdClearColorImage or |
| flink:vkCmdClearDepthStencilImage, respectively. |
| These commands are only allowed outside of a render pass instance. |
| |
| [open,refpage='vkCmdClearColorImage',desc='Clear regions of a color image',type='protos'] |
| -- |
| To clear one or more subranges of a color image, call: |
| |
| include::{generated}/api/protos/vkCmdClearColorImage.adoc[] |
| |
| * pname:commandBuffer is the command buffer into which the command will be |
| recorded. |
| * pname:image is the image to be cleared. |
| * pname:imageLayout specifies the current layout of the image subresource |
| ranges to be cleared, and must: be |
| ifdef::VK_KHR_shared_presentable_image[] |
| ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR, |
| endif::VK_KHR_shared_presentable_image[] |
| ename:VK_IMAGE_LAYOUT_GENERAL or |
| ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL. |
| * 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). |
| * pname:rangeCount is the number of image subresource range structures in |
| pname:pRanges. |
| * pname:pRanges is a pointer to an array of slink:VkImageSubresourceRange |
| structures describing a range of mipmap levels, array layers, and |
| aspects to be cleared, as described in <<resources-image-views,Image |
| Views>>. |
| |
| Each specified range in pname:pRanges is cleared to the value specified by |
| pname:pColor. |
| |
| .Valid Usage |
| **** |
| ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[] |
| * [[VUID-vkCmdClearColorImage-image-01993]] |
| The <<resources-image-format-features,format features>> of pname:image |
| must: contain ename:VK_FORMAT_FEATURE_TRANSFER_DST_BIT |
| endif::VK_VERSION_1_1,VK_KHR_maintenance1[] |
| * [[VUID-vkCmdClearColorImage-image-00002]] |
| pname:image must: have been created with |
| ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT usage flag |
| ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| * [[VUID-vkCmdClearColorImage-image-01545]] |
| pname:image must: not use any of the |
| <<formats-requiring-sampler-ycbcr-conversion, formats that require a |
| sampler {YCbCr} conversion>> |
| endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| * [[VUID-vkCmdClearColorImage-image-00003]] |
| If pname:image is non-sparse then it must: be bound completely and |
| contiguously to a single sname:VkDeviceMemory object |
| * [[VUID-vkCmdClearColorImage-imageLayout-00004]] |
| 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 |
| ifndef::VK_KHR_shared_presentable_image[] |
| * [[VUID-vkCmdClearColorImage-imageLayout-00005]] |
| pname:imageLayout must: be ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL or |
| ename:VK_IMAGE_LAYOUT_GENERAL |
| endif::VK_KHR_shared_presentable_image[] |
| ifdef::VK_KHR_shared_presentable_image[] |
| * [[VUID-vkCmdClearColorImage-imageLayout-01394]] |
| pname:imageLayout must: be ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL, |
| ename:VK_IMAGE_LAYOUT_GENERAL, or |
| ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR |
| endif::VK_KHR_shared_presentable_image[] |
| * [[VUID-vkCmdClearColorImage-aspectMask-02498]] |
| The slink:VkImageSubresourceRange::pname:aspectMask members of the |
| elements of the pname:pRanges array must: each only include |
| ename:VK_IMAGE_ASPECT_COLOR_BIT |
| * [[VUID-vkCmdClearColorImage-baseMipLevel-01470]] |
| The slink:VkImageSubresourceRange::pname:baseMipLevel members of the |
| elements of the pname:pRanges array must: each be less than the |
| pname:mipLevels specified in slink:VkImageCreateInfo when pname:image |
| was created |
| * [[VUID-vkCmdClearColorImage-pRanges-01692]] |
| For each slink:VkImageSubresourceRange element of pname:pRanges, if the |
| pname:levelCount member is not ename:VK_REMAINING_MIP_LEVELS, then |
| [eq]#pname:baseMipLevel {plus} pname:levelCount# must: be less than or |
| equal to the pname:mipLevels specified in slink:VkImageCreateInfo when |
| pname:image was created |
| * [[VUID-vkCmdClearColorImage-baseArrayLayer-01472]] |
| 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 |
| * [[VUID-vkCmdClearColorImage-pRanges-01693]] |
| For each slink:VkImageSubresourceRange element of pname:pRanges, if the |
| pname:layerCount member is not ename:VK_REMAINING_ARRAY_LAYERS, then |
| [eq]#pname:baseArrayLayer {plus} pname:layerCount# must: be less than or |
| equal to the pname:arrayLayers specified in slink:VkImageCreateInfo when |
| pname:image was created |
| * [[VUID-vkCmdClearColorImage-image-00007]] |
| pname:image must: not have a compressed or depth/stencil format |
| * [[VUID-vkCmdClearColorImage-pColor-04961]] |
| pname:pColor must: be a valid pointer to a slink:VkClearColorValue union |
| ifdef::VK_VERSION_1_1[] |
| * [[VUID-vkCmdClearColorImage-commandBuffer-01805]] |
| If pname:commandBuffer is an unprotected command buffer and |
| <<limits-protectedNoFault, pname:protectedNoFault>> is not supported, |
| pname:image must: not be a protected image |
| * [[VUID-vkCmdClearColorImage-commandBuffer-01806]] |
| If pname:commandBuffer is a protected command buffer and |
| <<limits-protectedNoFault, pname:protectedNoFault>> is not supported, |
| must: not be an unprotected image |
| endif::VK_VERSION_1_1[] |
| **** |
| |
| include::{generated}/validity/protos/vkCmdClearColorImage.adoc[] |
| -- |
