Merge pull request #58512 from Calinou/light3d-add-distance-fade

2 files changed, 29 insertions, 1 deletions

diff --git a/doc/classes/Light3D.xml b/doc/classes/Light3D.xml
index a058611915..0350d09dfd 100644
--- a/doc/classes/Light3D.xml
+++ b/doc/classes/Light3D.xml
@@ -28,6 +28,23 @@
 		</method>
 	</methods>
 	<members>
+		<member name="distance_fade_begin" type="float" setter="set_distance_fade_begin" getter="get_distance_fade_begin" default="40.0">
+			The distance from the camera at which the light begins to fade away (in 3D units).
+			[b]Note:[/b] Only effective for [OmniLight3D] and [SpotLight3D].
+		</member>
+		<member name="distance_fade_enabled" type="bool" setter="set_enable_distance_fade" getter="is_distance_fade_enabled" default="false">
+			If [code]true[/code], the light will smoothly fade away when far from the active [Camera3D] starting at [member distance_fade_begin]. This acts as a form of level of detail (LOD). The light will fade out over [member distance_fade_begin] + [member distance_fade_length], after which it will be culled and not sent to the shader at all. Use this to reduce the number of active lights in a scene and thus improve performance.
+			[b]Note:[/b] Only effective for [OmniLight3D] and [SpotLight3D].
+		</member>
+		<member name="distance_fade_length" type="float" setter="set_distance_fade_length" getter="get_distance_fade_length" default="10.0">
+			Distance over which the light fades. The light's energy is progressively reduced over this distance and is completely invisible at the end.
+			[b]Note:[/b] Only effective for [OmniLight3D] and [SpotLight3D].
+		</member>
+		<member name="distance_fade_shadow" type="float" setter="set_distance_fade_shadow" getter="get_distance_fade_shadow" default="50.0">
+			The distance from the camera at which the light's shadow cuts off (in 3D units). Set this to a value lower than [member distance_fade_begin] + [member distance_fade_length] to further improve performance, as shadow rendering is often more expensive than light rendering itself.
+			[b]Note:[/b] Only effective for [OmniLight3D] and [SpotLight3D], and only when [member shadow_enabled] is [code]true[/code].
+			[b]Note:[/b] Due to a rendering engine limitation, shadows will be disabled instantly instead of fading smoothly according to [member distance_fade_length]. This may result in visible pop-in depending on the scene topography.
+		</member>
 		<member name="editor_only" type="bool" setter="set_editor_only" getter="is_editor_only" default="false">
 			If [code]true[/code], the light only appears in the editor and will not be visible at runtime.
 		</member>
@@ -73,7 +90,7 @@
 			The color of shadows cast by this light.
 		</member>
 		<member name="shadow_enabled" type="bool" setter="set_shadow" getter="has_shadow" default="false">
-			If [code]true[/code], the light will cast shadows.
+			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>
diff --git a/doc/classes/RenderingServer.xml b/doc/classes/RenderingServer.xml
index 11a681b235..ba3f5e10f5 100644
--- a/doc/classes/RenderingServer.xml
+++ b/doc/classes/RenderingServer.xml
@@ -1650,6 +1650,17 @@
 				Sets the cull mask for this Light3D. Lights only affect objects in the selected layers. Equivalent to [member Light3D.light_cull_mask].
 			</description>
 		</method>
+		<method name="light_set_distance_fade">
+			<return type="void" />
+			<argument index="0" name="decal" type="RID" />
+			<argument index="1" name="enabled" type="bool" />
+			<argument index="2" name="begin" type="float" />
+			<argument index="3" name="shadow" type="float" />
+			<argument index="4" name="length" type="float" />
+			<description>
+				Sets the distance fade for this Light3D. This acts as a form of level of detail (LOD) and can be used to improve performance. Equivalent to [member Light3D.distance_fade_enabled], [member Light3D.distance_fade_begin], [member Light3D.distance_fade_shadow], and [member Light3D.distance_fade_length].
+			</description>
+		</method>
 		<method name="light_set_max_sdfgi_cascade">
 			<return type="void" />
 			<argument index="0" name="light" type="RID" />