Merge pull request #63413 from Calinou/volumetric-fog-add-per-light-energy-2

Add a per-light volumetric fog energy property

2 files changed, 43 insertions, 40 deletions

diff --git a/doc/classes/Light3D.xml b/doc/classes/Light3D.xml
index 80ff83ec46..cc8484d9fa 100644
--- a/doc/classes/Light3D.xml
+++ b/doc/classes/Light3D.xml
@@ -80,6 +80,10 @@
 		<member name="light_specular" type="float" setter="set_param" getter="get_param" default="0.5">
 			The intensity of the specular blob in objects affected by the light. At [code]0[/code], the light becomes a pure diffuse light. When not baking emission, this can be used to avoid unrealistic reflections when placing lights above an emissive surface.
 		</member>
+		<member name="light_volumetric_fog_energy" type="float" setter="set_param" getter="get_param" default="1.0">
+			Secondary multiplier multiplied with [member light_energy] then used with the [Environment]'s volumetric fog (if enabled). If set to [code]0.0[/code], computing volumetric fog will be skipped for this light, which can improve performance for large amounts of lights when volumetric fog is enabled.
+			[b]Note:[/b] To prevent short-lived dynamic light effects from poorly interacting with volumetric fog, lights used in those effects should have [member light_volumetric_fog_energy] set to [code]0.0[/code] unless [member Environment.volumetric_fog_temporal_reprojection_enabled] is disabled (or unless the reprojection amount is significantly lowered).
+		</member>
 		<member name="shadow_bias" type="float" setter="set_param" getter="get_param" default="0.1">
 			Used to adjust shadow appearance. Too small a value results in self-shadowing ("shadow acne"), while too large a value causes shadows to separate from casters ("peter-panning"). Adjust as needed.
 		</member>
@@ -89,8 +93,6 @@
 		<member name="shadow_enabled" type="bool" setter="set_shadow" getter="has_shadow" default="false">
 			If [code]true[/code], the light will cast real-time shadows. This has a significant performance cost. Only enable shadow rendering when it makes a noticeable difference in the scene's appearance, and consider using [member distance_fade_enabled] to hide the light when far away from the [Camera3D].
 		</member>
-		<member name="shadow_fog_fade" type="float" setter="set_param" getter="get_param" default="0.1">
-		</member>
 		<member name="shadow_normal_bias" type="float" setter="set_param" getter="get_param" default="1.0">
 			Offsets the lookup into the shadow map by the object's normal. This can be used to reduce self-shadowing artifacts without using [member shadow_bias]. In practice, this value should be tweaked along with [member shadow_bias] to reduce artifacts as much as possible.
 		</member>
@@ -110,57 +112,57 @@
 		<constant name="PARAM_INDIRECT_ENERGY" value="1" enum="Param">
 			Constant for accessing [member light_indirect_energy].
 		</constant>
-		<constant name="PARAM_SPECULAR" value="2" enum="Param">
+		<constant name="PARAM_VOLUMETRIC_FOG_ENERGY" value="2" enum="Param">
+			Constant for accessing [member light_volumetric_fog_energy].
+		</constant>
+		<constant name="PARAM_SPECULAR" value="3" enum="Param">
 			Constant for accessing [member light_specular].
 		</constant>
-		<constant name="PARAM_RANGE" value="3" enum="Param">
+		<constant name="PARAM_RANGE" value="4" enum="Param">
 			Constant for accessing [member OmniLight3D.omni_range] or [member SpotLight3D.spot_range].
 		</constant>
-		<constant name="PARAM_SIZE" value="4" enum="Param">
+		<constant name="PARAM_SIZE" value="5" enum="Param">
 			Constant for accessing [member light_size].
 		</constant>
-		<constant name="PARAM_ATTENUATION" value="5" enum="Param">
+		<constant name="PARAM_ATTENUATION" value="6" enum="Param">
 			Constant for accessing [member OmniLight3D.omni_attenuation] or [member SpotLight3D.spot_attenuation].
 		</constant>
-		<constant name="PARAM_SPOT_ANGLE" value="6" enum="Param">
+		<constant name="PARAM_SPOT_ANGLE" value="7" enum="Param">
 			Constant for accessing [member SpotLight3D.spot_angle].
 		</constant>
-		<constant name="PARAM_SPOT_ATTENUATION" value="7" enum="Param">
+		<constant name="PARAM_SPOT_ATTENUATION" value="8" enum="Param">
 			Constant for accessing [member SpotLight3D.spot_angle_attenuation].
 		</constant>
-		<constant name="PARAM_SHADOW_MAX_DISTANCE" value="8" enum="Param">
+		<constant name="PARAM_SHADOW_MAX_DISTANCE" value="9" enum="Param">
 			Constant for accessing [member DirectionalLight3D.directional_shadow_max_distance].
 		</constant>
