25. Fragment Operations

Fragment operations execute on a per-fragment or per-sample basis, affecting whether or how a fragment or sample is written to the framebuffer. Some operations execute before fragment shading, and others after. Fragment operations always adhere to rasterization order.

25.1. Early Per-Fragment Tests

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 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:

25.2. Scissor Test

The scissor test determines if a fragment’s framebuffer coordinates (xf,yf) lie within the scissor rectangle corresponding to the viewport index (see Controlling the Viewport) used by the primitive that generated the fragment. If the pipeline state object is created without VK_DYNAMIC_STATE_SCISSOR enabled then the scissor rectangles are set by the VkPipelineViewportStateCreateInfo state of the pipeline state object. Otherwise, to dynamically set the scissor rectangles call:

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

Each scissor rectangle is described by a VkRect2D structure, with the offset.x and offset.y values determining the upper left corner of the scissor rectangle, and the extent.width and extent.height values determining the size in pixels.

Valid Usage
  • The bound graphics pipeline must have been created with the VK_DYNAMIC_STATE_SCISSOR dynamic state enabled

  • 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 must be greater than or equal to 0

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

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

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

If offset.x ≤ xf < offset.x + extent.width and offset.y ≤ yf < 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.

25.3. Sample Mask

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 elements of the sample mask array are of type VkSampleMask, each representing 32 bits of coverage information:

typedef uint32_t VkSampleMask;

25.4. Early Fragment Test Mode

The depth bounds test, stencil test, depth 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.

25.5. Late Per-Fragment Tests

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 (xf,yf) 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.

25.6. Multisample Coverage

If a fragment shader is active and its entry point’s interface includes a built-in output variable decorated with SampleMask, 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.

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.

25.7. 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:

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 an extension-specific 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 and maxDepthBounds define the range of values 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

typedef VkFlags VkPipelineDepthStencilStateCreateFlags;

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

25.8. Depth Bounds Test

The depth bounds test conditionally disables coverage of a sample based on the outcome of a comparison between the value za in the depth attachment at location (xf,yf) (for the appropriate sample) and a range of values. The test is enabled or disabled by the depthBoundsTestEnable member of VkPipelineDepthStencilStateCreateInfo: If the pipeline state object is created without the VK_DYNAMIC_STATE_DEPTH_BOUNDS dynamic state enabled then the range of values used in the depth bounds test are defined by the minDepthBounds and maxDepthBounds members of the VkPipelineDepthStencilStateCreateInfo structure. Otherwise, to dynamically set the depth bounds range values call:

void vkCmdSetDepthBounds(
    VkCommandBuffer                             commandBuffer,
    float                                       minDepthBounds,
    float                                       maxDepthBounds);
  • commandBuffer is the command buffer into which the command will be recorded.

  • minDepthBounds is the lower bound of the range of depth values used in the depth bounds test.

  • maxDepthBounds is the upper bound of the range.

Valid Usage
  • The bound graphics pipeline must have been created with the VK_DYNAMIC_STATE_DEPTH_BOUNDS dynamic state enabled

  • minDepthBounds must be between 0.0 and 1.0, inclusive

  • maxDepthBounds must be between 0.0 and 1.0, inclusive

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

If minDepthBounds ≤ zamaxDepthBounds, 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.

25.9. Stencil Test

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 (xf,yf) (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.

The VkStencilOpState structure is defined as:

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)

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.

If the pipeline state object is created with the VK_DYNAMIC_STATE_STENCIL_COMPARE_MASK dynamic state enabled, then to dynamically set the stencil compare mask call:

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.

Valid Usage
  • The bound graphics pipeline must have been created with the VK_DYNAMIC_STATE_STENCIL_COMPARE_MASK dynamic state enabled

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

Bits which can be set in the vkCmdSetStencilCompareMask::faceMask parameter, and similar parameters of other commands specifying which stencil state to update stencil masks for, are:

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,
    VK_STENCIL_FACE_FLAG_BITS_MAX_ENUM = 0x7FFFFFFF
} 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.

typedef VkFlags VkStencilFaceFlags;

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

If the pipeline state object is created with the VK_DYNAMIC_STATE_STENCIL_WRITE_MASK dynamic state enabled, then to dynamically set the stencil write mask call:

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.

Valid Usage
  • The bound graphics pipeline must have been created with the VK_DYNAMIC_STATE_STENCIL_WRITE_MASK dynamic state enabled

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

If the pipeline state object is created with the VK_DYNAMIC_STATE_STENCIL_REFERENCE dynamic state enabled, then to dynamically set the stencil reference value call:

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.

Valid Usage
  • The bound graphics pipeline must have been created with the VK_DYNAMIC_STATE_STENCIL_REFERENCE dynamic state enabled

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

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,2s-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.

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

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,
    VK_COMPARE_OP_MAX_ENUM = 0x7FFFFFFF
} VkCompareOp;
  • VK_COMPARE_OP_NEVER specifies that the test never passes.

  • VK_COMPARE_OP_LESS specifies that the test passes when R < S.

  • VK_COMPARE_OP_EQUAL specifies that the test passes when R = S.

  • VK_COMPARE_OP_LESS_OR_EQUAL specifies that the test passes when R ≤ S.

  • VK_COMPARE_OP_GREATER specifies that the test passes when R > S.

  • VK_COMPARE_OP_NOT_EQUAL specifies that the test passes when R ≠ S.

  • VK_COMPARE_OP_GREATER_OR_EQUAL specifies that the test passes when R ≥ S.

  • VK_COMPARE_OP_ALWAYS specifies that the test always passes.

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:

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,
    VK_STENCIL_OP_MAX_ENUM = 0x7FFFFFFF
} 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.

If the stencil test fails, the sample’s coverage bit is cleared in the fragment. If there is no stencil framebuffer attachment, stencil modification cannot occur, and it is as if the stencil tests always pass.

If the stencil test passes, the writeMask member of the VkStencilOpState structures controls how the updated stencil value is written to the stencil framebuffer attachment.

The least significant s bits of writeMask, where s is the number of bits in the stencil framebuffer attachment, specify an integer mask. Where a 1 appears in this mask, the corresponding bit in the stencil value in the depth/stencil attachment is written; where a 0 appears, the bit is not written. The writeMask value uses either the front-facing or back-facing state based on the facingness of the fragment. Fragments generated by front-facing primitives use the front mask and fragments generated by back-facing primitives use the back mask.

25.10. Depth Test

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 (xf,yf). 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 zf be the incoming fragment’s depth value for a sample, and let za be the depth/stencil attachment value in memory for that sample. The depth test passes under the following conditions:

  • VK_COMPARE_OP_NEVER: the test never passes.

  • VK_COMPARE_OP_LESS: the test passes when zf < za.

  • VK_COMPARE_OP_EQUAL: the test passes when zf = za.

  • VK_COMPARE_OP_LESS_OR_EQUAL: the test passes when zf ≤ za.

  • VK_COMPARE_OP_GREATER: the test passes when zf > za.

  • VK_COMPARE_OP_NOT_EQUAL: the test passes when zf ≠ za.

  • VK_COMPARE_OP_GREATER_OR_EQUAL: the test passes when zf ≥ za.

  • VK_COMPARE_OP_ALWAYS: the test always passes.

If VkPipelineRasterizationStateCreateInfo::depthClampEnable is enabled, before the incoming fragment’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 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) zf 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. 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.

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

25.12. Coverage Reduction

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.