27. 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 rasterization order, and are typically performed in this order:

  1. Discard rectangles test

  2. Scissor test

  3. Exclusive scissor test

  4. Sample mask test

  5. Fragment shading

  6. Multisample coverage

  7. Depth bounds test

  8. Stencil test

  9. Depth test

  10. Representative fragment test

  11. Sample counting

  12. Coverage to color

  13. Coverage reduction

  14. Coverage modulation

The 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 OpDemoteToHelperInvocationEXT or OpKill.

If post-depth coverage is enabled, the sample mask test is instead performed after the depth test.

If early per-fragment operations are enabled, fragment shading and multisample coverage operations are instead performed after sample counting.

Once all fragment operations have completed, fragment shader outputs for covered color attachment samples pass through framebuffer operations.

27.1. Discard Rectangles Test

The discard rectangle test compares the framebuffer coordinates (xf,yf) of each sample covered by a fragment against a set of discard rectangles.

Each discard rectangle is defined by a VkRect2D. These values are either set by the VkPipelineDiscardRectangleStateCreateInfoEXT structure during pipeline creation, or dynamically by the vkCmdSetDiscardRectangleEXT command.

A given sample is considered inside a discard rectangle if the xf is in the range [VkRect2D::offset.x, VkRect2D::offset.x + VkRect2D::extent.x), and yf is in the range [VkRect2D::offset.y, VkRect2D::offset.y + VkRect2D::extent.y). If the test is set to be inclusive, samples that are not inside any of the discard rectangles will have their coverage set to 0. If the test is set to be exclusive, samples that are inside any of the discard rectangles will have their coverage set to 0.

If no discard rectangles are specified, the coverage mask is unmodified by this operation.

The VkPipelineDiscardRectangleStateCreateInfoEXT structure is defined as:

// Provided by VK_EXT_discard_rectangles
typedef struct VkPipelineDiscardRectangleStateCreateInfoEXT {
    VkStructureType                                  sType;
    const void*                                      pNext;
    VkPipelineDiscardRectangleStateCreateFlagsEXT    flags;
    VkDiscardRectangleModeEXT                        discardRectangleMode;
    uint32_t                                         discardRectangleCount;
    const VkRect2D*                                  pDiscardRectangles;
} VkPipelineDiscardRectangleStateCreateInfoEXT;

  • sType is the type of this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • flags is reserved for future use.

  • discardRectangleMode is a VkDiscardRectangleModeEXT value determining whether the discard rectangle test is inclusive or exclusive.

  • discardRectangleCount is the number of discard rectangles to use.

  • pDiscardRectangles is a pointer to an array of VkRect2D structures defining discard rectangles.

If the VK_DYNAMIC_STATE_DISCARD_RECTANGLE_EXT dynamic state is enabled for a pipeline, the pDiscardRectangles member is ignored.

When this structure is included in the pNext chain of VkGraphicsPipelineCreateInfo, it defines parameters of the discard rectangle test. If this structure is not included in the pNext chain, it is equivalent to specifying this structure with a discardRectangleCount of 0.

Valid Usage

  • discardRectangleCount must be less than or equal to VkPhysicalDeviceDiscardRectanglePropertiesEXT::maxDiscardRectangles

Valid Usage (Implicit)

  • sType must be VK_STRUCTURE_TYPE_PIPELINE_DISCARD_RECTANGLE_STATE_CREATE_INFO_EXT

  • flags must be 0

  • discardRectangleMode must be a valid VkDiscardRectangleModeEXT value

// Provided by VK_EXT_discard_rectangles
typedef VkFlags VkPipelineDiscardRectangleStateCreateFlagsEXT;

VkPipelineDiscardRectangleStateCreateFlagsEXT is a bitmask type for setting a mask, but is currently reserved for future use.

VkDiscardRectangleModeEXT values are:

// Provided by VK_EXT_discard_rectangles
typedef enum VkDiscardRectangleModeEXT {
    VK_DISCARD_RECTANGLE_MODE_INCLUSIVE_EXT = 0,
    VK_DISCARD_RECTANGLE_MODE_EXCLUSIVE_EXT = 1,
} VkDiscardRectangleModeEXT;

  • VK_DISCARD_RECTANGLE_MODE_INCLUSIVE_EXT specifies that the discard rectangle test is inclusive.

  • VK_DISCARD_RECTANGLE_MODE_EXCLUSIVE_EXT specifies that the discard rectangle test is exclusive.

The discard rectangles can be set dynamically with the command:

// Provided by VK_EXT_discard_rectangles
void vkCmdSetDiscardRectangleEXT(
    VkCommandBuffer                             commandBuffer,
    uint32_t                                    firstDiscardRectangle,
    uint32_t                                    discardRectangleCount,
    const VkRect2D*                             pDiscardRectangles);

  • commandBuffer is the command buffer into which the command will be recorded.

  • firstDiscardRectangle is the index of the first discard rectangle whose state is updated by the command.

  • discardRectangleCount is the number of discard rectangles whose state are updated by the command.

  • pDiscardRectangles is a pointer to an array of VkRect2D structures specifying discard rectangles.

The discard rectangle taken from element i of pDiscardRectangles replace the current state for the discard rectangle at index firstDiscardRectangle + i, for i in [0, discardRectangleCount).

This command sets the state for a given draw when the graphics pipeline is created with VK_DYNAMIC_STATE_DISCARD_RECTANGLE_EXT set in VkPipelineDynamicStateCreateInfo::pDynamicStates.

Valid Usage

  • The sum of firstDiscardRectangle and discardRectangleCount must be less than or equal to VkPhysicalDeviceDiscardRectanglePropertiesEXT::maxDiscardRectangles

  • The x and y member of offset in each VkRect2D element of pDiscardRectangles must be greater than or equal to 0

  • Evaluation of (offset.x + extent.width) in each VkRect2D element of pDiscardRectangles must not cause a signed integer addition overflow

  • Evaluation of (offset.y + extent.height) in each VkRect2D element of pDiscardRectangles must not cause a signed integer addition overflow

Valid Usage (Implicit)

  • commandBuffer must be a valid VkCommandBuffer handle

  • pDiscardRectangles must be a valid pointer to an array of discardRectangleCount VkRect2D structures

  • commandBuffer must be in the recording state

  • The VkCommandPool that commandBuffer was allocated from must support graphics operations

  • discardRectangleCount must be greater than 0

Host Synchronization

  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Supported Queue Types Pipeline Type

