Merge pull request #9332 from lawnjelly/lod

LOD and updating optimizing 3D docs

tutorials/3d/index.rst

@@ -19,6 +19,7 @@
    using_multi_mesh_instance
    csg_tools
    procedural_geometry/index
+   level_of_detail
    occluders
    portals/index
    merge_groups

tutorials/3d/level_of_detail.rst

@@ -0,0 +1,64 @@
+.. _doc_level_of_detail:
+
+Level of Detail (LOD)
+=====================
+
+Level of detail (LOD) is one of the most important ways to optimize rendering
+(and performance in general) in a 3D project, along with occlusion culling.
+
+The LOD node
+------------
+
+The ``LOD`` node provides a simple way of automatically switching between visual
+representations as the node gets closer or further from the
+:ref:`Camera <class_Camera>`, in order to increase performance.
+
+You might:
+
+-  substitute lower poly count meshes
+-  swap several separate meshes for a single approximate mesh
+-  swap from a mesh to a billboard
+-  turn off particle effects, animations, sounds, scripts according to distance
+-  entirely remove visuals in the distance
+
+The ``LOD`` node should be added as a parent to whatever you wish to use to show
+the object, e.g. a :ref:`MeshInstance <class_MeshInstance>`. You can place
+several :ref:`Spatial <class_Spatial>` derived nodes as children.
+
+.. image:: img/lod_node_scene.webp
+
+The ``LOD`` node will automatically hide and show Spatial children depending on
+the distance from the ``Camera``.
+
+.. tip::
+
+    You can react to ``NOTIFICATION_VISIBILITY_CHANGED`` in scripts to detect
+    when a node has been shown or hidden.
+    
+Children are shown in order with the first children shown when closest to the
+``Camera``, and the latter children shown when further away.
+
+You can determine the distance at which these swaps occur by setting the
+**lod_range** property of ``Spatial``.
+
+.. note::
+
+    Children of the ``LOD`` node can in turn have any number of children, of
+    any type. These grandchildren will inherit their visibility as the ``LOD``
+    node operates.
+
+One of the most common cases is to swap between high-poly and low-poly models.
+
+.. figure:: img/lod_wireframe.webp
+   :align: center
+   :alt: From most detailed (left) to least detailed (right), wireframe view
+
+   From most detailed (left) to least detailed (right), wireframe view
+
+.. note::
+
+    Godot 3.x does not currently generate decimated meshes for you.
+    You are advised to generate several versions of a mesh in your
+    modeling program (e.g. using the Decimate modifier in Blender).
+
+

tutorials/performance/optimizing_3d_performance.rst

@@ -44,12 +44,20 @@ It is a very powerful technique for speeding up rendering. You can also use it t
 restrict physics or AI to the local area, and speed these up as well as
 rendering.
 
+However, there are easier ways to take advantage of occlusion. Godot includes two
+built-in systems to automate occlusion culling:
+
+Occluders
+~~~~~~~~~
+
+Occluder nodes can manually be placed in a scene. These will automatically hide
+objects that are behind the occluder. See :ref:`Occluder Nodes <doc_occluders>`.
+
 Portal Rendering
 ~~~~~~~~~~~~~~~~
 
-However, there is a much easier way to take advantage of occlusion. Godot features
-an advanced portal rendering system, which can perform occlusion culling from cameras and
-lights. See :ref:`doc_rooms_and_portals`.
+Godot features an advanced portal rendering system, which can perform occlusion
+culling from cameras and lights. See :ref:`doc_rooms_and_portals`.
 
 This is not a fully automatic system and it requires some manual setup. However, it potentially
 offers significant performance increases.
@@ -92,6 +100,10 @@ in the far distance. There are several strategies for replacing models at
 varying distance. You could use lower poly models, or use transparency to
 simulate more complex geometry.
 
+You can either implement LOD manually, or make use of the ``LOD`` node, which
+automates much of the process. See the :ref:`Level of Detail <doc_level_of_detail>`
+documentation.
+
 Billboards and imposters
 ~~~~~~~~~~~~~~~~~~~~~~~~