Struct web_glitz::pipeline::graphics::StencilTest

pub struct StencilTest {
    pub test_function_front: TestFunction,
    pub fail_operation_front: StencilOperation,
    pub pass_depth_fail_operation_front: StencilOperation,
    pub pass_operation_front: StencilOperation,
    pub test_function_back: TestFunction,
    pub fail_operation_back: StencilOperation,
    pub pass_depth_fail_operation_back: StencilOperation,
    pub pass_operation_back: StencilOperation,
    pub reference_value_front: u32,
    pub test_mask_front: u32,
    pub reference_value_back: u32,
    pub test_mask_back: u32,
    pub write_mask_front: u32,
    pub write_mask_back: u32,
}

Provides instructions on how stencil testing should be performed.

In order to do a stencil test, a [RenderTarget] must have a stencil buffer. A stencil buffer stores a stencil value for each fragment as an unsigned integer. This means that for an 8-bit stencil buffer, stencil values can range from 0 (00000000) to 255 (11111111). When rendering to a [RenderTarget] with no stencil buffer attached, the stencil test behaves as though stencil testing is disabled.

The stencil test distinguishes between front-facing fragments obtained from the Front side of a triangle and back-facing fragments obtained from the Back side of a triangle; see [WindingOrder] for details on how the Front and Back faces are decided. Fragments obtained from non-polygonal primitives (points, lines) are always considered front-facing. Separate configurations are specified for the Front and Back cases respectively.

The stencil test is performed for each fragment. [test_function_front] specifies the function that is used to test front-facing fragments; [test_function_back] specifies the function that is used to test back-facing fragments. For each fragment sampled from a primitive (a point, line or triangle) a reference value ([reference_value_front] or [reference_value_back], for front- and back-facing fragments respectively) may be compared to the current stencil_value for this fragment in the stencil buffer. A bitmask ([test_mask_front] or [test_mask_back], for front- and back-facing fragments respectively) will be applied to both the reference value and the stencil_value with the bitwise AND operation (&), before the test function is evaluated; this allows masking off certain bits, reserving them for different conditional tests. The following test functions are available:

• TestFunction::Equal: the test passes if reference_value & test_mask is equal to stencil_value & test_mask.
• TestFunction::NotEqual: the test passes if reference_value & test_mask is not equal to stencil_value & test_mask.
• TestFunction::Less: the test passes if reference_value & test_mask is smaller than stencil_value & test_mask.
• TestFunction::Greater: the test passes if reference_value & test_mask is greater than stencil_value & test_mask.
• TestFunction::LessOrEqual: the test passes if reference_value & test_mask is smaller than or equal to stencil_value & test_mask.
• TestFunction::GreaterOrEqual: the test passes if reference_value & test_mask is greater than or equal to stencil_value & test_mask.
• TestFunction::NeverPass: the test never passes, regardless of how reference_value & test_mask compares to stencil_value & test_mask.
• TestFunction::AlwaysPass: the test always passes, regardless of how reference_value & test_mask compares to stencil_value & test_mask.

Typically, if either the DepthTest or StencilTest fails, a fragment will be discarded and a [RenderTarget]'s output buffers will not be updated. However, the stencil buffer is exceptional in that it may be updated even if the DepthTest or the StencilTest fails, or both tests fail. There are 3 relevant cases:

1. The StencilTest fails. The StencilTest is performed before the DepthTest. If the StencilTest fails the DepthTest will not be performed.
2. The StencilTest passes, but the DepthTest fails. If depth testing is disabled, then it is always assumed to pass and this case will never occur.
3. The StencilTest passes and the DepthTest passes. If depth testing is disabled, then it is always assumed to pass.

For each of these 3 cases the update operation that is performed on the stencil buffer can be controlled separately. For the Front stencil value this controlled by [fail_operation_front] (case 1), [pass_depth_fail_operation_front] (case 2), and [pass_operation_front] (case 3) for each case respectively. For the Back stencil value this is controlled by [fail_operation_back] (case 1), [pass_depth_fail_operation_back] (case 2), and [pass_operation_back] (case 3) for each case respectively. The following stencil update operations are available:

