Revamp global illumination documentation

- Add an introduction page with an explanation and comparison table. - Add a page on faking global illumination.
godotengine · Oct 12, 2022 · 8d8538d · 8d8538d
1 parent f5b3a2f
commit 8d8538d
Show file tree

Hide file tree

Showing 44 changed files with 1,431 additions and 625 deletions.
diff --git a/tutorials/3d/3d_rendering_limitations.rst b/tutorials/3d/3d_rendering_limitations.rst
@@ -23,6 +23,8 @@ your texture to display correctly on all platforms, you should avoid using
 textures larger than 4096×4096 and use a power of two size if the texture needs
 to repeat.
 
+.. _doc_3d_rendering_limitations_color_banding:
+
 Color banding
 -------------
 

diff --git a/tutorials/3d/baked_lightmaps.rst b/tutorials/3d/baked_lightmaps.rst
diff --git a/tutorials/3d/faking_global_illumination.rst b/tutorials/3d/faking_global_illumination.rst
@@ -0,0 +1,100 @@
+.. _doc_faking_global_illumination:
+
+Faking global illumination
+==========================
+
+Why fake global illumination?
+-----------------------------
+
+Godot provides several global illumination (GI) techniques, all with their advantages
+and drawbacks. Nonetheless, it remains possible to avoid using any GI technique
+and use a handmade approach instead. There are a few reasons for using a
+"handmade" approach to global illumination instead of VoxelGI, SDFGI or
+baked lightmaps:
+
+- You need to have good rendering performance, but can't afford going through
+  a potentially cumbersome lightmap baking process.
+- You need an approach to GI that is fully real-time *and* works in procedurally
+  generated levels.
+- You need an approach to GI that is fully real-time *and* does not suffer from
+  significant light leaks.
+
+The approaches described below only cover indirect diffuse lighting, not
+specular lighting. For specular lighting, consider using ReflectionProbes which
+are usually cheap enough to be used in conjunction with this fake GI approach.
+
+.. seealso::
+
+    Not sure if faking global illumination with lights is suited to your needs?
+    See :ref:`doc_introduction_to_global_illumination_comparison` for a
+    comparison of GI techniques available in Godot 4.
+
+Faking DirectionalLight3D global illumination
+---------------------------------------------
+
+While the sky provides its own directional lighting, the scene's main DirectionalLight3D
+node typically emits a large amount of light. When using a GI technique, this light
+would be reflected on solid surfaces and would bounce back on most outdoors shaded surfaces.
+
+We can fake this by adding a second DirectionalLight3D node with the following changes:
+
+- Rotate the light by 180 degrees. This allows it to represent lighting bounced
+  by the main DirectionalLight3D node.
+- Set **Shadows** to **Off**. This reduces the secondary light's performance burden
+  while also allowing shaded areas to receive *some* lighting (which is what we want here).
+- Set **Energy** to 10-40% of the original value. There is no "perfect" value,
+  so experiment with various energy values depending on the light and your typical
+  material colors.
+- Set **Specular** to ``0.0``. Indirect lighting shouldn't emit visible specular
+  lobes, so we need to disable specular lighting entirely for the secondary light.
+
+.. note::
+
+    This approach works best in scenes that are mostly outdoors. When going indoors,
+    the secondary DirectionalLight3D's light will still be visible as this light
+    has shadows disabled.
+
+    This can be worked around by smoothly decreasing the secondary DirectionalLight3D's
+    energy when entering an indoor area (and doing the opposite when leaving the indoor area).
+    For instance, this can be achieved using an Area3D node and AnimationPlayer.
+
+Faking positional light global illumination
+-------------------------------------------
+
+It's possible to follow the same approach as DirectionalLight3D for positional
+lights (OmniLight3D and SpotLight3D). However, this will require more manual
+work as this operation needs to be repeated for every positional light node in
+the scene to look good.
+
+In an ideal scenario, additional OmniLight3Ds should be added at every location
+where a significant amount of light hits a bright enough surface. However, due
+to time constraints, this isn't always easily feasible (especially when
+performing procedural level generation).
+
+If you're in a hurry, you can place a secondary OmniLight3D node at the same position
+as the main OmniLight3D node.
+You can add this node as a child of the main OmniLight3D node to make it easy to
+move and hide both nodes at the same time.
+
+In the secondary OmniLight3D node, perform the following changes:
+
+- Increase the light's **Range** by 25-50%. This allows the secondary light to lighten
+  what was previously not lit by the original light.
+- Set **Shadows** to **Off**. This reduces the secondary light's performance burden
+  while also allowing shaded areas to receive *some* lighting (which is what we want here).
+- Set **Energy** to 10-40% of the original value. There is no "perfect" value,
+  so experiment with various energy values depending on the light and its surroundings.
+- Set **Specular** to 0. Indirect lighting shouldn't emit visible specular lobes,
+  so we need to disable specular lighting entirely for the secondary light.
+
+For SpotLight3D, the same trick can be used. In this case, the secondary OmniLight3D
+should be placed in a way that reflects where *most* light will be bounced.
+This is usually close to the SpotLight3D's primary impact location.
+
+In the example below, a SpotLight3D node is used to light up the room's floor.
+However, since there is no indirect lighting, the rest of the room remains
+entirely dark. In real life, the room's walls and ceiling would be lit up by
+light bouncing around. Using an OmniLight3D node positioned between the
+SpotLight3D's origin and the floor allows simulating this effect:
+
+.. image:: img/faking_global_illumination_comparison.png
diff --git a/tutorials/3d/gi_probes.rst b/tutorials/3d/gi_probes.rst
diff --git a/tutorials/3d/img/average.png b/tutorials/3d/img/average.png
diff --git a/tutorials/3d/img/bad.png b/tutorials/3d/img/bad.png
diff --git a/tutorials/3d/img/baked_light_import.png b/tutorials/3d/img/baked_light_import.png
diff --git a/tutorials/3d/img/baked_light_indirect.gif b/tutorials/3d/img/baked_light_indirect.gif
diff --git a/tutorials/3d/img/faking_global_illumination_comparison.png b/tutorials/3d/img/faking_global_illumination_comparison.png
diff --git a/tutorials/3d/img/gi_lightmap_gi_direct_and_indirect.png b/tutorials/3d/img/gi_lightmap_gi_direct_and_indirect.png
diff --git a/tutorials/3d/img/gi_lightmap_gi_indirect_only.png b/tutorials/3d/img/gi_lightmap_gi_indirect_only.png
diff --git a/tutorials/3d/img/gi_lightmap_gi_indirect_only_reflection_probe.png b/tutorials/3d/img/gi_lightmap_gi_indirect_only_reflection_probe.png
diff --git a/tutorials/3d/img/gi_none.png b/tutorials/3d/img/gi_none.png
diff --git a/tutorials/3d/img/gi_none_reflection_probe.png b/tutorials/3d/img/gi_none_reflection_probe.png
diff --git a/tutorials/3d/img/gi_sdfgi.png b/tutorials/3d/img/gi_sdfgi.png
diff --git a/tutorials/3d/img/gi_ssil_only.png b/tutorials/3d/img/gi_ssil_only.png
diff --git a/tutorials/3d/img/gi_voxel_gi.png b/tutorials/3d/img/gi_voxel_gi.png
diff --git a/tutorials/3d/img/global_illumination_example.png b/tutorials/3d/img/global_illumination_example.png
diff --git a/tutorials/3d/img/good.png b/tutorials/3d/img/good.png
diff --git a/tutorials/3d/img/baked_light_bake.png → tutorials/3d/img/lightmap_gi_bake.png b/tutorials/3d/img/baked_light_bake.png → tutorials/3d/img/lightmap_gi_bake.png
diff --git a/tutorials/3d/img/baked_light_bake_mode.png → tutorials/3d/img/lightmap_gi_bake_mode.png b/tutorials/3d/img/baked_light_bake_mode.png → tutorials/3d/img/lightmap_gi_bake_mode.png
diff --git a/tutorials/3d/img/baked_light_blender.png → tutorials/3d/img/lightmap_gi_blender.png b/tutorials/3d/img/baked_light_blender.png → tutorials/3d/img/lightmap_gi_blender.png
diff --git a/tutorials/3d/img/baked_light_bounds.png → tutorials/3d/img/lightmap_gi_bounds.png b/tutorials/3d/img/baked_light_bounds.png → tutorials/3d/img/lightmap_gi_bounds.png
diff --git a/tutorials/3d/img/baked_light_capture.png → tutorials/3d/img/lightmap_gi_capture.png b/tutorials/3d/img/baked_light_capture.png → tutorials/3d/img/lightmap_gi_capture.png
diff --git a/tutorials/3d/img/baked_light_comparison.png → tutorials/3d/img/lightmap_gi_comparison.png b/tutorials/3d/img/baked_light_comparison.png → tutorials/3d/img/lightmap_gi_comparison.png
diff --git a/tutorials/3d/img/lightmap_gi_import.png b/tutorials/3d/img/lightmap_gi_import.png
diff --git a/tutorials/3d/img/baked_light_lmsize.png → tutorials/3d/img/lightmap_gi_lmsize.png b/tutorials/3d/img/baked_light_lmsize.png → tutorials/3d/img/lightmap_gi_lmsize.png
diff --git a/tutorials/3d/img/lightmap_gi_mesh_import_meshes.png b/tutorials/3d/img/lightmap_gi_mesh_import_meshes.png
diff --git a/tutorials/3d/img/baked_light_mesh_menu.png → tutorials/3d/img/lightmap_gi_mesh_menu.png b/tutorials/3d/img/baked_light_mesh_menu.png → tutorials/3d/img/lightmap_gi_mesh_menu.png
diff --git a/tutorials/3d/img/baked_light_mode.png → tutorials/3d/img/lightmap_gi_mode.png b/tutorials/3d/img/baked_light_mode.png → tutorials/3d/img/lightmap_gi_mode.png
diff --git a/...als/3d/img/baked_light_omnilight_size.png → ...als/3d/img/lightmap_gi_omnilight_size.png b/...als/3d/img/baked_light_omnilight_size.png → ...als/3d/img/lightmap_gi_omnilight_size.png
diff --git a/tutorials/3d/img/baked_light_scene.png → tutorials/3d/img/lightmap_gi_scene.png b/tutorials/3d/img/baked_light_scene.png → tutorials/3d/img/lightmap_gi_scene.png
diff --git a/tutorials/3d/img/baked_light_use.png → tutorials/3d/img/lightmap_gi_use.png b/tutorials/3d/img/baked_light_use.png → tutorials/3d/img/lightmap_gi_use.png
diff --git a/tutorials/3d/img/baked_light_uvchannel.png → tutorials/3d/img/lightmap_gi_uvchannel.png b/tutorials/3d/img/baked_light_uvchannel.png → tutorials/3d/img/lightmap_gi_uvchannel.png
diff --git a/tutorials/3d/index.rst b/tutorials/3d/index.rst
@@ -10,9 +10,6 @@
    3d_rendering_limitations
    standard_material_3d
    lights_and_shadows
-   reflection_probes
-   gi_probes
-   baked_lightmaps
    environment_and_post_processing
    volumetric_fog
    high_dynamic_range
@@ -24,3 +21,17 @@
    mesh_lod
    visibility_ranges
    occlusion_culling
+
+Global illumination
+-------------------
+
+.. toctree::
+   :maxdepth: 1
+   :name: toc-learn-features-3d-global-illumination
+
+   introduction_to_global_illumination
+   using_voxel_gi
+   sdfgi
+   using_lightmap_gi
+   reflection_probes
+   faking_global_illumination