Merge pull request #10762 from Calinou/mesh-automatic-instancing

Clarify the behavior of MeshInstance3D automatic instancing

contributing/development/core_and_modules/internal_rendering_architecture.rst

@@ -450,9 +450,10 @@ used to calculate particle collisions in 2D.
 Batching and instancing
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-In the Forward+ renderer, Vulkan instancing is used to group rendering
-of identical objects for performance. This is not as fast as static mesh
-merging, but it still allows instances to be culled individually.
+In the Forward+ renderer, Vulkan instancing is used to group rendering of
+identical opaque or alpha-tested objects for performance. (Alpha-blended objects
+are never instanced.) This is not as fast as static mesh merging, but it still
+allows instances to be culled individually.
 
 Light, decal and reflection probe rendering
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

tutorials/performance/optimizing_3d_performance.rst

@@ -104,8 +104,22 @@ the viewer a considerable distance for the angle of view to change
 significantly. This can be complex to get working, but may be worth it depending
 on the type of project you are making.
 
-Use instancing (MultiMesh)
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+Use automatic instancing
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+*This is only implemented in the Forward+ renderer, not Mobile or Compatibility.*
+
+If you have many identical objects in your scene, you can use automatic
+instancing to reduce the number of draw calls. This automatically happens for
+MeshInstance3D nodes that use the same mesh and material: no manual setup is required.
+
+For automatic instancing to be effective, the material must be opaque or
+alpha-tested (alpha scissor or alpha hash). Alpha-blended or depth pre-pass
+materials are never instanced this way. Instead, you must use MultiMesh as
+described below.
+
+Use manual instancing (MultiMesh)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 If several identical objects have to be drawn in the same place or nearby, try
 using :ref:`MultiMesh <class_MultiMesh>` instead. MultiMesh allows the drawing