Vulkan^® 1.1.114 - A Specification (with all published extensions)

Once fragments are produced by rasterization, a number of per-fragment operations are performed prior to fragment shader execution. If a fragment is discarded during any of these operations, it will not be processed by any subsequent stage, including fragment shader execution.

The scissor test, exclusive scissor test, and sample mask generation are always performed during early fragment tests.

Fragment operations are performed in the following order:

If early per-fragment operations are enabled by the fragment shader, these operations are also performed:

If post-depth coverage operation is enabled by the fragment shader, the SampleMask coverage is determined after the early stencil and depth tests.

The VkPipelineDiscardRectangleStateCreateInfoEXT state is set by adding an instance of this structure to the pNext chain of an instance of the VkGraphicsPipelineCreateInfo structure and setting the graphics pipeline state with vkCreateGraphicsPipelines.

If the bound pipeline state object was not created with the VK_DYNAMIC_STATE_DISCARD_RECTANGLE_EXT dynamic state enabled, discard rectangles are specified using the pDiscardRectangles member of VkPipelineDiscardRectangleStateCreateInfoEXT linked to the pipeline state object.

The VkOffset2D::x and VkOffset2D::y values of the discard rectangle VkRect2D specify the upper-left origin of the discard rectangle box. The lower-right corner of the discard rectangle box is specified as the VkExtent2D::width and VkExtent2D::height from the upper-left origin.

If offset.x ≤ x_f < offset.x + extent.width and offset.y ≤ y_f < offset.y + extent.height for the selected discard rectangle, then the fragment is within the discard rectangle box. When the discard rectangle mode is VK_DISCARD_RECTANGLE_MODE_INCLUSIVE_EXT a fragment within at least one of the active discard rectangle boxes passes the discard rectangle test; otherwise the fragment fails the discard rectangle test and is discarded. When the discard rectangle mode is VK_DISCARD_RECTANGLE_MODE_EXCLUSIVE_EXT a fragment within at least one of the active discard rectangle boxes fails the discard rectangle test, and the fragment is discarded; otherwise the fragment passes the discard rectangles test. The discard rectangles test only applies to drawing commands, not to other commands like clears or copies.

When the use of a shading rate image results in a fragment covering multiple pixels, the discard rectangle test is performed independently for each pixel in the fragment. If a pixel covered by a fragment fails the discard rectangle test, all samples in the fragment associated with that pixel are treated as not covered. If the discard rectangle test results in a fragment with no samples covered, that fragment is discarded.

If offset.x ≤ x_f < offset.x + extent.width and offset.y ≤ y_f < offset.y + extent.height for the selected scissor rectangle, then the scissor test passes. Otherwise, the test fails and the fragment is discarded. For points, lines, and polygons, the scissor rectangle for a primitive is selected in the same manner as the viewport (see Controlling the Viewport). The scissor rectangles test only applies to drawing commands, not to other commands like clears or copies.

It is legal for offset.x + extent.width or offset.y + extent.height to exceed the dimensions of the framebuffer - the scissor test still applies as defined above. Rasterization does not produce fragments outside of the framebuffer, so such fragments never have the scissor test performed on them.

The scissor test is always performed. Applications can effectively disable the scissor test by specifying a scissor rectangle that encompasses the entire framebuffer.

When the use of a shading rate image results in a fragment covering multiple pixels, the scissor test is performed independently for each pixel in the fragment. If a pixel covered by a fragment fails the scissor test, all samples in the fragment associated with that pixel are treated as not covered. If the scissor test results in a fragment with no samples covered, that fragment is discarded.

The exclusive scissor test determines if a pixel’s framebuffer coordinates (x_f,y_f) lie outside the exclusive scissor rectangle corresponding to the viewport index (see Controlling the Viewport) used by the primitive that generated the fragment. The exclusive scissor test behaves identically to the scissor test, except that it passes only if the pixel is outside the rectangle instead of passing if the pixel is inside the rectangle.

If offset.x ≤ x_f < offset.x + extent.width and offset.y ≤ y_f < offset.y + extent.height for the selected exclusive scissor rectangle, then the exclusive scissor test fails and the fragment is discarded. Otherwise, the exclusive scissor test passes. For points, lines, and polygons, the exclusive scissor rectangle for a primitive is selected in the same manner as the viewport (see Controlling the Viewport). The exclusive scissor test only applies to drawing commands, not to other commands like clears or copies.

It is legal for offset.x + extent.width or offset.y + extent.height to exceed the dimensions of the framebuffer - the exclusive scissor test still applies as defined above. Rasterization does not produce fragments outside of the framebuffer, so such fragments never have the exclusive scissor test performed on them.

The exclusive scissor test is performed if and only if the current pipeline was created with a non-zero exclusiveScissorCount. Applications can effectively disable the exclusive scissor test for specific viewports by specifying a scissor rectangle with a width or height of zero.

