Add initial stencil documentation

Author: QbieShay

tutorials/shaders/shader_reference/spatial_shader.rst

@@ -35,6 +35,10 @@ For visual examples of these render modes, see :ref:`Standard Material 3D and OR
 +-------------------------------+------------------------------------------------------------------------------------------------------+
 | **depth_test_disabled**       | Disable depth testing.                                                                               |
 +-------------------------------+------------------------------------------------------------------------------------------------------+
+| **depth_test_default**        | Depth test will discard the pixel if it is behind other pixels.                                      |
++-------------------------------+------------------------------------------------------------------------------------------------------+
+| **depth_test_inverted**       | Depth test will discard the pixel if it is in front of other pixels. Useful for stencil effects      |
++-------------------------------+------------------------------------------------------------------------------------------------------+
 | **sss_mode_skin**             | Subsurface Scattering mode for skin (optimizes visuals for human skin, e.g. boosted red channel).    |
 +-------------------------------+------------------------------------------------------------------------------------------------------+
 | **cull_back**                 | Cull back-faces (default).                                                                           |
@@ -90,6 +94,47 @@ For visual examples of these render modes, see :ref:`Standard Material 3D and OR
 | **fog_disabled**              | Disable receiving depth-based or volumetric fog. Useful for ``blend_add`` materials like particles.  |
 +-------------------------------+------------------------------------------------------------------------------------------------------+
 
+Stencil modes
+-------------
+
+.. note::
+    Stencil support is experimental, use at your own risk.
+    We will try to not break compatibility as much as possible, but if major flaws are found in the API, it may change in the next version.
+
+
+Stencil operations are a set of operations that allow to write into an efficient, often hardeware integrated, buffer.
+Stencil is generally use to mask in or out parts of the scene.
+
+Some of the most known uses are:
+- Outlines: stencil allows to mask out the inner mesh that is being outlined to avoid inner outlines.
+- Xray: display a mesh behind other objects.
+- Portals: Draw impossible geometry by masking objects
+
+NOTE: You can only read stencil in the transparent pass. Any attempt to read in the opaque pass will fail and it's not supported behaviour.
+NOTE: Stencil operations aren't yet supported in compositor effects. Please use full screen quad method.
+
++-------------------------------+------------------------------------------------------------------------------------------------------+
+| Stencil mode                  | Description                                                                                          |
++===============================+======================================================================================================+
+| **read**                      | Read from stencil buffer.                                                                            |
++-------------------------------+------------------------------------------------------------------------------------------------------+
+| **write**                     | Write reference value to stencil buffer.                                                             |
++-------------------------------+------------------------------------------------------------------------------------------------------+
+| **write_if_depth_fail**       | Write reference value to stencil buffer if depth test fails.                                         |
++-------------------------------+------------------------------------------------------------------------------------------------------+
+| **compare_equal**             | Pass stencil test if ref value is equal to stencil buffer value.                                     |
++-------------------------------+------------------------------------------------------------------------------------------------------+
+| **compare_not_equal**         | Pass stencil test if ref value is not equal to stencil buffer value.                                 |
++-------------------------------+------------------------------------------------------------------------------------------------------+
+| **compare_less**              | Pass stencil test if ref value is lesser than stencil buffer value.                                  |
++-------------------------------+------------------------------------------------------------------------------------------------------+
+| **compare_less_or_equal**     | Pass stencil test if ref value is lesser or equal than stencil buffer value.                         |
++-------------------------------+------------------------------------------------------------------------------------------------------+
+| **compare_greater**           | Pass stencil test if ref value is greater than stencil buffer value.                                 |
++-------------------------------+------------------------------------------------------------------------------------------------------+
+| **compare_greater_or_equal**  | Pass stencil test if ref value is lesser or equal than stencil buffer value.                         |
++-------------------------------+------------------------------------------------------------------------------------------------------+
+
 Built-ins
 ---------