Document SpatialMaterial refraction limitations

about/list_of_features.rst

@@ -181,7 +181,7 @@ Editor
 - Dithering can be determined on a per-pixel or per-object basis.
 - *GLES3:* Parallax/relief mapping with automatic level of detail based on distance.
 - *GLES3:* Sub-surface scattering and transmittance.
-- *GLES3:* Refraction with support for material roughness (resulting in blurry refraction).
+- *GLES3:* Screen-space refraction with support for material roughness (resulting in blurry refraction).
   On GLES2, refraction is still functional but lacks support for material roughness.
 - *GLES3:* Proximity fade (soft particles).
 

tutorials/3d/spatial_material.rst

@@ -484,8 +484,31 @@ When refraction is enabled, it supersedes alpha blending, and Godot attempts to
 fetch information from behind the object being rendered instead. This allows
 distorting the transparency in a way similar to refraction in real life.
 
+Remember to use a transparent albedo texture (or reduce the albedo color's alpha
+channel) to make refraction visible, as refraction relies on transparency to
+have a visible effect.
+
+A normal map can optionally be specified in the **Refraction Texture** property
+to allow distorting the refraction's direction on a per-pixel basis.
+
 .. image:: img/spatial_material23.png
 
+.. note::
+
+    Refraction is implemented as a screen-space effect and forces the material
+    to be transparent. This makes the effect relatively fast, but this results
+    in some limitations:
+
+    - :ref:`Transparency sorting <doc_3d_rendering_limitations_transparency_sorting>`
+      issues may occur.
+    - The refractive material cannot refract onto itself, or onto other
+      transparent materials. A refractive material behind another transparent
+      material will be invisible.
+    - Off-screen objects cannot appear in the refraction. This is most
+      noticeable with high refraction strength values.
+    - Opaque materials in front of the refractive material will appear to have
+      "refracted" edges, even though they shouldn't.
+
 Detail
 ~~~~~~