When the use of a shading rate image results in a fragment covering multiple pixels, the exclusive scissor test is performed independently for each pixel in the fragment. If a pixel covered by a fragment fails the exclusive scissor test, all samples in the fragment associated with that pixel are treated as not covered. If the exclusive scissor test results in a fragment with no samples covered, that fragment is discarded.

This step modifies fragment coverage values based on the values in the pSampleMask array member of VkPipelineMultisampleStateCreateInfo, as described previously in section Graphics Pipelines.

pSampleMask contains an array of static coverage information that is ANDed with the coverage information generated during rasterization. Bits that are zero disable coverage for the corresponding sample. Bit B of mask word M corresponds to sample 32 × M + B. The array is sized to a length of ⌈ rasterizationSamples / 32 ⌉ words. If pSampleMask is NULL, it is treated as if the mask has all bits enabled, i.e. no coverage is removed from fragments.

The depth bounds test, stencil test, depth test, representative fragment test, and occlusion query sample counting are performed before fragment shading if and only if early fragment tests are enabled by the fragment shader (see Early Fragment Tests). When early per-fragment operations are enabled, these operations are performed prior to fragment shader execution, and the stencil buffer, depth buffer, and occlusion query sample counts will be updated accordingly; these operations will not be performed again after fragment shader execution.

If a pipeline’s fragment shader has early fragment tests disabled, these operations are performed only after fragment program execution, in the order described below. If a pipeline does not contain a fragment shader, these operations are performed only once.

If early fragment tests are enabled, any depth value computed by the fragment shader has no effect. Additionally, the depth test (including depth writes), stencil test (including stencil writes) and sample counting operations are performed even for fragments or samples that would be discarded after fragment shader execution due to per-fragment operations such as alpha-to-coverage tests, or due to the fragment being discarded by the shader itself.

After programmable fragment processing, per-fragment operations are performed before blending and color output to the framebuffer.

A fragment is produced by rasterization with framebuffer coordinates of (x_f,y_f) and depth z, as described in Rasterization. The fragment is then modified by programmable fragment processing, which adds associated data as described in Shaders. The fragment is then further modified, and possibly discarded by the late per-fragment operations described in this chapter. Finally, if the fragment was not discarded, it is used to update the framebuffer at the fragment’s framebuffer coordinates for any samples that remain covered.

The depth bounds test, stencil test, and depth test are performed for each sample, rather than just once for each fragment. Stencil and depth operations are performed for a sample only if that sample’s fragment coverage bit is a value of 1 when the fragment executes the corresponding stage of the graphics pipeline. If the corresponding coverage bit is 0, no operations are performed for that sample. Failure of the depth bounds, stencil, or depth test results in termination of the processing of that sample by means of disabling coverage for that sample, rather than discarding of the fragment. If, at any point, a fragment’s coverage becomes zero for all samples, then the fragment is discarded. All operations are performed on the depth and stencil values stored in the depth/stencil attachment of the framebuffer. The contents of the color attachments are not modified at this point.

The depth bounds test, stencil test, depth test, and occlusion query operations described in Depth Bounds Test, Stencil Test, Depth Test, Sample Counting are instead performed prior to fragment processing, as described in Early Fragment Test Mode, if requested by the fragment shader.

When the VK_AMD_mixed_attachment_samples extension is enabled, special rules apply to per-fragment operations when the number of samples of the color attachments differs from the number of samples of the depth/stencil attachment used in a subpass.

Let C be the number of color attachment samples and D be the number of depth/stencil attachment samples used by a given subpass.

If C < D then only the first C number of samples are guaranteed to have a corresponding fragment shader invocation and thus a corresponding color output value, unless the fragment shaders produce inputs to the late per-fragment tests (e.g. by outputting to a variable decorated with the FragDepth built-in decoration). Implementations are allowed to produce fragment shader invocations for samples with indices greater than or equal to C but (other than potential side effects) the color outputs of fragment shader invocations corresponding to such samples are discarded.

If a fragment shader is active and its entry point’s interface includes a built-in output variable decorated with SampleMask and also decorated with OverrideCoverageNV the fragment coverage is replaced with the sample mask bits set in the shader. Otherwise if the built-in output variable decorated with SampleMask is not also decorated with OverrideCoverageNV then the fragment coverage is ANDed with the bits of the sample mask to generate a new fragment coverage value. If such a fragment shader did not assign a value to SampleMask due to flow of control, the value ANDed with the fragment coverage is undefined. If no fragment shader is active, or if the active fragment shader does not include SampleMask in its interface, the fragment coverage is not modified.

Next, the fragment alpha and coverage values are modified based on 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 alphaToCoverageEnable is enabled, a temporary coverage value with rasterizationSamples bits is generated where each bit is determined by the fragment’s alpha value. The temporary coverage value is then ANDed with the fragment coverage value to generate a new fragment coverage value.

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.

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.

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

