Document LightmapGI, LightmapGIData and LightmapProbe

This documents those 3 classes with 100% completion, while also
documenting the relevant project settings.

6 files changed, 74 insertions, 1 deletions

diff --git a/doc/classes/LightmapGI.xml b/doc/classes/LightmapGI.xml
index ee98356962..ffde0d95ce 100644
--- a/doc/classes/LightmapGI.xml
+++ b/doc/classes/LightmapGI.xml
@@ -4,80 +4,122 @@
 		Computes and stores baked lightmaps for fast global illumination.
 	</brief_description>
 	<description>
-		The [LightmapGI] node is used to compute and store baked lightmaps. Lightmaps are used to provide high-quality indirect lighting with very little light leaking. [LightmapGI] can also provide rough reflections using spherical harmonics if [member directional] is enabled. Dynamic objects can receive indirect lighting thanks to [i]light probes[/i], which can be automatically placed by setting [member generate_probes_subdiv]. Additional lightmap probes can also be added by creating [LightmapProbe] nodes. The downside is that lightmaps are fully static and cannot be baked in an exported project. Baking a [LightmapGI] node is also slower compared to [VoxelGI].
+		The [LightmapGI] node is used to compute and store baked lightmaps. Lightmaps are used to provide high-quality indirect lighting with very little light leaking. [LightmapGI] can also provide rough reflections using spherical harmonics if [member directional] is enabled. Dynamic objects can receive indirect lighting thanks to [i]light probes[/i], which can be automatically placed by setting [member generate_probes_subdiv] to a value other than [constant GENERATE_PROBES_DISABLED]. Additional lightmap probes can also be added by creating [LightmapProbe] nodes. The downside is that lightmaps are fully static and cannot be baked in an exported project. Baking a [LightmapGI] node is also slower compared to [VoxelGI].
 		[b]Procedural generation:[/b] Lightmap baking functionality is only available in the editor. This means [LightmapGI] is not suited to procedurally generated or user-built levels. For procedurally generated or user-built levels, use [VoxelGI] or SDFGI instead (see [member Environment.sdfgi_enabled]).
 		[b]Performance:[/b] [LightmapGI] provides the best possible run-time performance for global illumination. It is suitable for low-end hardware including integrated graphics and mobile devices.
+		[b]Note:[/b] Due to how lightmaps work, most properties only have a visible effect once lightmaps are baked again.
+		[b]Note:[/b] Lightmap baking on [CSGShape3D]s and [PrimitiveMesh]es is not supported, as these cannot store UV2 data required for baking.
+		[b]Note:[/b] If no custom lightmappers are installed, [LightmapGI] can only be baked when using the Vulkan backend (Clustered or Mobile), not OpenGL.
 	</description>
 	<tutorials>
 	</tutorials>
 	<members>
 		<member name="bias" type="float" setter="set_bias" getter="get_bias" default="0.0005">
+			The bias to use when computing shadows. Increasing [member bias] can fix shadow acne on the resulting baked lightmap, but can introduce peter-panning (shadows not connecting to their casters). Real-time [Light3D] shadows are not affected by this [member bias] property.
 		</member>
 		<member name="bounces" type="int" setter="set_bounces" getter="get_bounces" default="1">
+			Number of light bounces that are taken into account during baking. Higher values result in brighter, more realistic lighting, at the cost of longer bake times. If set to [code]0[/code], only environment lighting, direct light and emissive lighting is baked.
 		</member>
 		<member name="directional" type="bool" setter="set_directional" getter="is_directional" default="false">
+			If [code]true[/code], bakes lightmaps to contain directional information as spherical harmonics. This results in more realistic lighting appearance, especially with normal mapped materials and for lights that their have direct light baked ([member Light3D.light_bake_mode] set to [constant Light3D.BAKE_STATIC]). The directional information is also used to provide rough reflections for static and dynamic objects. This has a small run-time performance cost as the shader has to perform more work to interpret the direction information from the lightmap. Directional lightmaps also take longer to bake and result in larger file sizes.
+			[b]Note:[/b] The property's name has no relationship with [DirectionalLight3D]. [member directional] works with all light types.
 		</member>
 		<member name="environment_custom_color" type="Color" setter="set_environment_custom_color" getter="get_environment_custom_color">
+			The color to use for environment lighting. Only effective if [member environment_mode] is [constant ENVIRONMENT_MODE_CUSTOM_COLOR].
 		</member>
 		<member name="environment_custom_energy" type="float" setter="set_environment_custom_energy" getter="get_environment_custom_energy">
