| // 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 |
| * [[VUID-vkCmdClearColorImage-imageLayout-01394]] |
| pname:imageLayout 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_TRANSFER_DST_OPTIMAL or |
| ename:VK_IMAGE_LAYOUT_GENERAL |
| * [[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[] |
| -- |
| |
| [open,refpage='vkCmdClearDepthStencilImage',desc='Fill regions of a combined depth/stencil image',type='protos'] |
| -- |
| To clear one or more subranges of a depth/stencil image, call: |
| |
| include::{generated}/api/protos/vkCmdClearDepthStencilImage.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 ename:VK_IMAGE_LAYOUT_GENERAL or |
| ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL. |
| * pname:pDepthStencil is a pointer to a slink:VkClearDepthStencilValue |
| structure containing the values that the depth and stencil 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>>. |
| |
| .Valid Usage |
| **** |
| ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[] |
| * [[VUID-vkCmdClearDepthStencilImage-image-01994]] |
| 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[] |
| ifdef::VK_VERSION_1_2,VK_EXT_separate_stencil_usage[] |
| * [[VUID-vkCmdClearDepthStencilImage-pRanges-02658]] |
| If the pname:aspect member of any element of pname:pRanges includes |
| ename:VK_IMAGE_ASPECT_STENCIL_BIT, and pname:image was created with |
| <<VkImageStencilUsageCreateInfo,separate stencil usage>>, |
| ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT must: have been included in the |
| slink:VkImageStencilUsageCreateInfo::pname:stencilUsage used to create |
| pname:image |
| endif::VK_VERSION_1_2,VK_EXT_separate_stencil_usage[] |
| * [[VUID-vkCmdClearDepthStencilImage-pRanges-02659]] |
| If the pname:aspect member of any element of pname:pRanges includes |
| ename:VK_IMAGE_ASPECT_STENCIL_BIT, |
| ifdef::VK_VERSION_1_2,VK_EXT_separate_stencil_usage[] |
| and pname:image was not created with |
| <<VkImageStencilUsageCreateInfo,separate stencil usage>>, |
| endif::VK_VERSION_1_2,VK_EXT_separate_stencil_usage[] |
| ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT must: have been included in the |
| slink:VkImageCreateInfo::pname:usage used to create pname:image |
| * [[VUID-vkCmdClearDepthStencilImage-pRanges-02660]] |
| If the pname:aspect member of any element of pname:pRanges includes |
| ename:VK_IMAGE_ASPECT_DEPTH_BIT, ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT |
| must: have been included in the slink:VkImageCreateInfo::pname:usage |
| used to create pname:image |
| * [[VUID-vkCmdClearDepthStencilImage-image-00010]] |
| If pname:image is non-sparse then it must: be bound completely and |
| contiguously to a single sname:VkDeviceMemory object |
| * [[VUID-vkCmdClearDepthStencilImage-imageLayout-00011]] |
| 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 |
| * [[VUID-vkCmdClearDepthStencilImage-imageLayout-00012]] |
| pname:imageLayout must: be either of |
| ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL or |
| ename:VK_IMAGE_LAYOUT_GENERAL |
| * [[VUID-vkCmdClearDepthStencilImage-aspectMask-02824]] |
| The slink:VkImageSubresourceRange::pname:aspectMask member of each |
| element of the pname:pRanges array must: not include bits other than |
| ename:VK_IMAGE_ASPECT_DEPTH_BIT or ename:VK_IMAGE_ASPECT_STENCIL_BIT |
| * [[VUID-vkCmdClearDepthStencilImage-image-02825]] |
| If the pname:image's format does not have a stencil component, then the |
| slink:VkImageSubresourceRange::pname:aspectMask member of each element |
| of the pname:pRanges array must: not include the |
| ename:VK_IMAGE_ASPECT_STENCIL_BIT bit |
| * [[VUID-vkCmdClearDepthStencilImage-image-02826]] |
| If the pname:image's format does not have a depth component, then the |
| slink:VkImageSubresourceRange::pname:aspectMask member of each element |
| of the pname:pRanges array must: not include the |
| ename:VK_IMAGE_ASPECT_DEPTH_BIT bit |
| * [[VUID-vkCmdClearDepthStencilImage-baseMipLevel-01474]] |
| 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-vkCmdClearDepthStencilImage-pRanges-01694]] |
| 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-vkCmdClearDepthStencilImage-baseArrayLayer-01476]] |
| 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-vkCmdClearDepthStencilImage-pRanges-01695]] |
| 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-vkCmdClearDepthStencilImage-image-00014]] |
| pname:image must: have a depth/stencil format |
| ifdef::VK_VERSION_1_1[] |
| * [[VUID-vkCmdClearDepthStencilImage-commandBuffer-01807]] |
| 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-vkCmdClearDepthStencilImage-commandBuffer-01808]] |
| If pname:commandBuffer is a protected command buffer and |
| <<limits-protectedNoFault, pname:protectedNoFault>> is not supported, |
| pname:image must: not be an unprotected image |
| endif::VK_VERSION_1_1[] |
| **** |
| |
| include::{generated}/validity/protos/vkCmdClearDepthStencilImage.adoc[] |
| -- |
| |
| Clears outside render pass instances are treated as transfer operations for |
| the purposes of memory barriers. |
| |
| |
| [[clears-inside]] |
| == Clearing Images Inside a Render Pass Instance |
| |
| [open,refpage='vkCmdClearAttachments',desc='Clear regions within bound framebuffer attachments',type='protos'] |
| -- |
| To clear one or more regions of color and depth/stencil attachments inside a |
| render pass instance, call: |
| |
| include::{generated}/api/protos/vkCmdClearAttachments.adoc[] |
| |
| * pname:commandBuffer is the command buffer into which the command will be |
| recorded. |
| * pname:attachmentCount is the number of entries in the pname:pAttachments |
| array. |
| * pname:pAttachments is a pointer to an array of slink:VkClearAttachment |
| structures defining the attachments to clear and the clear values to |
| use. |
| * pname:rectCount is the number of entries in the pname:pRects array. |
| * pname:pRects is a pointer to an array of slink:VkClearRect structures |
| defining regions within each selected attachment to clear. |
| |
| ifdef::VK_EXT_fragment_density_map[] |
| If the render pass has a <<renderpass-fragmentdensitymapattachment,fragment |
| density map attachment>>, clears follow the |
| <<fragmentdensitymapops,operations of fragment density maps>> as if each |
| clear region was a primitive which generates fragments. |
| The clear color is applied to all pixels inside each fragment's area |
| regardless if the pixels lie outside of the clear region. |
| Clears may: have a different set of supported fragment areas than draws. |
| endif::VK_EXT_fragment_density_map[] |
| |
| Unlike other <<clears,clear commands>>, flink:vkCmdClearAttachments is not a |
| transfer command. |
| It performs its operations in <<primsrast-order, rasterization order>>. |
| For color attachments, the operations are executed as color attachment |
| writes, by the ename:VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT stage. |
| For depth/stencil attachments, the operations are executed as |
| <<fragops-depth, depth writes>> and <<fragops-stencil, stencil writes>> by |
| the ename:VK_PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BIT and |
| ename:VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT stages. |
| |
| fname:vkCmdClearAttachments is not affected by the bound pipeline state. |
| |
| [NOTE] |
| .Note |
| ==== |
| It is generally preferable to clear attachments by using the |
| ename:VK_ATTACHMENT_LOAD_OP_CLEAR load operation at the start of rendering, |
| as it is more efficient on some implementations. |
| ==== |
| |
| If any attachment's pname:aspectMask to be cleared is not backed by an image |
| view, the clear has no effect on that aspect. |
| |
| ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| If an attachment being cleared refers to an image view created with an |
| pname:aspectMask equal to one of ename:VK_IMAGE_ASPECT_PLANE_0_BIT, |
| ename:VK_IMAGE_ASPECT_PLANE_1_BIT or ename:VK_IMAGE_ASPECT_PLANE_2_BIT, it |
| is considered to be ename:VK_IMAGE_ASPECT_COLOR_BIT for purposes of this |
| command, and must: be cleared with the ename:VK_IMAGE_ASPECT_COLOR_BIT |
| aspect as specified by <<image-views-plane-promotion,image view creation>>. |
| endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| |
| .Valid Usage |
| **** |
| * [[VUID-vkCmdClearAttachments-aspectMask-07884]] |
| If |
| ifdef::VK_VERSION_1_3,VK_KHR_dynamic_rendering[] |
| the current render pass instance does not use dynamic rendering, and |
| endif::VK_VERSION_1_3,VK_KHR_dynamic_rendering[] |
| the pname:aspectMask member of any element of pname:pAttachments |
| contains ename:VK_IMAGE_ASPECT_DEPTH_BIT, the current subpass instance's |
| depth-stencil attachment must: be either ename:VK_ATTACHMENT_UNUSED or |
| the attachment pname:format must: contain a depth component |
| * [[VUID-vkCmdClearAttachments-aspectMask-07885]] |
| If |
| ifdef::VK_VERSION_1_3,VK_KHR_dynamic_rendering[] |
| the current render pass instance does not use dynamic rendering, and |
| endif::VK_VERSION_1_3,VK_KHR_dynamic_rendering[] |
| the pname:aspectMask member of any element of pname:pAttachments |
| contains ename:VK_IMAGE_ASPECT_STENCIL_BIT, the current subpass |
| instance's depth-stencil attachment must: be either |
| ename:VK_ATTACHMENT_UNUSED or the attachment pname:format must: contain |
| a stencil component |
| * [[VUID-vkCmdClearAttachments-aspectMask-07271]] |
| If the pname:aspectMask member of any element of pname:pAttachments |
| contains ename:VK_IMAGE_ASPECT_COLOR_BIT, the pname:colorAttachment |
| must: be a valid color attachment index in the current render pass |
| instance |
| * [[VUID-vkCmdClearAttachments-rect-02682]] |
| The pname:rect member of each element of pname:pRects must: have an |
| pname:extent.width greater than `0` |
| * [[VUID-vkCmdClearAttachments-rect-02683]] |
| The pname:rect member of each element of pname:pRects must: have an |
| pname:extent.height greater than `0` |
| * [[VUID-vkCmdClearAttachments-pRects-00016]] |
| The rectangular region specified by each element of pname:pRects must: |
| be contained within the render area of the current render pass instance |
| * [[VUID-vkCmdClearAttachments-pRects-06937]] |
| The layers specified by each element of pname:pRects must: be contained |
| within every attachment that pname:pAttachments refers to, i.e. for each |
| element of pname:pRects, slink:VkClearRect::pname:baseArrayLayer {plus} |
| slink:VkClearRect::pname:layerCount must: be less than or equal to the |
| number of layers rendered to in the current render pass instance |
| * [[VUID-vkCmdClearAttachments-layerCount-01934]] |
| The pname:layerCount member of each element of pname:pRects must: not be |
| `0` |
| ifdef::VK_VERSION_1_1[] |
| * [[VUID-vkCmdClearAttachments-commandBuffer-02504]] |
| If pname:commandBuffer is an unprotected command buffer and |
| <<limits-protectedNoFault, pname:protectedNoFault>> is not supported, |
| each attachment to be cleared must: not be a protected image |
| * [[VUID-vkCmdClearAttachments-commandBuffer-02505]] |
| If pname:commandBuffer is a protected command buffer and |
| <<limits-protectedNoFault, pname:protectedNoFault>> is not supported, |
| each attachment to be cleared must: not be an unprotected image |
| endif::VK_VERSION_1_1[] |
| ifdef::VK_VERSION_1_1,VK_KHR_multiview[] |
| * [[VUID-vkCmdClearAttachments-baseArrayLayer-00018]] |
| If the render pass instance this is recorded in uses multiview, then |
| pname:baseArrayLayer must: be zero and pname:layerCount must: be one |
| endif::VK_VERSION_1_1,VK_KHR_multiview[] |
| ifdef::VK_ANDROID_external_format_resolve[] |
| * [[VUID-vkCmdClearAttachments-aspectMask-09298]] |
| If the subpass this is recorded in performs an external format resolve, |
| the pname:aspectMask member of any element of pname:pAttachments must: |
| not include `VK_IMAGE_ASPECT_PLANE__{ibit}__BIT` for any index _i_ |
| endif::VK_ANDROID_external_format_resolve[] |
| **** |
| |
| include::{generated}/validity/protos/vkCmdClearAttachments.adoc[] |
| -- |
| |
| [open,refpage='VkClearRect',desc='Structure specifying a clear rectangle',type='structs'] |
| -- |
| The sname:VkClearRect structure is defined as: |
| |
| include::{generated}/api/structs/VkClearRect.adoc[] |
| |
| * pname:rect is the two-dimensional region to be cleared. |
| * pname:baseArrayLayer is the first layer to be cleared. |
| * pname:layerCount is the number of layers to clear. |
| |
| The layers [eq]#[pname:baseArrayLayer, pname:baseArrayLayer {plus} |
| pname:layerCount)# counting from the base layer of the attachment image view |
| are cleared. |
| |
| include::{generated}/validity/structs/VkClearRect.adoc[] |
| -- |
| |
| [open,refpage='VkClearAttachment',desc='Structure specifying a clear attachment',type='structs'] |
| -- |
| The sname:VkClearAttachment structure is defined as: |
| |
| include::{generated}/api/structs/VkClearAttachment.adoc[] |
| |
| * pname:aspectMask is a mask selecting the color, depth and/or stencil |
| aspects of the attachment to be cleared. |
| * pname:colorAttachment is only meaningful if |
| ename:VK_IMAGE_ASPECT_COLOR_BIT is set in pname:aspectMask, in which |
| case it is an index into the currently bound color attachments. |
| * pname:clearValue is the color or depth/stencil value to clear the |
| attachment to, as described in <<clears-values,Clear Values>> below. |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkClearAttachment-aspectMask-00019]] |
| If pname:aspectMask includes ename:VK_IMAGE_ASPECT_COLOR_BIT, it must: |
| not include ename:VK_IMAGE_ASPECT_DEPTH_BIT or |
| ename:VK_IMAGE_ASPECT_STENCIL_BIT |
| * [[VUID-VkClearAttachment-aspectMask-00020]] |
| pname:aspectMask must: not include ename:VK_IMAGE_ASPECT_METADATA_BIT |
| ifdef::VK_EXT_image_drm_format_modifier[] |
| * [[VUID-VkClearAttachment-aspectMask-02246]] |
| pname:aspectMask must: not include |
| `VK_IMAGE_ASPECT_MEMORY_PLANE__{ibit}__BIT_EXT` for any index _i_ |
| endif::VK_EXT_image_drm_format_modifier[] |
| **** |
| |
| include::{generated}/validity/structs/VkClearAttachment.adoc[] |
| -- |
| |
| |
| [[clears-values]] |
| == Clear Values |
| |
| [open,refpage='VkClearColorValue',desc='Structure specifying a clear color value',type='structs'] |
| -- |
| The sname:VkClearColorValue structure is defined as: |
| |
| include::{generated}/api/structs/VkClearColorValue.adoc[] |
| |
| * pname:float32 are the color clear values when the format of the image or |
| attachment is one of the <<formats-numericformat, numeric formats>> with |
| a numeric type that is floating-point. |
| Floating point values are automatically converted to the format of the |
| image, with the clear value being treated as linear if the image is |
| sRGB. |
| * pname:int32 are the color clear values when the format of the image or |
| attachment has a numeric type that is signed integer (etext:SINT). |
| Signed integer values are converted to the format of the image by |
| casting to the smaller type (with negative 32-bit values mapping to |
| negative values in the smaller type). |
| If the integer clear value is not representable in the target type (e.g. |
| would overflow in conversion to that type), the clear value is |
| undefined:. |
| * pname:uint32 are the color clear values when the format of the image or |
| attachment has a numeric type that is unsigned integer (etext:UINT). |
| Unsigned integer values are converted to the format of the image by |
| casting to the integer type with fewer bits. |
| |
| The four array elements of the clear color map to R, G, B, and A components |
| of image formats, in order. |
| |
| If the image has more than one sample, the same value is written to all |
| samples for any pixels being cleared. |
| |
| include::{generated}/validity/structs/VkClearColorValue.adoc[] |
| -- |
| |
| [open,refpage='VkClearDepthStencilValue',desc='Structure specifying a clear depth stencil value',type='structs'] |
| -- |
| The sname:VkClearDepthStencilValue structure is defined as: |
| |
| include::{generated}/api/structs/VkClearDepthStencilValue.adoc[] |
| |
| * pname:depth is the clear value for the depth aspect of the depth/stencil |
| attachment. |
| It is a floating-point value which is automatically converted to the |
| attachment's format. |
| * pname:stencil is the clear value for the stencil aspect of the |
| depth/stencil attachment. |
| It is a 32-bit integer value which is converted to the attachment's |
| format by taking the appropriate number of LSBs. |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkClearDepthStencilValue-depth-00022]] |
| ifdef::VK_EXT_depth_range_unrestricted[] |
| Unless the `apiext:VK_EXT_depth_range_unrestricted` extension is enabled |
| endif::VK_EXT_depth_range_unrestricted[] |
| pname:depth must: be between `0.0` and `1.0`, inclusive |
| **** |
| |
| include::{generated}/validity/structs/VkClearDepthStencilValue.adoc[] |
| -- |
| |
| [open,refpage='VkClearValue',desc='Structure specifying a clear value',type='structs'] |
| -- |
| The sname:VkClearValue union is defined as: |
| |
| include::{generated}/api/structs/VkClearValue.adoc[] |
| |
| * pname:color specifies the color image clear values to use when clearing |
| a color image or attachment. |
| * pname:depthStencil specifies the depth and stencil clear values to use |
| when clearing a depth/stencil image or attachment. |
| |
| This union is used where part of the API requires either color or |
| depth/stencil clear values, depending on the attachment, and defines the |
| initial clear values in the slink:VkRenderPassBeginInfo structure. |
| |
| include::{generated}/validity/structs/VkClearValue.adoc[] |
| -- |
| |
| |
| [[clears-filling-buffers]] |
| == Filling Buffers |
| |
| [open,refpage='vkCmdFillBuffer',desc='Fill a region of a buffer with a fixed value',type='protos'] |
| -- |
| To clear buffer data, call: |
| |
| include::{generated}/api/protos/vkCmdFillBuffer.adoc[] |
| |
| * pname:commandBuffer is the command buffer into which the command will be |
| recorded. |
| * pname:dstBuffer is the buffer to be filled. |
| * pname:dstOffset is the byte offset into the buffer at which to start |
| filling, and must: be a multiple of 4. |
| * pname:size is the number of bytes to fill, and must: be either a |
| multiple of 4, or ename:VK_WHOLE_SIZE to fill the range from |
| pname:offset to the end of the buffer. |
| If ename:VK_WHOLE_SIZE is used and the remaining size of the buffer is |
| not a multiple of 4, then the nearest smaller multiple is used. |
| * pname:data is the 4-byte word written repeatedly to the buffer to fill |
| pname:size bytes of data. |
| The data word is written to memory according to the host endianness. |
| |
| fname:vkCmdFillBuffer is treated as a "`transfer`" operation for the |
| purposes of synchronization barriers. |
| The ename:VK_BUFFER_USAGE_TRANSFER_DST_BIT must: be specified in pname:usage |
| of slink:VkBufferCreateInfo in order for the buffer to be compatible with |
| fname:vkCmdFillBuffer. |
| |
| .Valid Usage |
| **** |
| * [[VUID-vkCmdFillBuffer-dstOffset-00024]] |
| pname:dstOffset must: be less than the size of pname:dstBuffer |
| * [[VUID-vkCmdFillBuffer-dstOffset-00025]] |
| pname:dstOffset must: be a multiple of `4` |
| * [[VUID-vkCmdFillBuffer-size-00026]] |
| If pname:size is not equal to ename:VK_WHOLE_SIZE, pname:size must: be |
| greater than `0` |
| * [[VUID-vkCmdFillBuffer-size-00027]] |
| If pname:size is not equal to ename:VK_WHOLE_SIZE, pname:size must: be |
| less than or equal to the size of pname:dstBuffer minus pname:dstOffset |
| * [[VUID-vkCmdFillBuffer-size-00028]] |
| If pname:size is not equal to ename:VK_WHOLE_SIZE, pname:size must: be a |
| multiple of `4` |
| * [[VUID-vkCmdFillBuffer-dstBuffer-00029]] |
| pname:dstBuffer must: have been created with |
| ename:VK_BUFFER_USAGE_TRANSFER_DST_BIT usage flag |
| * [[VUID-vkCmdFillBuffer-apiVersion-07894]] |
| ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[] |
| ifndef::VKSC_VERSION_1_0[] |
| If the apiext:VK_KHR_maintenance1 extension is not enabled and |
| slink:VkPhysicalDeviceProperties::pname:apiVersion is less than Vulkan |
| 1.1, the |
| endif::VKSC_VERSION_1_0[] |
| endif::VK_VERSION_1_1,VK_KHR_maintenance1[] |
| ifndef::VK_VERSION_1_1,VK_KHR_maintenance1[The] |
| slink:VkCommandPool that pname:commandBuffer was allocated from must: |
| support graphics or compute operations |
| * [[VUID-vkCmdFillBuffer-dstBuffer-00031]] |
| If pname:dstBuffer is non-sparse then it must: be bound completely and |
| contiguously to a single slink:VkDeviceMemory object |
| ifdef::VK_VERSION_1_1[] |
| * [[VUID-vkCmdFillBuffer-commandBuffer-01811]] |
| If pname:commandBuffer is an unprotected command buffer and |
| <<limits-protectedNoFault, pname:protectedNoFault>> is not supported, |
| pname:dstBuffer must: not be a protected buffer |
| * [[VUID-vkCmdFillBuffer-commandBuffer-01812]] |
| If pname:commandBuffer is a protected command buffer and |
| <<limits-protectedNoFault, pname:protectedNoFault>> is not supported, |
| pname:dstBuffer must: not be an unprotected buffer |
| endif::VK_VERSION_1_1[] |
| **** |
| |
| include::{generated}/validity/protos/vkCmdFillBuffer.adoc[] |
| -- |
| |
| |
| [[clears-updating-buffers]] |
| == Updating Buffers |
| |
| [open,refpage='vkCmdUpdateBuffer',desc='Update a buffer\'s contents from host memory',type='protos'] |
| -- |
| To update buffer data inline in a command buffer, call: |
| |
| include::{generated}/api/protos/vkCmdUpdateBuffer.adoc[] |
| |
| * pname:commandBuffer is the command buffer into which the command will be |
| recorded. |
| * pname:dstBuffer is a handle to the buffer to be updated. |
| * pname:dstOffset is the byte offset into the buffer to start updating, |
| and must: be a multiple of 4. |
| * pname:dataSize is the number of bytes to update, and must: be a multiple |
| of 4. |
| * pname:pData is a pointer to the source data for the buffer update, and |
| must: be at least pname:dataSize bytes in size. |
| |
| pname:dataSize must: be less than or equal to 65536 bytes. |
| For larger updates, applications can: use buffer to buffer |
| <<copies-buffers,copies>>. |
| |
| [NOTE] |
| .Note |
| ==== |
| Buffer updates performed with fname:vkCmdUpdateBuffer first copy the data |
| into command buffer memory when the command is recorded (which requires |
| additional storage and may incur an additional allocation), and then copy |
| the data from the command buffer into pname:dstBuffer when the command is |
| executed on a device. |
| |
| The additional cost of this functionality compared to <<copies-buffers, |
| buffer to buffer copies>> means it is only recommended for very small |
| amounts of data, and is why it is limited to only 65536 bytes. |
| |
| Applications can: work around this by issuing multiple |
| fname:vkCmdUpdateBuffer commands to different ranges of the same buffer, but |
| it is strongly recommended that they should: not. |
| ==== |
| |
| The source data is copied from the user pointer to the command buffer when |
| the command is called. |
| |
| fname:vkCmdUpdateBuffer is only allowed outside of a render pass. |
| This command is treated as a "`transfer`" operation for the purposes of |
| synchronization barriers. |
| The ename:VK_BUFFER_USAGE_TRANSFER_DST_BIT must: be specified in pname:usage |
| of slink:VkBufferCreateInfo in order for the buffer to be compatible with |
| fname:vkCmdUpdateBuffer. |
| |
| .Valid Usage |
| **** |
| * [[VUID-vkCmdUpdateBuffer-dstOffset-00032]] |
| pname:dstOffset must: be less than the size of pname:dstBuffer |
| * [[VUID-vkCmdUpdateBuffer-dataSize-00033]] |
| pname:dataSize must: be less than or equal to the size of |
| pname:dstBuffer minus pname:dstOffset |
| * [[VUID-vkCmdUpdateBuffer-dstBuffer-00034]] |
| pname:dstBuffer must: have been created with |
| ename:VK_BUFFER_USAGE_TRANSFER_DST_BIT usage flag |
| * [[VUID-vkCmdUpdateBuffer-dstBuffer-00035]] |
| If pname:dstBuffer is non-sparse then it must: be bound completely and |
| contiguously to a single sname:VkDeviceMemory object |
| * [[VUID-vkCmdUpdateBuffer-dstOffset-00036]] |
| pname:dstOffset must: be a multiple of `4` |
| * [[VUID-vkCmdUpdateBuffer-dataSize-00037]] |
| pname:dataSize must: be less than or equal to `65536` |
| * [[VUID-vkCmdUpdateBuffer-dataSize-00038]] |
| pname:dataSize must: be a multiple of `4` |
| ifdef::VK_VERSION_1_1[] |
| * [[VUID-vkCmdUpdateBuffer-commandBuffer-01813]] |
| If pname:commandBuffer is an unprotected command buffer and |
| <<limits-protectedNoFault, pname:protectedNoFault>> is not supported, |
| pname:dstBuffer must: not be a protected buffer |
| * [[VUID-vkCmdUpdateBuffer-commandBuffer-01814]] |
| If pname:commandBuffer is a protected command buffer and |
| <<limits-protectedNoFault, pname:protectedNoFault>> is not supported, |
| pname:dstBuffer must: not be an unprotected buffer |
| endif::VK_VERSION_1_1[] |
| **** |
| |
| include::{generated}/validity/protos/vkCmdUpdateBuffer.adoc[] |
| -- |
| |
| ifndef::VKSC_VERSION_1_0[] |
| [NOTE] |
| .Note |
| ==== |
| The pname:pData parameter was of type code:uint32_t* instead of code:void* |
| prior to version 1.0.19 of the Specification and dlink:VK_HEADER_VERSION 19 |
| of the <<boilerplate-headers,Vulkan Header Files>>. |
| This was a historical anomaly, as the source data may be of other types. |
| ==== |
| endif::VKSC_VERSION_1_0[] |