If minDepthBounds ≤ z_a ≤ maxDepthBounds, then the depth bounds test passes. Otherwise, the test fails and the sample’s coverage bit is cleared in the fragment. If there is no depth framebuffer attachment or if the depth bounds test is disabled, it is as if the depth bounds test always passes.

The stencil test conditionally disables coverage of a sample based on the outcome of a comparison between the stencil value in the depth/stencil attachment at location (x_f,y_f) (for the appropriate sample) and a reference value. The stencil test also updates the value in the stencil attachment, depending on the test state, the stencil value and the stencil write masks. The test is enabled or disabled by the stencilTestEnable member of VkPipelineDepthStencilStateCreateInfo.

When disabled, the stencil test and associated modifications are not made, and the sample’s coverage is not modified.

The stencil test is controlled with the front and back members of VkPipelineDepthStencilStateCreateInfo which are of type VkStencilOpState.

There are two sets of stencil-related state, the front stencil state set and the back stencil state set. Stencil tests and writes use the front set of stencil state when processing front-facing fragments and use the back set of stencil state when processing back-facing fragments. Fragments rasterized from non-polygon primitives (points and lines) are always considered front-facing. Fragments rasterized from polygon primitives inherit their facingness from the polygon, even if the polygon is rasterized as points or lines due to the current VkPolygonMode. Whether a polygon is front- or back-facing is determined in the same manner used for face culling (see Basic Polygon Rasterization).

The operation of the stencil test is also affected by the compareMask, writeMask, and reference members of VkStencilOpState set in the pipeline state object if the pipeline state object is created without the VK_DYNAMIC_STATE_STENCIL_COMPARE_MASK, VK_DYNAMIC_STATE_STENCIL_WRITE_MASK, and VK_DYNAMIC_STATE_STENCIL_REFERENCE dynamic states enabled, respectively.

reference is an integer reference value that is used in the unsigned stencil comparison. The reference value used by stencil comparison must be within the range [0,2^s-1] , where s is the number of bits in the stencil framebuffer attachment, otherwise the reference value is considered undefined. The s least significant bits of compareMask are bitwise ANDed with both the reference and the stored stencil value, and the resulting masked values are those that participate in the comparison controlled by compareOp. Let R be the masked reference value and S be the masked stored stencil value.

The depth test conditionally disables coverage of a sample based on the outcome of a comparison between the fragment’s depth value at the sample location and the sample’s depth value in the depth/stencil attachment at location (x_f,y_f). The comparison is enabled or disabled with the depthTestEnable member of the VkPipelineDepthStencilStateCreateInfo structure. When disabled, the depth comparison and subsequent possible updates to the value of the depth component of the depth/stencil attachment are bypassed and the fragment is passed to the next operation. The stencil value, however, can be modified as indicated above as if the depth test passed. If enabled, the comparison takes place and the depth/stencil attachment value can subsequently be modified.

The comparison is specified with the depthCompareOp member of VkPipelineDepthStencilStateCreateInfo. Let z_f be the incoming fragment’s depth value for a sample, and let z_a be the depth/stencil attachment value in memory for that sample. The depth test passes under the following conditions:

If VkPipelineRasterizationStateCreateInfo::depthClampEnable is enabled, before the incoming fragment’s z_f is compared to z_a, z_f 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 depth test fails, the sample’s coverage bit is cleared in the fragment. The stencil value at the sample’s location is updated according to the function currently in effect for depth test failure.

If the depth test passes, the sample’s (possibly clamped) z_f value is conditionally written to the depth framebuffer attachment based on the depthWriteEnable member of VkPipelineDepthStencilStateCreateInfo. If depthWriteEnable is VK_TRUE the value is written, and if it is VK_FALSE the value is not written. If the depth framebuffer attachment is a fixed-point format and the depth value is outside of the 0.0 to 1.0 range the depth value is clamped between 0.0 and 1.0 inclusive before writing. The stencil value at the sample’s location is updated according to the function currently in effect for depth test success.

If there is no depth framebuffer attachment, it is as if the depth test always passes.

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.

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.

Coverage reduction generates a color sample mask from the coverage mask, with one bit for each sample in the color attachment(s) for the subpass. If a bit in the color sample mask is 0, then blending and writing to the framebuffer are not performed for that sample.

When the VK_NV_framebuffer_mixed_samples extension is not enabled, each color sample is associated with a unique rasterization sample, and the value of the coverage mask is assigned to the color sample mask.

If the render pass has a fragment density map attachment, rasterizationSamples is greater than 1, and the fragment area covers multiple pixels; there is an implementation-dependent association of rasterization samples to color attachment samples within the fragment. Each color sample’s mask bit is assigned the union of the coverage bits of its associated raster samples.

If the VK_NV_coverage_reduction_mode extension is not enabled, there is an implementation-dependent association of raster samples to color samples. The reduced color sample mask is computed such that the bit for each color sample is 1 if any of the associated bits in the fragment’s coverage is on, and 0 otherwise.