Merge pull request #11373 from Calinou/standard-material-3d-stencil

Document Depth Test and Stencil features in Standard Material 3D

Author: mhilbrunner

tutorials/3d/img/material_depth_test.webp

@@ -241,6 +241,16 @@ and works very well with the *Render Priority* property of Material
 
 .. image:: img/spatial_material3.png
 
+Depth Test
+~~~~~~~~~~
+
+This can be used to invert the standard depth test. When set to **Inverted**,
+the object will only appear when occluded, and will be hidden otherwise.
+
+This has no effect if **No Depth Test** is enabled.
+
+.. image:: img/material_depth_test.webp
+
 Shading
 -------
 
@@ -272,7 +282,7 @@ You can also use per-vertex lighting to achieve a retro look.
 .. figure:: img/standard_material_shading_modes_textured.webp
   :align: center
   :alt: Two cubes with a brick texture, one shaded and one unshaded.
-  
+
   Texture from `AmbientCG <https://ambientcg.com/view?id=Bricks051>`__
 
 The **Unshaded** shading mode does not calculate lighting at all. Instead, the
@@ -703,6 +713,8 @@ Billboard Keep Scale
 
 Enables scaling a mesh in billboard mode.
 
+.. _ref_standard_material_3d_grow:
+
 Grow
 ----
 
@@ -721,6 +733,10 @@ make it black and unshaded, reverse culling (Cull Front), and add some grow:
     vertices, or "smooth shading". If the mesh has disconnected faces with unique
     vertices, or "flat shading", the mesh will appear to have gaps when using Grow.
 
+Note that in Godot 4.5 onwards, stencil buffer-based outlines are available
+using the **Outline** :ref:`stencil mode <doc_standard_material_3d_stencil>`.
+This can be used as an alternative to Grow for outlines.
+
 Transform
 ---------
 
@@ -812,6 +828,36 @@ is the same across the entire object's surface.
 
 .. image:: img/standart_material_distance_fade_object_dither_mode.webp
 
+.. _doc_standard_material_3d_stencil:
+
+Stencil
+-------
+
+Since Godot 4.5, Godot allows materials to make use of the stencil buffer.
+This feature is commonly used to create outlines and X-ray effects,
+which can be useful to highlight objects, especially behind walls.
+
+The **Outline** and **X-Ray** modes assign a preconfigured stencil material
+in the material's **Next Pass** property. The **Custom** mode can be used for
+advanced effects.
+
+.. image:: img/material_stencil.webp
+
+Materials that write to the stencil buffer are always drawn in the transparent pass,
+so they are subject to the usual
+:ref:`transparency limitations <doc_3d_rendering_limitations_transparency_sorting>`.
+
+.. note::
+
+    Like with the :ref:`Grow property <ref_standard_material_3d_grow>`, for the
+    stencil outline to work as expected, the mesh must have connected faces with
+    shared vertices, or "smooth shading". If the mesh has disconnected faces with
+    unique vertices, or "flat shading", the mesh will appear to have gaps when using
+    a stencil outline.
+
+    Stencil outlines render similarly to the Grow property, but won't look identical
+    in every scenario, especially when intersections with opaque surfaces are involved.
+
 Material Settings
 -----------------
 

tutorials/3d/img/material_stencil.webp

@@ -36,6 +36,11 @@ 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.                                      |
+|                               | In Forward+ only, the pixel is also discarded if it's at the exact same depth as another pixel.      |
++-------------------------------+------------------------------------------------------------------------------------------------------+
+| **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).                                                                           |
@@ -91,6 +96,58 @@ 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 significant flaws are found in the API, it may change
+    in the next minor version.
+
+Stencil operations are a set of operations that allow writing to
+an efficient buffer in an hardware-accelerated manner.
+This is generally used to mask in or out parts of the scene.
+
+Some of the most well-known uses are:
+
+- Outlines: Mask out the inner mesh that is being outlined to avoid inner outlines.
+- X-Ray: Display a mesh behind other objects.
+- Portals: Draw geometry that is normally "impossible" (non-Euclidian) by masking objects.
+
+.. note::
+
+    You can only read from the stencil buffer in the transparent pass.
+    Any attempt to read in the opaque pass will fail, as it's currently not supported behavior.
+
+    Note that for compositor effects, the main renderer's stencil buffer can't be copied
+    to a custom texture.
+
++-------------------------------+------------------------------------------------------------------------------------------------------+
+| Stencil mode                  | Description                                                                                          |
++===============================+======================================================================================================+
+| **read**                      | Read from the stencil buffer.                                                                        |
++-------------------------------+------------------------------------------------------------------------------------------------------+
+| **write**                     | Write reference value to the stencil buffer.                                                         |
++-------------------------------+------------------------------------------------------------------------------------------------------+
+| **write_if_depth_fail**       | Write reference value to the stencil buffer if the depth test fails.                                 |
++-------------------------------+------------------------------------------------------------------------------------------------------+
+| **compare_always**            | Always pass stencil test.                                                                            |
++-------------------------------+------------------------------------------------------------------------------------------------------+
+| **compare_equal**             | Pass stencil test if the reference value is equal to the stencil buffer value.                       |
++-------------------------------+------------------------------------------------------------------------------------------------------+
+| **compare_not_equal**         | Pass stencil test if the reference value is not equal to the stencil buffer value.                   |
++-------------------------------+------------------------------------------------------------------------------------------------------+
+| **compare_less**              | Pass stencil test if the reference value is less than the stencil buffer value.                      |
++-------------------------------+------------------------------------------------------------------------------------------------------+
+| **compare_less_or_equal**     | Pass stencil test if the reference value is less than or equal to the stencil buffer value.          |
++-------------------------------+------------------------------------------------------------------------------------------------------+
+| **compare_greater**           | Pass stencil test if the reference value is greater than the stencil buffer value.                   |
++-------------------------------+------------------------------------------------------------------------------------------------------+
+| **compare_greater_or_equal**  | Pass stencil test if the reference value is greater than or equal to the stencil buffer value.       |
++-------------------------------+------------------------------------------------------------------------------------------------------+
+
 Built-ins
 ---------