| // Copyright 2015-2021 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>> |
| ** <<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_KHR_shader_terminate_invocation[] |
| * code:OpTerminateInvocation |
| endif::VK_KHR_shader_terminate_invocation[] |
| ifdef::VK_EXT_shader_demote_to_helper_invocation[] |
| * code:OpDemoteToHelperInvocationEXT |
| endif::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 the <<fragops-shader, fragment shader>> 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[] |
| |
| If the <<fragops-shader, fragment shader>> declares the |
| code:EarlyFragmentTests execution mode, <<fragops-shader,fragment shading>> |
| and <<fragops-covg, multisample coverage>> operations are instead performed |
| after <<fragops-samplecount, sample counting>>. |
| |
| 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::offset.x, slink:VkRect2D::offset.x {plus} |
| slink:VkRect2D::extent.x)#, and [eq]#y~f~# is in the range |
| [eq]#[slink:VkRect2D::offset.y, slink:VkRect2D::offset.y {plus} |
| slink:VkRect2D::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.txt[] |
| |
| * pname:sType is the type of 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. |
| |
| When this structure is included in the pname:pNext chain of |
| slink:VkGraphicsPipelineCreateInfo, it defines parameters of the discard |
| rectangle test. |
| If 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.txt[] |
| -- |
| |
| [open,refpage='VkPipelineDiscardRectangleStateCreateFlagsEXT',desc='Reserved for future use',type='flags'] |
| -- |
| include::{generated}/api/flags/VkPipelineDiscardRectangleStateCreateFlagsEXT.txt[] |
| |
| 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.txt[] |
| |
| * 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.txt[] |
| |
| * 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 |
| 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.txt[] |
| -- |
| 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::offset.x, slink:VkRect2D::offset.x {plus} |
| slink:VkRect2D::extent.x)#, and [eq]#y~f~# is in the range |
| [eq]#[slink:VkRect2D::offset.y, slink:VkRect2D::offset.y {plus} |
| slink:VkRect2D::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.txt[] |
| |
| * 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 |
| 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,multiple viewports>> feature is not |
| enabled, pname:firstScissor must: be `0` |
| * [[VUID-vkCmdSetScissor-scissorCount-00594]] |
| If the <<features-multiViewport,multiple viewports>> 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.txt[] |
| -- |
| |
| |
| 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::offset.x, |
| slink:VkRect2D::offset.x {plus} slink:VkRect2D::extent.x)#, and [eq]#y~f~# |
| is in the range [eq]#[slink:VkRect2D::offset.y, slink:VkRect2D::offset.y |
| {plus} slink:VkRect2D::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.txt[] |
| |
| * pname:sType is the type of 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,multiple viewports>> 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.txt[] |
| -- |
| |
| [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.txt[] |
| |
| * 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 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,exclusive scissor>> 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,multiple viewports>> feature is not |
| enabled, pname:firstExclusiveScissor must: be `0` |
| * [[VUID-vkCmdSetExclusiveScissorNV-exclusiveScissorCount-02036]] |
| If the <<features-multiViewport,multiple viewports>> 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.txt[] |
| -- |
| 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. |
| |
| 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. |
| |
| |
| [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. |
| |
| |
| [[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. |
| |
| 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 buffers, or |
| by 1.0 for floating-point buffers. |
| 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.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:flags is reserved for future use. |
| * 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 the comparison operator used in 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 control the 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,depth bounds testing>> 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[] |
| **** |
| |
| include::{generated}/validity/structs/VkPipelineDepthStencilStateCreateInfo.txt[] |
| -- |
| |
| [open,refpage='VkPipelineDepthStencilStateCreateFlags',desc='Reserved for future use',type='flags'] |
| -- |
| include::{generated}/api/flags/VkPipelineDepthStencilStateCreateFlags.txt[] |
| |
| tname:VkPipelineDepthStencilStateCreateFlags is a bitmask type for setting a |
| mask, but is currently reserved for future use. |
| -- |
| |
| |
| [[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_EXT_extended_dynamic_state[] |
| flink:vkCmdSetDepthBoundsTestEnableEXT and |
| endif::VK_EXT_extended_dynamic_state[] |
| 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_EXT_extended_dynamic_state[] |
| [open,refpage='vkCmdSetDepthBoundsTestEnableEXT',desc='Set depth bounds test enable dynamically for a command buffer',type='protos'] |
| -- |
| To <<pipelines-dynamic-state, dynamically enable or disable>> the depth |
| bounds test, call: |
| |
| include::{generated}/api/protos/vkCmdSetDepthBoundsTestEnableEXT.txt[] |
| |
| * 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 |
| when the graphics pipeline is created with |
| ename:VK_DYNAMIC_STATE_DEPTH_BOUNDS_TEST_ENABLE_EXT set in |
| slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. |
| Otherwise, this state is specified by the |
| slink:VkPipelineDepthStencilStateCreateInfo::pname:depthBoundsTestEnable |
| value used to create the currently active pipeline. |
| |
| .Valid Usage |
| **** |
| * [[VUID-vkCmdSetDepthBoundsTestEnableEXT-None-03349]] |
| The <<features-extendedDynamicState, extendedDynamicState>> feature |
| must: be enabled |
| **** |
| |
| include::{generated}/validity/protos/vkCmdSetDepthBoundsTestEnableEXT.txt[] |
| -- |
| endif::VK_EXT_extended_dynamic_state[] |
| |
| [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.txt[] |
| |
| * 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 |
| 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 |
| **** |
| ifdef::VK_EXT_depth_range_unrestricted[] |
| * [[VUID-vkCmdSetDepthBounds-minDepthBounds-00600]] |
| Unless the `apiext:VK_EXT_depth_range_unrestricted` extension is enabled |
| pname:minDepthBounds must: be between `0.0` and `1.0`, inclusive |
| endif::VK_EXT_depth_range_unrestricted[] |
| ifndef::VK_EXT_depth_range_unrestricted[] |
| * [[VUID-vkCmdSetDepthBounds-minDepthBounds-02508]] |
| pname:minDepthBounds must: be between `0.0` and `1.0`, inclusive |
| endif::VK_EXT_depth_range_unrestricted[] |
| ifdef::VK_EXT_depth_range_unrestricted[] |
| * [[VUID-vkCmdSetDepthBounds-maxDepthBounds-00601]] |
| Unless the `apiext:VK_EXT_depth_range_unrestricted` extension is enabled |
| pname:maxDepthBounds must: be between `0.0` and `1.0`, inclusive |
| endif::VK_EXT_depth_range_unrestricted[] |
| ifndef::VK_EXT_depth_range_unrestricted[] |
| * [[VUID-vkCmdSetDepthBounds-maxDepthBounds-02509]] |
| pname:maxDepthBounds must: be between `0.0` and `1.0`, inclusive |
| endif::VK_EXT_depth_range_unrestricted[] |
| **** |
| |
| include::{generated}/validity/protos/vkCmdSetDepthBounds.txt[] |
| -- |
| |
| |
| [[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_EXT_extended_dynamic_state[] |
| flink:vkCmdSetStencilTestEnableEXT or |
| endif::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 performed is based on the elink:VkCompareOp, compare mask |
| [eq]#s~c~# , and stencil reference value [eq]#s~r~# of the relevant state |
| set. |
| The compare mask and stencil reference value are set by either the |
| slink:VkPipelineDepthStencilStateCreateInfo structure during pipeline |
| creation, or by the flink:vkCmdSetStencilCompareMask and |
| flink:vkCmdSetStencilReference commands respectively. |
| The compare operation is set by slink:VkStencilOpState::pname:compareOp |
| during pipeline creation. |
| |
| The stencil reference and attachment values [eq]#s~r~# and [eq]#s~a~# are |
| each independently combined with the compare mask [eq]#s~c~# using a logical |
| 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 [eq]#A# and [eq]#B#, respectively, |
| in the operation specified by 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_EXT_extended_dynamic_state[] |
| flink:vkCmdSetStencilOpEXT or |
| endif::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 |
| slink:VkPipelineDepthStencilStateCreateInfo::pname:writeMask as: |
| |
| {empty}:: [eq]#s~a~ = (s~a~ & ¬s~w~) | (s~g~ & s~w~)# |
| |
| If there is no stencil attachment, no value is written. |
| |
| ifdef::VK_EXT_extended_dynamic_state[] |
| |
| [open,refpage='vkCmdSetStencilTestEnableEXT',desc='Set stencil test enable dynamically for a command buffer',type='protos'] |
| -- |
| To <<pipelines-dynamic-state, dynamically enable or disable>> the stencil |
| test, call: |
| |
| include::{generated}/api/protos/vkCmdSetStencilTestEnableEXT.txt[] |
| |
| * 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 |
| when the graphics pipeline is created with |
| ename:VK_DYNAMIC_STATE_STENCIL_TEST_ENABLE_EXT set in |
| slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. |
| Otherwise, this state is specified by the |
| slink:VkPipelineDepthStencilStateCreateInfo::pname:stencilTestEnable value |
| used to create the currently active pipeline. |
| |
| .Valid Usage |
| **** |
| * [[VUID-vkCmdSetStencilTestEnableEXT-None-03350]] |
| The <<features-extendedDynamicState, extendedDynamicState>> feature |
| must: be enabled |
| **** |
| |
| include::{generated}/validity/protos/vkCmdSetStencilTestEnableEXT.txt[] |
| -- |
| |
| [open,refpage='vkCmdSetStencilOpEXT',desc='Set stencil operation dynamically for a command buffer',type='protos'] |
| -- |
| To <<pipelines-dynamic-state, dynamically set>> the stencil operation, call: |
| |
| include::{generated}/api/protos/vkCmdSetStencilOpEXT.txt[] |
| |
| * 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 |
| the graphics pipeline is created with ename:VK_DYNAMIC_STATE_STENCIL_OP_EXT |
| set in slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. |
| 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. |
| |
| .Valid Usage |
| **** |
| * [[VUID-vkCmdSetStencilOpEXT-None-03351]] |
| The <<features-extendedDynamicState, extendedDynamicState>> feature |
| must: be enabled |
| **** |
| |
| include::{generated}/validity/protos/vkCmdSetStencilOpEXT.txt[] |
| -- |
| |
| endif::VK_EXT_extended_dynamic_state[] |
| |
| [open,refpage='VkStencilOpState',desc='Structure specifying stencil operation state',type='structs'] |
| -- |
| The sname:VkStencilOpState structure is defined as: |
| |
| include::{generated}/api/structs/VkStencilOpState.txt[] |
| |
| * 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 reference value that is used in the |
| unsigned stencil comparison. |
| |
| include::{generated}/validity/structs/VkStencilOpState.txt[] |
| -- |
| |
| [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.txt[] |
| |
| * 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 |
| 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:VkPipelineDepthStencilStateCreateInfo::pname:compareMask value used to |
| create the currently active pipeline, for both front and back faces. |
| |
| include::{generated}/validity/protos/vkCmdSetStencilCompareMask.txt[] |
| -- |
| |
| [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.txt[] |
| |
| * 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. |
| |
| -- |
| |
| [open,refpage='VkStencilFaceFlags',desc='Bitmask of VkStencilFaceFlagBits',type='flags'] |
| -- |
| include::{generated}/api/flags/VkStencilFaceFlags.txt[] |
| |
| 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.txt[] |
| |
| * 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 |
| 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 |
| slink:VkPipelineDepthStencilStateCreateInfo::pname:writeMask value used to |
| create the currently active pipeline, for both front and back faces. |
| |
| include::{generated}/validity/protos/vkCmdSetStencilWriteMask.txt[] |
| -- |
| |
| [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.txt[] |
| |
| * 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 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.txt[] |
| -- |
| |
| [open,refpage='VkCompareOp',desc='Stencil comparison function',type='enums'] |
| -- |
| Possible values of slink:VkStencilOpState::pname:compareOp, specifying the |
| stencil comparison function, are: |
| |
| include::{generated}/api/enums/VkCompareOp.txt[] |
| |
| * ename:VK_COMPARE_OP_NEVER specifies that the test evaluates to false. |
| * ename:VK_COMPARE_OP_LESS specifies that the test evaluates [eq]#A < B#. |
| * ename:VK_COMPARE_OP_EQUAL specifies that the test evaluates [eq]#A = B#. |
| * ename:VK_COMPARE_OP_LESS_OR_EQUAL specifies that the test evaluates |
| [eq]#A {leq} B#. |
| * ename:VK_COMPARE_OP_GREATER specifies that the test evaluates [eq]#A > |
| B#. |
| * ename:VK_COMPARE_OP_NOT_EQUAL specifies that the test evaluates [eq]#A |
| {neq} B#. |
| * ename:VK_COMPARE_OP_GREATER_OR_EQUAL specifies that the test evaluates |
| [eq]#A {geq} B#. |
| * ename:VK_COMPARE_OP_ALWAYS specifies that the test evaluates to true. |
| -- |
| |
| [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.txt[] |
| |
| * 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, before the sample's [eq]#z~f~# is compared to [eq]#z~a~#, |
| [eq]#z~f~# is clamped to [eq]#[min(n,f),max(n,f)]#, where [eq]#n# and |
| [eq]#f# are the pname:minDepth and pname:maxDepth depth range values of the |
| viewport used by this fragment, respectively. |
| |
| If depth clamping is not enabled and [eq]#z~f~# is not in the range [eq]#[0, |
| 1]# |
| ifdef::VK_EXT_depth_range_unrestricted[] |
| and either apiext:VK_EXT_depth_range_unrestricted is not enabled, or the |
| depth attachment has a fixed-point format, |
| endif::VK_EXT_depth_range_unrestricted[] |
| then [eq]#z~f~# is undefined: following this step. |
| |
| |
| === Depth Comparison |
| |
| If the depth test is not enabled, as specified by |
| ifdef::VK_EXT_extended_dynamic_state[] |
| flink:vkCmdSetDepthTestEnableEXT or |
| endif::VK_EXT_extended_dynamic_state[] |
| slink:VkPipelineDepthStencilStateCreateInfo::pname:depthTestEnable, then |
| this step is skipped. |
| |
| The comparison performed is based on the elink:VkCompareOp, set by |
| ifdef::VK_EXT_extended_dynamic_state[] |
| flink:vkCmdSetDepthCompareOpEXT or |
| endif::VK_EXT_extended_dynamic_state[] |
| slink:VkPipelineDepthStencilStateCreateInfo::pname:depthCompareOp during |
| pipeline creation. |
| [eq]#z~f~# and [eq]#z~a~# are used as [eq]#A# and [eq]#B#, 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 Buffer Writes |
| |
| If depth writes are enabled, as specified by |
| ifdef::VK_EXT_extended_dynamic_state[] |
| flink:vkCmdSetDepthWriteEnableEXT or |
| endif::VK_EXT_extended_dynamic_state[] |
| 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_EXT_extended_dynamic_state[] |
| [open,refpage='vkCmdSetDepthTestEnableEXT',desc='Set depth test enable dynamically for a command buffer',type='protos'] |
| -- |
| To <<pipelines-dynamic-state, dynamically enable or disable>> the depth |
| test, call: |
| |
| include::{generated}/api/protos/vkCmdSetDepthTestEnableEXT.txt[] |
| |
| * 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 when |
| the graphics pipeline is created with |
| ename:VK_DYNAMIC_STATE_DEPTH_TEST_ENABLE_EXT set in |
| slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. |
| Otherwise, this state is specified by the |
| slink:VkPipelineDepthStencilStateCreateInfo::pname:depthTestEnable value |
| used to create the currently active pipeline. |
| |
| .Valid Usage |
| **** |
| * [[VUID-vkCmdSetDepthTestEnableEXT-None-03352]] |
| The <<features-extendedDynamicState, extendedDynamicState>> feature |
| must: be enabled |
| **** |
| |
| include::{generated}/validity/protos/vkCmdSetDepthTestEnableEXT.txt[] |
| -- |
| |
| [open,refpage='vkCmdSetDepthCompareOpEXT',desc='Set depth comparison operator dynamically for a command buffer',type='protos'] |
| -- |
| To <<pipelines-dynamic-state, dynamically set>> the depth compare operator, |
| call: |
| |
| include::{generated}/api/protos/vkCmdSetDepthCompareOpEXT.txt[] |
| |
| * pname:commandBuffer is the command buffer into which the command will be |
| recorded. |
| * pname:depthCompareOp specifies the depth comparison operator. |
| |
| This command sets the depth comparison operator for subsequent drawing |
| commands when the graphics pipeline is created with |
| ename:VK_DYNAMIC_STATE_DEPTH_COMPARE_OP_EXT set in |
| slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. |
| Otherwise, this state is specified by the |
| slink:VkPipelineDepthStencilStateCreateInfo::pname:depthCompareOp value used |
| to create the currently active pipeline. |
| |
| .Valid Usage |
| **** |
| * [[VUID-vkCmdSetDepthCompareOpEXT-None-03353]] |
| The <<features-extendedDynamicState, extendedDynamicState>> feature |
| must: be enabled |
| **** |
| |
| include::{generated}/validity/protos/vkCmdSetDepthCompareOpEXT.txt[] |
| -- |
| |
| [open,refpage='vkCmdSetDepthWriteEnableEXT',desc='Set depth write enable dynamically for a command buffer',type='protos'] |
| -- |
| To <<pipelines-dynamic-state, dynamically set>> the depth write enable, |
| call: |
| |
| include::{generated}/api/protos/vkCmdSetDepthWriteEnableEXT.txt[] |
| |
| * 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 |
| when the graphics pipeline is created with |
| ename:VK_DYNAMIC_STATE_DEPTH_WRITE_ENABLE_EXT set in |
| slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. |
| Otherwise, this state is specified by the |
| slink:VkPipelineDepthStencilStateCreateInfo::pname:depthWriteEnable value |
| used to create the currently active pipeline. |
| |
| .Valid Usage |
| **** |
| * [[VUID-vkCmdSetDepthWriteEnableEXT-None-03354]] |
| The <<features-extendedDynamicState, extendedDynamicState>> feature |
| must: be enabled |
| **** |
| |
| include::{generated}/validity/protos/vkCmdSetDepthWriteEnableEXT.txt[] |
| -- |
| endif::VK_EXT_extended_dynamic_state[] |
| |
| |
| 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 that control the representative fragment |
| test. |
| |
| The sname:VkPipelineRepresentativeFragmentTestStateCreateInfoNV structure is |
| defined as: |
| |
| include::{generated}/api/structs/VkPipelineRepresentativeFragmentTestStateCreateInfoNV.txt[] |
| |
| * pname:sType is the type of 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 specifies the code:EarlyFragmentTests |
| execution mode, the representative fragment shader test has no effect, even |
| if enabled. |
| |
| include::{generated}/validity/structs/VkPipelineRepresentativeFragmentTestStateCreateInfoNV.txt[] |
| -- |
| |
| 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.txt[] |
| |
| * pname:sType is the type of 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.txt[] |
| -- |
| |
| [open,refpage='VkPipelineCoverageToColorStateCreateFlagsNV',desc='Reserved for future use',type='flags'] |
| -- |
| include::{generated}/api/flags/VkPipelineCoverageToColorStateCreateFlagsNV.txt[] |
| |
| tname:VkPipelineCoverageToColorStateCreateFlagsNV is a bitmask type for |
| setting a mask, but is currently reserved for future use. |
| -- |
| 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 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_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.txt[] |
| |
| * pname:sType is the type of 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.txt[] |
| -- |
| |
| [open,refpage='VkPipelineCoverageReductionStateCreateFlagsNV',desc='Reserved for future use',type='flags'] |
| -- |
| include::{generated}/api/flags/VkPipelineCoverageReductionStateCreateFlagsNV.txt[] |
| |
| 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.txt[] |
| |
| * 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. |
| -- |
| |
| [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.txt[] |
| |
| * 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.txt[] |
| -- |
| |
| [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.txt[] |
| |
| * pname:sType is the type of 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.txt[] |
| -- |
| 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.txt[] |
| |
| * pname:sType is the type of 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.txt[] |
| -- |
| |
| [open,refpage='VkPipelineCoverageModulationStateCreateFlagsNV',desc='Reserved for future use',type='flags'] |
| -- |
| include::{generated}/api/flags/VkPipelineCoverageModulationStateCreateFlagsNV.txt[] |
| |
| 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.txt[] |
| |
| * 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. |
| -- |
| |
| endif::VK_NV_framebuffer_mixed_samples[] |
