Skip to content

Commit 7009af3

Browse files
QbieShayCalinouAThousandShips
committed
Add documentation for stencil modes
Co-authored-by: Hugo Locurcio <[email protected]> Co-authored-by: A Thousand Ships <[email protected]>
1 parent dd72262 commit 7009af3

File tree

1 file changed

+57
-0
lines changed

1 file changed

+57
-0
lines changed

‎tutorials/shaders/shader_reference/spatial_shader.rst

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,10 @@ For visual examples of these render modes, see :ref:`Standard Material 3D and OR
3535
+-------------------------------+------------------------------------------------------------------------------------------------------+
3636
| **depth_test_disabled** | Disable depth testing. |
3737
+-------------------------------+------------------------------------------------------------------------------------------------------+
38+
| **depth_test_default** | Depth test will discard the pixel if it is behind other pixels. |
39+
+-------------------------------+------------------------------------------------------------------------------------------------------+
40+
| **depth_test_inverted** | Depth test will discard the pixel if it is in front of other pixels. Useful for stencil effects. |
41+
+-------------------------------+------------------------------------------------------------------------------------------------------+
3842
| **sss_mode_skin** | Subsurface Scattering mode for skin (optimizes visuals for human skin, e.g. boosted red channel). |
3943
+-------------------------------+------------------------------------------------------------------------------------------------------+
4044
| **cull_back** | Cull back-faces (default). |
@@ -90,6 +94,59 @@ For visual examples of these render modes, see :ref:`Standard Material 3D and OR
9094
| **fog_disabled** | Disable receiving depth-based or volumetric fog. Useful for ``blend_add`` materials like particles. |
9195
+-------------------------------+------------------------------------------------------------------------------------------------------+
9296

97+
Stencil modes
98+
-------------
99+
100+
.. note::
101+
102+
Stencil support is experimental, use at your own risk.
103+
We will try to not break compatibility as much as possible,
104+
but if significant flaws are found in the API, it may change
105+
in the next minor version.
106+
107+
Stencil operations are a set of operations that allow writing to
108+
an efficient buffer in an hardware-accelerated manner.
109+
This is generally used to mask in or out parts of the scene.
110+
111+
Some of the most well-known uses are:
112+
113+
- Outlines: Mask out the inner mesh that is being outlined to avoid inner outlines.
114+
- X-Ray: Display a mesh behind other objects.
115+
- Portals: Draw geometry that is normally "impossible" (non-Euclidian) by masking objects.
116+
117+
.. note::
118+
119+
You can only read from stencil in the transparent pass.
120+
Any attempt to read in the opaque pass will fail, as it's currently not supported behavior.
121+
122+
Also, stencil operations aren't yet supported in compositor effects.
123+
Please use the full screen quad method described in
124+
:ref:`doc_advanced_postprocessing` instead.
125+
126+
+-------------------------------+------------------------------------------------------------------------------------------------------+
127+
| Stencil mode | Description |
128+
+===============================+======================================================================================================+
129+
| **read** | Read from the stencil buffer. |
130+
+-------------------------------+------------------------------------------------------------------------------------------------------+
131+
| **write** | Write reference value to the stencil buffer. |
132+
+-------------------------------+------------------------------------------------------------------------------------------------------+
133+
| **write_if_depth_fail** | Write reference value to the stencil buffer if the depth test fails. |
134+
+-------------------------------+------------------------------------------------------------------------------------------------------+
135+
| **compare_always** | Always pass stencil test |
136+
+-------------------------------+------------------------------------------------------------------------------------------------------+
137+
| **compare_equal** | Pass stencil test if the reference value is equal to the stencil buffer value. |
138+
+-------------------------------+------------------------------------------------------------------------------------------------------+
139+
| **compare_not_equal** | Pass stencil test if the reference value is not equal to the stencil buffer value. |
140+
+-------------------------------+------------------------------------------------------------------------------------------------------+
141+
| **compare_less** | Pass stencil test if the reference value is less than the stencil buffer value. |
142+
+-------------------------------+------------------------------------------------------------------------------------------------------+
143+
| **compare_less_or_equal** | Pass stencil test if the reference value is less than or equal to the stencil buffer value. |
144+
+-------------------------------+------------------------------------------------------------------------------------------------------+
145+
| **compare_greater** | Pass stencil test if the reference value is greater than the stencil buffer value. |
146+
+-------------------------------+------------------------------------------------------------------------------------------------------+
147+
| **compare_greater_or_equal** | Pass stencil test if the reference value is greater than or equal to the stencil buffer value. |
148+
+-------------------------------+------------------------------------------------------------------------------------------------------+
149+
93150
Built-ins
94151
---------
95152

0 commit comments

Comments
 (0)