// Copyright 2015-2023 The Khronos Group Inc. // // SPDX-License-Identifier: CC-BY-4.0 [[fragops]] = Fragment Operations Fragments produced by rasterization go through a number of operations to determine whether or how values produced by fragment shading are written to the framebuffer. The following fragment operations adhere to <>, and are typically performed in this order: ifdef::VK_EXT_discard_rectangles[] . <> endif::VK_EXT_discard_rectangles[] . <> ifdef::VK_NV_scissor_exclusive[] . <> endif::VK_NV_scissor_exclusive[] . <> . Certain <> operations: ** <> ifdef::VK_EXT_shader_tile_image[] ** <> endif::VK_EXT_shader_tile_image[] ** <> ifdef::VK_EXT_shader_stencil_export[] ** <> endif::VK_EXT_shader_stencil_export[] ifdef::VK_EXT_fragment_shader_interlock[] ** <> endif::VK_EXT_fragment_shader_interlock[] . <> . <> . <> . <> ifdef::VK_NV_representative_fragment_test[] . <> endif::VK_NV_representative_fragment_test[] . <> ifdef::VK_NV_fragment_coverage_to_color[] . <> endif::VK_NV_fragment_coverage_to_color[] . <> ifdef::VK_NV_framebuffer_mixed_samples[] . <> endif::VK_NV_framebuffer_mixed_samples[] The <> generated by rasterization describes the initial coverage of each sample covered by the fragment. Fragment operations will update the coverage mask to add or subtract coverage where appropriate. If a fragment operation results in all bits of the coverage mask being `0`, the fragment is discarded, and no further operations are performed. Fragments can also be programmatically discarded in a fragment shader by executing one of ifdef::VK_VERSION_1_3,VK_KHR_shader_terminate_invocation[] * code:OpTerminateInvocation endif::VK_VERSION_1_3,VK_KHR_shader_terminate_invocation[] ifdef::VK_VERSION_1_3,VK_EXT_shader_demote_to_helper_invocation[] * code:OpDemoteToHelperInvocationEXT endif::VK_VERSION_1_3,VK_EXT_shader_demote_to_helper_invocation[] * code:OpKill. When one of the fragment operations in this chapter is described as "`replacing`" a fragment shader output, that output is replaced unconditionally, even if no fragment shader previously wrote to that output. ifdef::VK_EXT_post_depth_coverage[] If there is a <> and it declares the code:PostDepthCoverage execution mode, the <> is instead performed after the <>. endif::VK_EXT_post_depth_coverage[] ifdef::VK_KHR_maintenance5[] If sname:VkPhysicalDeviceMaintenance5PropertiesKHR::pname:earlyFragmentMultisampleCoverageAfterSampleCounting is set to ename:VK_TRUE and there is a <> which declares the code:EarlyFragmentTests execution mode, <> and <> operations must: be performed after <>. Otherwise, if sname:VkPhysicalDeviceMaintenance5PropertiesKHR::pname:earlyFragmentMultisampleCoverageAfterSampleCounting is set to ename:VK_FALSE and there is a <> which declares the code:EarlyFragmentTests execution mode, <> and <> operations should: instead be performed after <>, but may: be performed before <>. If sname:VkPhysicalDeviceMaintenance5PropertiesKHR::pname:earlyFragmentSampleMaskTestBeforeSampleCounting is set to ename:VK_TRUE and there is a <> which declares the code:EarlyFragmentTests execution mode <> operations must: follow the order of fragment operations from above. Otherwise, if sname:VkPhysicalDeviceMaintenance5PropertiesKHR::pname:earlyFragmentSampleMaskTestBeforeSampleCounting is set to ename:VK_FALSE and there is a <> which declares the code:EarlyFragmentTests execution mode, <> operations should: follow the order of fragment operations from above but may: instead be performed after <>. endif::VK_KHR_maintenance5[] ifndef::VK_KHR_maintenance5[] If there is a <> and it declares the code:EarlyFragmentTests execution mode, <> and <> operations should: instead be performed after <>, and <> may: instead be performed after <>. endif::VK_KHR_maintenance5[] ifdef::VK_AMD_shader_early_and_late_fragment_tests[] If there is a <> which declares the code:EarlyAndLateFragmentTestsAMD execution mode, and it does not declare the code:DepthReplacing ifdef::VK_EXT_shader_stencil_export[] or code:StencilRefReplacingEXT endif::VK_EXT_shader_stencil_export[] execution mode, <> and <> operations are instead be performed after <>. ifdef::VK_EXT_shader_stencil_export[] For a pipeline with the following properties: * a fragment shader is specified * the fragment shader either specifies code:EarlyAndLateFragmentTestsAMD or does not write to storage resources; * the fragment shader specifies the code:StencilRefReplacingEXT execution mode; * either ** the fragment shader specifies the code:StencilRefUnchangedFrontAMD execution mode; ** the fragment shader specifies the code:StencilRefLessFrontAMD execution mode and the pipeline uses a slink:VkPipelineDepthStencilStateCreateInfo::pname:front.compareOp of ename:VK_COMPARE_OP_GREATER or ename:VK_COMPARE_OP_GREATER_OR_EQUAL; or ** the fragment shader specifies the code:StencilRefGreaterFrontAMD execution mode and the pipeline uses a slink:VkPipelineDepthStencilStateCreateInfo::pname:front.compareOp of ename:VK_COMPARE_OP_LESS or ename:VK_COMPARE_OP_LESS_OR_EQUAL; and * either ** the fragment shader specifies the code:StencilRefUnchangedBackAMD execution mode; ** the fragment shader specifies the code:StencilRefLessBackAMD execution mode and the pipeline uses a slink:VkPipelineDepthStencilStateCreateInfo::pname:back.compareOp of ename:VK_COMPARE_OP_GREATER or ename:VK_COMPARE_OP_GREATER_OR_EQUAL; or ** the fragment shader specifies the code:StencilRefGreaterBackAMD execution mode and the pipeline uses a slink:VkPipelineDepthStencilStateCreateInfo::pname:back.compareOp of ename:VK_COMPARE_OP_LESS or ename:VK_COMPARE_OP_LESS_OR_EQUAL an additional <> may: be performed before <>, using the stencil reference value specified by slink:VkPipelineDepthStencilStateCreateInfo::pname:front.reference or slink:VkPipelineDepthStencilStateCreateInfo::pname:back.reference. endif::VK_EXT_shader_stencil_export[] endif::VK_AMD_shader_early_and_late_fragment_tests[] For a pipeline with the following properties: * a fragment shader is specified * the fragment shader ifdef::VK_AMD_shader_early_and_late_fragment_tests[] either specifies code:EarlyAndLateFragmentTestsAMD or endif::VK_AMD_shader_early_and_late_fragment_tests[] does not write to storage resources; * the fragment shader specifies the code:DepthReplacing execution mode; and * either ** the fragment shader specifies the code:DepthUnchanged execution mode; ** the fragment shader specifies the code:DepthLess execution mode and the pipeline uses a slink:VkPipelineDepthStencilStateCreateInfo::pname:depthCompareOp of ename:VK_COMPARE_OP_GREATER or ename:VK_COMPARE_OP_GREATER_OR_EQUAL; or ** the fragment shader specifies the code:DepthGreater execution mode and the pipeline uses a slink:VkPipelineDepthStencilStateCreateInfo::pname:depthCompareOp of ename:VK_COMPARE_OP_LESS or ename:VK_COMPARE_OP_LESS_OR_EQUAL the implementation may: perform <> before <> and perform an additional <> immediately after that using the interpolated depth value generated by rasterization. Once all fragment operations have completed, fragment shader outputs for covered color attachment samples pass through <>. ifdef::VK_EXT_discard_rectangles[] [[fragops-discard-rectangles]] == Discard Rectangles Test The discard rectangle test compares the framebuffer coordinates [eq]#(x~f~,y~f~)# of each sample covered by a fragment against a set of _discard rectangles_. Each discard rectangle is defined by a slink:VkRect2D. These values are either set by the slink:VkPipelineDiscardRectangleStateCreateInfoEXT structure during pipeline creation, or dynamically by the flink:vkCmdSetDiscardRectangleEXT command. A given sample is considered inside a discard rectangle if the [eq]#x~f~# is in the range [eq]#[slink:VkRect2D::pname:offset.x, slink:VkRect2D::pname:offset.x {plus} slink:VkRect2D::pname:extent.x)#, and [eq]#y~f~# is in the range [eq]#[slink:VkRect2D::pname:offset.y, slink:VkRect2D::pname:offset.y {plus} slink:VkRect2D::pname:extent.y)#. If the test is set to be inclusive, samples that are not inside any of the discard rectangles will have their coverage set to `0`. If the test is set to be exclusive, samples that are inside any of the discard rectangles will have their coverage set to `0`. If no discard rectangles are specified, the coverage mask is unmodified by this operation. [open,refpage='VkPipelineDiscardRectangleStateCreateInfoEXT',desc='Structure specifying discard rectangle',type='structs'] -- The sname:VkPipelineDiscardRectangleStateCreateInfoEXT structure is defined as: include::{generated}/api/structs/VkPipelineDiscardRectangleStateCreateInfoEXT.adoc[] * pname:sType is a elink:VkStructureType value identifying this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. * pname:flags is reserved for future use. * pname:discardRectangleMode is a elink:VkDiscardRectangleModeEXT value determining whether the discard rectangle test is inclusive or exclusive. * pname:discardRectangleCount is the number of discard rectangles to use. * pname:pDiscardRectangles is a pointer to an array of slink:VkRect2D structures defining discard rectangles. If the ename:VK_DYNAMIC_STATE_DISCARD_RECTANGLE_EXT dynamic state is enabled for a pipeline, the pname:pDiscardRectangles member is ignored. If the ename:VK_DYNAMIC_STATE_DISCARD_RECTANGLE_ENABLE_EXT dynamic state is not enabled for the pipeline the presence of this structure in the slink:VkGraphicsPipelineCreateInfo chain, and a pname:discardRectangleCount greater than zero, implicitly enables discard rectangles in the pipeline, otherwise discard rectangles must: enabled or disabled by flink:vkCmdSetDiscardRectangleEnableEXT. If the ename:VK_DYNAMIC_STATE_DISCARD_RECTANGLE_MODE_EXT dynamic state is enabled for the pipeline, the pname:discardRectangleMode member is ignored, and the discard rectangle mode must: be set by flink:vkCmdSetDiscardRectangleModeEXT. When this structure is included in the pname:pNext chain of slink:VkGraphicsPipelineCreateInfo, it defines parameters of the discard rectangle test. If the ename:VK_DYNAMIC_STATE_DISCARD_RECTANGLE_EXT dynamic state is not enabled, and this structure is not included in the pname:pNext chain, it is equivalent to specifying this structure with a pname:discardRectangleCount of `0`. .Valid Usage **** * [[VUID-VkPipelineDiscardRectangleStateCreateInfoEXT-discardRectangleCount-00582]] pname:discardRectangleCount must: be less than or equal to sname:VkPhysicalDeviceDiscardRectanglePropertiesEXT::pname:maxDiscardRectangles **** include::{generated}/validity/structs/VkPipelineDiscardRectangleStateCreateInfoEXT.adoc[] -- [open,refpage='VkPipelineDiscardRectangleStateCreateFlagsEXT',desc='Reserved for future use',type='flags'] -- include::{generated}/api/flags/VkPipelineDiscardRectangleStateCreateFlagsEXT.adoc[] tname:VkPipelineDiscardRectangleStateCreateFlagsEXT is a bitmask type for setting a mask, but is currently reserved for future use. -- [open,refpage='VkDiscardRectangleModeEXT',desc='Specify the discard rectangle mode',type='enums'] -- ename:VkDiscardRectangleModeEXT values are: include::{generated}/api/enums/VkDiscardRectangleModeEXT.adoc[] * ename:VK_DISCARD_RECTANGLE_MODE_INCLUSIVE_EXT specifies that the discard rectangle test is inclusive. * ename:VK_DISCARD_RECTANGLE_MODE_EXCLUSIVE_EXT specifies that the discard rectangle test is exclusive. -- [open,refpage='vkCmdSetDiscardRectangleEXT',desc='Set discard rectangles dynamically for a command buffer',type='protos'] -- To <> the discard rectangles, call: include::{generated}/api/protos/vkCmdSetDiscardRectangleEXT.adoc[] * pname:commandBuffer is the command buffer into which the command will be recorded. * pname:firstDiscardRectangle is the index of the first discard rectangle whose state is updated by the command. * pname:discardRectangleCount is the number of discard rectangles whose state are updated by the command. * pname:pDiscardRectangles is a pointer to an array of slink:VkRect2D structures specifying discard rectangles. The discard rectangle taken from element [eq]#i# of pname:pDiscardRectangles replace the current state for the discard rectangle at index [eq]#pname:firstDiscardRectangle {plus} i#, for [eq]#i# in [eq]#[0, pname:discardRectangleCount)#. This command sets the discard rectangles for subsequent drawing commands ifdef::VK_EXT_shader_object[when drawing using <>, or] when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_DISCARD_RECTANGLE_EXT set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. Otherwise, this state is specified by the slink:VkPipelineDiscardRectangleStateCreateInfoEXT::pname:pDiscardRectangles values used to create the currently active pipeline. .Valid Usage **** * [[VUID-vkCmdSetDiscardRectangleEXT-firstDiscardRectangle-00585]] The sum of pname:firstDiscardRectangle and pname:discardRectangleCount must: be less than or equal to slink:VkPhysicalDeviceDiscardRectanglePropertiesEXT::pname:maxDiscardRectangles * [[VUID-vkCmdSetDiscardRectangleEXT-x-00587]] The pname:x and pname:y member of pname:offset in each slink:VkRect2D element of pname:pDiscardRectangles must: be greater than or equal to `0` * [[VUID-vkCmdSetDiscardRectangleEXT-offset-00588]] Evaluation of [eq]#(pname:offset.x {plus} pname:extent.width)# in each slink:VkRect2D element of pname:pDiscardRectangles must: not cause a signed integer addition overflow * [[VUID-vkCmdSetDiscardRectangleEXT-offset-00589]] Evaluation of [eq]#(pname:offset.y {plus} pname:extent.height)# in each slink:VkRect2D element of pname:pDiscardRectangles must: not cause a signed integer addition overflow ifdef::VK_NV_inherited_viewport_scissor[] * [[VUID-vkCmdSetDiscardRectangleEXT-viewportScissor2D-04788]] If this command is recorded in a secondary command buffer with slink:VkCommandBufferInheritanceViewportScissorInfoNV::pname:viewportScissor2D enabled, then this function must: not be called endif::VK_NV_inherited_viewport_scissor[] **** include::{generated}/validity/protos/vkCmdSetDiscardRectangleEXT.adoc[] -- [open,refpage='vkCmdSetDiscardRectangleEnableEXT',desc='Enable discard rectangles dynamically for a command buffer',type='protos'] -- To <> whether discard rectangles are enabled, call: include::{generated}/api/protos/vkCmdSetDiscardRectangleEnableEXT.adoc[] * pname:commandBuffer is the command buffer into which the command will be recorded. * pname:discardRectangleEnable specifies whether discard rectangles are enabled or not. This command sets the discard rectangle enable for subsequent drawing commands ifdef::VK_EXT_shader_object[when drawing using <>, or] when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_DISCARD_RECTANGLE_ENABLE_EXT set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. Otherwise, this state is implied by the slink:VkPipelineDiscardRectangleStateCreateInfoEXT::pname:discardRectangleCount value used to create the currently active pipeline, where a non-zero pname:discardRectangleCount implicitly enables discard rectangles, otherwise they are disabled. .Valid Usage **** * [[VUID-vkCmdSetDiscardRectangleEnableEXT-specVersion-07851]] The `apiext:VK_EXT_discard_rectangles` extension must: be enabled, and the implementation must: support at least pname:specVersion `2` of this extension **** include::{generated}/validity/protos/vkCmdSetDiscardRectangleEnableEXT.adoc[] -- [open,refpage='vkCmdSetDiscardRectangleModeEXT',desc='Sets the discard rectangle mode dynamically for a command buffer',type='protos'] -- To <> the discard rectangle mode, call: include::{generated}/api/protos/vkCmdSetDiscardRectangleModeEXT.adoc[] * pname:commandBuffer is the command buffer into which the command will be recorded. * pname:discardRectangleMode specifies the discard rectangle mode for all discard rectangles, either inclusive or exclusive. This command sets the discard rectangle mode for subsequent drawing commands ifdef::VK_EXT_shader_object[when drawing using <>, or] when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_DISCARD_RECTANGLE_MODE_EXT set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. Otherwise, this state is specified by the slink:VkPipelineDiscardRectangleStateCreateInfoEXT::pname:discardRectangleMode value used to create the currently active pipeline. .Valid Usage **** * [[VUID-vkCmdSetDiscardRectangleModeEXT-specVersion-07852]] The `apiext:VK_EXT_discard_rectangles` extension must: be enabled, and the implementation must: support at least pname:specVersion `2` of this extension **** include::{generated}/validity/protos/vkCmdSetDiscardRectangleModeEXT.adoc[] -- endif::VK_EXT_discard_rectangles[] [[fragops-scissor]] == Scissor Test The scissor test compares the framebuffer coordinates [eq]#(x~f~,y~f~)# of each sample covered by a fragment against a _scissor rectangle_ at the index equal to the fragment's <>. Each scissor rectangle is defined by a slink:VkRect2D. These values are either set by the slink:VkPipelineViewportStateCreateInfo structure during pipeline creation, or dynamically by the flink:vkCmdSetScissor command. A given sample is considered inside a scissor rectangle if [eq]#x~f~# is in the range [eq]#[slink:VkRect2D::pname:offset.x, slink:VkRect2D::pname:offset.x {plus} slink:VkRect2D::pname:extent.x)#, and [eq]#y~f~# is in the range [eq]#[slink:VkRect2D::pname:offset.y, slink:VkRect2D::pname:offset.y {plus} slink:VkRect2D::pname:extent.y)#. Samples with coordinates outside the scissor rectangle at the corresponding code:ViewportIndex will have their coverage set to `0`. ifdef::VK_QCOM_render_pass_transform[] If a render pass transform is enabled, the (pname:offset.x and pname:offset.y) and (pname:extent.width and pname:extent.height) values are transformed as described in <> before participating in the scissor test. endif::VK_QCOM_render_pass_transform[] [open,refpage='vkCmdSetScissor',desc='Set scissor rectangles dynamically for a command buffer',type='protos'] -- To <> the scissor rectangles, call: include::{generated}/api/protos/vkCmdSetScissor.adoc[] * pname:commandBuffer is the command buffer into which the command will be recorded. * pname:firstScissor is the index of the first scissor whose state is updated by the command. * pname:scissorCount is the number of scissors whose rectangles are updated by the command. * pname:pScissors is a pointer to an array of slink:VkRect2D structures defining scissor rectangles. The scissor rectangles taken from element [eq]#i# of pname:pScissors replace the current state for the scissor index [eq]#pname:firstScissor {plus} i#, for [eq]#i# in [eq]#[0, pname:scissorCount)#. This command sets the scissor rectangles for subsequent drawing commands ifdef::VK_EXT_shader_object[when drawing using <>, or] when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_SCISSOR set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. Otherwise, this state is specified by the slink:VkPipelineViewportStateCreateInfo::pname:pScissors values used to create the currently active pipeline. .Valid Usage **** * [[VUID-vkCmdSetScissor-firstScissor-00592]] The sum of pname:firstScissor and pname:scissorCount must: be between `1` and sname:VkPhysicalDeviceLimits::pname:maxViewports, inclusive * [[VUID-vkCmdSetScissor-firstScissor-00593]] If the <> feature is not enabled, pname:firstScissor must: be `0` * [[VUID-vkCmdSetScissor-scissorCount-00594]] If the <> feature is not enabled, pname:scissorCount must: be `1` * [[VUID-vkCmdSetScissor-x-00595]] The pname:x and pname:y members of pname:offset member of any element of pname:pScissors must: be greater than or equal to `0` * [[VUID-vkCmdSetScissor-offset-00596]] Evaluation of [eq]#(pname:offset.x {plus} pname:extent.width)# must: not cause a signed integer addition overflow for any element of pname:pScissors * [[VUID-vkCmdSetScissor-offset-00597]] Evaluation of [eq]#(pname:offset.y {plus} pname:extent.height)# must: not cause a signed integer addition overflow for any element of pname:pScissors ifdef::VK_NV_inherited_viewport_scissor[] * [[VUID-vkCmdSetScissor-viewportScissor2D-04789]] If this command is recorded in a secondary command buffer with slink:VkCommandBufferInheritanceViewportScissorInfoNV::pname:viewportScissor2D enabled, then this function must: not be called endif::VK_NV_inherited_viewport_scissor[] **** include::{generated}/validity/protos/vkCmdSetScissor.adoc[] -- ifdef::VK_NV_scissor_exclusive[] [[fragops-exclusive-scissor]] == Exclusive Scissor Test The exclusive scissor test compares the framebuffer coordinates [eq]#(x~f~,y~f~)# of each sample covered by a fragment against an _exclusive scissor rectangle_ at the index equal to the fragment's <>. Each exclusive scissor rectangle is defined by a slink:VkRect2D. These values are either set by the slink:VkPipelineViewportExclusiveScissorStateCreateInfoNV structure during pipeline creation, or dynamically by the flink:vkCmdSetExclusiveScissorNV command. A given sample is considered inside an exclusive scissor rectangle if [eq]#x~f~# is in the range [eq]#[slink:VkRect2D::pname:offset.x, slink:VkRect2D::pname:offset.x {plus} slink:VkRect2D::pname:extent.x)#, and [eq]#y~f~# is in the range [eq]#[slink:VkRect2D::pname:offset.y, slink:VkRect2D::pname:offset.y {plus} slink:VkRect2D::pname:extent.y)#. Samples with coordinates inside the exclusive scissor rectangle at the corresponding code:ViewportIndex will have their coverage set to `0`. If no exclusive scissor rectangles are specified, the coverage mask is unmodified by this operation. [open,refpage='VkPipelineViewportExclusiveScissorStateCreateInfoNV',desc='Structure specifying parameters controlling exclusive scissor testing',type='structs'] -- The sname:VkPipelineViewportExclusiveScissorStateCreateInfoNV structure is defined as: include::{generated}/api/structs/VkPipelineViewportExclusiveScissorStateCreateInfoNV.adoc[] * pname:sType is a elink:VkStructureType value identifying this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. * pname:exclusiveScissorCount is the number of exclusive scissor rectangles. * pname:pExclusiveScissors is a pointer to an array of slink:VkRect2D structures defining exclusive scissor rectangles. If the ename:VK_DYNAMIC_STATE_EXCLUSIVE_SCISSOR_NV dynamic state is enabled for a pipeline, the pname:pExclusiveScissors member is ignored. When this structure is included in the pname:pNext chain of slink:VkGraphicsPipelineCreateInfo, it defines parameters of the exclusive scissor test. If this structure is not included in the pname:pNext chain, it is equivalent to specifying this structure with a pname:exclusiveScissorCount of `0`. .Valid Usage **** * [[VUID-VkPipelineViewportExclusiveScissorStateCreateInfoNV-exclusiveScissorCount-02027]] If the <> feature is not enabled, pname:exclusiveScissorCount must: be `0` or `1` * [[VUID-VkPipelineViewportExclusiveScissorStateCreateInfoNV-exclusiveScissorCount-02028]] pname:exclusiveScissorCount must: be less than or equal to sname:VkPhysicalDeviceLimits::pname:maxViewports * [[VUID-VkPipelineViewportExclusiveScissorStateCreateInfoNV-exclusiveScissorCount-02029]] pname:exclusiveScissorCount must: be `0` or greater than or equal to the pname:viewportCount member of slink:VkPipelineViewportStateCreateInfo **** include::{generated}/validity/structs/VkPipelineViewportExclusiveScissorStateCreateInfoNV.adoc[] -- [open,refpage='vkCmdSetExclusiveScissorNV',desc='Set exclusive scissor rectangles dynamically for a command buffer',type='protos'] -- To <> the exclusive scissor rectangles, call: include::{generated}/api/protos/vkCmdSetExclusiveScissorNV.adoc[] * pname:commandBuffer is the command buffer into which the command will be recorded. * pname:firstExclusiveScissor is the index of the first exclusive scissor rectangle whose state is updated by the command. * pname:exclusiveScissorCount is the number of exclusive scissor rectangles updated by the command. * pname:pExclusiveScissors is a pointer to an array of slink:VkRect2D structures defining exclusive scissor rectangles. The scissor rectangles taken from element [eq]#i# of pname:pExclusiveScissors replace the current state for the scissor index [eq]#pname:firstExclusiveScissor {plus} i#, for [eq]#i# in [eq]#[0, pname:exclusiveScissorCount)#. This command sets the exclusive scissor rectangles for subsequent drawing commands ifdef::VK_EXT_shader_object[when drawing using <>, or] when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_EXCLUSIVE_SCISSOR_NV set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. Otherwise, this state is specified by the slink:VkPipelineViewportExclusiveScissorStateCreateInfoNV::pname:pExclusiveScissors values used to create the currently active pipeline. .Valid Usage **** * [[VUID-vkCmdSetExclusiveScissorNV-None-02031]] The <> feature must: be enabled * [[VUID-vkCmdSetExclusiveScissorNV-firstExclusiveScissor-02034]] The sum of pname:firstExclusiveScissor and pname:exclusiveScissorCount must: be between `1` and sname:VkPhysicalDeviceLimits::pname:maxViewports, inclusive * [[VUID-vkCmdSetExclusiveScissorNV-firstExclusiveScissor-02035]] If the <> feature is not enabled, pname:firstExclusiveScissor must: be `0` * [[VUID-vkCmdSetExclusiveScissorNV-exclusiveScissorCount-02036]] If the <> feature is not enabled, pname:exclusiveScissorCount must: be `1` * [[VUID-vkCmdSetExclusiveScissorNV-x-02037]] The pname:x and pname:y members of pname:offset in each member of pname:pExclusiveScissors must: be greater than or equal to `0` * [[VUID-vkCmdSetExclusiveScissorNV-offset-02038]] Evaluation of [eq]#(pname:offset.x {plus} pname:extent.width)# for each member of pname:pExclusiveScissors must: not cause a signed integer addition overflow * [[VUID-vkCmdSetExclusiveScissorNV-offset-02039]] Evaluation of [eq]#(pname:offset.y {plus} pname:extent.height)# for each member of pname:pExclusiveScissors must: not cause a signed integer addition overflow **** include::{generated}/validity/protos/vkCmdSetExclusiveScissorNV.adoc[] -- [open,refpage='vkCmdSetExclusiveScissorEnableNV',desc='Dynamically enable each exclusive scissor for a command buffer',type='protos'] -- To <> whether an exclusive scissor is enabled or not, call: include::{generated}/api/protos/vkCmdSetExclusiveScissorEnableNV.adoc[] * pname:commandBuffer is the command buffer into which the command will be recorded. * pname:firstExclusiveScissor is the index of the first exclusive scissor rectangle whose state is updated by the command. * pname:exclusiveScissorCount is the number of exclusive scissor rectangles updated by the command. * pname:pExclusiveScissorEnables is a pointer to an array of basetype:VkBool32 values defining whether the exclusive scissor is enabled. The exclusive scissor enables taken from element [eq]#i# of pname:pExclusiveScissorEnables replace the current state for the scissor index [eq]#pname:firstExclusiveScissor {plus} i#, for [eq]#i# in [eq]#[0, pname:exclusiveScissorCount)#. This command sets the exclusive scissor enable for subsequent drawing commands ifdef::VK_EXT_shader_object[when drawing using <>, or] when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_EXCLUSIVE_SCISSOR_ENABLE_NV set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. Otherwise, this state is implied by the slink:VkPipelineViewportExclusiveScissorStateCreateInfoNV::pname:exclusiveScissorCount value used to create the currently active pipeline, where all pname:exclusiveScissorCount exclusive scissors are implicitly enabled and the remainder up to sname:VkPhysicalDeviceLimits::pname:maxViewports are implicitly disabled. .Valid Usage **** * [[VUID-vkCmdSetExclusiveScissorEnableNV-exclusiveScissor-07853]] The <> feature must: be enabled, and the implementation must: support at least pname:specVersion `2` of the `apiext:VK_NV_scissor_exclusive` extension **** include::{generated}/validity/protos/vkCmdSetExclusiveScissorEnableNV.adoc[] -- endif::VK_NV_scissor_exclusive[] [[fragops-samplemask]] == Sample Mask Test The sample mask test compares the <> for a fragment with the _sample mask_ defined by slink:VkPipelineMultisampleStateCreateInfo::pname:pSampleMask. ifdef::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] [open,refpage='vkCmdSetSampleMaskEXT',desc='Specify the sample mask dynamically for a command buffer',type='protos'] -- To <> the sample mask, call: include::{generated}/api/protos/vkCmdSetSampleMaskEXT.adoc[] * pname:commandBuffer is the command buffer into which the command will be recorded. * pname:samples specifies the number of sample bits in the pname:pSampleMask. * pname:pSampleMask is a pointer to an array of basetype:VkSampleMask values, where the array size is based on the pname:samples parameter. This command sets the sample mask for subsequent drawing commands ifdef::VK_EXT_shader_object[] ifdef::VK_EXT_extended_dynamic_state3[when drawing using <>, or] ifndef::VK_EXT_extended_dynamic_state3[when drawing using <>.] endif::VK_EXT_shader_object[] ifdef::VK_EXT_extended_dynamic_state3[] when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_SAMPLE_MASK_EXT set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. endif::VK_EXT_extended_dynamic_state3[] Otherwise, this state is specified by the slink:VkPipelineMultisampleStateCreateInfo::pname:pSampleMask value used to create the currently active pipeline. :refpage: vkCmdSetSampleMaskEXT :requiredfeature: extendedDynamicState3SampleMask .Valid Usage **** include::{chapters}/commonvalidity/dynamic_state3_feature_common.adoc[] **** include::{generated}/validity/protos/vkCmdSetSampleMaskEXT.adoc[] -- endif::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] Each bit of the coverage mask is associated with a sample index as described in the <>. If the bit in slink:VkPipelineMultisampleStateCreateInfo::pname:pSampleMask which is associated with that same sample index is set to `0`, the coverage mask bit is set to `0`. [[fragops-shader]] == Fragment Shading <> are invoked for each fragment, or as <>. Most operations in the fragment shader are not performed in <>, with exceptions called out in the following sections. For fragment shaders invoked by fragments, the following rules apply: * A fragment shader must: not be executed if a <> that executes before fragment shading discards the fragment. * A fragment shader may: not be executed if: ** An implementation determines that another fragment shader, invoked by a subsequent primitive in <>, overwrites all results computed by the shader (including writes to storage resources). ** Any other <> discards the fragment, and the shader does not write to any storage resources. * Otherwise, at least one fragment shader must: be executed. ** If <> is enabled and multiple invocations per fragment are required:, additional invocations must: be executed as specified. ifdef::VK_NV_shading_rate_image[] ** If a <> is used and multiple invocations per fragment are required:, additional invocations must: be executed as specified. endif::VK_NV_shading_rate_image[] ** Each covered sample must: be included in at least one fragment shader invocation. If no fragment shader is included in the pipeline, no fragment shader is executed, and undefined: values may: be written to all color attachment outputs during this fragment operation. [NOTE] .Note ==== Multiple fragment shader invocations may be executed for the same fragment for any number of implementation-dependent reasons. When there is more than one fragment shader invocation per fragment, the association of samples to invocations is implementation-dependent. Stores and atomics performed by these additional invocations have the normal effect. ifdef::VK_VERSION_1_1,VK_KHR_multiview[] For example, if the subpass includes multiple views in its view mask, a fragment shader may be invoked separately for each view. endif::VK_VERSION_1_1,VK_KHR_multiview[] ifdef::VK_EXT_fragment_density_map[] Similarly, if the render pass has a fragment density map attachment, more than one fragment shader invocation may be invoked for each covered sample. Such additional invocations are only produced if sname:VkPhysicalDeviceFragmentDensityMapPropertiesEXT::pname:fragmentDensityInvocations is ename:VK_TRUE. Implementations may generate these additional fragment shader invocations in order to make transitions between fragment areas with different fragment densities more smooth. endif::VK_EXT_fragment_density_map[] ==== [[fragops-shader-samplemask]] === Sample Mask Reading from the <> built-in in the code:Input storage class will return the coverage mask for the current fragment as calculated by fragment operations that executed prior to fragment shading. If <> is enabled, fragment shaders will only see values of `1` for samples being shaded - other bits will be `0`. Each bit of the coverage mask is associated with a sample index as described in the <>. If the bit in code:SampleMask which is associated with that same sample index is set to `0`, that coverage mask bit is set to `0`. Values written to the <> built-in in the code:Output storage class will be used by the <> operation, with the same encoding as the input built-in. ifdef::VK_EXT_shader_tile_image[] [[fragops-shader-tileimage-reads]] === Fragment Shader Tile Image Reads If the `apiext:VK_EXT_shader_tile_image` extension is enabled, implementations divide the framebuffer into a grid of tiles. A <> is a view of a framebuffer attachment tile for fragments with locations within the tile. Within a render pass instance initiated by flink:vkCmdBeginRenderingKHR, fragment shader invocations can: read the framebuffer color, depth, and stencil values at the fragment location via tile images. [NOTE] .Note ==== Even though fragment shader invocation can only read from the corresponding fragment location, the abstraction of a tile image is introduced for the following reasons: * Tile dimensions will be exposed in a future extension * Future functionality such as executing compute dispatches within render passes via tile shaders can leverage tile images. ==== Enabling <>, <>, <> enables fragment shader invocations to read from color, depth, and stencil, respectively. Color values are read from tile image variables with code:OpColorAttachmentReadEXT. Tile image variables are linked to specific color attachments using code:Location decoration. See <> for more details. Depth values are read with code:OpDepthAttachmentReadEXT. Stencil values are read with code:OpStencilAttachmentReadEXT. The sample to read is specified by a <> value specified as the code:Sample operand to code:OpColorAttachmentReadEXT, code:OpDepthAttachmentReadEXT, or code:OpStencilAttachmentReadEXT. If <> is disabled, a fragment invocation can: read from all sample locations associated with the fragment regardless of the fragment's coverage. This functionality is supported for slink:VkPipelineMultisampleStateCreateInfo::pname:rasterizationSamples > 1 when slink:VkPhysicalDeviceShaderTileImagePropertiesEXT::pname:shaderTileImageReadSampleFromPixelRateInvocation is ename:VK_TRUE. If <> is enabled, and pname:minSampleShading is 1.0, a fragment invocation must: only read from the <> sample. Tile image access must: not be used if the value of pname:minSampleShading is not 1.0. If the <> declares the code:EarlyFragmentTests execution mode, depth reads are allowed only if depth writes are disabled and stencil reads are allowed only if stencil writes are disabled. If slink:VkPhysicalDeviceShaderTileImagePropertiesEXT::pname:shaderTileImageReadFromHelperInvocation is ename:VK_FALSE, values read from helper invocations are undefined: otherwise the values read are subject to the coherency guarantees described below. code:OpDepthAttachmentReadEXT returns an undefined: value if no depth attachment is present. code:OpStencilAttachmentReadEXT returns an undefined: value if no stencil attachment is present. Tile image reads from color, depth and stencil attachments are said to be coherent when the accesses happen in raster order and without <> with respect to accesses to the attachments from framebuffer-space pipeline stages. The samples which qualify for coherent access and the enabling conditions are described below. * Let [eq]#Rc# be the set of components being read from an attachment [eq]#A# in a draw call * Let [eq]#Wc# be the set of components being written to [eq]#A# by the draw call The samples which qualify for coherent tile image reads from an attachment [eq]#A# are: * All samples in a pixel when [eq]#Rc# is disjoint with [eq]#Wc#. * The samples with coverage in a fragment when [eq]#Rc# is not disjoint with [eq]#Wc#. The samples with coverage are determined by the coverage mask for the fragment as calculated by fragment operations that executed prior to fragment shading, including early fragment tests if enabled for the draw call. A fragment shader can: declare code:NonCoherentColorAttachmentReadEXT, code:NonCoherentDepthAttachmentReadEXT, or code:NonCoherentStencilAttachmentReadEXT execution modes to enable non-coherent tile image reads which requires <> for the writes to an attachment to be made visible via tile image reads. When slink:VkPhysicalDeviceShaderTileImagePropertiesEXT::pname:shaderTileImageCoherentReadAccelerated is ename:VK_TRUE, the implementation prefers that coherent tile image reads are used, otherwise the implementation prefers that non-coherent tile image reads are used. [NOTE] .Note ==== In practice, the most common tile image reads usage patterns fall under one of the following: * Programmable blending - each fragment reads from a single sample (SampleID) at its location. Per-sample shading is typically enabled when multisampled rendertargets are used. * G-buffer generation and shading in one render pass - in the shading phase a fragment reads from a single sample at its location. * Programmable resolve - a fragment reads from all samples at its location (per-sample shading is disabled). This requires the use of a "full-screen triangle" instead of a rectangle composed of two triangles in order to avoid data races along the shared edge of the triangles. * 1:1 texturing with LOD - in use cases such a deferred screen space decals a fragment reads a single sample (SampleID) from depth buffer, but requires being able to read from helper threads to derive the texture LOD. This use case is supported as long as the attachment components being read are not overwritten by color, depth, or stencil attachment writes. All of the above use cases are supported by coherent tile image reads, but only the latter three are supported when non-coherent reads are used as there is no mechanism to synchronize non-coherent reads with writes within a draw call. ==== endif::VK_EXT_shader_tile_image[] [[fragops-shader-depthreplacement]] === Depth Replacement Writing to the <> built-in will replace the fragment's calculated depth values for each sample in the input code:SampleMask. <> performed after the fragment shader for this fragment will use this new value as [eq]#z~f~#. ifdef::VK_EXT_shader_stencil_export[] [[fragops-shader-stencilrefreplacement]] === Stencil Reference Replacement Writing to the <> built-in will replace the fragment's stencil reference value for each sample in the input code:SampleMask. <> performed after the fragment shader for this fragment will use this new value as [eq]#s~r~#. endif::VK_EXT_shader_stencil_export[] ifdef::VK_EXT_fragment_shader_interlock[] [[fragops-shader-interlock]] === Interlocked Operations code:OpBeginInvocationInterlockEXT and code:OpEndInvocationInterlockEXT define a section of a fragment shader which imposes additional ordering constraints on operations performed within them. These operations are defined as _interlocked operations_. How interlocked operations are ordered against other fragment shader invocations depends on the specified execution modes. ifdef::VK_NV_shading_rate_image,VK_KHR_fragment_shading_rate[] If the code:ShadingRateInterlockOrderedEXT execution mode is specified, any interlocked operations in a fragment shader must: happen before interlocked operations in fragment shader invocations that execute later in <> and cover at least one sample in the same fragment area, and must: happen after interlocked operations in a fragment shader that executes earlier in <> and cover at least one sample in the same fragment area. If the code:ShadingRateInterlockUnorderedEXT execution mode is specified, any interlocked operations in a fragment shader must: happen before or after interlocked operations in fragment shader invocations that execute earlier or later in <> and cover at least one sample in the same fragment area. endif::VK_NV_shading_rate_image,VK_KHR_fragment_shading_rate[] If the code:PixelInterlockOrderedEXT execution mode is specified, any interlocked operations in a fragment shader must: happen before interlocked operations in fragment shader invocations that execute later in <> and cover at least one sample in the same pixel, and must: happen after interlocked operations in a fragment shader that executes earlier in <> and cover at least one sample in the same pixel. If the code:PixelInterlockUnorderedEXT execution mode is specified, any interlocked operations in a fragment shader must: happen before or after interlocked operations in fragment shader invocations that execute earlier or later in <> and cover at least one sample in the same pixel. If the code:SampleInterlockOrderedEXT execution mode is specified, any interlocked operations in a fragment shader must: happen before interlocked operations in fragment shader invocations that execute later in <> and cover at least one of the same samples, and must: happen after interlocked operations in a fragment shader that executes earlier in <> and cover at least one of the same samples. If the code:SampleInterlockUnorderedEXT execution mode is specified, any interlocked operations in a fragment shader must: happen before or after interlocked operations in fragment shader invocations that execute earlier or later in <> and cover at least one of the same samples. endif::VK_EXT_fragment_shader_interlock[] [[fragops-covg]] == Multisample Coverage If a fragment shader is active and its entry point's interface includes a built-in output variable decorated with code:SampleMask, ifdef::VK_NV_sample_mask_override_coverage[] but not code:OverrideCoverageNV, endif::VK_NV_sample_mask_override_coverage[] the coverage mask is code:ANDed with the bits of the code:SampleMask built-in to generate a new coverage mask. ifdef::VK_NV_sample_mask_override_coverage[] If the code:SampleMask built-in is also decorated with code:OverrideCoverageNV, the coverage mask is replaced with the mask bits set in the shader. endif::VK_NV_sample_mask_override_coverage[] If <> is enabled, bits written to code:SampleMask corresponding to samples that are not being shaded by the fragment shader invocation are ignored. If no fragment shader is active, or if the active fragment shader does not include code:SampleMask in its interface, the coverage mask is not modified. Next, the fragment alpha value and coverage mask are modified based on the ifdef::VK_EXT_line_rasterization[] line coverage factor if the pname:lineRasterizationMode member of the slink:VkPipelineRasterizationStateCreateInfo structure is ename:VK_LINE_RASTERIZATION_MODE_RECTANGULAR_SMOOTH_EXT, and the endif::VK_EXT_line_rasterization[] pname:alphaToCoverageEnable and pname:alphaToOneEnable members of the slink:VkPipelineMultisampleStateCreateInfo structure. ifdef::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] [open,refpage='vkCmdSetAlphaToCoverageEnableEXT',desc='Specify the alpha to coverage enable state dynamically for a command buffer',type='protos'] -- To <> the pname:alphaToCoverageEnable state, call: include::{generated}/api/protos/vkCmdSetAlphaToCoverageEnableEXT.adoc[] * pname:commandBuffer is the command buffer into which the command will be recorded. * pname:alphaToCoverageEnable specifies the pname:alphaToCoverageEnable state. This command sets the pname:alphaToCoverageEnable state for subsequent drawing commands ifdef::VK_EXT_shader_object[] ifdef::VK_EXT_extended_dynamic_state3[when drawing using <>, or] ifndef::VK_EXT_extended_dynamic_state3[when drawing using <>.] endif::VK_EXT_shader_object[] ifdef::VK_EXT_extended_dynamic_state3[] when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_ALPHA_TO_COVERAGE_ENABLE_EXT set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. endif::VK_EXT_extended_dynamic_state3[] Otherwise, this state is specified by the slink:VkPipelineMultisampleStateCreateInfo::pname:alphaToCoverageEnable value used to create the currently active pipeline. :refpage: vkCmdSetAlphaToCoverageEnableEXT :requiredfeature: extendedDynamicState3AlphaToCoverageEnable .Valid Usage **** include::{chapters}/commonvalidity/dynamic_state3_feature_common.adoc[] **** include::{generated}/validity/protos/vkCmdSetAlphaToCoverageEnableEXT.adoc[] -- [open,refpage='vkCmdSetAlphaToOneEnableEXT',desc='Specify the alpha to one enable state dynamically for a command buffer',type='protos'] -- To <> the pname:alphaToOneEnable state, call: include::{generated}/api/protos/vkCmdSetAlphaToOneEnableEXT.adoc[] * pname:commandBuffer is the command buffer into which the command will be recorded. * pname:alphaToOneEnable specifies the pname:alphaToOneEnable state. This command sets the pname:alphaToOneEnable state for subsequent drawing commands ifdef::VK_EXT_shader_object[] ifdef::VK_EXT_extended_dynamic_state3[when drawing using <>, or] ifndef::VK_EXT_extended_dynamic_state3[when drawing using <>.] endif::VK_EXT_shader_object[] ifdef::VK_EXT_extended_dynamic_state3[] when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_ALPHA_TO_ONE_ENABLE_EXT set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. endif::VK_EXT_extended_dynamic_state3[] Otherwise, this state is specified by the slink:VkPipelineMultisampleStateCreateInfo::pname:alphaToOneEnable value used to create the currently active pipeline. :refpage: vkCmdSetAlphaToOneEnableEXT :requiredfeature: extendedDynamicState3AlphaToOneEnable .Valid Usage **** include::{chapters}/commonvalidity/dynamic_state3_feature_common.adoc[] * [[VUID-vkCmdSetAlphaToOneEnableEXT-alphaToOne-07607]] If the <> feature is not enabled, pname:alphaToOneEnable must: be ename:VK_FALSE **** include::{generated}/validity/protos/vkCmdSetAlphaToOneEnableEXT.adoc[] -- endif::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] All alpha values in this section refer only to the alpha component of the fragment shader output that has a code:Location and code:Index decoration of zero (see the <> section). If that shader output has an integer or unsigned integer type, then these operations are skipped. ifdef::VK_EXT_line_rasterization[] If the pname:lineRasterizationMode member of the slink:VkPipelineRasterizationStateCreateInfo structure is ename:VK_LINE_RASTERIZATION_MODE_RECTANGULAR_SMOOTH_EXT and the fragment came from a line segment, then the alpha value is replaced by multiplying it by the coverage factor for the fragment computed during <>. endif::VK_EXT_line_rasterization[] If pname:alphaToCoverageEnable is enabled, a temporary coverage mask is generated where each bit is determined by the fragment's alpha value, which is ANDed with the fragment coverage mask. No specific algorithm is specified for converting the alpha value to a temporary coverage mask. It is intended that the number of 1's in this value be proportional to the alpha value (clamped to [eq]#[0,1]#), with all 1's corresponding to a value of 1.0 and all 0's corresponding to 0.0. The algorithm may: be different at different framebuffer coordinates. [NOTE] .Note ==== Using different algorithms at different framebuffer coordinates may: help to avoid artifacts caused by regular coverage sample locations. ==== Finally, if pname:alphaToOneEnable is enabled, each alpha value is replaced by the maximum representable alpha value for fixed-point color attachments, or by 1.0 for floating-point attachments. Otherwise, the alpha values are not changed. [[fragops-ds-state]] == Depth and Stencil Operations Pipeline state controlling the <>, <>, and <> is specified through the members of the sname:VkPipelineDepthStencilStateCreateInfo structure. [open,refpage='VkPipelineDepthStencilStateCreateInfo',desc='Structure specifying parameters of a newly created pipeline depth stencil state',type='structs'] -- The sname:VkPipelineDepthStencilStateCreateInfo structure is defined as: include::{generated}/api/structs/VkPipelineDepthStencilStateCreateInfo.adoc[] * pname:sType is a elink:VkStructureType value identifying this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. ifndef::VK_EXT_rasterization_order_attachment_access,VK_ARM_rasterization_order_attachment_access[] * pname:flags is reserved for future use. endif::VK_EXT_rasterization_order_attachment_access,VK_ARM_rasterization_order_attachment_access[] ifdef::VK_EXT_rasterization_order_attachment_access,VK_ARM_rasterization_order_attachment_access[] * pname:flags is a bitmask of elink:VkPipelineDepthStencilStateCreateFlagBits specifying additional depth/stencil state information. endif::VK_EXT_rasterization_order_attachment_access,VK_ARM_rasterization_order_attachment_access[] * pname:depthTestEnable controls whether <> is enabled. * pname:depthWriteEnable controls whether <> are enabled when pname:depthTestEnable is ename:VK_TRUE. Depth writes are always disabled when pname:depthTestEnable is ename:VK_FALSE. * pname:depthCompareOp is a elink:VkCompareOp value specifying the comparison operator to use in the <> step of the <>. * pname:depthBoundsTestEnable controls whether <> is enabled. * pname:stencilTestEnable controls whether <> is enabled. * pname:front and pname:back are slink:VkStencilOpState values controlling the corresponding parameters of the <>. * pname:minDepthBounds is the minimum depth bound used in the <>. * pname:maxDepthBounds is the maximum depth bound used in the <>. .Valid Usage **** * [[VUID-VkPipelineDepthStencilStateCreateInfo-depthBoundsTestEnable-00598]] If the <> feature is not enabled, pname:depthBoundsTestEnable must: be ename:VK_FALSE ifdef::VK_KHR_portability_subset[] * [[VUID-VkPipelineDepthStencilStateCreateInfo-separateStencilMaskRef-04453]] If the `apiext:VK_KHR_portability_subset` extension is enabled, and slink:VkPhysicalDevicePortabilitySubsetFeaturesKHR::pname:separateStencilMaskRef is ename:VK_FALSE, and the value of slink:VkPipelineDepthStencilStateCreateInfo::pname:stencilTestEnable is ename:VK_TRUE, and the value of slink:VkPipelineRasterizationStateCreateInfo::pname:cullMode is ename:VK_CULL_MODE_NONE, the value of pname:reference in each of the slink:VkStencilOpState structs in pname:front and pname:back must: be the same endif::VK_KHR_portability_subset[] ifdef::VK_EXT_rasterization_order_attachment_access,VK_ARM_rasterization_order_attachment_access[] * [[VUID-VkPipelineDepthStencilStateCreateInfo-rasterizationOrderDepthAttachmentAccess-06463]] If the <> feature is not enabled, pname:flags must: not include ename:VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_DEPTH_ACCESS_BIT_EXT * [[VUID-VkPipelineDepthStencilStateCreateInfo-rasterizationOrderStencilAttachmentAccess-06464]] If the <> feature is not enabled, pname:flags must: not include ename:VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_STENCIL_ACCESS_BIT_EXT endif::VK_EXT_rasterization_order_attachment_access,VK_ARM_rasterization_order_attachment_access[] **** include::{generated}/validity/structs/VkPipelineDepthStencilStateCreateInfo.adoc[] -- [open,refpage='VkPipelineDepthStencilStateCreateFlags',desc='Bitmask of VkPipelineDepthStencilStateCreateFlagBits',type='flags'] -- include::{generated}/api/flags/VkPipelineDepthStencilStateCreateFlags.adoc[] ifndef::VK_EXT_rasterization_order_attachment_access,VK_ARM_rasterization_order_attachment_access[] tname:VkPipelineDepthStencilStateCreateFlags is a bitmask type for setting a mask, but is currently reserved for future use. endif::VK_EXT_rasterization_order_attachment_access,VK_ARM_rasterization_order_attachment_access[] ifdef::VK_EXT_rasterization_order_attachment_access,VK_ARM_rasterization_order_attachment_access[] tname:VkPipelineDepthStencilStateCreateFlags is a bitmask type for setting a mask of zero or more elink:VkPipelineDepthStencilStateCreateFlagBits. endif::VK_EXT_rasterization_order_attachment_access,VK_ARM_rasterization_order_attachment_access[] -- ifdef::VK_EXT_rasterization_order_attachment_access,VK_ARM_rasterization_order_attachment_access[] [open,refpage='VkPipelineDepthStencilStateCreateFlagBits',desc='Bitmask specifying additional depth/stencil state information.',type='enums'] -- Bits which can: be set in the slink:VkPipelineDepthStencilStateCreateInfo::pname:flags parameter are: include::{generated}/api/enums/VkPipelineDepthStencilStateCreateFlagBits.adoc[] * ename:VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_DEPTH_ACCESS_BIT_EXT indicates that access to the depth aspects of depth/stencil and input attachments will have implicit framebuffer-local memory dependencies. * ename:VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_STENCIL_ACCESS_BIT_EXT indicates that access to the stencil aspects of depth/stencil and input attachments will have implicit framebuffer-local memory dependencies. When ename:VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_DEPTH_ACCESS_BIT_EXT is included in a pipeline, it forms a framebuffer-local memory dependency for each fragment generated by draw commands for that pipeline with the following scopes: * The first <> includes ename:VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT and ename:VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT pipeline stages executed by all previous fragments (as defined by <>) in the corresponding <> including those generated by the same draw command. * The second <> includes ename:VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT stage executed by the generated fragment. * The first <> includes all writes to the depth aspect of depth/stencil attachments. * The second <> includes all reads from the depth aspect of input attachments. When ename:VK_PIPELINE_DEPTH_STENCIL_STATE_CREATE_RASTERIZATION_ORDER_ATTACHMENT_STENCIL_ACCESS_BIT_EXT is included in a pipeline, it forms a framebuffer-local memory dependency for each fragment generated by draw commands for that pipeline with the following scopes: * The first <> includes ename:VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT ename:VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT pipeline stages executed by all previous fragments (as defined by <>) in the corresponding <> including those generated by the same draw command. * The second <> includes ename:VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT and ename:VK_PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT pipeline stages executed by the generated fragment. * The first <> includes all writes to the stencil aspect of depth/stencil attachments. * The second <> includes all reads from the stencil aspect of input attachments. -- endif::VK_EXT_rasterization_order_attachment_access,VK_ARM_rasterization_order_attachment_access[] [[fragops-dbt]] == Depth Bounds Test The depth bounds test compares the depth value [eq]#z~a~# in the depth/stencil attachment at each sample's framebuffer coordinates [eq]#(x~f~,y~f~)# and <> [eq]#i# against a set of _depth bounds_. The depth bounds are determined by two floating point values defining a minimum (pname:minDepthBounds) and maximum (pname:maxDepthBounds) depth value. These values are either set by the slink:VkPipelineDepthStencilStateCreateInfo structure during pipeline creation, or dynamically by ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] flink:vkCmdSetDepthBoundsTestEnable and endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] flink:vkCmdSetDepthBounds. A given sample is considered within the depth bounds if [eq]#z~a~# is in the range [eq]#[pname:minDepthBounds,pname:maxDepthBounds]#. Samples with depth attachment values outside of the depth bounds will have their coverage set to `0`. If the depth bounds test is disabled, or if there is no depth attachment, the coverage mask is unmodified by this operation. ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] [open,refpage='vkCmdSetDepthBoundsTestEnable',desc='Set depth bounds test enable dynamically for a command buffer',type='protos',alias='vkCmdSetDepthBoundsTestEnableEXT'] -- To <> the depth bounds test, call: ifdef::VK_VERSION_1_3[] include::{generated}/api/protos/vkCmdSetDepthBoundsTestEnable.adoc[] ifdef::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[or the equivalent command] endif::VK_VERSION_1_3[] ifdef::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] include::{generated}/api/protos/vkCmdSetDepthBoundsTestEnableEXT.adoc[] endif::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] * pname:commandBuffer is the command buffer into which the command will be recorded. * pname:depthBoundsTestEnable specifies if the depth bounds test is enabled. This command sets the depth bounds enable for subsequent drawing commands ifdef::VK_EXT_shader_object[] ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[when drawing using <>, or] ifndef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[when drawing using <>.] endif::VK_EXT_shader_object[] ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_DEPTH_BOUNDS_TEST_ENABLE set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] Otherwise, this state is specified by the slink:VkPipelineDepthStencilStateCreateInfo::pname:depthBoundsTestEnable value used to create the currently active pipeline. :refpage: vkCmdSetDepthBoundsTestEnable .Valid Usage **** include::{chapters}/commonvalidity/dynamic_state_feature_common.adoc[] **** include::{generated}/validity/protos/vkCmdSetDepthBoundsTestEnable.adoc[] -- endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] [open,refpage='vkCmdSetDepthBounds',desc='Set depth bounds range dynamically for a command buffer',type='protos'] -- To <> the depth bounds range, call: include::{generated}/api/protos/vkCmdSetDepthBounds.adoc[] * pname:commandBuffer is the command buffer into which the command will be recorded. * pname:minDepthBounds is the minimum depth bound. * pname:maxDepthBounds is the maximum depth bound. This command sets the depth bounds range for subsequent drawing commands ifdef::VK_EXT_shader_object[when drawing using <>, or] when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_DEPTH_BOUNDS set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. Otherwise, this state is specified by the slink:VkPipelineDepthStencilStateCreateInfo::pname:minDepthBounds and slink:VkPipelineDepthStencilStateCreateInfo::pname:maxDepthBounds values used to create the currently active pipeline. .Valid Usage **** * [[VUID-vkCmdSetDepthBounds-minDepthBounds-00600]] ifdef::VK_EXT_depth_range_unrestricted[] If the `apiext:VK_EXT_depth_range_unrestricted` extension is not enabled endif::VK_EXT_depth_range_unrestricted[] pname:minDepthBounds must: be between `0.0` and `1.0`, inclusive * [[VUID-vkCmdSetDepthBounds-maxDepthBounds-00601]] ifdef::VK_EXT_depth_range_unrestricted[] If the `apiext:VK_EXT_depth_range_unrestricted` extension is not enabled endif::VK_EXT_depth_range_unrestricted[] pname:maxDepthBounds must: be between `0.0` and `1.0`, inclusive **** include::{generated}/validity/protos/vkCmdSetDepthBounds.adoc[] -- [[fragops-stencil]] == Stencil Test The stencil test compares the stencil attachment value [eq]#s~a~# in the depth/stencil attachment at each sample's framebuffer coordinates [eq]#(x~f~,y~f~)# and <> [eq]#i# against a _stencil reference value_. ifdef::VK_EXT_fragment_density_map[] If the render pass has a fragment density map attachment and the fragment covers multiple pixels, there is an implementation-dependent association of coverage samples to stencil attachment samples within the fragment. However, if all samples in the fragment are covered, and the stencil attachment value is updated as a result of this test, all stencil attachment samples will be updated. endif::VK_EXT_fragment_density_map[] If the stencil test is not enabled, as specified by ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] flink:vkCmdSetStencilTestEnable or endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] slink:VkPipelineDepthStencilStateCreateInfo::pname:stencilTestEnable, or if there is no stencil attachment, the coverage mask is unmodified by this operation. The stencil test is controlled by one of two sets of stencil-related state, the front stencil state and the back stencil state. Stencil tests and writes use the back stencil state when processing fragments generated by <> <>, and the front stencil state when processing fragments generated by <> or any other primitives. The comparison operation performed is determined by the elink:VkCompareOp value set by ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] flink:vkCmdSetStencilOp::pname:compareOp, or by endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] slink:VkStencilOpState::pname:compareOp during pipeline creation. The compare mask [eq]#s~c~# and stencil reference value [eq]#s~r~# of the front or the back stencil state set determine arguments of the comparison operation. [eq]#s~c~# is set by the slink:VkPipelineDepthStencilStateCreateInfo structure during pipeline creation, or by the flink:vkCmdSetStencilCompareMask command. [eq]#s~r~# is set by slink:VkPipelineDepthStencilStateCreateInfo or by flink:vkCmdSetStencilReference. [eq]#s~r~# and [eq]#s~a~# are each independently combined with [eq]#s~c~# using a bitwise code:AND operation to create masked reference and attachment values [eq]#s'~r~# and [eq]#s'~a~#. [eq]#s'~r~# and [eq]#s'~a~# are used as the _reference_ and _test_ values, respectively, in the operation specified by the elink:VkCompareOp. If the comparison evaluates to false, the coverage for the sample is set to `0`. A new stencil value [eq]#s~g~# is generated according to a stencil operation defined by elink:VkStencilOp parameters set by ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] flink:vkCmdSetStencilOp or endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] slink:VkPipelineDepthStencilStateCreateInfo. If the stencil test fails, pname:failOp defines the stencil operation used. If the stencil test passes however, the stencil op used is based on the <> - if it passes, slink:VkPipelineDepthStencilStateCreateInfo::pname:passOp is used, otherwise slink:VkPipelineDepthStencilStateCreateInfo::pname:depthFailOp is used. The stencil attachment value [eq]#s~a~# is then updated with the generated stencil value [eq]#s~g~# according to the write mask [eq]#s~w~# defined by pname:writeMask in slink:VkPipelineDepthStencilStateCreateInfo::pname:front and slink:VkPipelineDepthStencilStateCreateInfo::pname:back as: {empty}:: [eq]#s~a~ = (s~a~ & ¬s~w~) | (s~g~ & s~w~)# ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] [open,refpage='vkCmdSetStencilTestEnable',desc='Set stencil test enable dynamically for a command buffer',type='protos',alias='vkCmdSetStencilTestEnableEXT'] -- To <> the stencil test, call: ifdef::VK_VERSION_1_3[] include::{generated}/api/protos/vkCmdSetStencilTestEnable.adoc[] ifdef::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[or the equivalent command] endif::VK_VERSION_1_3[] ifdef::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] include::{generated}/api/protos/vkCmdSetStencilTestEnableEXT.adoc[] endif::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] * pname:commandBuffer is the command buffer into which the command will be recorded. * pname:stencilTestEnable specifies if the stencil test is enabled. This command sets the stencil test enable for subsequent drawing commands ifdef::VK_EXT_shader_object[] ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[when drawing using <>, or] ifndef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[when drawing using <>.] endif::VK_EXT_shader_object[] ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_STENCIL_TEST_ENABLE set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] Otherwise, this state is specified by the slink:VkPipelineDepthStencilStateCreateInfo::pname:stencilTestEnable value used to create the currently active pipeline. :refpage: vkCmdSetStencilTestEnable .Valid Usage **** include::{chapters}/commonvalidity/dynamic_state_feature_common.adoc[] **** include::{generated}/validity/protos/vkCmdSetStencilTestEnable.adoc[] -- [open,refpage='vkCmdSetStencilOp',desc='Set stencil operation dynamically for a command buffer',type='protos',alias='vkCmdSetStencilOpEXT'] -- To <> the stencil operation, call: ifdef::VK_VERSION_1_3[] include::{generated}/api/protos/vkCmdSetStencilOp.adoc[] ifdef::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[or the equivalent command] endif::VK_VERSION_1_3[] ifdef::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] include::{generated}/api/protos/vkCmdSetStencilOpEXT.adoc[] endif::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] * pname:commandBuffer is the command buffer into which the command will be recorded. * pname:faceMask is a bitmask of elink:VkStencilFaceFlagBits specifying the set of stencil state for which to update the stencil operation. * pname:failOp is a elink:VkStencilOp value specifying the action performed on samples that fail the stencil test. * pname:passOp is a elink:VkStencilOp value specifying the action performed on samples that pass both the depth and stencil tests. * pname:depthFailOp is a elink:VkStencilOp value specifying the action performed on samples that pass the stencil test and fail the depth test. * pname:compareOp is a elink:VkCompareOp value specifying the comparison operator used in the stencil test. This command sets the stencil operation for subsequent drawing commands when ifdef::VK_EXT_shader_object[] ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[when drawing using <>, or] ifndef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[when drawing using <>.] endif::VK_EXT_shader_object[] ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_STENCIL_OP set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] Otherwise, this state is specified by the corresponding sname:VkPipelineDepthStencilStateCreateInfo::pname:failOp, pname:passOp, pname:depthFailOp, and pname:compareOp values used to create the currently active pipeline, for both front and back faces. :refpage: vkCmdSetStencilOp .Valid Usage **** include::{chapters}/commonvalidity/dynamic_state_feature_common.adoc[] **** include::{generated}/validity/protos/vkCmdSetStencilOp.adoc[] -- endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] [open,refpage='VkStencilOpState',desc='Structure specifying stencil operation state',type='structs'] -- The sname:VkStencilOpState structure is defined as: include::{generated}/api/structs/VkStencilOpState.adoc[] * pname:failOp is a elink:VkStencilOp value specifying the action performed on samples that fail the stencil test. * pname:passOp is a elink:VkStencilOp value specifying the action performed on samples that pass both the depth and stencil tests. * pname:depthFailOp is a elink:VkStencilOp value specifying the action performed on samples that pass the stencil test and fail the depth test. * pname:compareOp is a elink:VkCompareOp value specifying the comparison operator used in the stencil test. * pname:compareMask selects the bits of the unsigned integer stencil values participating in the stencil test. * pname:writeMask selects the bits of the unsigned integer stencil values updated by the stencil test in the stencil framebuffer attachment. * pname:reference is an integer stencil reference value that is used in the unsigned stencil comparison. include::{generated}/validity/structs/VkStencilOpState.adoc[] -- [open,refpage='vkCmdSetStencilCompareMask',desc='Set stencil compare mask dynamically for a command buffer',type='protos'] -- To <> the stencil compare mask, call: include::{generated}/api/protos/vkCmdSetStencilCompareMask.adoc[] * pname:commandBuffer is the command buffer into which the command will be recorded. * pname:faceMask is a bitmask of elink:VkStencilFaceFlagBits specifying the set of stencil state for which to update the compare mask. * pname:compareMask is the new value to use as the stencil compare mask. This command sets the stencil compare mask for subsequent drawing commands ifdef::VK_EXT_shader_object[when drawing using <>, or] when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_STENCIL_COMPARE_MASK set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. Otherwise, this state is specified by the slink:VkStencilOpState::pname:compareMask value used to create the currently active pipeline, for both front and back faces. include::{generated}/validity/protos/vkCmdSetStencilCompareMask.adoc[] -- [open,refpage='VkStencilFaceFlagBits',desc='Bitmask specifying sets of stencil state for which to update the compare mask',type='enums'] -- ename:VkStencilFaceFlagBits values are: include::{generated}/api/enums/VkStencilFaceFlagBits.adoc[] * ename:VK_STENCIL_FACE_FRONT_BIT specifies that only the front set of stencil state is updated. * ename:VK_STENCIL_FACE_BACK_BIT specifies that only the back set of stencil state is updated. * ename:VK_STENCIL_FACE_FRONT_AND_BACK is the combination of ename:VK_STENCIL_FACE_FRONT_BIT and ename:VK_STENCIL_FACE_BACK_BIT, and specifies that both sets of stencil state are updated. ifdef::VKSC_VERSION_1_0[] ifdef::hidden[] // tag::scremoved[] * elink:VkStencilFaceFlagBits (deprecated alias) ** etext:VK_STENCIL_FRONT_AND_BACK <> // end::scremoved[] endif::hidden[] endif::VKSC_VERSION_1_0[] -- [open,refpage='VkStencilFaceFlags',desc='Bitmask of VkStencilFaceFlagBits',type='flags'] -- include::{generated}/api/flags/VkStencilFaceFlags.adoc[] tname:VkStencilFaceFlags is a bitmask type for setting a mask of zero or more elink:VkStencilFaceFlagBits. -- [open,refpage='vkCmdSetStencilWriteMask',desc='Set stencil write mask dynamically for a command buffer',type='protos'] -- To <> the stencil write mask, call: include::{generated}/api/protos/vkCmdSetStencilWriteMask.adoc[] * pname:commandBuffer is the command buffer into which the command will be recorded. * pname:faceMask is a bitmask of elink:VkStencilFaceFlagBits specifying the set of stencil state for which to update the write mask, as described above for flink:vkCmdSetStencilCompareMask. * pname:writeMask is the new value to use as the stencil write mask. This command sets the stencil write mask for subsequent drawing commands ifdef::VK_EXT_shader_object[when drawing using <>, or] when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_STENCIL_WRITE_MASK set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. Otherwise, this state is specified by the pname:writeMask value used to create the currently active pipeline, for both slink:VkPipelineDepthStencilStateCreateInfo::pname:front and slink:VkPipelineDepthStencilStateCreateInfo::pname:back faces. include::{generated}/validity/protos/vkCmdSetStencilWriteMask.adoc[] -- [open,refpage='vkCmdSetStencilReference',desc='Set stencil reference value dynamically for a command buffer',type='protos'] -- To <> the stencil reference value, call: include::{generated}/api/protos/vkCmdSetStencilReference.adoc[] * pname:commandBuffer is the command buffer into which the command will be recorded. * pname:faceMask is a bitmask of elink:VkStencilFaceFlagBits specifying the set of stencil state for which to update the reference value, as described above for flink:vkCmdSetStencilCompareMask. * pname:reference is the new value to use as the stencil reference value. This command sets the stencil reference value for subsequent drawing commands ifdef::VK_EXT_shader_object[when drawing using <>, or] when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_STENCIL_REFERENCE set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. Otherwise, this state is specified by the slink:VkPipelineDepthStencilStateCreateInfo::pname:reference value used to create the currently active pipeline, for both front and back faces. include::{generated}/validity/protos/vkCmdSetStencilReference.adoc[] -- [open,refpage='VkStencilOp',desc='Stencil comparison function',type='enums'] -- Possible values of the pname:failOp, pname:passOp, and pname:depthFailOp members of slink:VkStencilOpState, specifying what happens to the stored stencil value if this or certain subsequent tests fail or pass, are: include::{generated}/api/enums/VkStencilOp.adoc[] * ename:VK_STENCIL_OP_KEEP keeps the current value. * ename:VK_STENCIL_OP_ZERO sets the value to 0. * ename:VK_STENCIL_OP_REPLACE sets the value to pname:reference. * ename:VK_STENCIL_OP_INCREMENT_AND_CLAMP increments the current value and clamps to the maximum representable unsigned value. * ename:VK_STENCIL_OP_DECREMENT_AND_CLAMP decrements the current value and clamps to 0. * ename:VK_STENCIL_OP_INVERT bitwise-inverts the current value. * ename:VK_STENCIL_OP_INCREMENT_AND_WRAP increments the current value and wraps to 0 when the maximum value would have been exceeded. * ename:VK_STENCIL_OP_DECREMENT_AND_WRAP decrements the current value and wraps to the maximum possible value when the value would go below 0. For purposes of increment and decrement, the stencil bits are considered as an unsigned integer. -- [[fragops-depth]] == Depth Test The depth test compares the depth value [eq]#z~a~# in the depth/stencil attachment at each sample's framebuffer coordinates [eq]#(x~f~,y~f~)# and <> [eq]#i# against the sample's depth value [eq]#z~f~#. If there is no depth attachment then the depth test is skipped. ifdef::VK_EXT_fragment_density_map[] If the render pass has a fragment density map attachment and the fragment covers multiple pixels, there is an implementation-dependent association of rasterization samples to depth attachment samples within the fragment. However, if all samples in the fragment are covered, and the depth attachment value is updated as a result of this test, all depth attachment samples will be updated. endif::VK_EXT_fragment_density_map[] The depth test occurs in three stages, as detailed in the following sections. === Depth Clamping and Range Adjustment If slink:VkPipelineRasterizationStateCreateInfo::pname:depthClampEnable is enabled, [eq]#z~f~# is clamped to [eq]#[z~min~, z~max~]#, where [eq]#z~min~ = min(n,f)#, [eq]#z~max~ = max(n,f)]#, and [eq]#n# and [eq]#f# are the pname:minDepth and pname:maxDepth depth range values of the viewport used by this fragment, respectively. ifdef::VK_EXT_depth_clamp_zero_one[] If slink:VkPhysicalDeviceDepthClampZeroOneFeaturesEXT::pname:depthClampZeroOne is enabled: ifdef::VK_EXT_depth_range_unrestricted[] * If the depth attachment has a floating-point format and apiext:VK_EXT_depth_range_unrestricted is enabled then [eq]#z~f~# is unchanged. * Otherwise, [eq]#z~f~# is clamped to the range [eq]#[0, 1]#. endif::VK_EXT_depth_range_unrestricted[] ifndef::VK_EXT_depth_range_unrestricted[] * [eq]#z~f~# is clamped to the range [eq]#[0, 1]#. endif::VK_EXT_depth_range_unrestricted[] Otherwise: endif::VK_EXT_depth_clamp_zero_one[] ifndef::VK_EXT_depth_clamp_zero_one[] Following depth clamping: endif::VK_EXT_depth_clamp_zero_one[] * If [eq]#z~f~# is not in the range [eq]#[z~min~, z~max~]#, then [eq]#z~f~# is undefined: following this step. ifdef::VK_EXT_depth_range_unrestricted[] * If the depth attachment has a fixed-point format and [eq]#z~f~# is not in the range [eq]#[0, 1]#, then [eq]#z~f~# is undefined: following this step. endif::VK_EXT_depth_range_unrestricted[] [[fragops-depth-comparison]] === Depth Comparison If the depth test is not enabled, as specified by ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] flink:vkCmdSetDepthTestEnable or endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] slink:VkPipelineDepthStencilStateCreateInfo::pname:depthTestEnable, then this step is skipped. The comparison operation performed is determined by the elink:VkCompareOp value set by ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] flink:vkCmdSetDepthCompareOp, or by endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] slink:VkPipelineDepthStencilStateCreateInfo::pname:depthCompareOp during pipeline creation. [eq]#z~f~# and [eq]#z~a~# are used as the _reference_ and _test_ values, respectively, in the operation specified by the elink:VkCompareOp. If the comparison evaluates to false, the coverage for the sample is set to `0`. [[fragops-depth-write]] === Depth Attachment Writes If depth writes are enabled, as specified by ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] flink:vkCmdSetDepthWriteEnable or endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] slink:VkPipelineDepthStencilStateCreateInfo::pname:depthWriteEnable, and the comparison evaluated to true, the depth attachment value [eq]#z~a~# is set to the sample's depth value [eq]#z~f~#. If there is no depth attachment, no value is written. ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] [open,refpage='vkCmdSetDepthTestEnable',desc='Set depth test enable dynamically for a command buffer',type='protos',alias='vkCmdSetDepthTestEnableEXT'] -- To <> the depth test, call: ifdef::VK_VERSION_1_3[] include::{generated}/api/protos/vkCmdSetDepthTestEnable.adoc[] ifdef::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[or the equivalent command] endif::VK_VERSION_1_3[] ifdef::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] include::{generated}/api/protos/vkCmdSetDepthTestEnableEXT.adoc[] endif::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] * pname:commandBuffer is the command buffer into which the command will be recorded. * pname:depthTestEnable specifies if the depth test is enabled. This command sets the depth test enable for subsequent drawing commands ifdef::VK_EXT_shader_object[] ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[when drawing using <>, or] ifndef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[when drawing using <>.] endif::VK_EXT_shader_object[] ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_DEPTH_TEST_ENABLE set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] Otherwise, this state is specified by the slink:VkPipelineDepthStencilStateCreateInfo::pname:depthTestEnable value used to create the currently active pipeline. :refpage: vkCmdSetDepthTestEnable .Valid Usage **** include::{chapters}/commonvalidity/dynamic_state_feature_common.adoc[] **** include::{generated}/validity/protos/vkCmdSetDepthTestEnable.adoc[] -- [open,refpage='vkCmdSetDepthCompareOp',desc='Set depth comparison operator dynamically for a command buffer',type='protos',alias='vkCmdSetDepthCompareOpEXT'] -- To <> the depth compare operator, call: ifdef::VK_VERSION_1_3[] include::{generated}/api/protos/vkCmdSetDepthCompareOp.adoc[] ifdef::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[or the equivalent command] endif::VK_VERSION_1_3[] ifdef::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] include::{generated}/api/protos/vkCmdSetDepthCompareOpEXT.adoc[] endif::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] * pname:commandBuffer is the command buffer into which the command will be recorded. * pname:depthCompareOp is a elink:VkCompareOp value specifying the comparison operator used for the <> step of the <>. This command sets the depth comparison operator for subsequent drawing commands ifdef::VK_EXT_shader_object[] ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[when drawing using <>, or] ifndef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[when drawing using <>.] endif::VK_EXT_shader_object[] ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_DEPTH_COMPARE_OP set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] Otherwise, this state is specified by the slink:VkPipelineDepthStencilStateCreateInfo::pname:depthCompareOp value used to create the currently active pipeline. :refpage: vkCmdSetDepthCompareOp .Valid Usage **** include::{chapters}/commonvalidity/dynamic_state_feature_common.adoc[] **** include::{generated}/validity/protos/vkCmdSetDepthCompareOp.adoc[] -- [open,refpage='vkCmdSetDepthWriteEnable',desc='Set depth write enable dynamically for a command buffer',type='protos',alias='vkCmdSetDepthWriteEnableEXT'] -- To <> the depth write enable, call: ifdef::VK_VERSION_1_3[] include::{generated}/api/protos/vkCmdSetDepthWriteEnable.adoc[] ifdef::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[or the equivalent command] endif::VK_VERSION_1_3[] ifdef::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] include::{generated}/api/protos/vkCmdSetDepthWriteEnableEXT.adoc[] endif::VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] * pname:commandBuffer is the command buffer into which the command will be recorded. * pname:depthWriteEnable specifies if depth writes are enabled. This command sets the depth write enable for subsequent drawing commands ifdef::VK_EXT_shader_object[] ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[when drawing using <>, or] ifndef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[when drawing using <>.] endif::VK_EXT_shader_object[] ifdef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_DEPTH_WRITE_ENABLE set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[] Otherwise, this state is specified by the slink:VkPipelineDepthStencilStateCreateInfo::pname:depthWriteEnable value used to create the currently active pipeline. :refpage: vkCmdSetDepthWriteEnable .Valid Usage **** include::{chapters}/commonvalidity/dynamic_state_feature_common.adoc[] **** include::{generated}/validity/protos/vkCmdSetDepthWriteEnable.adoc[] -- endif::VK_VERSION_1_3,VK_EXT_extended_dynamic_state,VK_EXT_shader_object[] ifdef::VK_NV_representative_fragment_test[] [[fragops-rep-frag-test]] == Representative Fragment Test The representative fragment test allows implementations to reduce the amount of rasterization and fragment processing work performed for each point, line, or triangle primitive. For any primitive that produces one or more fragments that pass all prior early fragment tests, the implementation may: choose one or more "`representative`" fragments for processing and discard all other fragments. For draw calls rendering multiple points, lines, or triangles arranged in lists, strips, or fans, the representative fragment test is performed independently for each of those primitives. The set of fragments discarded by the representative fragment test is implementation-dependent. In some cases, the representative fragment test may not discard any fragments for a given primitive. [open,refpage='VkPipelineRepresentativeFragmentTestStateCreateInfoNV',desc='Structure specifying representative fragment test',type='structs'] -- If the pname:pNext chain of slink:VkGraphicsPipelineCreateInfo includes a sname:VkPipelineRepresentativeFragmentTestStateCreateInfoNV structure, then that structure includes parameters controlling the representative fragment test. The sname:VkPipelineRepresentativeFragmentTestStateCreateInfoNV structure is defined as: include::{generated}/api/structs/VkPipelineRepresentativeFragmentTestStateCreateInfoNV.adoc[] * pname:sType is a elink:VkStructureType value identifying this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. * pname:representativeFragmentTestEnable controls whether the representative fragment test is enabled. If this structure is not included in the pname:pNext chain, pname:representativeFragmentTestEnable is considered to be ename:VK_FALSE, and the representative fragment test is disabled. If the active fragment shader does not specify the code:EarlyFragmentTests execution mode, the representative fragment shader test has no effect, even if enabled. include::{generated}/validity/structs/VkPipelineRepresentativeFragmentTestStateCreateInfoNV.adoc[] -- ifdef::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] [open,refpage='vkCmdSetRepresentativeFragmentTestEnableNV',desc='Specify the representative fragment test enable dynamically for a command buffer',type='protos'] -- To <> the pname:representativeFragmentTestEnable state, call: include::{generated}/api/protos/vkCmdSetRepresentativeFragmentTestEnableNV.adoc[] * pname:commandBuffer is the command buffer into which the command will be recorded. * pname:representativeFragmentTestEnable specifies the pname:representativeFragmentTestEnable state. This command sets the pname:representativeFragmentTestEnable state for subsequent drawing commands ifdef::VK_EXT_shader_object[] ifdef::VK_EXT_extended_dynamic_state3[when drawing using <>, or] ifndef::VK_EXT_extended_dynamic_state3[when drawing using <>.] endif::VK_EXT_shader_object[] ifdef::VK_EXT_extended_dynamic_state3[] when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_REPRESENTATIVE_FRAGMENT_TEST_ENABLE_NV set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. endif::VK_EXT_extended_dynamic_state3[] Otherwise, this state is specified by the slink:VkPipelineRepresentativeFragmentTestStateCreateInfoNV::pname:representativeFragmentTestEnable value used to create the currently active pipeline. :refpage: vkCmdSetRepresentativeFragmentTestEnableNV :requiredfeature: extendedDynamicState3RepresentativeFragmentTestEnable .Valid Usage **** include::{chapters}/commonvalidity/dynamic_state3_feature_common.adoc[] **** include::{generated}/validity/protos/vkCmdSetRepresentativeFragmentTestEnableNV.adoc[] -- endif::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] endif::VK_NV_representative_fragment_test[] [[fragops-samplecount]] == Sample Counting Occlusion queries use query pool entries to track the number of samples that pass all the per-fragment tests. The mechanism of collecting an occlusion query value is described in <>. The occlusion query sample counter increments by one for each sample with a coverage value of 1 in each fragment that survives all the per-fragment tests, including scissor, ifdef::VK_NV_scissor_exclusive[] exclusive scissor, endif::VK_NV_scissor_exclusive[] sample mask, alpha to coverage, stencil, and depth tests. ifdef::VK_NV_fragment_coverage_to_color[] [[fragops-coverage-to-color]] == Fragment Coverage to Color [open,refpage='VkPipelineCoverageToColorStateCreateInfoNV',desc='Structure specifying whether fragment coverage replaces a color',type='structs'] -- The sname:VkPipelineCoverageToColorStateCreateInfoNV structure is defined as: include::{generated}/api/structs/VkPipelineCoverageToColorStateCreateInfoNV.adoc[] * pname:sType is a elink:VkStructureType value identifying this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. * pname:flags is reserved for future use. * pname:coverageToColorEnable controls whether the fragment coverage value replaces a fragment color output. * pname:coverageToColorLocation controls which fragment shader color output value is replaced. If the pname:pNext chain of slink:VkPipelineMultisampleStateCreateInfo includes a sname:VkPipelineCoverageToColorStateCreateInfoNV structure, then that structure controls whether the fragment coverage is substituted for a fragment color output and, if so, which output is replaced. If pname:coverageToColorEnable is ename:VK_TRUE, the <> replaces the first component of the color value corresponding to the fragment shader output location with code:Location equal to pname:coverageToColorLocation and code:Index equal to zero. If the color attachment format has fewer bits than the coverage mask, the low bits of the sample coverage mask are taken without any clamping. If the color attachment format has more bits than the coverage mask, the high bits of the sample coverage mask are filled with zeros. If pname:coverageToColorEnable is ename:VK_FALSE, these operations are skipped. If this structure is not included in the pname:pNext chain, it is as if pname:coverageToColorEnable is ename:VK_FALSE. .Valid Usage **** * [[VUID-VkPipelineCoverageToColorStateCreateInfoNV-coverageToColorEnable-01404]] If pname:coverageToColorEnable is ename:VK_TRUE, then the render pass subpass indicated by slink:VkGraphicsPipelineCreateInfo::pname:renderPass and slink:VkGraphicsPipelineCreateInfo::pname:subpass must: have a color attachment at the location selected by pname:coverageToColorLocation, with a elink:VkFormat of ename:VK_FORMAT_R8_UINT, ename:VK_FORMAT_R8_SINT, ename:VK_FORMAT_R16_UINT, ename:VK_FORMAT_R16_SINT, ename:VK_FORMAT_R32_UINT, or ename:VK_FORMAT_R32_SINT **** include::{generated}/validity/structs/VkPipelineCoverageToColorStateCreateInfoNV.adoc[] -- [open,refpage='VkPipelineCoverageToColorStateCreateFlagsNV',desc='Reserved for future use',type='flags'] -- include::{generated}/api/flags/VkPipelineCoverageToColorStateCreateFlagsNV.adoc[] tname:VkPipelineCoverageToColorStateCreateFlagsNV is a bitmask type for setting a mask, but is currently reserved for future use. -- ifdef::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] [open,refpage='vkCmdSetCoverageToColorEnableNV',desc='Specify the coverage to color enable state dynamically for a command buffer',type='protos'] -- To <> the pname:coverageToColorEnable state, call: include::{generated}/api/protos/vkCmdSetCoverageToColorEnableNV.adoc[] * pname:commandBuffer is the command buffer into which the command will be recorded. * pname:coverageToColorEnable specifies the pname:coverageToColorEnable state. This command sets the pname:coverageToColorEnable state for subsequent drawing commands ifdef::VK_EXT_shader_object[] ifdef::VK_EXT_extended_dynamic_state3[when drawing using <>, or] ifndef::VK_EXT_extended_dynamic_state3[when drawing using <>.] endif::VK_EXT_shader_object[] ifdef::VK_EXT_extended_dynamic_state3[] when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_COVERAGE_TO_COLOR_ENABLE_NV set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. endif::VK_EXT_extended_dynamic_state3[] Otherwise, this state is specified by the slink:VkPipelineCoverageToColorStateCreateInfoNV::pname:coverageToColorEnable value used to create the currently active pipeline. :refpage: vkCmdSetCoverageToColorEnableNV :requiredfeature: extendedDynamicState3CoverageToColorEnable .Valid Usage **** include::{chapters}/commonvalidity/dynamic_state3_feature_common.adoc[] **** include::{generated}/validity/protos/vkCmdSetCoverageToColorEnableNV.adoc[] -- [open,refpage='vkCmdSetCoverageToColorLocationNV',desc='Specify the coverage to color location dynamically for a command buffer',type='protos'] -- To <> the pname:coverageToColorLocation state, call: include::{generated}/api/protos/vkCmdSetCoverageToColorLocationNV.adoc[] * pname:commandBuffer is the command buffer into which the command will be recorded. * pname:coverageToColorLocation specifies the pname:coverageToColorLocation state. This command sets the pname:coverageToColorLocation state for subsequent drawing commands ifdef::VK_EXT_shader_object[] ifdef::VK_EXT_extended_dynamic_state3[when drawing using <>, or] ifndef::VK_EXT_extended_dynamic_state3[when drawing using <>.] endif::VK_EXT_shader_object[] ifdef::VK_EXT_extended_dynamic_state3[] when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_COVERAGE_TO_COLOR_LOCATION_NV set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. endif::VK_EXT_extended_dynamic_state3[] Otherwise, this state is specified by the slink:VkPipelineCoverageToColorStateCreateInfoNV::pname:coverageToColorLocation value used to create the currently active pipeline. :refpage: vkCmdSetCoverageToColorLocationNV :requiredfeature: extendedDynamicState3CoverageToColorLocation .Valid Usage **** include::{chapters}/commonvalidity/dynamic_state3_feature_common.adoc[] **** include::{generated}/validity/protos/vkCmdSetCoverageToColorLocationNV.adoc[] -- endif::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] endif::VK_NV_fragment_coverage_to_color[] [[fragops-coverage-reduction]] == Coverage Reduction Coverage reduction takes the coverage information for a fragment and converts that to a boolean coverage value for each color sample in each pixel covered by the fragment. === Pixel Coverage Coverage for each pixel is first extracted from the total fragment coverage mask. This consists of pname:rasterizationSamples unique coverage samples for each pixel in the fragment area, each with a unique <>. If the fragment only contains a single pixel, coverage for the pixel is equivalent to the fragment coverage. ifdef::VK_EXT_fragment_density_map[] If the render pass has a fragment density map attachment and the fragment covers multiple pixels, pixel coverage is generated in an implementation-dependent manner. If all samples in the fragment are covered, all samples will be covered in each pixel coverage. endif::VK_EXT_fragment_density_map[] ifdef::VK_NV_shading_rate_image[] If a <> is used, and the fragment covers multiple pixels, each pixel's coverage consists of the coverage samples corresponding to that pixel, and each sample retains its unique <>. endif::VK_NV_shading_rate_image[] ifdef::VK_KHR_fragment_shading_rate[] If the <> is set, and the fragment covers multiple pixels, each pixel's coverage consists of the coverage samples with a <> matching that pixel, and each sample retains its unique <>. endif::VK_KHR_fragment_shading_rate[] === Color Sample Coverage Once pixel coverage is determined, coverage for each individual color sample corresponding to that pixel is determined. ifdef::VK_AMD_mixed_attachment_samples,VK_NV_framebuffer_mixed_samples,VK_NV_coverage_reduction_mode[If the] ifndef::VK_AMD_mixed_attachment_samples,VK_NV_framebuffer_mixed_samples,VK_NV_coverage_reduction_mode[The] number of pname:rasterizationSamples is identical to the number of samples in the color ifdef::VK_AMD_mixed_attachment_samples,VK_NV_framebuffer_mixed_samples,VK_NV_coverage_reduction_mode[attachments, a] ifndef::VK_AMD_mixed_attachment_samples,VK_NV_framebuffer_mixed_samples,VK_NV_coverage_reduction_mode[attachments. A] color sample is covered if the pixel coverage sample with the same <> [eq]#i# is covered. ifdef::VK_AMD_mixed_attachment_samples,VK_NV_framebuffer_mixed_samples,VK_NV_coverage_reduction_mode[] Otherwise, the coverage for each color sample is computed from the pixel coverage as follows. endif::VK_AMD_mixed_attachment_samples,VK_NV_framebuffer_mixed_samples,VK_NV_coverage_reduction_mode[] ifdef::VK_AMD_mixed_attachment_samples[] If the `apiext:VK_AMD_mixed_attachment_samples` extension is enabled, for color samples present in the color attachments, a color sample is covered if the pixel coverage sample with the same <> [eq]#i# is covered; additional pixel coverage samples are discarded. endif::VK_AMD_mixed_attachment_samples[] ifdef::VK_EXT_multisampled_render_to_single_sampled[] If the pname:pNext chain of slink:VkSubpassDescription2 ifdef::VK_VERSION_1_3,VK_KHR_dynamic_rendering[or slink:VkRenderingInfo] includes a slink:VkMultisampledRenderToSingleSampledInfoEXT structure with the pname:multisampledRenderToSingleSampledEnable field equal to ename:VK_TRUE, sample coverage is calculated as if the attachment has slink:VkMultisampledRenderToSingleSampledInfoEXT::pname:rasterizationSamples samples. endif::VK_EXT_multisampled_render_to_single_sampled[] ifdef::VK_NV_framebuffer_mixed_samples[] ifndef::VK_NV_coverage_reduction_mode[] When the `apiext:VK_NV_framebuffer_mixed_samples` extension is enabled, if the pipeline's slink:VkPipelineMultisampleStateCreateInfo::pname:rasterizationSamples is greater than the slink:VkAttachmentDescription::pname:samples of the color attachments in the subpass, each color sample will be associated with an implementation-dependent subset of samples in the pixel coverage. If any of those associated samples are covered, the color sample is covered. endif::VK_NV_coverage_reduction_mode[] ifdef::VK_NV_coverage_reduction_mode[] When the `apiext:VK_NV_coverage_reduction_mode` extension is enabled, the pipeline state controlling coverage reduction is specified through the members of the sname:VkPipelineCoverageReductionStateCreateInfoNV structure. [open,refpage='VkPipelineCoverageReductionStateCreateInfoNV',desc='Structure specifying parameters controlling coverage reduction',type='structs'] -- The sname:VkPipelineCoverageReductionStateCreateInfoNV structure is defined as: include::{generated}/api/structs/VkPipelineCoverageReductionStateCreateInfoNV.adoc[] * pname:sType is a elink:VkStructureType value identifying this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. * pname:flags is reserved for future use. * pname:coverageReductionMode is a elink:VkCoverageReductionModeNV value controlling how color sample coverage is generated from pixel coverage. If this structure is not included in the pname:pNext chain, or if the extension is not enabled, the default coverage reduction mode is inferred as follows: * If the `apiext:VK_NV_framebuffer_mixed_samples` extension is enabled, then it is as if the pname:coverageReductionMode is ename:VK_COVERAGE_REDUCTION_MODE_MERGE_NV. * If the `apiext:VK_AMD_mixed_attachment_samples` extension is enabled, then it is as if the pname:coverageReductionMode is ename:VK_COVERAGE_REDUCTION_MODE_TRUNCATE_NV. * If both `apiext:VK_NV_framebuffer_mixed_samples` and `apiext:VK_AMD_mixed_attachment_samples` are enabled, then the default coverage reduction mode is implementation-dependent. include::{generated}/validity/structs/VkPipelineCoverageReductionStateCreateInfoNV.adoc[] -- [open,refpage='VkPipelineCoverageReductionStateCreateFlagsNV',desc='Reserved for future use',type='flags'] -- include::{generated}/api/flags/VkPipelineCoverageReductionStateCreateFlagsNV.adoc[] tname:VkPipelineCoverageReductionStateCreateFlagsNV is a bitmask type for setting a mask, but is currently reserved for future use. -- [open,refpage='VkCoverageReductionModeNV',desc='Specify the coverage reduction mode',type='enums'] -- Possible values of slink:VkPipelineCoverageReductionStateCreateInfoNV::pname:coverageReductionMode, specifying how color sample coverage is generated from pixel coverage, are: include::{generated}/api/enums/VkCoverageReductionModeNV.adoc[] * ename:VK_COVERAGE_REDUCTION_MODE_MERGE_NV specifies that each color sample will be associated with an implementation-dependent subset of samples in the pixel coverage. If any of those associated samples are covered, the color sample is covered. * ename:VK_COVERAGE_REDUCTION_MODE_TRUNCATE_NV specifies that for color samples present in the color attachments, a color sample is covered if the pixel coverage sample with the same <> [eq]#i# is covered; other pixel coverage samples are discarded. -- ifdef::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] [open,refpage='vkCmdSetCoverageReductionModeNV',desc='Specify the coverage reduction mode dynamically for a command buffer',type='protos'] -- To <> the pname:coverageReductionMode state, call: include::{generated}/api/protos/vkCmdSetCoverageReductionModeNV.adoc[] * pname:commandBuffer is the command buffer into which the command will be recorded. * pname:coverageReductionMode specifies the pname:coverageReductionMode state. This command sets the pname:coverageReductionMode state for subsequent drawing commands ifdef::VK_EXT_shader_object[] ifdef::VK_EXT_extended_dynamic_state3[when drawing using <>, or] ifndef::VK_EXT_extended_dynamic_state3[when drawing using <>.] endif::VK_EXT_shader_object[] ifdef::VK_EXT_extended_dynamic_state3[] when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_COVERAGE_REDUCTION_MODE_NV set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. endif::VK_EXT_extended_dynamic_state3[] Otherwise, this state is specified by the slink:VkPipelineCoverageReductionStateCreateInfoNV::pname:coverageReductionMode value used to create the currently active pipeline. :refpage: vkCmdSetCoverageReductionModeNV :requiredfeature: extendedDynamicState3CoverageReductionMode .Valid Usage **** include::{chapters}/commonvalidity/dynamic_state3_feature_common.adoc[] **** include::{generated}/validity/protos/vkCmdSetCoverageReductionModeNV.adoc[] -- endif::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] [open,refpage='vkGetPhysicalDeviceSupportedFramebufferMixedSamplesCombinationsNV',desc='Query supported sample count combinations',type='protos'] -- To query the set of mixed sample combinations of coverage reduction mode, rasterization samples and color, depth, stencil attachment sample counts that are supported by a physical device, call: include::{generated}/api/protos/vkGetPhysicalDeviceSupportedFramebufferMixedSamplesCombinationsNV.adoc[] * pname:physicalDevice is the physical device from which to query the set of combinations. * pname:pCombinationCount is a pointer to an integer related to the number of combinations available or queried, as described below. * pname:pCombinations is either `NULL` or a pointer to an array of slink:VkFramebufferMixedSamplesCombinationNV values, indicating the supported combinations of coverage reduction mode, rasterization samples, and color, depth, stencil attachment sample counts. If pname:pCombinations is `NULL`, then the number of supported combinations for the given pname:physicalDevice is returned in pname:pCombinationCount. Otherwise, pname:pCombinationCount must: point to a variable set by the user to the number of elements in the pname:pCombinations array, and on return the variable is overwritten with the number of values actually written to pname:pCombinations. If the value of pname:pCombinationCount is less than the number of combinations supported for the given pname:physicalDevice, at most pname:pCombinationCount values will be written to pname:pCombinations, and ename:VK_INCOMPLETE will be returned instead of ename:VK_SUCCESS, to indicate that not all the supported values were returned. include::{generated}/validity/protos/vkGetPhysicalDeviceSupportedFramebufferMixedSamplesCombinationsNV.adoc[] -- [open,refpage='VkFramebufferMixedSamplesCombinationNV',desc='Structure specifying a supported sample count combination',type='structs'] -- The sname:VkFramebufferMixedSamplesCombinationNV structure is defined as: include::{generated}/api/structs/VkFramebufferMixedSamplesCombinationNV.adoc[] * pname:sType is a elink:VkStructureType value identifying this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. * pname:coverageReductionMode is a elink:VkCoverageReductionModeNV value specifying the coverage reduction mode. * pname:rasterizationSamples is a elink:VkSampleCountFlagBits specifying the number of rasterization samples in the supported combination. * pname:depthStencilSamples specifies the number of samples in the depth stencil attachment in the supported combination. A value of 0 indicates the combination does not have a depth stencil attachment. * pname:colorSamples specifies the number of color samples in a color attachment in the supported combination. A value of 0 indicates the combination does not have a color attachment. include::{generated}/validity/structs/VkFramebufferMixedSamplesCombinationNV.adoc[] -- endif::VK_NV_coverage_reduction_mode[] [[fragops-coverage-modulation]] === Coverage Modulation [open,refpage='VkPipelineCoverageModulationStateCreateInfoNV',desc='Structure specifying parameters controlling coverage modulation',type='structs'] -- As part of coverage reduction, fragment color values can: also be modulated (multiplied) by a value that is a function of fraction of covered rasterization samples associated with that color sample. Pipeline state controlling coverage modulation is specified through the members of the sname:VkPipelineCoverageModulationStateCreateInfoNV structure. The sname:VkPipelineCoverageModulationStateCreateInfoNV structure is defined as: include::{generated}/api/structs/VkPipelineCoverageModulationStateCreateInfoNV.adoc[] * pname:sType is a elink:VkStructureType value identifying this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. * pname:flags is reserved for future use. * pname:coverageModulationMode is a elink:VkCoverageModulationModeNV value controlling which color components are modulated. * pname:coverageModulationTableEnable controls whether the modulation factor is looked up from a table in pname:pCoverageModulationTable. * pname:coverageModulationTableCount is the number of elements in pname:pCoverageModulationTable. * pname:pCoverageModulationTable is a table of modulation factors containing a value for each number of covered samples. If pname:coverageModulationTableEnable is ename:VK_FALSE, then for each color sample the associated bits of the pixel coverage are counted and divided by the number of associated bits to produce a modulation factor [eq]#R# in the range [eq]#(0,1]# (a value of zero would have been killed due to a color coverage of 0). Specifically: * [eq]#N# = value of pname:rasterizationSamples * [eq]#M# = value of slink:VkAttachmentDescription::pname:samples for any color attachments * [eq]#R = popcount(associated coverage bits) / (N / M)# If pname:coverageModulationTableEnable is ename:VK_TRUE, the value [eq]#R# is computed using a programmable lookup table. The lookup table has [eq]#N / M# elements, and the element of the table is selected by: * [eq]#R = pname:pCoverageModulationTable[popcount(associated coverage bits)-1]# Note that the table does not have an entry for [eq]#popcount(associated coverage bits) = 0#, because such samples would have been killed. The values of pname:pCoverageModulationTable may: be rounded to an implementation-dependent precision, which is at least as fine as [eq]#1 / N#, and clamped to [eq]#[0,1]#. For each color attachment with a floating point or normalized color format, each fragment output color value is replicated to [eq]#M# values which can: each be modulated (multiplied) by that color sample's associated value of [eq]#R#. Which components are modulated is controlled by pname:coverageModulationMode. If this structure is not included in the pname:pNext chain, it is as if pname:coverageModulationMode is ename:VK_COVERAGE_MODULATION_MODE_NONE_NV. ifdef::VK_NV_coverage_reduction_mode[] If the <> is ename:VK_COVERAGE_REDUCTION_MODE_TRUNCATE_NV, each color sample is associated with only a single coverage sample. In this case, it is as if pname:coverageModulationMode is ename:VK_COVERAGE_MODULATION_MODE_NONE_NV. endif::VK_NV_coverage_reduction_mode[] .Valid Usage **** * [[VUID-VkPipelineCoverageModulationStateCreateInfoNV-coverageModulationTableEnable-01405]] If pname:coverageModulationTableEnable is ename:VK_TRUE, pname:coverageModulationTableCount must: be equal to the number of rasterization samples divided by the number of color samples in the subpass **** include::{generated}/validity/structs/VkPipelineCoverageModulationStateCreateInfoNV.adoc[] -- [open,refpage='VkPipelineCoverageModulationStateCreateFlagsNV',desc='Reserved for future use',type='flags'] -- include::{generated}/api/flags/VkPipelineCoverageModulationStateCreateFlagsNV.adoc[] tname:VkPipelineCoverageModulationStateCreateFlagsNV is a bitmask type for setting a mask, but is currently reserved for future use. -- [open,refpage='VkCoverageModulationModeNV',desc='Specify the coverage modulation mode',type='enums'] -- Possible values of slink:VkPipelineCoverageModulationStateCreateInfoNV::pname:coverageModulationMode, specifying which color components are modulated, are: include::{generated}/api/enums/VkCoverageModulationModeNV.adoc[] * ename:VK_COVERAGE_MODULATION_MODE_NONE_NV specifies that no components are multiplied by the modulation factor. * ename:VK_COVERAGE_MODULATION_MODE_RGB_NV specifies that the red, green, and blue components are multiplied by the modulation factor. * ename:VK_COVERAGE_MODULATION_MODE_ALPHA_NV specifies that the alpha component is multiplied by the modulation factor. * ename:VK_COVERAGE_MODULATION_MODE_RGBA_NV specifies that all components are multiplied by the modulation factor. -- ifdef::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] [open,refpage='vkCmdSetCoverageModulationModeNV',desc='Specify the coverage modulation mode dynamically for a command buffer',type='protos'] -- To <> the pname:coverageModulationMode state, call: include::{generated}/api/protos/vkCmdSetCoverageModulationModeNV.adoc[] * pname:commandBuffer is the command buffer into which the command will be recorded. * pname:coverageModulationMode specifies the pname:coverageModulationMode state. This command sets the pname:coverageModulationMode state for subsequent drawing commands ifdef::VK_EXT_shader_object[] ifdef::VK_EXT_extended_dynamic_state3[when drawing using <>, or] ifndef::VK_EXT_extended_dynamic_state3[when drawing using <>.] endif::VK_EXT_shader_object[] ifdef::VK_EXT_extended_dynamic_state3[] the graphics pipeline is created with ename:VK_DYNAMIC_STATE_COVERAGE_MODULATION_MODE_NV set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. endif::VK_EXT_extended_dynamic_state3[] Otherwise, this state is specified by the slink:VkPipelineCoverageModulationStateCreateInfoNV::pname:coverageModulationMode value used to create the currently active pipeline. :refpage: vkCmdSetCoverageModulationModeNV :requiredfeature: extendedDynamicState3CoverageModulationMode .Valid Usage **** include::{chapters}/commonvalidity/dynamic_state3_feature_common.adoc[] **** include::{generated}/validity/protos/vkCmdSetCoverageModulationModeNV.adoc[] -- [open,refpage='vkCmdSetCoverageModulationTableEnableNV',desc='Specify the coverage modulation table enable state dynamically for a command buffer',type='protos'] -- To <> the pname:coverageModulationTableEnable state, call: include::{generated}/api/protos/vkCmdSetCoverageModulationTableEnableNV.adoc[] * pname:commandBuffer is the command buffer into which the command will be recorded. * pname:coverageModulationTableEnable specifies the pname:coverageModulationTableEnable state. This command sets the pname:coverageModulationTableEnable state for subsequent drawing commands ifdef::VK_EXT_shader_object[] ifdef::VK_EXT_extended_dynamic_state3[when drawing using <>, or] ifndef::VK_EXT_extended_dynamic_state3[when drawing using <>.] endif::VK_EXT_shader_object[] ifdef::VK_EXT_extended_dynamic_state3[] when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_COVERAGE_MODULATION_TABLE_ENABLE_NV set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. endif::VK_EXT_extended_dynamic_state3[] Otherwise, this state is specified by the slink:VkPipelineCoverageModulationStateCreateInfoNV::pname:coverageModulationTableEnable value used to create the currently active pipeline. :refpage: vkCmdSetCoverageModulationTableEnableNV :requiredfeature: extendedDynamicState3CoverageModulationTableEnable .Valid Usage **** include::{chapters}/commonvalidity/dynamic_state3_feature_common.adoc[] **** include::{generated}/validity/protos/vkCmdSetCoverageModulationTableEnableNV.adoc[] -- [open,refpage='vkCmdSetCoverageModulationTableNV',desc='Specify the coverage modulation table dynamically for a command buffer',type='protos'] -- To <> the pname:pCoverageModulationTable state, call: include::{generated}/api/protos/vkCmdSetCoverageModulationTableNV.adoc[] * pname:commandBuffer is the command buffer into which the command will be recorded. * pname:coverageModulationTableCount specifies the number of elements in pname:pCoverageModulationTable. * pname:pCoverageModulationTable specifies the table of modulation factors containing a value for each number of covered samples. This command sets the table of modulation factors for subsequent drawing commands ifdef::VK_EXT_shader_object[] ifdef::VK_EXT_extended_dynamic_state3[when drawing using <>, or] ifndef::VK_EXT_extended_dynamic_state3[when drawing using <>.] endif::VK_EXT_shader_object[] ifdef::VK_EXT_extended_dynamic_state3[] when the graphics pipeline is created with ename:VK_DYNAMIC_STATE_COVERAGE_MODULATION_TABLE_NV set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. endif::VK_EXT_extended_dynamic_state3[] Otherwise, this state is specified by the slink:VkPipelineCoverageModulationStateCreateInfoNV::pname:coverageModulationTableCount, and slink:VkPipelineCoverageModulationStateCreateInfoNV::pname:pCoverageModulationTable values used to create the currently active pipeline. :refpage: vkCmdSetCoverageModulationTableNV :requiredfeature: extendedDynamicState3CoverageModulationTable .Valid Usage **** include::{chapters}/commonvalidity/dynamic_state3_feature_common.adoc[] **** include::{generated}/validity/protos/vkCmdSetCoverageModulationTableNV.adoc[] -- endif::VK_EXT_extended_dynamic_state3,VK_EXT_shader_object[] endif::VK_NV_framebuffer_mixed_samples[]