Link to transparency sorting limitations page in Spatial shaders (#5740)

Co-authored-by: Clay John <[email protected]>

tutorials/3d/3d_rendering_limitations.rst

@@ -76,6 +76,8 @@ Depending on the scene and viewing conditions, you may also be able to move the
 Z-fighting objects further apart without the difference being visible to the
 player.
 
+.. _doc_3d_rendering_limitations_transparency_sorting:
+
 Transparency sorting
 --------------------
 

tutorials/shaders/shader_reference/spatial_shader.rst

@@ -340,6 +340,13 @@ these properties, and if you don't write to them, Godot will optimize away the c
 | out vec4 **IRRADIANCE**                | If written to, blends environment map IRRADIANCE with IRRADIANCE.rgb based on IRRADIANCE.a.      |
 +----------------------------------------+--------------------------------------------------------------------------------------------------+
 
+.. note::
+
+    Shaders going through the transparent pipeline when ``ALPHA`` is written to
+    may exhibit transparency sorting issues. Read the
+    :ref:`transparency sorting section in the 3D rendering limitations page <doc_3d_rendering_limitations_transparency_sorting>`
+    for more information and ways to avoid issues.
+
 Light built-ins
 ^^^^^^^^^^^^^^^
 
@@ -423,3 +430,10 @@ If you want the lights to add together, add the light contribution to ``DIFFUSE_
 | out float **ALPHA**               | Alpha (0..1); if written to, the material will go  |
 |                                   | to the transparent pipeline.                       |
 +-----------------------------------+----------------------------------------------------+
+
+.. note::
+
+    Shaders going through the transparent pipeline when ``ALPHA`` is written to
+    may exhibit transparency sorting issues. Read the
+    :ref:`transparency sorting section in the 3D rendering limitations page <doc_3d_rendering_limitations_transparency_sorting>`
+    for more information and ways to avoid issues.