xref: /third_party/vk-gl-cts/external/vulkan-docs/src/chapters/fragops.adoc (revision e5c31af7)

// Copyright 2015-2024 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.
  ** If a fragment shader statically computes the same values for different
     framebuffer locations, and does not write to any storage resources,
     multiple fragments may: be shaded by one fragment shader invocation.
     This may: affect
     ename:VK_QUERY_PIPELINE_STATISTIC_FRAGMENT_SHADER_INVOCATIONS_BIT
     results, but must: otherwise not be visible behavior to applications.
  * 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[]