+			The color multiplier to use for environment lighting. Only effective if [member environment_mode] is [constant ENVIRONMENT_MODE_CUSTOM_COLOR].
 		</member>
 		<member name="environment_custom_sky" type="Sky" setter="set_environment_custom_sky" getter="get_environment_custom_sky">
+			The sky to use as a source of environment lighting. Only effective if [member environment_mode] is [constant ENVIRONMENT_MODE_CUSTOM_SKY].
 		</member>
 		<member name="environment_mode" type="int" setter="set_environment_mode" getter="get_environment_mode" enum="LightmapGI.EnvironmentMode" default="0">
+			The environment mode to use when baking lightmaps.
 		</member>
 		<member name="generate_probes_subdiv" type="int" setter="set_generate_probes" getter="get_generate_probes" enum="LightmapGI.GenerateProbes" default="0">
+			The level of subdivision to use when automatically generating [LightmapProbe]s for dynamic object lighting. Higher values result in more accurate indirect lighting on dynamic objects, at the cost of longer bake times and larger file sizes.
+			[b]Note:[/b] Automatically generated [LightmapProbe]s are not visible as nodes in the Scene tree dock, and cannot be modified this way after they are generated.
+			[b]Note:[/b] Regardless of [member generate_probes_subdiv], direct lighting on dynamic objects is always applied using [Light3D] nodes in real-time.
 		</member>
 		<member name="interior" type="bool" setter="set_interior" getter="is_interior" default="false">
+			If [code]true[/code], ignore environment lighting when baking lightmaps.
 		</member>
 		<member name="light_data" type="LightmapGIData" setter="set_light_data" getter="get_light_data">
+			The [LightmapGIData] associated to this [LightmapGI] node. This resource is automatically created after baking, and is not meant to be created manually.
 		</member>
 		<member name="max_texture_size" type="int" setter="set_max_texture_size" getter="get_max_texture_size" default="16384">
+			The maximum texture size for the generated texture atlas. Higher values will result in fewer slices being generated, but may not work on all hardware as a result of hardware limitations on texture sizes. Leave [member max_texture_size] at its default value of [code]16384[/code] if unsure.
 		</member>
 		<member name="quality" type="int" setter="set_bake_quality" getter="get_bake_quality" enum="LightmapGI.BakeQuality" default="1">
+			The quality preset to use when baking lightmaps. This affects bake times, but output file sizes remain mostly identical across quality levels.
+			To further speed up bake times, decrease [member bounces], disable [member use_denoiser] and increase the lightmap texel size on 3D scenes in the Import doc.
 		</member>
 		<member name="use_denoiser" type="bool" setter="set_use_denoiser" getter="is_using_denoiser" default="true">
+			If [code]true[/code], uses a CPU-based denoising algorithm on the generated lightmap. This eliminates most noise within the generated lightmap at the cost of longer bake times. File sizes are generally not impacted significantly by the use of a denoiser, although lossless compression may do a better job at compressing a denoised image.
+			[b]Note:[/b] The built-in denoiser (OpenImageDenoise) may crash when denoising lightmaps in large scenes. If you encounter a crash at the end of lightmap baking, try disabling [member use_denoiser].
 		</member>
 	</members>
 	<constants>
 		<constant name="BAKE_QUALITY_LOW" value="0" enum="BakeQuality">
+			Low bake quality (fastest bake times). The quality of this preset can be adjusted by changing [member ProjectSettings.rendering/lightmapping/bake_quality/low_quality_ray_count] and [member ProjectSettings.rendering/lightmapping/bake_quality/low_quality_probe_ray_count].
 		</constant>
 		<constant name="BAKE_QUALITY_MEDIUM" value="1" enum="BakeQuality">
+			Medium bake quality (fast bake times). The quality of this preset can be adjusted by changing [member ProjectSettings.rendering/lightmapping/bake_quality/medium_quality_ray_count] and [member ProjectSettings.rendering/lightmapping/bake_quality/medium_quality_probe_ray_count].
 		</constant>
 		<constant name="BAKE_QUALITY_HIGH" value="2" enum="BakeQuality">
+			High bake quality (slow bake times). The quality of this preset can be adjusted by changing [member ProjectSettings.rendering/lightmapping/bake_quality/high_quality_ray_count] and [member ProjectSettings.rendering/lightmapping/bake_quality/high_quality_probe_ray_count].
 		</constant>
 		<constant name="BAKE_QUALITY_ULTRA" value="3" enum="BakeQuality">
