<cat>Don'tListMePlease Dev</cat> <title>Render Reference - Stencils</title> # Render Library References These pages seek to provide helpful insight into the groups of functions provided by the <page text="Render Library">render</page>. The major function groups are: * <page text="Beams">render_beams</page> * <page text="Minification and Magnification Texture Filters">render_min_mag_filters</page> * <page text="Render Targets">render_rendertargets</page> * **Stencils** # A Brief Preamble It's going to be very helpful to you if you already have a grasp on <page text="Render Targets">render_rendertargets</page> before learning about Stencils. It's not necessarily a hard requirement, but you will have a much easier time mentally "Connecting the dots." To avoid repetition, the shorthand term `byte` is used throughout this page to mean "An <page>Number</page> with an integer value between `0` and `255`, representing 8 bits of data." While this is not a term used in Lua, it is commmon in programming. # What are Stencils? **Stencils are a system to constrain drawing to <page text="Render Targets">render_rendertargets</page> on a per-pixel basis.** **Stencils are a system to constrain drawing operations on <page text="Render Targets">render_rendertargets</page> on a per-pixel basis.** Whenever anything is drawn to a Render Target, including the main game view, the Stencil performs logical checks (More on these later) for each pixel that is about to be affected by the draw operation and determines whether or not that pixel should be allowed to change from its current values. # What are the Parts of the Stencil System? * The **Stencil Buffer** holds a `byte` for every individual pixel on the Render Target it belongs to. * By default, every pixel's Stencil value is `0`. * The **Reference Value** is a `byte` that Stencil Buffer values are compared against. When a draw operation is performed, each of the affected pixels has its Stencil Buffer value compared to the Reference Value. * The **Compare Function** determines which of the possible relationships (Greater than, less than, equal to, etc.) between the Stencil Buffer value for a pixel and the current Reference Value should be considered a "**Pass**" and which should be considered a "**Fail**". * The **Compare Function** determines which of the possible relationships (Greater than, less than, equal to, etc.) between the Stencil Buffer value for a pixel and the current Reference Value should be considered a "**Pass**" and which should be considered a "**Fail**". <page text="The full list of possible Compare Functions can be found here">Enums/STENCILCOMPARISONFUNCTION</page>⤶ Depending on if a pixel Passed or Failed the Compare Function, its value is then potentially modified, depending on the current Stencil configuration. * **Operations** modify the Stencil Buffer value for a given pixel depending on if it has Passed or Failed. Operations include incrementing the current value by one (1), replacing the current value with the Reference Value, making no change, and others. <page text="The full list of possible Operations can be found here">Enums/STENCILOPERATION</page> ⤶ If a pixel Fails the Compare Function, then the * The **Fail Operation** will be performed if ⤶ * The **Fail Operation** is performed on pixels that Fail the Compare Function. ⤶ For the pixels that Pass the Compare Function, there is one additional check they must Pass before they are allowed to be modified by the draw operation. ⤶ * The **Depth Test** (or "Z test") compares the pixel's current Depth Buffer value against the Depth value of the draw operation.⤶ ⤶ Unlike the Compare Function, this comparison is fixed and cannot be configured. ⤶ ⤶ * The **Z Fail Operation** is performed on the Stencil Buffer for pixels where the current Depth Buffer value is less than the draw operation's proposed depth value, indicating that the draw operation is drawing something behind the current pixel and should therefore be hidden by what is already there. ⤶ ⤶ If a pixel has passed both the Compare Function as well as the Depth Test, it is considered Passed and will have its contents replaced/modified by the draw operation. This will affect the Color, Depth, and Stencil values for the pixel.⤶ ⤶ * The **Pass Operation** is performed on the Stencil Buffer for pixels that have passed both the Compare Function and the Depth Test and are being updated by the draw operation.⤶ ⤶ * Masks⤶ ---⤶ ⤶ ⤶ When performing draw operations, the exact same Stencil logic is used for every individual pixel affected by the draw operation. ⤶ Inbetween draw operations, the Stencil logic can be re-configured to achieve different results.⤶ ⤶ ⤶ ⤶ **Stencils are a multi-part system.**⤶ ⤶ The **Stencil Buffer** holds a `byte` for every individual pixel on the Render Target it belongs to. By default, every pixel's Stencil value is `0`. ⤶ The **Reference Value** is a `byte` that all Stencil Buffer values are compared against during draw operations. ⤶ ⤶ The **Compare Function**⤶ ⤶ The **Fail Operation**⤶ ⤶ The **Pass Operation**⤶ ⤶ The **Z Fail Operation**⤶ ⤶ The **Test Mask**⤶ The **Test Mask**⤶ The **Write Mask**