Implement distance fade properties in OmniLight3D and SpotLight3D

This can be used to fade lights and their shadows in the distance,
similar to Decal nodes. This can bring significant performance
improvements, especially for lights with shadows enabled and when
using higher-than-default shadow quality settings.

While lights can be smoothly faded out over distance, shadows are
currently "all or nothing" since per-light shadow color is no longer
customizable in the Vulkan renderer. This may result in noticeable
pop-in when leaving the shadow cutoff distance, but depending on the
scene, it may not always be that noticeable.

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 bb8aa8c9db..07e7ebc55b 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" />