+			Highest bake quality (slowest bake times). The quality of this preset can be adjusted by changing [member ProjectSettings.rendering/lightmapping/bake_quality/high_quality_ray_count] and [member ProjectSettings.rendering/lightmapping/bake_quality/ultra_quality_probe_ray_count].
 		</constant>
 		<constant name="GENERATE_PROBES_DISABLED" value="0" enum="GenerateProbes">
+			Don't generate lightmap probes for lighting dynamic objects.
 		</constant>
 		<constant name="GENERATE_PROBES_SUBDIV_4" value="1" enum="GenerateProbes">
+			Lowest level of subdivision (fastest bake times, smallest file sizes).
 		</constant>
 		<constant name="GENERATE_PROBES_SUBDIV_8" value="2" enum="GenerateProbes">
+			Low level of subdivision (fast bake times, small file sizes).
 		</constant>
 		<constant name="GENERATE_PROBES_SUBDIV_16" value="3" enum="GenerateProbes">
+			High level of subdivision (slow bake times, large file sizes).
 		</constant>
 		<constant name="GENERATE_PROBES_SUBDIV_32" value="4" enum="GenerateProbes">
+			Highest level of subdivision (slowest bake times, largest file sizes).
 		</constant>
 		<constant name="BAKE_ERROR_OK" value="0" enum="BakeError">
+			Lightmap baking was successful.
 		</constant>
 		<constant name="BAKE_ERROR_NO_LIGHTMAPPER" value="1" enum="BakeError">
+			Lightmap baking failed as there is no lightmapper available in this Godot build.
 		</constant>
 		<constant name="BAKE_ERROR_NO_SAVE_PATH" value="2" enum="BakeError">
+			Lightmap baking failed as the [LightmapGIData] save path isn't configured in the resource.
 		</constant>
 		<constant name="BAKE_ERROR_NO_MESHES" value="3" enum="BakeError">
+			Lightmap baking failed as there are no meshes whose [member GeometryInstance3D.gi_mode] is [constant GeometryInstance3D.GI_MODE_STATIC] and with valid UV2 mapping in the current scene. You may need to select 3D scenes in the Import dock and change their global illumination mode accordingly.
 		</constant>
 		<constant name="BAKE_ERROR_MESHES_INVALID" value="4" enum="BakeError">
+			Lightmap baking failed as the lightmapper failed to analyze some of the meshes marked as static for baking.
 		</constant>
 		<constant name="BAKE_ERROR_CANT_CREATE_IMAGE" value="5" enum="BakeError">
+			Lightmap baking failed as the resulting image couldn't be saved or imported by Godot after it was saved.
 		</constant>
 		<constant name="BAKE_ERROR_USER_ABORTED" value="6" enum="BakeError">
+			The user aborted the lightmap baking operation (typically by clicking the [b]Cancel[/b] button in the progress dialog).
 		</constant>
 		<constant name="ENVIRONMENT_MODE_DISABLED" value="0" enum="EnvironmentMode">
+			Ignore environment lighting when baking lightmaps.
 		</constant>
 		<constant name="ENVIRONMENT_MODE_SCENE" value="1" enum="EnvironmentMode">
+			Use the scene's environment lighting when baking lightmaps.
+			[b]Note:[/b] If baking lightmaps in a scene with no [WorldEnvironment] node, this will act like [constant ENVIRONMENT_MODE_DISABLED]. The editor's preview sky and sun is [i]not[/i] taken into account by [LightmapGI] when baking lightmaps.
 		</constant>
 		<constant name="ENVIRONMENT_MODE_CUSTOM_SKY" value="2" enum="EnvironmentMode">
+			Use [member environment_custom_sky] as a source of environment lighting when baking lightmaps.
 		</constant>
 		<constant name="ENVIRONMENT_MODE_CUSTOM_COLOR" value="3" enum="EnvironmentMode">
+			Use [member environment_custom_color] multiplied by [member environment_custom_energy] as a constant source of environment lighting when baking lightmaps.
 		</constant>
 	</constants>
 </class>
diff --git a/doc/classes/LightmapGIData.xml b/doc/classes/LightmapGIData.xml
index c2423daef0..20113ac309 100644
--- a/doc/classes/LightmapGIData.xml
+++ b/doc/classes/LightmapGIData.xml
@@ -1,8 +1,10 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="LightmapGIData" inherits="Resource" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
 	<brief_description>
+		Contains baked lightmap and dynamic object probe data for [LightmapGI].
 	</brief_description>
 	<description>
+		[LightmapGIData] contains baked lightmap and dynamic object probe data for [LightmapGI]. It is replaced every time lightmaps are baked in [LightmapGI].
 	</description>
 	<tutorials>
 	</tutorials>
