Document caveats of high attenuation in OmniLight3D and SpotLight3D

High attenuation values will negatively impact performance for 2 reasons:

- The light won't be culled as often.
- The light will cover more pixels, which have to be shaded individually.

Therefore, lower attenuation values (with a lower range to compensate)
should be preferred whenever possible.

1 files changed, 2 insertions, 1 deletions

diff --git a/doc/classes/OmniLight3D.xml b/doc/classes/OmniLight3D.xml
index 013ad0cc42..ce286ce51c 100644
--- a/doc/classes/OmniLight3D.xml
+++ b/doc/classes/OmniLight3D.xml
@@ -11,7 +11,8 @@
 	</tutorials>
 	<members>
 		<member name="omni_attenuation" type="float" setter="set_param" getter="get_param" default="1.0">
-			The light's attenuation (drop-off) curve. A number of presets are available in the [b]Inspector[/b] by right-clicking the curve.
+			The light's attenuation (drop-off) curve. A number of presets are available in the [b]Inspector[/b] by right-clicking the curve. Zero and negative values are allowed but can produce unusual effects.
+			[b]Note:[/b] Very high [member omni_attenuation] values (typically above 10) can impact performance negatively if the light is made to use a larger [member omni_range] to compensate. This is because culling opportunities will become less common and shading costs will be increased (as the light will cover more pixels on screen while resulting in the same amount of brightness). To improve performance, use the lowest [member omni_attenuation] value possible for the visuals you're trying to achieve.
 		</member>
 		<member name="omni_range" type="float" setter="set_param" getter="get_param" default="5.0">
 			The light's radius. Note that the effectively lit area may appear to be smaller depending on the [member omni_attenuation] in use. No matter the [member omni_attenuation] in use, the light will never reach anything outside this radius.