Merge pull request godotengine#8059 from Calinou/decal-reflection-probe-cluster-limits

Document Forward+ limitations with decal and reflection probe rendering

Author: akien-mga

tutorials/3d/global_illumination/reflection_probes.rst

@@ -3,6 +3,11 @@
 Reflection probes
 =================
 
+.. note::
+
+    Reflection probes are only supported in the Clustered Forward and Forward
+    Mobile rendering backends, not the Compatibility backend.
+
 As stated in the :ref:`doc_standard_material_3d`, objects can show reflected and/or
 diffuse light. Reflection probes are used as a source of reflected *and* ambient
 light for objects inside their area of influence. They can be used to provide
@@ -166,3 +171,19 @@ To make several ReflectionProbes blend with each other, you need to have part of
 each ReflectionProbe overlap each other's area. The extents should only overlap
 as little possible with other reflection probes to improve rendering performance
 (typically a few units in 3D space).
+
+Limitations
+-----------
+
+When using the Forward+ renderer, Godot uses a *clustering* approach for
+reflection probe rendering. As many reflection probes as desired can be added (as long as
+performance allows). However, there's still a default limit of 512 *clustered
+elements* that can be present in the current camera view. A clustered element is
+an omni light, a spot light, a :ref:`decal <doc_using_decals>` or a
+:ref:`reflection probe <doc_reflection_probes>`. This limit can be increased by
+adjusting the **Rendering > Limits > Cluster Builder > Max Clustered Elements**
+advanced project setting.
+
+When using the Forward Mobile backend, only 8 reflection probes can be applied on each
+individual Mesh *resource*. If there are more reflection probes affecting a single mesh,
+not all of them will be rendered on the mesh.

tutorials/3d/using_decals.rst

@@ -229,6 +229,15 @@ decals cannot use custom shaders. However, custom shaders on the projected
 surfaces are able to read the information that is overridden by decals on top of
 them, such as roughness and metallic.
 
+When using the Forward+ renderer, Godot uses a *clustering* approach for
+decal rendering. As many decals as desired can be added (as long as
+performance allows). However, there's still a default limit of 512 *clustered
+elements* that can be present in the current camera view. A clustered element is
+an omni light, a spot light, a :ref:`decal <doc_using_decals>` or a
+:ref:`reflection probe <doc_reflection_probes>`. This limit can be increased by
+adjusting the **Rendering > Limits > Cluster Builder > Max Clustered Elements**
+advanced project setting.
+
 When using the Forward Mobile backend, only 8 decals can be applied on each
 individual Mesh *resource*. If there are more decals affecting a single mesh,
 not all of them will be rendered on the mesh.