| // 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 <<primsrast-order,rasterization |
| order>>, and are typically performed in this order: |
| |
| ifdef::VK_EXT_discard_rectangles[] |
| . <<fragops-discard-rectangles,Discard rectangles test>> |
| endif::VK_EXT_discard_rectangles[] |
| . <<fragops-scissor,Scissor test>> |
| ifdef::VK_NV_scissor_exclusive[] |
| . <<fragops-exclusive-scissor,Exclusive scissor test>> |
| endif::VK_NV_scissor_exclusive[] |
| . <<fragops-samplemask,Sample mask test>> |
| . Certain <<fragops-shader,Fragment shading>> operations: |
| ** <<fragops-shader-samplemask, Sample Mask Accesses>> |
| ifdef::VK_EXT_shader_tile_image[] |
| ** <<fragops-shader-tileimage-reads, Tile Image Reads>> |
| endif::VK_EXT_shader_tile_image[] |
| ** <<fragops-shader-depthreplacement, Depth Replacement>> |
| ifdef::VK_EXT_shader_stencil_export[] |
| ** <<fragops-shader-stencilrefreplacement, Stencil Reference Replacement>> |
| endif::VK_EXT_shader_stencil_export[] |
| ifdef::VK_EXT_fragment_shader_interlock[] |
| ** <<fragops-shader-interlock, Interlocked Operations>> |
| endif::VK_EXT_fragment_shader_interlock[] |
| . <<fragops-covg, Multisample coverage>> |
| . <<fragops-dbt, Depth bounds test>> |
| . <<fragops-stencil, Stencil test>> |
| . <<fragops-depth, Depth test>> |
| ifdef::VK_NV_representative_fragment_test[] |
| . <<fragops-rep-frag-test, Representative fragment test>> |
| endif::VK_NV_representative_fragment_test[] |
| . <<fragops-samplecount, Sample counting>> |
| ifdef::VK_NV_fragment_coverage_to_color[] |
| . <<fragops-coverage-to-color, Coverage to color>> |
| endif::VK_NV_fragment_coverage_to_color[] |
| . <<fragops-coverage-reduction, Coverage reduction>> |
| ifdef::VK_NV_framebuffer_mixed_samples[] |
| . <<fragops-coverage-modulation, Coverage modulation>> |
| endif::VK_NV_framebuffer_mixed_samples[] |
| |
| The <<primsrast-multisampling-coverage-mask, coverage mask>> 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 <<fragops-shader, fragment shader>> and it declares the |
| code:PostDepthCoverage execution mode, the <<fragops-samplemask, sample mask |
| test>> is instead performed after the <<fragops-depth, depth test>>. |
| 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 <<fragops-shader, fragment shader>> |
| which declares the code:EarlyFragmentTests execution mode, <<fragops-shader, |
| fragment shading>> and <<fragops-covg, multisample coverage>> operations |
| must: be performed after <<fragops-samplecount, sample counting>>. |
| |
| Otherwise, if |
| sname:VkPhysicalDeviceMaintenance5PropertiesKHR::pname:earlyFragmentMultisampleCoverageAfterSampleCounting |
| is set to ename:VK_FALSE and there is a <<fragops-shader, fragment shader>> |
| which declares the code:EarlyFragmentTests execution mode, <<fragops-shader, |
| fragment shading>> and <<fragops-covg, multisample coverage>> operations |
| should: instead be performed after <<fragops-samplecount, sample counting>>, |
| but may: be performed before <<fragops-samplecount, sample counting>>. |
| |
| If |
| sname:VkPhysicalDeviceMaintenance5PropertiesKHR::pname:earlyFragmentSampleMaskTestBeforeSampleCounting |
| is set to ename:VK_TRUE and there is a <<fragops-shader, fragment shader>> |
| which declares the code:EarlyFragmentTests execution mode |
| <<fragops-samplemask, sample mask test>> 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 <<fragops-shader, fragment shader>> |
| which declares the code:EarlyFragmentTests execution mode, |
| <<fragops-samplemask, sample mask test>> operations should: follow the order |
| of fragment operations from above but may: instead be performed after |
| <<fragops-samplecount, sample counting>>. |
| endif::VK_KHR_maintenance5[] |
| ifndef::VK_KHR_maintenance5[] |
| If there is a <<fragops-shader, fragment shader>> and it declares the |
| code:EarlyFragmentTests execution mode, <<fragops-shader,fragment shading>> |
| and <<fragops-covg, multisample coverage>> operations should: instead be |
| performed after <<fragops-samplecount, sample counting>>, and |
| <<fragops-samplemask,sample mask test>> may: instead be performed after |
| <<fragops-samplecount, sample counting>>. |
| endif::VK_KHR_maintenance5[] |
| |
| ifdef::VK_AMD_shader_early_and_late_fragment_tests[] |
| If there is a <<fragops-shader, fragment shader>> 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, <<fragops-shader,fragment shading>> and <<fragops-covg, |
| multisample coverage>> operations are instead be performed after |
| <<fragops-samplecount, sample counting>>. |
| |
| 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 <<fragops-stencil, stencil test>> may: be performed before |
| <<fragops-shader, fragment shading>>, 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 <<fragops-dbt,depth bounds test>> before |
| <<fragops-shader, fragment shading>> and perform an additional |
| <<fragops-depth, depth test>> 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 <<framebuffer, framebuffer |
| operations>>. |
| |
| |
| 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 <<pipelines-dynamic-state, dynamically set>> 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 <<shaders-objects, shader objects>>, 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 <<pipelines-dynamic-state, dynamically set>> 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 <<shaders-objects, shader objects>>, 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 <<pipelines-dynamic-state, dynamically set>> 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 <<shaders-objects, shader objects>>, 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 <<interfaces-builtin-variables-viewportindex, |
| code:ViewportIndex>>. |
| |
| 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 <<vertexpostproc-renderpass-transform, render |
| pass transform>> 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 <<pipelines-dynamic-state, dynamically set>> 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 <<shaders-objects, shader objects>>, 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 <<features-multiViewport, pname:multiViewport>> feature is not |
| enabled, pname:firstScissor must: be `0` |
| * [[VUID-vkCmdSetScissor-scissorCount-00594]] |
| If the <<features-multiViewport, pname:multiViewport>> 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 |
| <<interfaces-builtin-variables-viewportindex, code:ViewportIndex>>. |
| |
| 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 <<features-multiViewport, pname:multiViewport>> 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 <<pipelines-dynamic-state, dynamically set>> 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 <<shaders-objects, shader objects>>, 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 <<features-exclusiveScissor, pname:exclusiveScissor>> 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 <<features-multiViewport, pname:multiViewport>> feature is not |
| enabled, pname:firstExclusiveScissor must: be `0` |
| * [[VUID-vkCmdSetExclusiveScissorNV-exclusiveScissorCount-02036]] |
| If the <<features-multiViewport, pname:multiViewport>> 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 <<pipelines-dynamic-state, dynamically set>> 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 <<shaders-objects, shader objects>>, 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 <<features-exclusiveScissor, pname:exclusiveScissor>> 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 <<primsrast-multisampling-coverage-mask, |
| coverage mask>> 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 <<pipelines-dynamic-state, dynamically set>> 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 <<shaders-objects, shader objects>>, or] |
| ifndef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>.] |
| 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 <<primsrast-multisampling-coverage-mask, rasterization chapter>>. |
| 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 |
| |
| <<shaders-fragment, Fragment shaders>> are invoked for each fragment, or as |
| <<shaders-helper-invocations, helper invocations>>. |
| |
| Most operations in the fragment shader are not performed in |
| <<primsrast-order, rasterization order>>, 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 <<fragops, fragment |
| operation>> 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 <<drawing-primitive-order, primitive order>>, |
| overwrites all results computed by the shader (including writes to |
| storage resources). |
| ** Any other <<fragops, fragment operation>> discards the fragment, and |
| the shader does not write to any storage resources. |
| * Otherwise, at least one fragment shader must: be executed. |
| ** If <<primsrast-sampleshading,sample shading>> is enabled and multiple |
| invocations per fragment are required:, additional invocations must: be |
| executed as specified. |
| ifdef::VK_NV_shading_rate_image[] |
| ** If a <<primsrast-shading-rate-image,shading rate image>> 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 <<interfaces-builtin-variables-samplemask, |
| code:SampleMask>> 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 <<primsrast-sampleshading, sample shading>> 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 <<primsrast-multisampling-coverage-mask, rasterization chapter>>. |
| 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 <<interfaces-builtin-variables-samplemask, |
| code:SampleMask>> built-in in the code:Output storage class will be used by |
| the <<fragops-covg, multisample coverage>> 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 <<glossary-tile-image, tile image>> 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 <<features-shaderTileImageColorReadAccess, |
| shaderTileImageColorReadAccess>>, <<features-shaderTileImageDepthReadAccess, |
| shaderTileImageDepthReadAccess>>, |
| <<features-shaderTileImageStencilReadAccess, |
| shaderTileImageStencilReadAccess>> 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 <<interfaces-fragmenttileimage, Fragment Tile Image Interface>> 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 |
| <<primsrast-multisampling-coverage-mask, sample index>> value specified as |
| the code:Sample operand to code:OpColorAttachmentReadEXT, |
| code:OpDepthAttachmentReadEXT, or code:OpStencilAttachmentReadEXT. |
| |
| If <<primsrast-sampleshading, sample shading>> 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 <<primsrast-sampleshading, sample shading>> is enabled, and |
| pname:minSampleShading is 1.0, a fragment invocation must: only read from |
| the <<primsrast-multisampling-coverageindex, coverage index>> sample. |
| Tile image access must: not be used if the value of pname:minSampleShading |
| is not 1.0. |
| |
| If the <<fragops-shader, fragment shader>> 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 |
| <<memory-model-access-data-race, data race>> 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 |
| <<synchronization-pipeline-barriers-explicit-renderpass-tileimage, explicit |
| tile image synchronization>> 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 <<interfaces-builtin-variables-fragdepth,code:FragDepth>> |
| built-in will replace the fragment's calculated depth values for each sample |
| in the input code:SampleMask. |
| <<fragops-depth, Depth testing>> 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 |
| <<interfaces-builtin-variables-fragdepth,code:FragStencilRefEXT>> built-in |
| will replace the fragment's stencil reference value for each sample in the |
| input code:SampleMask. |
| <<fragops-stencil, Stencil testing>> 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 |
| <<primsrast-order, rasterization order>> 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 <<primsrast-order, rasterization |
| order>> 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 <<primsrast-order, rasterization order>> 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 |
| <<primsrast-order, rasterization order>> and cover at least one sample in |
| the same pixel, and must: happen after interlocked operations in a fragment |
| shader that executes earlier in <<primsrast-order, rasterization order>> 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 <<primsrast-order, rasterization order>> 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 |
| <<primsrast-order, rasterization order>> and cover at least one of the same |
| samples, and must: happen after interlocked operations in a fragment shader |
| that executes earlier in <<primsrast-order, rasterization order>> 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 <<primsrast-order, rasterization order>> 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 <<primsrast-sampleshading,sample shading>> 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 <<pipelines-dynamic-state, dynamically set>> 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 <<shaders-objects, shader objects>>, or] |
| ifndef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>.] |
| 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 <<pipelines-dynamic-state, dynamically set>> 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 <<shaders-objects, shader objects>>, or] |
| ifndef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>.] |
| 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 <<features-alphaToOne, pname:alphaToOne>> 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 <<interfaces-fragmentoutput,Fragment Output Interface>> |
| 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 |
| <<primsrast-lines-smooth,smooth line rasterization>>. |
| 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 <<fragops-dbt,depth bounds tests>>, |
| <<fragops-stencil,stencil test>>, and <<fragops-depth,depth test>> 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 <<fragops-depth,depth testing>> |
| is enabled. |
| * pname:depthWriteEnable controls whether <<fragops-depth-write,depth |
| writes>> 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 <<fragops-depth-comparison, Depth |
| Comparison>> step of the <<fragops-depth,depth test>>. |
| * pname:depthBoundsTestEnable controls whether <<fragops-dbt,depth bounds |
| testing>> is enabled. |
| * pname:stencilTestEnable controls whether <<fragops-stencil,stencil |
| testing>> is enabled. |
| * pname:front and pname:back are slink:VkStencilOpState values controlling |
| the corresponding parameters of the <<fragops-stencil,stencil test>>. |
| * pname:minDepthBounds is the minimum depth bound used in the |
| <<fragops-dbt, depth bounds test>>. |
| * pname:maxDepthBounds is the maximum depth bound used in the |
| <<fragops-dbt, depth bounds test>>. |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkPipelineDepthStencilStateCreateInfo-depthBoundsTestEnable-00598]] |
| If the <<features-depthBounds, pname:depthBounds>> 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 <<features-rasterizationOrderDepthAttachmentAccess, |
| pname:rasterizationOrderDepthAttachmentAccess>> 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 <<features-rasterizationOrderStencilAttachmentAccess, |
| pname:rasterizationOrderStencilAttachmentAccess>> 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 <<synchronization-dependencies-scopes, synchronization scope>> |
| 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 <<drawing-primitive-order, |
| primitive order>>) in the corresponding |
| <<synchronization-framebuffer-regions, framebuffer regions>> including |
| those generated by the same draw command. |
| * The second <<synchronization-dependencies-scopes, synchronization |
| scope>> includes ename:VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT stage |
| executed by the generated fragment. |
| * The first <<synchronization-dependencies-access-scopes, access scope>> |
| includes all writes to the depth aspect of depth/stencil attachments. |
| * The second <<synchronization-dependencies-access-scopes, access scope>> |
| 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 <<synchronization-dependencies-scopes, synchronization scope>> |
| 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 <<drawing-primitive-order, |
| primitive order>>) in the corresponding |
| <<synchronization-framebuffer-regions, framebuffer regions>> including |
| those generated by the same draw command. |
| * The second <<synchronization-dependencies-scopes, synchronization |
| scope>> 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 <<synchronization-dependencies-access-scopes, access scope>> |
| includes all writes to the stencil aspect of depth/stencil attachments. |
| * The second <<synchronization-dependencies-access-scopes, access scope>> |
| 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 <<primsrast-multisampling-coverage-mask, sample |
| index>> [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 <<pipelines-dynamic-state, dynamically enable or disable>> 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 <<shaders-objects, shader objects>>, or] |
| ifndef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[when drawing using <<shaders-objects, shader objects>>.] |
| 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 <<pipelines-dynamic-state, dynamically set>> 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 <<shaders-objects, shader objects>>, 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 <<primsrast-multisampling-coverage-mask, sample |
| index>> [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 <<primsrast-polygons-basic,back-facing>> |
| <<primsrast-polygons,polygons>>, and the front stencil state when processing |
| fragments generated by <<primsrast-polygons-basic,front-facing polygons>> 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 |
| <<fragops-depth, depth test>> - 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 <<pipelines-dynamic-state, dynamically enable or disable>> 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 <<shaders-objects, shader objects>>, or] |
| ifndef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[when drawing using <<shaders-objects, shader objects>>.] |
| 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 <<pipelines-dynamic-state, dynamically set>> 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 <<shaders-objects, shader objects>>, or] |
| ifndef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[when drawing using <<shaders-objects, shader objects>>.] |
| 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 <<pipelines-dynamic-state, dynamically set>> 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 <<shaders-objects, shader objects>>, 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 <<SCID-8>> |
| // 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 <<pipelines-dynamic-state, dynamically set>> 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 <<shaders-objects, shader objects>>, 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 <<pipelines-dynamic-state, dynamically set>> 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 <<shaders-objects, shader objects>>, 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 |
| <<primsrast-multisampling-coverage-mask, sample index>> [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 <<pipelines-dynamic-state, dynamically enable or disable>> 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 <<shaders-objects, shader objects>>, or] |
| ifndef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[when drawing using <<shaders-objects, shader objects>>.] |
| 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 <<pipelines-dynamic-state, dynamically set>> 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 <<fragops-depth-comparison, Depth |
| Comparison>> step of the <<fragops-depth,depth test>>. |
| |
| 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 <<shaders-objects, shader objects>>, or] |
| ifndef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[when drawing using <<shaders-objects, shader objects>>.] |
| 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 <<pipelines-dynamic-state, dynamically set>> 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 <<shaders-objects, shader objects>>, or] |
| ifndef::VK_VERSION_1_3,VK_EXT_extended_dynamic_state[when drawing using <<shaders-objects, shader objects>>.] |
| 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 <<pipelines-dynamic-state, dynamically set>> 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 <<shaders-objects, shader objects>>, or] |
| ifndef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>.] |
| 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 |
| <<queries-occlusion,Occlusion Queries>>. |
| |
| 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 |
| <<primsrast-multisampling-coverage-mask, coverage mask>> 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 <<pipelines-dynamic-state, dynamically set>> 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 <<shaders-objects, shader objects>>, or] |
| ifndef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>.] |
| 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 <<pipelines-dynamic-state, dynamically set>> 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 <<shaders-objects, shader objects>>, or] |
| ifndef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>.] |
| 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 |
| <<primsrast-multisampling-coverage-mask, sample index>>. |
| 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 <<primsrast-shading-rate-image,shading rate image>> 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 <<primsrast-multisampling-coverage-mask, sample index [eq]#i#>>. |
| endif::VK_NV_shading_rate_image[] |
| |
| ifdef::VK_KHR_fragment_shading_rate[] |
| If the <<primsrast-fragment-shading-rate, fragment shading rate>> is set, |
| and the fragment covers multiple pixels, each pixel's coverage consists of |
| the coverage samples with a <<primsrast-multisampling-coverage-mask-vrfs, |
| pixel index>> matching that pixel, and each sample retains its unique |
| <<primsrast-multisampling-coverage-mask, sample index [eq]#i#>>. |
| 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 |
| <<primsrast-multisampling-coverage-mask, sample index>> [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 |
| <<primsrast-multisampling-coverage-mask, sample index>> [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 |
| <<primsrast-multisampling-coverage-mask, sample index>> [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 <<pipelines-dynamic-state, dynamically set>> 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 <<shaders-objects, shader objects>>, or] |
| ifndef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>.] |
| 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 <<fragops-coverage-reduction, coverage reduction mode>> 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 <<pipelines-dynamic-state, dynamically set>> 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 <<shaders-objects, shader objects>>, or] |
| ifndef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>.] |
| 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 <<pipelines-dynamic-state, dynamically set>> 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 <<shaders-objects, shader objects>>, or] |
| ifndef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>.] |
| 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 <<pipelines-dynamic-state, dynamically set>> 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 <<shaders-objects, shader objects>>, or] |
| ifndef::VK_EXT_extended_dynamic_state3[when drawing using <<shaders-objects, shader objects>>.] |
| 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[] |
