Stencil
 | Stencil Set | This node sets a stencil mask to the stencil buffer. |
 | Stencil Test | This node tests the stencil mask and renders only those areas where a specified stencil value is set. |
 | Stencil Clear | This node clears the whole stencil buffer. |
 | Stencil Advanced | This node provides advanced and customizable stencil mask and test functionalities. |
The Stencil Buffer is similar to the Z-Buffer in that it stores an additional value for each pixel in the render output. It is usually applied to mask certain areas of the output and restrict subsequent drawing to that area.
Set & Test
The easiest way to use the Stencil Buffer is via the Stencil Set and Stencil Test nodes. They represent the Stencil Buffer as eight independent layers where each pixel on each layer can store a true/false information.
The Stencil Set node is used to create a mask. All nodes below the Stencil Set will not be rendered to the output image but to the Stencil Buffer. Each pixel that would usually be assigned a color by the contents in the subtree of the Stencil Set node instead sets its corresponding Stencil Buffer value to true for all Layer Input Properties checked in the Stencil Set node.
Its counterpart is the Stencil Test node. All nodes below this node will perform an additional test against the Stencil Buffer to decide if they are allowed to change the pixel color. If the stencil value on any of the layers activated via the Layer input properties is true, the pixel fragment will be dropped and neither the color nor Z-Buffer information will be updated. By activating the Inverse property, rendering will instead be restricted to those pixels where the stencil value on at least one of the activated layers is true.
The Stencil Buffer is only valid for the current 3D Layer. Meaning that Stencils Set in a 3D Layer can not be used in another 3D Layer. But also that each 3D Layer can have up to eight stencil layers.
Clear
If you run out of stencil layers, you can clear the stencil buffer.
You can use the clear value to initialize layers as already set, which can be useful with the advanced stencil options. The layers 1 to 8 are represented by bits 0 to 7. The clear-value of 17 would set layer 1 (1) and layer 5 (16)
Advanced
The functionality implemented by the Stencil Set and Stencil Test nodes is a simplified abstraction of the full Stencil Buffer functionality which should cover the majority of situations. Extended, low-level functionality can be accessed via the Stencil Advanced node.
Two of these Nodes have to be used to gain a stencil effect. One Node works as the mask writer and the second as the mask reader.
Read
When an object is rendered, the graphics card first performs a stencil test between the Reference property value and the stencil value stored in the Stencil Buffer to see if the fragment has to be rejected. A bitwise AND operation is applied to both values before performing the compare operation.
(reference & mask) ComparisonOperation (buffer_value & mask)
The Function property specifies what type of comparison should be performed:
- Inherit: The comparison function is inherited from a superior Advanced Stencil Node. If there is none, the comparison function is set to Always which is the default value.
- Always: The stencil test passes always.
- GreaterEqual: The test passes if the reference value is greater than or equal to the value in the Stencil Buffer.
- NotEqual: The test passes if the reference value is not equal to the buffer value.
- Greater: The test passes if the reference value is greater than the value in the buffer.
- LessEqual: The test passes if the reference value is less than or equal to the value in the buffer.
- Equal: The test passes if the reference value is equal to the buffer value.
- Less: The test passes if the reference value is less than the value in the buffer.
- Never: The stencil test never passes.
Write
There are three possible outcomes of the test: Either the fragment passes, the fragment fails or the fragment has already been rejected by the Z-Buffer test and therefore never had a chance to perform the stencil test. For each of these three cases, an operation that is to be performed on the Stencil Buffer value can be set:
- Inherit: The setting is inherited from a superior Advanced Stencil Node. If there is none the operation is set to Keep, which is the default value.
- Zero: The Stencil Buffer value is set to zero.
- Decrement: The stencil buffer value is decremented. If the new value is less than zero, it is wrapped to the maximum value.
- Increment: The stencil buffer value is incremented. If the new value exceeds the maximum value, it is wrapped down to zero.
- Invert: The buffer value is inverted.
- DecrementSaturation: The stencil buffer value is decremented. If the new value is less than zero, it is clamped to zero.
- IncrementSaturation: The stencil buffer value is incremented. If the new value exceeds the maximum value, it is clamped to the maximum value.
- Keep: The old buffer value is kept.
- Replace: The buffer value is replaced by the reference value.
The result of the above operation is masked by the WriteMask property. Every bit that is 1 in the WriteMask is taken from the operation result, every bit that is 0 is taken from the old stencil buffer value.
new_buffer_value = (old_buffer_value & ~StencilWriteMask)
| (WriteMask & StencilOperation(old_buffer_value))
Two-Sided
The properties in the CCW (counter-clockwise) category correspond to the ones in the Operation category. These settings only affect the back-faces of geometries if the TwoSided property is enabled.