-		<constant name="PARAM_SHADOW_SPLIT_1_OFFSET" value="9" enum="Param">
+		<constant name="PARAM_SHADOW_SPLIT_1_OFFSET" value="10" enum="Param">
 			Constant for accessing [member DirectionalLight3D.directional_shadow_split_1].
 		</constant>
-		<constant name="PARAM_SHADOW_SPLIT_2_OFFSET" value="10" enum="Param">
+		<constant name="PARAM_SHADOW_SPLIT_2_OFFSET" value="11" enum="Param">
 			Constant for accessing [member DirectionalLight3D.directional_shadow_split_2].
 		</constant>
-		<constant name="PARAM_SHADOW_SPLIT_3_OFFSET" value="11" enum="Param">
+		<constant name="PARAM_SHADOW_SPLIT_3_OFFSET" value="12" enum="Param">
 			Constant for accessing [member DirectionalLight3D.directional_shadow_split_3].
 		</constant>
-		<constant name="PARAM_SHADOW_FADE_START" value="12" enum="Param">
+		<constant name="PARAM_SHADOW_FADE_START" value="13" enum="Param">
 			Constant for accessing [member DirectionalLight3D.directional_shadow_fade_start].
 		</constant>
-		<constant name="PARAM_SHADOW_NORMAL_BIAS" value="13" enum="Param">
+		<constant name="PARAM_SHADOW_NORMAL_BIAS" value="14" enum="Param">
 			Constant for accessing [member shadow_normal_bias].
 		</constant>
-		<constant name="PARAM_SHADOW_BIAS" value="14" enum="Param">
+		<constant name="PARAM_SHADOW_BIAS" value="15" enum="Param">
 			Constant for accessing [member shadow_bias].
 		</constant>
-		<constant name="PARAM_SHADOW_PANCAKE_SIZE" value="15" enum="Param">
+		<constant name="PARAM_SHADOW_PANCAKE_SIZE" value="16" enum="Param">
 			Constant for accessing [member DirectionalLight3D.directional_shadow_pancake_size].
 		</constant>
-		<constant name="PARAM_SHADOW_OPACITY" value="16" enum="Param">
+		<constant name="PARAM_SHADOW_OPACITY" value="17" enum="Param">
 			Constant for accessing [member shadow_opacity].
 		</constant>
-		<constant name="PARAM_SHADOW_BLUR" value="17" enum="Param">
+		<constant name="PARAM_SHADOW_BLUR" value="18" enum="Param">
 			Constant for accessing [member shadow_blur].
 		</constant>
-		<constant name="PARAM_SHADOW_VOLUMETRIC_FOG_FADE" value="18" enum="Param">
-			Constant for accessing [member shadow_fog_fade].
-		</constant>
 		<constant name="PARAM_TRANSMITTANCE_BIAS" value="19" enum="Param">
 			Constant for accessing [member shadow_transmittance_bias].
 		</constant>
diff --git a/doc/classes/RenderingServer.xml b/doc/classes/RenderingServer.xml
index 755e8a5839..310e2334fb 100644
--- a/doc/classes/RenderingServer.xml
+++ b/doc/classes/RenderingServer.xml
@@ -3792,61 +3792,62 @@
 			Is a spot light.
 		</constant>
 		<constant name="LIGHT_PARAM_ENERGY" value="0" enum="LightParam">
-			The light's energy.
+			The light's energy multiplier.
 		</constant>
 		<constant name="LIGHT_PARAM_INDIRECT_ENERGY" value="1" enum="LightParam">
 			The light's indirect energy multiplier (final indirect energy is [constant LIGHT_PARAM_ENERGY] * [constant LIGHT_PARAM_INDIRECT_ENERGY]).
 		</constant>
-		<constant name="LIGHT_PARAM_SPECULAR" value="2" enum="LightParam">
+		<constant name="LIGHT_PARAM_VOLUMETRIC_FOG_ENERGY" value="2" enum="LightParam">
+			The light's volumetric fog energy multiplier (final volumetric fog energy is [constant LIGHT_PARAM_ENERGY] * [constant LIGHT_PARAM_VOLUMETRIC_FOG_ENERGY]).
+		</constant>
+		<constant name="LIGHT_PARAM_SPECULAR" value="3" enum="LightParam">
 			The light's influence on specularity.
 		</constant>
-		<constant name="LIGHT_PARAM_RANGE" value="3" enum="LightParam">
+		<constant name="LIGHT_PARAM_RANGE" value="4" enum="LightParam">
 			The light's range.
 		</constant>
-		<constant name="LIGHT_PARAM_SIZE" value="4" enum="LightParam">
+		<constant name="LIGHT_PARAM_SIZE" value="5" enum="LightParam">
 			The size of the light when using spot light or omni light. The angular size of the light when using directional light.
 		</constant>
