diff --git a/tutorials/3d/img/material_depth_test.webp b/tutorials/3d/img/material_depth_test.webp new file mode 100644 index 00000000000..6eb6342c614 Binary files /dev/null and b/tutorials/3d/img/material_depth_test.webp differ diff --git a/tutorials/3d/img/material_stencil.webp b/tutorials/3d/img/material_stencil.webp new file mode 100644 index 00000000000..c3f2d36e916 Binary files /dev/null and b/tutorials/3d/img/material_stencil.webp differ diff --git a/tutorials/3d/standard_material_3d.rst b/tutorials/3d/standard_material_3d.rst index b72add16b42..365fcde17c7 100644 --- a/tutorials/3d/standard_material_3d.rst +++ b/tutorials/3d/standard_material_3d.rst @@ -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 `__ 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 `. +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 `. + +.. note:: + + Like with the :ref:`Grow property `, 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 ----------------- diff --git a/tutorials/shaders/shader_reference/spatial_shader.rst b/tutorials/shaders/shader_reference/spatial_shader.rst index 267c2f9dc45..82ef8c90ff4 100644 --- a/tutorials/shaders/shader_reference/spatial_shader.rst +++ b/tutorials/shaders/shader_reference/spatial_shader.rst @@ -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 ---------