Primary
Secondary

Both

Graphics

27.2. Scissor Test

The scissor test compares the framebuffer coordinates (xf,yf) of each sample covered by a fragment against a scissor rectangle at the index equal to the fragment’s ViewportIndex.

Each scissor rectangle is defined by a VkRect2D. These values are either set by the VkPipelineViewportStateCreateInfo structure during pipeline creation, or dynamically by the vkCmdSetScissor command.

A given sample is considered inside a scissor rectangle if xf is in the range [VkRect2D::offset.x, VkRect2D::offset.x + VkRect2D::extent.x), and yf is in the range [VkRect2D::offset.y, VkRect2D::offset.y + VkRect2D::extent.y). Samples with coordinates outside the scissor rectangle at the corresponding ViewportIndex will have their coverage set to 0.

If a render pass transform is enabled, the (offset.x and offset.y) and (extent.width and extent.height) values are transformed as described in render pass transform before participating in the scissor test.

The scissor rectangles can be set dynamically with the command:

// Provided by VK_VERSION_1_0
void vkCmdSetScissor(
    VkCommandBuffer                             commandBuffer,
    uint32_t                                    firstScissor,
    uint32_t                                    scissorCount,
    const VkRect2D*                             pScissors);

  • commandBuffer is the command buffer into which the command will be recorded.

  • firstScissor is the index of the first scissor whose state is updated by the command.

  • scissorCount is the number of scissors whose rectangles are updated by the command.

  • pScissors is a pointer to an array of VkRect2D structures defining scissor rectangles.

The scissor rectangles taken from element i of pScissors replace the current state for the scissor index firstScissor + i, for i in [0, scissorCount).

This command sets the state for a given draw when the graphics pipeline is created with VK_DYNAMIC_STATE_SCISSOR set in VkPipelineDynamicStateCreateInfo::pDynamicStates.

Valid Usage

  • firstScissor must be less than VkPhysicalDeviceLimits::maxViewports

  • The sum of firstScissor and scissorCount must be between 1 and VkPhysicalDeviceLimits::maxViewports, inclusive

  • If the multiple viewports feature is not enabled, firstScissor must be 0

  • If the multiple viewports feature is not enabled, scissorCount must be 1

  • The x and y members of offset member of any element of pScissors must be greater than or equal to 0

  • Evaluation of (offset.x + extent.width) must not cause a signed integer addition overflow for any element of pScissors

  • Evaluation of (offset.y + extent.height) must not cause a signed integer addition overflow for any element of pScissors

Valid Usage (Implicit)

  • commandBuffer must be a valid VkCommandBuffer handle

  • pScissors must be a valid pointer to an array of scissorCount VkRect2D structures

  • commandBuffer must be in the recording state

  • The VkCommandPool that commandBuffer was allocated from must support graphics operations

  • scissorCount must be greater than 0

Host Synchronization

  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Supported Queue Types Pipeline Type

Primary
Secondary

Both

Graphics

27.3. Exclusive Scissor Test

The exclusive scissor test compares the framebuffer coordinates (xf,yf) of each sample covered by a fragment against an exclusive scissor rectangle at the index equal to the fragment’s ViewportIndex.

Each exclusive scissor rectangle is defined by a VkRect2D. These values are either set by the VkPipelineViewportExclusiveScissorStateCreateInfoNV structure during pipeline creation, or dynamically by the vkCmdSetExclusiveScissorNV command.

A given sample is considered inside an exclusive scissor rectangle if xf is in the range [VkRect2D::offset.x, VkRect2D::offset.x + VkRect2D::extent.x), and yf is in the range [VkRect2D::offset.y, VkRect2D::offset.y + VkRect2D::extent.y). Samples with coordinates inside the exclusive scissor rectangle at the corresponding ViewportIndex will have their coverage set to 0.

If no exclusive scissor rectangles are specified, the coverage mask is unmodified by this operation.

The VkPipelineViewportExclusiveScissorStateCreateInfoNV structure is defined as:

// Provided by VK_NV_scissor_exclusive
typedef struct VkPipelineViewportExclusiveScissorStateCreateInfoNV {
    VkStructureType    sType;
    const void*        pNext;
    uint32_t           exclusiveScissorCount;
    const VkRect2D*    pExclusiveScissors;
} VkPipelineViewportExclusiveScissorStateCreateInfoNV;

  • sType is the type of this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • exclusiveScissorCount is the number of exclusive scissor rectangles.

  • pExclusiveScissors is a pointer to an array of VkRect2D structures defining exclusive scissor rectangles.

If the VK_DYNAMIC_STATE_EXCLUSIVE_SCISSOR_NV dynamic state is enabled for a pipeline, the pExclusiveScissors member is ignored.

When this structure is included in the pNext chain of VkGraphicsPipelineCreateInfo, it defines parameters of the exclusive scissor test. If this structure is not included in the pNext chain, it is equivalent to specifying this structure with a exclusiveScissorCount of 0.

Valid Usage

  • If the multiple viewports feature is not enabled, exclusiveScissorCount must be 0 or 1

  • exclusiveScissorCount must be less than or equal to VkPhysicalDeviceLimits::maxViewports

  • exclusiveScissorCount must be 0 or identical to the viewportCount member of VkPipelineViewportStateCreateInfo

Valid Usage (Implicit)

  • sType must be VK_STRUCTURE_TYPE_PIPELINE_VIEWPORT_EXCLUSIVE_SCISSOR_STATE_CREATE_INFO_NV

The exclusive scissor rectangles can be set dynamically with the command:

// Provided by VK_NV_scissor_exclusive
void vkCmdSetExclusiveScissorNV(
    VkCommandBuffer                             commandBuffer,
    uint32_t                                    firstExclusiveScissor,
    uint32_t                                    exclusiveScissorCount,
    const VkRect2D*                             pExclusiveScissors);

  • commandBuffer is the command buffer into which the command will be recorded.

  • firstExclusiveScissor is the index of the first exclusive scissor rectangle whose state is updated by the command.

  • exclusiveScissorCount is the number of exclusive scissor rectangles updated by the command.

  • pExclusiveScissors is a pointer to an array of VkRect2D structures defining exclusive scissor rectangles.

The scissor rectangles taken from element i of pExclusiveScissors replace the current state for the scissor index firstExclusiveScissor + i, for i in [0, exclusiveScissorCount).