-		<constant name="LIGHT_PARAM_ATTENUATION" value="5" enum="LightParam">
+		<constant name="LIGHT_PARAM_ATTENUATION" value="6" enum="LightParam">
 			The light's attenuation.
 		</constant>
-		<constant name="LIGHT_PARAM_SPOT_ANGLE" value="6" enum="LightParam">
+		<constant name="LIGHT_PARAM_SPOT_ANGLE" value="7" enum="LightParam">
 			The spotlight's angle.
 		</constant>
-		<constant name="LIGHT_PARAM_SPOT_ATTENUATION" value="7" enum="LightParam">
+		<constant name="LIGHT_PARAM_SPOT_ATTENUATION" value="8" enum="LightParam">
 			The spotlight's attenuation.
 		</constant>
-		<constant name="LIGHT_PARAM_SHADOW_MAX_DISTANCE" value="8" enum="LightParam">
+		<constant name="LIGHT_PARAM_SHADOW_MAX_DISTANCE" value="9" enum="LightParam">
 			Max distance that shadows will be rendered.
 		</constant>
-		<constant name="LIGHT_PARAM_SHADOW_SPLIT_1_OFFSET" value="9" enum="LightParam">
+		<constant name="LIGHT_PARAM_SHADOW_SPLIT_1_OFFSET" value="10" enum="LightParam">
 			Proportion of shadow atlas occupied by the first split.
 		</constant>
-		<constant name="LIGHT_PARAM_SHADOW_SPLIT_2_OFFSET" value="10" enum="LightParam">
+		<constant name="LIGHT_PARAM_SHADOW_SPLIT_2_OFFSET" value="11" enum="LightParam">
 			Proportion of shadow atlas occupied by the second split.
 		</constant>
-		<constant name="LIGHT_PARAM_SHADOW_SPLIT_3_OFFSET" value="11" enum="LightParam">
+		<constant name="LIGHT_PARAM_SHADOW_SPLIT_3_OFFSET" value="12" enum="LightParam">
 			Proportion of shadow atlas occupied by the third split. The fourth split occupies the rest.
 		</constant>
-		<constant name="LIGHT_PARAM_SHADOW_FADE_START" value="12" enum="LightParam">
+		<constant name="LIGHT_PARAM_SHADOW_FADE_START" value="13" enum="LightParam">
 			Proportion of shadow max distance where the shadow will start to fade out.
 		</constant>
-		<constant name="LIGHT_PARAM_SHADOW_NORMAL_BIAS" value="13" enum="LightParam">
+		<constant name="LIGHT_PARAM_SHADOW_NORMAL_BIAS" value="14" enum="LightParam">
 			Normal bias used to offset shadow lookup by object normal. Can be used to fix self-shadowing artifacts.
 		</constant>
-		<constant name="LIGHT_PARAM_SHADOW_BIAS" value="14" enum="LightParam">
+		<constant name="LIGHT_PARAM_SHADOW_BIAS" value="15" enum="LightParam">
 			Bias the shadow lookup to fix self-shadowing artifacts.
 		</constant>
-		<constant name="LIGHT_PARAM_SHADOW_PANCAKE_SIZE" value="15" enum="LightParam">
+		<constant name="LIGHT_PARAM_SHADOW_PANCAKE_SIZE" value="16" enum="LightParam">
 			Sets the size of the directional shadow pancake. The pancake offsets the start of the shadow's camera frustum to provide a higher effective depth resolution for the shadow. However, a high pancake size can cause artifacts in the shadows of large objects that are close to the edge of the frustum. Reducing the pancake size can help. Setting the size to [code]0[/code] turns off the pancaking effect.
 		</constant>
-		<constant name="LIGHT_PARAM_SHADOW_OPACITY" value="16" enum="LightParam">
+		<constant name="LIGHT_PARAM_SHADOW_OPACITY" value="17" enum="LightParam">
 			The light's shadow opacity. Values lower than [code]1.0[/code] make the light appear through shadows. This can be used to fake global illumination at a low performance cost.
 		</constant>
-		<constant name="LIGHT_PARAM_SHADOW_BLUR" value="17" enum="LightParam">
+		<constant name="LIGHT_PARAM_SHADOW_BLUR" value="18" enum="LightParam">
 			Blurs the edges of the shadow. Can be used to hide pixel artifacts in low resolution shadow maps. A high value can make shadows appear grainy and can cause other unwanted artifacts. Try to keep as near default as possible.
 		</constant>
-		<constant name="LIGHT_PARAM_SHADOW_VOLUMETRIC_FOG_FADE" value="18" enum="LightParam">
-		</constant>
 		<constant name="LIGHT_PARAM_TRANSMITTANCE_BIAS" value="19" enum="LightParam">
 		</constant>
 		<constant name="LIGHT_PARAM_MAX" value="20" enum="LightParam">