@@ -14,38 +16,46 @@
 			<argument index="2" name="slice_index" type="int" />
 			<argument index="3" name="sub_instance" type="int" />
 			<description>
+				Adds an object that is considered baked within this [LightmapGIData].
 			</description>
 		</method>
 		<method name="clear_users">
 			<return type="void" />
 			<description>
+				Clear all objects that are considred baked within this [LightmapGIData].
 			</description>
 		</method>
 		<method name="get_user_count" qualifiers="const">
 			<return type="int" />
 			<description>
+				Returns the number of objects that are considered baked within this [LightmapGIData].
 			</description>
 		</method>
 		<method name="get_user_path" qualifiers="const">
 			<return type="NodePath" />
 			<argument index="0" name="user_idx" type="int" />
 			<description>
+				Returns the [NodePath] of the baked object at index [code]user_idx[/code].
 			</description>
 		</method>
 		<method name="is_using_spherical_harmonics" qualifiers="const">
 			<return type="bool" />
 			<description>
+				If [code]true[/code], lightmaps were baked with directional information. See also [member LightmapGI.directional].
 			</description>
 		</method>
 		<method name="set_uses_spherical_harmonics">
 			<return type="void" />
 			<argument index="0" name="uses_spherical_harmonics" type="bool" />
 			<description>
+				If [code]uses_spherical_harmonics[/code] is [code]true[/code], tells the engine to treat the lightmap data as if it was baked with directional information.
+				[b]Note:[/b] Changing this value on already baked lightmaps will not cause them to be baked again. This means the material appearance will look incorrect until lightmaps are baked again, in which case the value set here is discarded as the entire [LightmapGIData] resource is replaced by the lightmapper.
 			</description>
 		</method>
 	</methods>
 	<members>
 		<member name="light_texture" type="TextureLayered" setter="set_light_texture" getter="get_light_texture">
+			The lightmap atlas texture generated by the lightmapper.
 		</member>
 	</members>
 </class>
diff --git a/doc/classes/LightmapProbe.xml b/doc/classes/LightmapProbe.xml
index a5ba6294b9..cb4879b6c7 100644
--- a/doc/classes/LightmapProbe.xml
+++ b/doc/classes/LightmapProbe.xml
@@ -1,8 +1,11 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="LightmapProbe" inherits="Node3D" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
 	<brief_description>
+		Represents a single manually placed probe for dynamic object lighting with [LightmapGI].
 	</brief_description>
 	<description>
+		[LightmapProbe] represents the position of a single manually placed probe for dynamic object lighting with [LightmapGI].
+		Typically, [LightmapGI] probes are placed automatically by setting [member LightmapGI.generate_probes_subdiv] to a value other than [constant LightmapGI.GENERATE_PROBES_DISABLED]. By creating [LightmapProbe] nodes before baking lightmaps, you can add more probes in specific areas for greater detail, or disable automatic generation and rely only on manually placed probes instead.
 	</description>
 	<tutorials>
 	</tutorials>
diff --git a/doc/classes/Lightmapper.xml b/doc/classes/Lightmapper.xml
index f9a1e2fa99..58ef2ed0cf 100644
--- a/doc/classes/Lightmapper.xml
+++ b/doc/classes/Lightmapper.xml
@@ -1,8 +1,11 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="Lightmapper" inherits="RefCounted" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
 	<brief_description>
+		Abstract class extended by lightmappers, for use in [LightmapGI].
 	</brief_description>
 	<description>
+		This class should be extended by custom lightmapper classes. Lightmappers can then be used with [LightmapGI] to provide fast baked global illumination in 3D.
+		Godot contains a built-in GPU-based lightmapper [LightmapperRD] that uses compute shaders, but custom lightmappers can be implemented by C++ modules.
 	</description>
 	<tutorials>
 	</tutorials>
diff --git a/doc/classes/LightmapperRD.xml b/doc/classes/LightmapperRD.xml
index 29d95244ce..e4b68a7ef8 100644
--- a/doc/classes/LightmapperRD.xml
+++ b/doc/classes/LightmapperRD.xml
@@ -1,8 +1,11 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="LightmapperRD" inherits="Lightmapper" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
 	<brief_description>
+		The built-in GPU-based lightmapper for use with [LightmapGI].
 	</brief_description>
 	<description>
+		LightmapperRD ("RD" stands for [RenderingDevice]) is the built-in GPU-based lightmapper for use with [LightmapGI]. On most dedicated GPUs, it can bake lightmaps much faster than most CPU-based lightmappers. LightmapperRD uses compute shaders to bake lightmaps, so it does not require CUDA or OpenCL libraries to be installed to be usable.
+		[b]Note:[/b] Only usable when using the Vulkan backend (Clustered or Mobile), not OpenGL.
 	</description>
 	<tutorials>
 	</tutorials>