• StencilOperation::Keep: the stencil value in the stencil buffer is not updated.
• StencilOperation::Zero: the stencil value in the stencil buffer is set to 0.
• StencilOperation::Replace: the stencil value in the stencil buffer is replaced with the masked reference value reference_value & test_mask.
• StencilOperation::Increment: the stencil value in the stencil buffer is incremented. If the current stencil value is the maximum value, don't do anything.
• StencilOperation::WrappingIncrement: the stencil value in the stencil buffer is incremented. If the current stencil value is the maximum value (as determined by the stencil buffer's bit-depth, e.g. 255 for an 8-bit stencil buffer), set the value to 0.
• StencilOperation::Decrement: the stencil value in the stencil buffer is decremented. If the current stencil value is 0, don't do anything.
• StencilOperation::WrappingDecrement: the stencil value in the stencil buffer is decremented. If the current stencil value is 0, set the value to the maximum stencil value (as determined by the stencil buffer's bit-depth, e.g. 255 for an 8-bit stencil buffer).
• StencilOperation::Invert: inverts the bits of the stencil value in the stencil buffer (for example: 10110011 becomes 01001100).

Finally, the bitmask specified by [write_mask_front] (when testing a front-facing fragment) or [write_mask_back] (when testing a back-facing fragment) controls which individual bits can be written too. Suppose an 8-bit stencil buffer and a write mask of 0000011, then only the final two bits will be updated; where 0 appears, the bits are write-protected.

Note that reference values, test masks and write masks are declared here as u32 values, but when testing only the bottom X values are used, where X is the bit-depth of the stencil buffer.

A StencilTest may be instantiated with the default configuration via Default:

use web_glitz::pipeline::graphics::{StencilTest, TestFunction, StencilOperation};

assert_eq!(StencilTest::default(), StencilTest {
    test_function_front: TestFunction::AlwaysPass,
    fail_operation_front: StencilOperation::Keep,
    pass_depth_fail_operation_front: StencilOperation::Keep,
    pass_operation_front: StencilOperation::Keep,
    test_function_back: TestFunction::AlwaysPass,
    fail_operation_back: StencilOperation::Keep,
    pass_depth_fail_operation_back: StencilOperation::Keep,
    pass_operation_back: StencilOperation::Keep,
    reference_value_front: 0,
    test_mask_front: 0xffffffff,
    reference_value_back: 0,
    test_mask_back: 0xffffffff,
    write_mask_front: 0xffffffff,
    write_mask_back: 0xffffffff,
});

Fields

test_function_front: TestFunction

The TestFunction used by this StencilTest for front-facing fragments.

Only applies to fragments that originate from front-facing triangles, lines or points. For fragments originating from back-facing triangles [test_function_back] is used instead.

See the type documentation for StencilTest for details on how the available functions are evaluated.

fail_operation_front: StencilOperation

The StencilOperation that will be used to update the stencil buffer when a front-facing fragment passes neither the DepthTest, nor [test_function_front].

Only applies to fragments that originate from front-facing triangles, lines or points. For fragments originating from back-facing triangles [fail_operation_back] is used instead.

pass_depth_fail_operation_front: StencilOperation

The StencilOperation that will be used to update the stencil buffer when a front-facing fragment passes the DepthTest, but fails [test_function_front].

Only applies to fragments that originate from front-facing triangles, lines or points. For fragments originating from back-facing triangles [fail_operation_back] is used instead.

pass_operation_front: StencilOperation

The StencilOperation that will be used to update the stencil buffer when a front-facing fragment passes both the DepthTest and [test_function_front].

Only applies to fragments that originate from front-facing triangles, lines or points. For fragments originating from back-facing triangles [fail_operation_back] is used instead.

test_function_back: TestFunction

The TestFunction used by this StencilTest for back-facing fragments.

Only applies to fragments that originate from back-facing triangles. For fragments originating from back-facing triangles, lines or points, [test_function_front] is used instead.

See the type documentation for StencilTest for details on how the available functions are evaluated.

fail_operation_back: StencilOperation

The StencilOperation that will be used to update the stencil buffer when a back-facing fragment passes neither the DepthTest, nor [test_function_back].

Only applies to fragments that originate from back-facing triangles. For fragments originating from front-facing triangles, lines or points, [fail_operation_front] is used instead.

pass_depth_fail_operation_back: StencilOperation

The StencilOperation that will be used to update the stencil buffer when a back-facing fragment passes the DepthTest, but fails [test_function_back].

Only applies to fragments that originate from back-facing triangles. For fragments originating from front-facing triangles, lines or points, [fail_operation_front] is used instead.

pass_operation_back: StencilOperation

The StencilOperation that will be used to update the stencil buffer when a back-facing fragment passes both the DepthTest and [test_function_back].

Only applies to fragments that originate from back-facing triangles. For fragments originating from front-facing triangles, lines or points, [fail_operation_front] is used instead.

reference_value_front: u32

The value that is compared to a front-facing fragment's stencil value in the stencil buffer, in order to decide if the fragment passes the stencil test.

See the type documentation for StencilTest for details on how this value is used when stencil testing.

test_mask_front: u32

The bitmask that is applied to both the [reference_value_front] and the stencil value in the stencil buffer to which it is compared, before the stencil test is evaluated on a front-facing fragment.

Can be used to mask off certain bits, reserving them for different conditional tests.

See the type documentation for StencilTest for details on how the [test_mask] is applied.

reference_value_back: u32

The value that is compared to a back-facing fragment's stencil value in the stencil buffer, in order to decide if the fragment passes the stencil test.

See the type documentation for StencilTest for details on how this value is used when stencil testing.

test_mask_back: u32

The bitmask that is applied to both the [reference_value_back] and the stencil value in the stencil buffer to which it is compared, before the stencil test is evaluated on a back-facing fragment.

Can be used to mask off certain bits, reserving them for different conditional tests.

See the type documentation for StencilTest for details on how the [test_mask_back] is applied.

write_mask_front: u32

The bitmask that controls which of a stencil value's individual bits may be updated in the stencil buffer when testing a front-facing fragment.

Suppose an 8-bit stencil buffer and a [write_mask] of 0000011, then only the final two bits will be updated; where 0 appears, the bits are write-protected.

write_mask_back: u32

The bitmask that controls which of a stencil value's individual bits may be updated in the stencil buffer when testing a back-facing fragment.

Suppose an 8-bit stencil buffer and a [write_mask] of 0000011, then only the final two bits will be updated; where 0 appears, the bits are write-protected.

Trait Implementations

impl Default for StencilTest

fn default() -> Self

Returns the "default value" for a type.

impl Clone for StencilTest

fn clone(&self) -> StencilTest

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl PartialEq<StencilTest> for StencilTest

fn eq(&self, other: &StencilTest) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &StencilTest) -> bool

This method tests for !=.

impl Debug for StencilTest

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.