This command sets the state for a given draw when the graphics pipeline is created with VK_DYNAMIC_STATE_EXCLUSIVE_SCISSOR_NV set in VkPipelineDynamicStateCreateInfo::pDynamicStates.

Valid Usage

  • The exclusive scissor feature must be enabled

  • firstExclusiveScissor must be less than VkPhysicalDeviceLimits::maxViewports

  • The sum of firstExclusiveScissor and exclusiveScissorCount must be between 1 and VkPhysicalDeviceLimits::maxViewports, inclusive

  • If the multiple viewports feature is not enabled, firstExclusiveScissor must be 0

  • If the multiple viewports feature is not enabled, exclusiveScissorCount must be 1

  • The x and y members of offset in each member of pExclusiveScissors must be greater than or equal to 0

  • Evaluation of (offset.x + extent.width) for each member of pExclusiveScissors must not cause a signed integer addition overflow

  • Evaluation of (offset.y + extent.height) for each member of pExclusiveScissors must not cause a signed integer addition overflow

Valid Usage (Implicit)

  • commandBuffer must be a valid VkCommandBuffer handle

  • pExclusiveScissors must be a valid pointer to an array of exclusiveScissorCount VkRect2D structures

  • commandBuffer must be in the recording state

  • The VkCommandPool that commandBuffer was allocated from must support graphics operations

  • exclusiveScissorCount must be greater than 0

Host Synchronization

  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Supported Queue Types Pipeline Type

Primary
Secondary

Both

Graphics

27.4. Sample Mask Test

The sample mask test compares the coverage mask for a fragment with the sample mask defined by VkPipelineMultisampleStateCreateInfo::pSampleMask.

Each bit of the coverage mask is associated with a sample index as described in the rasterization chapter. If the bit in VkPipelineMultisampleStateCreateInfo::pSampleMask which is associated with that same sample index is set to 0, the coverage mask bit is set to 0.

27.5. Multisample Coverage

If a fragment shader is active and its entry point’s interface includes a built-in output variable decorated with SampleMask, but not OverrideCoverageNV, the coverage mask is ANDed with the bits of the SampleMask built-in to generate a new coverage mask. If the SampleMask built-in is also decorated with OverrideCoverageNV, the coverage mask is replaced with the mask bits set in the shader. If sample shading is enabled, bits written to 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 SampleMask in its interface, the coverage mask is not modified.

Next, the fragment alpha value and coverage mask are modified based on the line coverage factor if the lineRasterizationMode member of the VkPipelineRasterizationStateCreateInfo structure is VK_LINE_RASTERIZATION_MODE_RECTANGULAR_SMOOTH_EXT, and the alphaToCoverageEnable and alphaToOneEnable members of the VkPipelineMultisampleStateCreateInfo structure.

All alpha values in this section refer only to the alpha component of the fragment shader output that has a Location and Index decoration of zero (see the Fragment Output Interface section). If that shader output has an integer or unsigned integer type, then these operations are skipped.

If the lineRasterizationMode member of the VkPipelineRasterizationStateCreateInfo structure is 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 smooth line rasterization.

