Skip to content

Add initial stencil documentation #10991

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
+57 −0
Open

Add initial stencil documentation #10991

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
57 changes: 57 additions & 0 deletions tutorials/shaders/shader_reference/spatial_shader.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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. |
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Will need to mention using Depth test equal for opaque pass in in Forward+ renderer

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Will need to mention using Depth test equal for opaque pass in in Forward+ renderer

What would a user do with that extra information? I can't think of a scenario in which the user can tell the difference.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don' tthink i can fit it in this line of the documentation. any suggestion on where to put it?

+-------------------------------+------------------------------------------------------------------------------------------------------+
| **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). |
Expand Down Expand Up @@ -90,6 +94,59 @@ 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 stencil in the transparent pass.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
You can only read from stencil in the transparent pass.
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.

Also, stencil operations aren't yet supported in compositor effects.
Please use the full screen quad method described in
:ref:`doc_advanced_postprocessing` instead.

+-------------------------------+------------------------------------------------------------------------------------------------------+
| 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. |
+-------------------------------+------------------------------------------------------------------------------------------------------+
Comment on lines +136 to +138
Copy link
Contributor

@MJacred MJacred Jun 6, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

missing documentation:

+-------------------------------+------------------------------------------------------------------------------------------------------+
| **compare_always**            | Always pass stencil test.                                                                            |
+-------------------------------+------------------------------------------------------------------------------------------------------+

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The missing documentation was amended. Though there seems to be one space too many in the Stencil mode column and the dot is missing in the Description text.

| **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
---------

Expand Down
Loading