diff --git a/doc/classes/ProjectSettings.xml b/doc/classes/ProjectSettings.xml
index 8a3677c0b4..25f0a997ba 100644
--- a/doc/classes/ProjectSettings.xml
+++ b/doc/classes/ProjectSettings.xml
@@ -1714,28 +1714,40 @@
 		<member name="rendering/global_illumination/voxel_gi/quality" type="int" setter="" getter="" default="0">
 		</member>
 		<member name="rendering/lightmapping/bake_performance/max_rays_per_pass" type="int" setter="" getter="" default="32">
+			The maximum number of rays that can be thrown per pass when baking lightmaps with [LightmapGI]. Depending on the scene, adjusting this value may result in higher GPU utilization when baking lightmaps, leading to faster bake times.
 		</member>
 		<member name="rendering/lightmapping/bake_performance/max_rays_per_probe_pass" type="int" setter="" getter="" default="64">
+			The maximum number of rays that can be thrown per pass when baking dynamic object lighting in [LightmapProbe]s with [LightmapGI]. Depending on the scene, adjusting this value may result in higher GPU utilization when baking lightmaps, leading to faster bake times.
 		</member>
 		<member name="rendering/lightmapping/bake_performance/region_size" type="int" setter="" getter="" default="512">
+			The region size to use when baking lightmaps with [LightmapGI].
 		</member>
 		<member name="rendering/lightmapping/bake_quality/high_quality_probe_ray_count" type="int" setter="" getter="" default="512">
+			The number of rays to use for baking dynamic object lighting in [LightmapProbe]s when [member LightmapGI.quality] is [constant LightmapGI.BAKE_QUALITY_HIGH].
 		</member>
 		<member name="rendering/lightmapping/bake_quality/high_quality_ray_count" type="int" setter="" getter="" default="256">
+			The number of rays to use for baking lightmaps with [LightmapGI] when [member LightmapGI.quality] is [constant LightmapGI.BAKE_QUALITY_HIGH].
 		</member>
 		<member name="rendering/lightmapping/bake_quality/low_quality_probe_ray_count" type="int" setter="" getter="" default="64">
+			The number of rays to use for baking dynamic object lighting in [LightmapProbe]s when [member LightmapGI.quality] is [constant LightmapGI.BAKE_QUALITY_LOW].
 		</member>
 		<member name="rendering/lightmapping/bake_quality/low_quality_ray_count" type="int" setter="" getter="" default="16">
+			The number of rays to use for baking lightmaps with [LightmapGI] when [member LightmapGI.quality] is [constant LightmapGI.BAKE_QUALITY_LOW].
 		</member>
 		<member name="rendering/lightmapping/bake_quality/medium_quality_probe_ray_count" type="int" setter="" getter="" default="256">
+			The number of rays to use for baking dynamic object lighting in [LightmapProbe]s when [member LightmapGI.quality] is [constant LightmapGI.BAKE_QUALITY_MEDIUM].
 		</member>
 		<member name="rendering/lightmapping/bake_quality/medium_quality_ray_count" type="int" setter="" getter="" default="64">
+			The number of rays to use for baking lightmaps with [LightmapGI] when [member LightmapGI.quality] is [constant LightmapGI.BAKE_QUALITY_MEDIUM].
 		</member>
 		<member name="rendering/lightmapping/bake_quality/ultra_quality_probe_ray_count" type="int" setter="" getter="" default="2048">
+			The number of rays to use for baking dynamic object lighting in [LightmapProbe]s when [member LightmapGI.quality] is [constant LightmapGI.BAKE_QUALITY_ULTRA].
 		</member>
 		<member name="rendering/lightmapping/bake_quality/ultra_quality_ray_count" type="int" setter="" getter="" default="1024">
+			The number of rays to use for baking lightmaps with [LightmapGI] when [member LightmapGI.quality] is [constant LightmapGI.BAKE_QUALITY_ULTRA].
 		</member>
 		<member name="rendering/lightmapping/probe_capture/update_speed" type="float" setter="" getter="" default="15">
+			The framerate-independent update speed when representing dynamic object lighting from [LightmapProbe]s. Higher values make dynamic object lighting update faster. Higher values can prevent fast-moving objects from having "outdated" indirect lighting displayed on them, at the cost of possible flickering when an object moves from a bright area to a shaded area.
 		</member>
 		<member name="rendering/limits/cluster_builder/max_clustered_elements" type="float" setter="" getter="" default="512">
 		</member>