If 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 [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

Using different algorithms at different framebuffer coordinates may help to avoid artifacts caused by regular coverage sample locations.

Next, if alphaToOneEnable is enabled, each alpha value is replaced by the maximum representable alpha value for fixed-point color buffers, or by 1.0 for floating-point buffers. Otherwise, the alpha values are not changed.

27.6. Depth and Stencil Operations

Pipeline state controlling the depth bounds tests, stencil test, and depth test is specified through the members of the VkPipelineDepthStencilStateCreateInfo structure.

The VkPipelineDepthStencilStateCreateInfo structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkPipelineDepthStencilStateCreateInfo {
    VkStructureType                           sType;
    const void*                               pNext;
    VkPipelineDepthStencilStateCreateFlags    flags;
    VkBool32                                  depthTestEnable;
    VkBool32                                  depthWriteEnable;
    VkCompareOp                               depthCompareOp;
    VkBool32                                  depthBoundsTestEnable;
    VkBool32                                  stencilTestEnable;
    VkStencilOpState                          front;
    VkStencilOpState                          back;
    float                                     minDepthBounds;
    float                                     maxDepthBounds;
} VkPipelineDepthStencilStateCreateInfo;

  • sType is the type of this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • flags is reserved for future use.

  • depthTestEnable controls whether depth testing is enabled.

  • depthWriteEnable controls whether depth writes are enabled when depthTestEnable is VK_TRUE. Depth writes are always disabled when depthTestEnable is VK_FALSE.

  • depthCompareOp is the comparison operator used in the depth test.

  • depthBoundsTestEnable controls whether depth bounds testing is enabled.

  • stencilTestEnable controls whether stencil testing is enabled.

  • front and back control the parameters of the stencil test.

  • minDepthBounds is the minimum depth bound used in the depth bounds test.

  • maxDepthBounds is the maximum depth bound used in the depth bounds test.

Valid Usage
Valid Usage (Implicit)

  • sType must be VK_STRUCTURE_TYPE_PIPELINE_DEPTH_STENCIL_STATE_CREATE_INFO

  • pNext must be NULL

  • flags must be 0

  • depthCompareOp must be a valid VkCompareOp value

  • front must be a valid VkStencilOpState structure

  • back must be a valid VkStencilOpState structure

// Provided by VK_VERSION_1_0
typedef VkFlags VkPipelineDepthStencilStateCreateFlags;

VkPipelineDepthStencilStateCreateFlags is a bitmask type for setting a mask, but is currently reserved for future use.

27.7. Depth Bounds Test

The depth bounds test compares the depth value za in the depth/stencil attachment at each sample’s framebuffer coordinates (xf,yf) and sample index i against a set of depth bounds.

The depth bounds are determined by two floating point values defining a minimum (minDepthBounds) and maximum (maxDepthBounds) depth value. These values are either set by the VkPipelineDepthStencilStateCreateInfo structure during pipeline creation, or dynamically by vkCmdSetDepthBoundsTestEnableEXT and vkCmdSetDepthBounds.

A given sample is considered within the depth bounds if za is in the range [minDepthBounds,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.

To dynamically enable or disable the depth bounds test:

// Provided by VK_EXT_extended_dynamic_state
void vkCmdSetDepthBoundsTestEnableEXT(
    VkCommandBuffer                             commandBuffer,
    VkBool32                                    depthBoundsTestEnable);

  • commandBuffer is the command buffer into which the command will be recorded.

  • depthBoundsTestEnable specifies if the depth bounds test is enabled.

This command sets the state for a given draw when the graphics pipeline is created with VK_DYNAMIC_STATE_DEPTH_BOUNDS_TEST_ENABLE_EXT set in VkPipelineDynamicStateCreateInfo::pDynamicStates.

Valid Usage
Valid Usage (Implicit)

  • commandBuffer must be a valid VkCommandBuffer handle

  • commandBuffer must be in the recording state

  • The VkCommandPool that commandBuffer was allocated from must support graphics operations

Host Synchronization

  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Supported Queue Types Pipeline Type

Primary
Secondary

Both

Graphics

To dynamically set the depth bounds range values call:

// Provided by VK_VERSION_1_0
void vkCmdSetDepthBounds(
    VkCommandBuffer                             commandBuffer,
    float                                       minDepthBounds,
    float                                       maxDepthBounds);

  • commandBuffer is the command buffer into which the command will be recorded.

  • minDepthBounds is the minimum depth bound.

  • maxDepthBounds is the maximum depth bound.

This command sets the state for a given draw when the graphics pipeline is created with VK_DYNAMIC_STATE_DEPTH_BOUNDS set in VkPipelineDynamicStateCreateInfo::pDynamicStates.

Valid Usage
Valid Usage (Implicit)

  • commandBuffer must be a valid VkCommandBuffer handle

  • commandBuffer must be in the recording state

  • The VkCommandPool that commandBuffer was allocated from must support graphics operations

Host Synchronization

  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Supported Queue Types Pipeline Type

Primary
Secondary

Both

Graphics

27.8. Stencil Test

The stencil test compares the stencil attachment value sa in the depth/stencil attachment at each sample’s framebuffer coordinates (xf,yf) and sample index i against a stencil reference value.

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.

If the stencil test is not enabled, as specified by vkCmdSetStencilTestEnableEXT or VkPipelineDepthStencilStateCreateInfo::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 back-facing polygons, and the front stencil state when processing fragments generated by front-facing polygons or any other primitives.

The comparison performed is based on the VkCompareOp, compare mask sc , and stencil reference value sr of the relevant state set. The compare mask and stencil reference value are set by either the VkPipelineDepthStencilStateCreateInfo structure during pipeline creation, or by the vkCmdSetStencilCompareMask and vkCmdSetStencilReference commands respectively. The compare operation is set by VkStencilOpState::compareOp during pipeline creation.

The stencil reference and attachment values sr and sa are each independently combined with the compare mask sc using a logical AND operation to create masked reference and attachment values s'r and s'a. s'r and s'a are used as A and B, respectively, in the operation specified by VkCompareOp.

If the comparison evaluates to false, the coverage for the sample is set to 0.

A new stencil value sg is generated according to a stencil operation defined by VkStencilOp parameters set by vkCmdSetStencilOpEXT or VkPipelineDepthStencilStateCreateInfo. If the stencil test fails, failOp defines the stencil operation used. If the stencil test passes however, the stencil op used is based on the depth test - if it passes, VkPipelineDepthStencilStateCreateInfo::passOp is used, otherwise VkPipelineDepthStencilStateCreateInfo::depthFailOp is used.

The stencil attachment value sa is then updated with the generated stencil value sg according to the write mask sw defined by VkPipelineDepthStencilStateCreateInfo::writeMask as:

sa = (sa & ¬sw) | (sg & sw)

To dynamically enable or disable the stencil test, call:

// Provided by VK_EXT_extended_dynamic_state
void vkCmdSetStencilTestEnableEXT(
    VkCommandBuffer                             commandBuffer,
    VkBool32                                    stencilTestEnable);

  • commandBuffer is the command buffer into which the command will be recorded.

  • stencilTestEnable specifies if the stencil test is enabled.

This command sets the state for a given draw when the graphics pipeline is created with VK_DYNAMIC_STATE_STENCIL_TEST_ENABLE_EXT set in VkPipelineDynamicStateCreateInfo::pDynamicStates.

Valid Usage
Valid Usage (Implicit)

  • commandBuffer must be a valid VkCommandBuffer handle

  • commandBuffer must be in the recording state

  • The VkCommandPool that commandBuffer was allocated from must support graphics operations

Host Synchronization

  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Supported Queue Types Pipeline Type

Primary
Secondary

Both

Graphics

To dynamically set the stencil operations, call:

// Provided by VK_EXT_extended_dynamic_state
void vkCmdSetStencilOpEXT(
    VkCommandBuffer                             commandBuffer,
    VkStencilFaceFlags                          faceMask,
    VkStencilOp                                 failOp,
    VkStencilOp                                 passOp,
    VkStencilOp                                 depthFailOp,
    VkCompareOp                                 compareOp);

  • commandBuffer is the command buffer into which the command will be recorded.

  • faceMask is a bitmask of VkStencilFaceFlagBits specifying the set of stencil state for which to update the stencil operation.

  • failOp is a VkStencilOp value specifying the action performed on samples that fail the stencil test.

  • passOp is a VkStencilOp value specifying the action performed on samples that pass both the depth and stencil tests.

  • depthFailOp is a VkStencilOp value specifying the action performed on samples that pass the stencil test and fail the depth test.

  • compareOp is a VkCompareOp value specifying the comparison operator used in the stencil test.

This command sets the state for a given draw when the graphics pipeline is created with VK_DYNAMIC_STATE_STENCIL_OP_EXT set in VkPipelineDynamicStateCreateInfo::pDynamicStates.

Valid Usage
Valid Usage (Implicit)
Host Synchronization

  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Supported Queue Types Pipeline Type

Primary
Secondary

Both

Graphics

The VkStencilOpState structure is defined as:

// Provided by VK_VERSION_1_0
typedef struct VkStencilOpState {
    VkStencilOp    failOp;
    VkStencilOp    passOp;
    VkStencilOp    depthFailOp;
    VkCompareOp    compareOp;
    uint32_t       compareMask;
    uint32_t       writeMask;
    uint32_t       reference;
} VkStencilOpState;

  • failOp is a VkStencilOp value specifying the action performed on samples that fail the stencil test.

  • passOp is a VkStencilOp value specifying the action performed on samples that pass both the depth and stencil tests.

  • depthFailOp is a VkStencilOp value specifying the action performed on samples that pass the stencil test and fail the depth test.

  • compareOp is a VkCompareOp value specifying the comparison operator used in the stencil test.

  • compareMask selects the bits of the unsigned integer stencil values participating in the stencil test.

  • writeMask selects the bits of the unsigned integer stencil values updated by the stencil test in the stencil framebuffer attachment.

  • reference is an integer reference value that is used in the unsigned stencil comparison.

Valid Usage (Implicit)

To dynamically set the stencil compare mask call:

// Provided by VK_VERSION_1_0
void vkCmdSetStencilCompareMask(
    VkCommandBuffer                             commandBuffer,
    VkStencilFaceFlags                          faceMask,
    uint32_t                                    compareMask);

  • commandBuffer is the command buffer into which the command will be recorded.

  • faceMask is a bitmask of VkStencilFaceFlagBits specifying the set of stencil state for which to update the compare mask.

  • compareMask is the new value to use as the stencil compare mask.

This command sets the state for a given draw when the graphics pipeline is created with VK_DYNAMIC_STATE_STENCIL_COMPARE_MASK set in VkPipelineDynamicStateCreateInfo::pDynamicStates.

Valid Usage (Implicit)

  • commandBuffer must be a valid VkCommandBuffer handle

  • faceMask must be a valid combination of VkStencilFaceFlagBits values

  • faceMask must not be 0

  • commandBuffer must be in the recording state

  • The VkCommandPool that commandBuffer was allocated from must support graphics operations

Host Synchronization

  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Supported Queue Types Pipeline Type

Primary
Secondary

Both

Graphics

VkStencilFaceFlagBits values are:

// Provided by VK_VERSION_1_0
typedef enum VkStencilFaceFlagBits {
    VK_STENCIL_FACE_FRONT_BIT = 0x00000001,
    VK_STENCIL_FACE_BACK_BIT = 0x00000002,
    VK_STENCIL_FACE_FRONT_AND_BACK = 0x00000003,
    VK_STENCIL_FRONT_AND_BACK = VK_STENCIL_FACE_FRONT_AND_BACK,
} VkStencilFaceFlagBits;

  • VK_STENCIL_FACE_FRONT_BIT specifies that only the front set of stencil state is updated.

  • VK_STENCIL_FACE_BACK_BIT specifies that only the back set of stencil state is updated.

  • VK_STENCIL_FACE_FRONT_AND_BACK is the combination of VK_STENCIL_FACE_FRONT_BIT and VK_STENCIL_FACE_BACK_BIT, and specifies that both sets of stencil state are updated.

// Provided by VK_VERSION_1_0
typedef VkFlags VkStencilFaceFlags;

VkStencilFaceFlags is a bitmask type for setting a mask of zero or more VkStencilFaceFlagBits.

To dynamically set the stencil write mask call:

// Provided by VK_VERSION_1_0
void vkCmdSetStencilWriteMask(
    VkCommandBuffer                             commandBuffer,
    VkStencilFaceFlags                          faceMask,
    uint32_t                                    writeMask);

  • commandBuffer is the command buffer into which the command will be recorded.

  • faceMask is a bitmask of VkStencilFaceFlagBits specifying the set of stencil state for which to update the write mask, as described above for vkCmdSetStencilCompareMask.

  • writeMask is the new value to use as the stencil write mask.

This command sets the state for a given draw when the graphics pipeline is created with VK_DYNAMIC_STATE_STENCIL_WRITE_MASK set in VkPipelineDynamicStateCreateInfo::pDynamicStates.

Valid Usage (Implicit)

  • commandBuffer must be a valid VkCommandBuffer handle

  • faceMask must be a valid combination of VkStencilFaceFlagBits values

  • faceMask must not be 0

  • commandBuffer must be in the recording state

  • The VkCommandPool that commandBuffer was allocated from must support graphics operations

Host Synchronization

  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Supported Queue Types Pipeline Type

Primary
Secondary

Both

Graphics

To dynamically set the stencil reference value call:

// Provided by VK_VERSION_1_0
void vkCmdSetStencilReference(
    VkCommandBuffer                             commandBuffer,
    VkStencilFaceFlags                          faceMask,
    uint32_t                                    reference);

  • commandBuffer is the command buffer into which the command will be recorded.

  • faceMask is a bitmask of VkStencilFaceFlagBits specifying the set of stencil state for which to update the reference value, as described above for vkCmdSetStencilCompareMask.

  • reference is the new value to use as the stencil reference value.

This command sets the state for a given draw when the graphics pipeline is created with VK_DYNAMIC_STATE_STENCIL_REFERENCE set in VkPipelineDynamicStateCreateInfo::pDynamicStates.

Valid Usage (Implicit)

  • commandBuffer must be a valid VkCommandBuffer handle

  • faceMask must be a valid combination of VkStencilFaceFlagBits values

  • faceMask must not be 0

  • commandBuffer must be in the recording state

  • The VkCommandPool that commandBuffer was allocated from must support graphics operations

Host Synchronization

  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Supported Queue Types Pipeline Type

Primary
Secondary

Both

Graphics

Possible values of VkStencilOpState::compareOp, specifying the stencil comparison function, are:

// Provided by VK_VERSION_1_0
typedef enum VkCompareOp {
    VK_COMPARE_OP_NEVER = 0,
    VK_COMPARE_OP_LESS = 1,
    VK_COMPARE_OP_EQUAL = 2,
    VK_COMPARE_OP_LESS_OR_EQUAL = 3,
    VK_COMPARE_OP_GREATER = 4,
    VK_COMPARE_OP_NOT_EQUAL = 5,
    VK_COMPARE_OP_GREATER_OR_EQUAL = 6,
    VK_COMPARE_OP_ALWAYS = 7,
} VkCompareOp;

  • VK_COMPARE_OP_NEVER specifies that the test evaluates to false.

  • VK_COMPARE_OP_LESS specifies that the test evaluates A < B.

  • VK_COMPARE_OP_EQUAL specifies that the test evaluates A = B.

  • VK_COMPARE_OP_LESS_OR_EQUAL specifies that the test evaluates A ≤ B.

  • VK_COMPARE_OP_GREATER specifies that the test evaluates A > B.

  • VK_COMPARE_OP_NOT_EQUAL specifies that the test evaluates A ≠ B.

  • VK_COMPARE_OP_GREATER_OR_EQUAL specifies that the test evaluates A ≥ B.

  • VK_COMPARE_OP_ALWAYS specifies that the test evaluates to true.

Possible values of the failOp, passOp, and depthFailOp members of VkStencilOpState, specifying what happens to the stored stencil value if this or certain subsequent tests fail or pass, are:

// Provided by VK_VERSION_1_0
typedef enum VkStencilOp {
    VK_STENCIL_OP_KEEP = 0,
    VK_STENCIL_OP_ZERO = 1,
    VK_STENCIL_OP_REPLACE = 2,
    VK_STENCIL_OP_INCREMENT_AND_CLAMP = 3,
    VK_STENCIL_OP_DECREMENT_AND_CLAMP = 4,
    VK_STENCIL_OP_INVERT = 5,
    VK_STENCIL_OP_INCREMENT_AND_WRAP = 6,
    VK_STENCIL_OP_DECREMENT_AND_WRAP = 7,
} VkStencilOp;

  • VK_STENCIL_OP_KEEP keeps the current value.

  • VK_STENCIL_OP_ZERO sets the value to 0.

  • VK_STENCIL_OP_REPLACE sets the value to reference.

  • VK_STENCIL_OP_INCREMENT_AND_CLAMP increments the current value and clamps to the maximum representable unsigned value.

  • VK_STENCIL_OP_DECREMENT_AND_CLAMP decrements the current value and clamps to 0.

  • VK_STENCIL_OP_INVERT bitwise-inverts the current value.

  • VK_STENCIL_OP_INCREMENT_AND_WRAP increments the current value and wraps to 0 when the maximum value would have been exceeded.

  • 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.

27.9. Depth Test

The depth test compares the depth value za in the depth/stencil attachment at each sample’s framebuffer coordinates (xf,yf) and sample index i against the sample’s depth value zf.

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.

If the depth test is not enabled, as specified by vkCmdSetDepthTestEnableEXT or VkPipelineDepthStencilStateCreateInfo::depthTestEnable, or if there is no depth attachment, the coverage mask is unmodified by this operation.

The comparison performed is based on the VkCompareOp, set by vkCmdSetDepthCompareOpEXT or VkPipelineDepthStencilStateCreateInfo::depthCompareOp during pipeline creation. zf and za are used as A and B, respectively, in the operation specified by the VkCompareOp.

If VkPipelineRasterizationStateCreateInfo::depthClampEnable is enabled, before the sample’s zf is compared to za, zf is clamped to [min(n,f),max(n,f)], where n and f are the minDepth and maxDepth depth range values of the viewport used by this fragment, respectively.

If the comparison evaluates to false, the coverage for the sample is set to 0.

If depth writes are enabled, as specified by vkCmdSetDepthWriteEnableEXT or VkPipelineDepthStencilStateCreateInfo::depthWriteEnable, and the comparison evaluated to true, the depth attachment value za is set to the sample’s depth value zf.

If the depth attachment has a fixed-point format and zf is outside of the range [0.0,1.0], it is clamped to that range before writing.

To dynamically enable or disable the depth test, call:

// Provided by VK_EXT_extended_dynamic_state
void vkCmdSetDepthTestEnableEXT(
    VkCommandBuffer                             commandBuffer,
    VkBool32                                    depthTestEnable);

  • commandBuffer is the command buffer into which the command will be recorded.

  • depthTestEnable specifies if the depth test is enabled.

This command sets the state for a given draw when the graphics pipeline is created with VK_DYNAMIC_STATE_DEPTH_TEST_ENABLE_EXT set in VkPipelineDynamicStateCreateInfo::pDynamicStates.

Valid Usage
Valid Usage (Implicit)

  • commandBuffer must be a valid VkCommandBuffer handle

  • commandBuffer must be in the recording state

  • The VkCommandPool that commandBuffer was allocated from must support graphics operations

Host Synchronization

  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Supported Queue Types Pipeline Type

Primary
Secondary

Both

Graphics

To dynamically set the depth compare operations, call:

// Provided by VK_EXT_extended_dynamic_state
void vkCmdSetDepthCompareOpEXT(
    VkCommandBuffer                             commandBuffer,
    VkCompareOp                                 depthCompareOp);

  • commandBuffer is the command buffer into which the command will be recorded.

  • depthCompareOp specifies the depth comparison operator.

This command sets the state for a given draw when the graphics pipeline is created with VK_DYNAMIC_STATE_DEPTH_COMPARE_OP_EXT set in VkPipelineDynamicStateCreateInfo::pDynamicStates.

Valid Usage
Valid Usage (Implicit)

  • commandBuffer must be a valid VkCommandBuffer handle

  • depthCompareOp must be a valid VkCompareOp value

  • commandBuffer must be in the recording state

  • The VkCommandPool that commandBuffer was allocated from must support graphics operations

Host Synchronization

  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Supported Queue Types Pipeline Type

Primary
Secondary

Both

Graphics

To dynamically enable or disable depth writes, call:

// Provided by VK_EXT_extended_dynamic_state
void vkCmdSetDepthWriteEnableEXT(
    VkCommandBuffer                             commandBuffer,
    VkBool32                                    depthWriteEnable);

  • commandBuffer is the command buffer into which the command will be recorded.

  • depthWriteEnable specifies if depth writes are enabled.

This command sets the state for a given draw when the graphics pipeline is created with VK_DYNAMIC_STATE_DEPTH_WRITE_ENABLE_EXT set in VkPipelineDynamicStateCreateInfo::pDynamicStates.

Valid Usage
Valid Usage (Implicit)

  • commandBuffer must be a valid VkCommandBuffer handle

  • commandBuffer must be in the recording state

  • The VkCommandPool that commandBuffer was allocated from must support graphics operations

Host Synchronization

  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Supported Queue Types Pipeline Type

Primary
Secondary

Both

Graphics

27.10. 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.

If the pNext chain of VkGraphicsPipelineCreateInfo includes a VkPipelineRepresentativeFragmentTestStateCreateInfoNV structure, then that structure includes parameters that control the representative fragment test.

The VkPipelineRepresentativeFragmentTestStateCreateInfoNV structure is defined as:

// Provided by VK_NV_representative_fragment_test
typedef struct VkPipelineRepresentativeFragmentTestStateCreateInfoNV {
    VkStructureType    sType;
    const void*        pNext;
    VkBool32           representativeFragmentTestEnable;
} VkPipelineRepresentativeFragmentTestStateCreateInfoNV;

  • sType is the type of this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • representativeFragmentTestEnable controls whether the representative fragment test is enabled.

If this structure is not present, representativeFragmentTestEnable is considered to be VK_FALSE, and the representative fragment test is disabled.

If early fragment tests are not enabled in the active fragment shader, the representative fragment shader test has no effect, even if enabled.

Valid Usage (Implicit)

  • sType must be VK_STRUCTURE_TYPE_PIPELINE_REPRESENTATIVE_FRAGMENT_TEST_STATE_CREATE_INFO_NV

27.11. 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 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, exclusive scissor, sample mask, alpha to coverage, stencil, and depth tests.

27.12. Fragment Coverage To Color

The VkPipelineCoverageToColorStateCreateInfoNV structure is defined as:

// Provided by VK_NV_fragment_coverage_to_color
typedef struct VkPipelineCoverageToColorStateCreateInfoNV {
    VkStructureType                                sType;
    const void*                                    pNext;
    VkPipelineCoverageToColorStateCreateFlagsNV    flags;
    VkBool32                                       coverageToColorEnable;
    uint32_t                                       coverageToColorLocation;
} VkPipelineCoverageToColorStateCreateInfoNV;

  • sType is the type of this structure

  • pNext is NULL or a pointer to a structure extending this structure

  • flags is reserved for future use.

  • coverageToColorEnable controls whether the fragment coverage value replaces a fragment color output.

  • coverageToColorLocation controls which fragment shader color output value is replaced.

If the pNext chain of VkPipelineMultisampleStateCreateInfo includes a 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 coverageToColorEnable is VK_TRUE, the coverage mask replaces the first component of the color value corresponding to the fragment shader output location with Location equal to coverageToColorLocation and 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 coverageToColorEnable is VK_FALSE, these operations are skipped. If this structure is not present, it is as if coverageToColorEnable is VK_FALSE.

Valid Usage

  • If coverageToColorEnable is VK_TRUE, then the render pass subpass indicated by VkGraphicsPipelineCreateInfo::renderPass and VkGraphicsPipelineCreateInfo::subpass must have a color attachment at the location selected by coverageToColorLocation, with a VkFormat of VK_FORMAT_R8_UINT, VK_FORMAT_R8_SINT, VK_FORMAT_R16_UINT, VK_FORMAT_R16_SINT, VK_FORMAT_R32_UINT, or VK_FORMAT_R32_SINT

Valid Usage (Implicit)

  • sType must be VK_STRUCTURE_TYPE_PIPELINE_COVERAGE_TO_COLOR_STATE_CREATE_INFO_NV

  • flags must be 0

// Provided by VK_NV_fragment_coverage_to_color
typedef VkFlags VkPipelineCoverageToColorStateCreateFlagsNV;

VkPipelineCoverageToColorStateCreateFlagsNV is a bitmask type for setting a mask, but is currently reserved for future use.

27.13. 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.

27.13.1. Pixel Coverage

Coverage for each pixel is first extracted from the total fragment coverage mask. This consists of rasterizationSamples unique coverage samples for each pixel in the fragment area, each with a unique sample index. If the fragment only contains a single pixel, coverage for the pixel is equivalent to the fragment coverage.

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.

If a 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 sample index i.

27.13.2. Color Sample Coverage

Once pixel coverage is determined, coverage for each individual color sample corresponding to that pixel is determined.

If the number of rasterizationSamples is identical to the number of samples in the color attachments, a color sample is covered if the pixel coverage sample with the same sample index i is covered. Otherwise, the coverage for each color sample is computed from the pixel coverage as follows.

If the 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 sample index i is covered; additional pixel coverage samples are discarded.

When the VK_NV_coverage_reduction_mode extension is enabled, the pipeline state controlling coverage reduction is specified through the members of the VkPipelineCoverageReductionStateCreateInfoNV structure.

The VkPipelineCoverageReductionStateCreateInfoNV structure is defined as:

// Provided by VK_NV_coverage_reduction_mode
typedef struct VkPipelineCoverageReductionStateCreateInfoNV {
    VkStructureType                                  sType;
    const void*                                      pNext;
    VkPipelineCoverageReductionStateCreateFlagsNV    flags;
    VkCoverageReductionModeNV                        coverageReductionMode;
} VkPipelineCoverageReductionStateCreateInfoNV;

  • sType is the type of this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • flags is reserved for future use.

  • coverageReductionMode is a VkCoverageReductionModeNV value controlling how color sample coverage is generated from pixel coverage.

If this structure is not present, or if the extension is not enabled, the default coverage reduction mode is inferred as follows:

  • If the VK_NV_framebuffer_mixed_samples extension is enabled, then it is as if the coverageReductionMode is VK_COVERAGE_REDUCTION_MODE_MERGE_NV.

  • If the VK_AMD_mixed_attachment_samples extension is enabled, then it is as if the coverageReductionMode is VK_COVERAGE_REDUCTION_MODE_TRUNCATE_NV.

  • If both VK_NV_framebuffer_mixed_samples and VK_AMD_mixed_attachment_samples are enabled, then the default coverage reduction mode is implementation-dependent.

Valid Usage (Implicit)

  • sType must be VK_STRUCTURE_TYPE_PIPELINE_COVERAGE_REDUCTION_STATE_CREATE_INFO_NV

  • flags must be 0

  • coverageReductionMode must be a valid VkCoverageReductionModeNV value

// Provided by VK_NV_coverage_reduction_mode
typedef VkFlags VkPipelineCoverageReductionStateCreateFlagsNV;

VkPipelineCoverageReductionStateCreateFlagsNV is a bitmask type for setting a mask, but is currently reserved for future use.

Possible values of VkPipelineCoverageReductionStateCreateInfoNV::coverageReductionMode, specifying how color sample coverage is generated from pixel coverage, are:

// Provided by VK_NV_coverage_reduction_mode
typedef enum VkCoverageReductionModeNV {
    VK_COVERAGE_REDUCTION_MODE_MERGE_NV = 0,
    VK_COVERAGE_REDUCTION_MODE_TRUNCATE_NV = 1,
} VkCoverageReductionModeNV;

  • 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.

  • 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 sample index i is covered; other pixel coverage samples are discarded.

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:

// Provided by VK_NV_coverage_reduction_mode
VkResult vkGetPhysicalDeviceSupportedFramebufferMixedSamplesCombinationsNV(
    VkPhysicalDevice                            physicalDevice,
    uint32_t*                                   pCombinationCount,
    VkFramebufferMixedSamplesCombinationNV*     pCombinations);

  • physicalDevice is the physical device from which to query the set of combinations.

  • pCombinationCount is a pointer to an integer related to the number of combinations available or queried, as described below.

  • pCombinations is either NULL or a pointer to an array of VkFramebufferMixedSamplesCombinationNV values, indicating the supported combinations of coverage reduction mode, rasterization samples, and color, depth, stencil attachment sample counts.

If pCombinations is NULL, then the number of supported combinations for the given physicalDevice is returned in pCombinationCount. Otherwise, pCombinationCount must point to a variable set by the user to the number of elements in the pCombinations array, and on return the variable is overwritten with the number of values actually written to pCombinations. If the value of pCombinationCount is less than the number of combinations supported for the given physicalDevice, at most pCombinationCount values will be written pCombinations and VK_INCOMPLETE will be returned instead of VK_SUCCESS to indicate that not all the supported values were returned.

Valid Usage (Implicit)

  • physicalDevice must be a valid VkPhysicalDevice handle

  • pCombinationCount must be a valid pointer to a uint32_t value

  • If the value referenced by pCombinationCount is not 0, and pCombinations is not NULL, pCombinations must be a valid pointer to an array of pCombinationCount VkFramebufferMixedSamplesCombinationNV structures

Return Codes
Success

  • VK_SUCCESS

  • VK_INCOMPLETE

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

The VkFramebufferMixedSamplesCombinationNV structure is defined as:

// Provided by VK_NV_coverage_reduction_mode
typedef struct VkFramebufferMixedSamplesCombinationNV {
    VkStructureType              sType;
    void*                        pNext;
    VkCoverageReductionModeNV    coverageReductionMode;
    VkSampleCountFlagBits        rasterizationSamples;
    VkSampleCountFlags           depthStencilSamples;
    VkSampleCountFlags           colorSamples;
} VkFramebufferMixedSamplesCombinationNV;

  • sType is the type of this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • coverageReductionMode is a VkCoverageReductionModeNV value specifying the coverage reduction mode.

  • rasterizationSamples specifies the number of rasterization samples in the supported combination.

  • 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.

  • 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.

Valid Usage (Implicit)

  • sType must be VK_STRUCTURE_TYPE_FRAMEBUFFER_MIXED_SAMPLES_COMBINATION_NV

  • pNext must be NULL

27.13.3. Coverage Modulation

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 VkPipelineCoverageModulationStateCreateInfoNV structure.

The VkPipelineCoverageModulationStateCreateInfoNV structure is defined as:

// Provided by VK_NV_framebuffer_mixed_samples
typedef struct VkPipelineCoverageModulationStateCreateInfoNV {
    VkStructureType                                   sType;
    const void*                                       pNext;
    VkPipelineCoverageModulationStateCreateFlagsNV    flags;
    VkCoverageModulationModeNV                        coverageModulationMode;
    VkBool32                                          coverageModulationTableEnable;
    uint32_t                                          coverageModulationTableCount;
    const float*                                      pCoverageModulationTable;
} VkPipelineCoverageModulationStateCreateInfoNV;

  • sType is the type of this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • flags is reserved for future use.

  • coverageModulationMode is a VkCoverageModulationModeNV value controlling which color components are modulated.

  • coverageModulationTableEnable controls whether the modulation factor is looked up from a table in pCoverageModulationTable.

  • coverageModulationTableCount is the number of elements in pCoverageModulationTable.

  • pCoverageModulationTable is a table of modulation factors containing a value for each number of covered samples.

If coverageModulationTableEnable is 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 R in the range (0,1] (a value of zero would have been killed due to a color coverage of 0). Specifically:

  • N = value of rasterizationSamples

  • M = value of VkAttachmentDescription::samples for any color attachments

  • R = popcount(associated coverage bits) / (N / M)

If coverageModulationTableEnable is VK_TRUE, the value R is computed using a programmable lookup table. The lookup table has N / M elements, and the element of the table is selected by:

  • R = pCoverageModulationTable[popcount(associated coverage bits)-1]

Note that the table does not have an entry for popcount(associated coverage bits) = 0, because such samples would have been killed.

The values of pCoverageModulationTable may be rounded to an implementation-dependent precision, which is at least as fine as 1 / N, and clamped to [0,1].

For each color attachment with a floating point or normalized color format, each fragment output color value is replicated to M values which can each be modulated (multiplied) by that color sample’s associated value of R. Which components are modulated is controlled by coverageModulationMode.

If this structure is not present, it is as if coverageModulationMode is VK_COVERAGE_MODULATION_MODE_NONE_NV.

If the coverage reduction mode is VK_COVERAGE_REDUCTION_MODE_TRUNCATE_NV, each color sample is associated with only a single coverage sample. In this case, it is as if coverageModulationMode is VK_COVERAGE_MODULATION_MODE_NONE_NV.

Valid Usage

  • If coverageModulationTableEnable is VK_TRUE, coverageModulationTableCount must be equal to the number of rasterization samples divided by the number of color samples in the subpass

Valid Usage (Implicit)

  • sType must be VK_STRUCTURE_TYPE_PIPELINE_COVERAGE_MODULATION_STATE_CREATE_INFO_NV

  • flags must be 0

  • coverageModulationMode must be a valid VkCoverageModulationModeNV value

// Provided by VK_NV_framebuffer_mixed_samples
typedef VkFlags VkPipelineCoverageModulationStateCreateFlagsNV;

VkPipelineCoverageModulationStateCreateFlagsNV is a bitmask type for setting a mask, but is currently reserved for future use.

Possible values of VkPipelineCoverageModulationStateCreateInfoNV::coverageModulationMode, specifying which color components are modulated, are:

// Provided by VK_NV_framebuffer_mixed_samples
typedef enum VkCoverageModulationModeNV {
    VK_COVERAGE_MODULATION_MODE_NONE_NV = 0,
    VK_COVERAGE_MODULATION_MODE_RGB_NV = 1,
    VK_COVERAGE_MODULATION_MODE_ALPHA_NV = 2,
    VK_COVERAGE_MODULATION_MODE_RGBA_NV = 3,
} VkCoverageModulationModeNV;

  • VK_COVERAGE_MODULATION_MODE_NONE_NV specifies that no components are multiplied by the modulation factor.

  • VK_COVERAGE_MODULATION_MODE_RGB_NV specifies that the red, green, and blue components are multiplied by the modulation factor.

  • VK_COVERAGE_MODULATION_MODE_ALPHA_NV specifies that the alpha component is multiplied by the modulation factor.

  • VK_COVERAGE_MODULATION_MODE_RGBA_NV specifies that all components are multiplied by the modulation factor.