Add Rectangular Area Light Source

doc/classes/AreaLight3D.xml

@@ -0,0 +1,38 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<class name="AreaLight3D" inherits="Light3D" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
+	<brief_description>
+		An area light, such as a neon light tube or a screen.
+	</brief_description>
+	<description>
+		An area light is a type of [Light3D] node that emits light over a 2-dimensional area, in the shape of a rectangle. The light is attenuated through the distance. This attenuation can be configured by changing the energy, [member area_attenuation], and [member area_range].
+		Light is emitted in the -Z direction of the node's global basis. For an unrotated light, this means that the light is emitted forwards, illuminating the front side of a 3D model (see [constant Vector3.FORWARD] and [constant Vector3.MODEL_FRONT]).
+		Area lights can cast soft shadows using PCSS, which you can control by tweaking the size parameter. The shadow map is drawn from the center of the light.
+		[b]Note:[/b] Area lights have limited support in the Mobile or Compatibility renderer. In the Mobile renderer, the size of the penumbra doesn't vary is it should with PCSS. In Compatibility, area lights cannot cast shadows. For static lighting, consider instead using [LightmapGI] and a [QuadMesh] with [member PrimitiveMesh.add_uv2] set to [code]true[/code] and assign an emissive material to the [QuadMesh], then hide the [QuadMesh] after baking lightmaps.
+	</description>
+	<tutorials>
+	</tutorials>
+	<members>
+		<member name="area_attenuation" type="float" setter="set_param" getter="get_param" default="1.0">
+			Controls the distance attenuation function for area lights.
+			A value of [code]0.0[/code] will maintain a constant brightness through most of the range, but smoothly attenuate the light at the edge of the range. Use a value of [code]2.0[/code] for physically accurate lights as it results in the proper inverse square attenuation.
+			[b]Note:[/b] Setting attenuation to [code]2.0[/code] or higher may result in distant objects receiving minimal light, even within range. For example, with a range of [code]4096[/code], an object at [code]100[/code] units is attenuated by a factor of [code]0.0001[/code]. With a default brightness of [code]1[/code], the light would not be visible at that distance.
+			[b]Note:[/b] Using negative or values higher than [code]10.0[/code] may lead to unexpected results.
+		</member>
+		<member name="area_normalize_energy" type="bool" setter="set_area_normalize_energy" getter="get_area_normalize_energy" default="true">
+			Defines whether the energy is normalized (divided) by the surface area of the light. If set to [code]true[/code], changing the size does not affect the amount of total energy output, and does not dramatically alter the brightness of the scene.
+		</member>
+		<member name="area_range" type="float" setter="set_param" getter="get_param" default="5.0">
+			The range of the area in meters. This determines the maximum distance at which the area can still emit light relative to its surface, but also to its borders (which are positioned according to [member area_size]).
+		</member>
+		<member name="area_size" type="Vector2" setter="set_area_size" getter="get_area_size" default="Vector2(1, 1)">
+			The extents (width and height) of the area in meters.
+		</member>
+		<member name="area_texture" type="Texture2D" setter="set_area_texture" getter="get_area_texture">
+			An optional texture to use as a light source. Changing the texture at runtime might impact performance, as it needs to be drawn to the area light atlas with filtered mipmaps.
+			If no texture is assigned, the area light emits uniform light across its surface.
+		</member>
+		<member name="light_size" type="float" setter="set_param" getter="get_param" overrides="Light3D" default="0.5" />
+		<member name="shadow_bias" type="float" setter="set_param" getter="get_param" overrides="Light3D" default="0.03" />
+		<member name="shadow_normal_bias" type="float" setter="set_param" getter="get_param" overrides="Light3D" default="1.0" />
+	</members>
+</class>

doc/classes/Light3D.xml

@@ -12,6 +12,24 @@
 		<link title="Third Person Shooter (TPS) Demo">https://godotengine.org/asset-library/asset/2710</link>
 	</tutorials>
 	<methods>
+		<method name="get_area_normalize_energy" qualifiers="const">
+			<return type="bool" />
+			<description>
+				Getter for [member AreaLight3D.area_normalize_energy]. If [code]true[/code], the energy of an [AreaLight3D] is normalized by its area.
+			</description>
+		</method>
+		<method name="get_area_size" qualifiers="const">
+			<return type="Vector2" />
+			<description>
+				Returns the width and height of the area.
+			</description>
+		</method>
+		<method name="get_area_texture" qualifiers="const">
+			<return type="Texture2D" />
+			<description>
+				Returns the texture used for the area light.
+			</description>
+		</method>
 		<method name="get_correlated_color" qualifiers="const">
 			<return type="Color" />
 			<description>
@@ -25,6 +43,26 @@
 				Returns the value of the specified [enum Light3D.Param] parameter.
 			</description>
 		</method>
+		<method name="set_area_normalize_energy">
+			<return type="void" />
+			<param index="0" name="enable" type="bool" />
+			<description>
+				Setter for [member AreaLight3D.area_normalize_energy]. If [code]true[/code], the energy of an [AreaLight3D] is normalized by its area.
+			</description>
+		</method>
+		<method name="set_area_size">
+			<return type="void" />
+			<param index="0" name="area_size" type="Vector2" />
+			<description>
+				Sets the width and height of the area.
+			</description>
+		</method>
+		<method name="set_area_texture">
+			<return type="void" />
+			<param index="0" name="texture" type="Texture2D" />
+			<description>
+			</description>
+		</method>
 		<method name="set_param">
 			<return type="void" />
 			<param index="0" name="param" type="int" enum="Light3D.Param" />

doc/classes/RenderingServer.xml

@@ -18,6 +18,11 @@
 		<link title="Optimization using Servers">$DOCS_URL/tutorials/performance/using_servers.html</link>
 	</tutorials>
 	<methods>
+		<method name="area_light_create">
+			<return type="RID" />
+			<description>
+			</description>
+		</method>
 		<method name="bake_render_uv2">
 			<return type="Image[]" />
 			<param index="0" name="base" type="RID" />
@@ -2100,6 +2105,22 @@
 				Returns [code]true[/code] if our code is currently executing on the rendering thread.
 			</description>
 		</method>
+		<method name="light_area_set_normalize_energy">
+			<return type="void" />
+			<param index="0" name="light" type="RID" />
+			<param index="1" name="enable" type="bool" />
+			<description>
+				Defines whether the energy of an [AreaLight3D] is normalized (divided) by its area. If set to [code]true[/code], changing the size does not affect the amount of total energy output. Equivalent to [member AreaLight3D.area_normalize_energy].
+			</description>
+		</method>
+		<method name="light_area_set_size">
+			<return type="void" />
+			<param index="0" name="light" type="RID" />
+			<param index="1" name="size" type="Vector2" />
+			<description>
+				Sets the extents (width and height) in meters for this area light. Equivalent to [member AreaLight3D.area_size].
+			</description>
+		</method>
 		<method name="light_directional_set_blend_splits">
 			<return type="void" />
 			<param index="0" name="light" type="RID" />
@@ -4847,6 +4868,8 @@
 		<constant name="LIGHT_SPOT" value="2" enum="LightType">
 			Spot light (see [SpotLight3D]).
 		</constant>
+		<constant name="LIGHT_AREA" value="3" enum="LightType">
+		</constant>
 		<constant name="LIGHT_PARAM_ENERGY" value="0" enum="LightParam">
 			The light's energy multiplier.
 		</constant>

doc/classes/Viewport.xml

@@ -750,6 +750,14 @@
 			Draws the internal resolution buffer of the scene in linear colorspace before tonemapping or post-processing is applied.
 			[b]Note:[/b] Only supported when using the Forward+ or Mobile rendering methods.
 		</constant>
+		<constant name="DEBUG_DRAW_CLUSTER_AREA_LIGHTS" value="27" enum="DebugDraw">
+			Draws the cluster used by [AreaLight3D] nodes to optimize light rendering.
+			[b]Note:[/b] Only supported when using the Forward+ rendering method.
+		</constant>
+		<constant name="DEBUG_DRAW_AREA_LIGHT_ATLAS" value="28" enum="DebugDraw">
+			Draws the atlas used by [AreaLight3D] nodes in the upper left quadrant of the [Viewport].
+			[b]Note:[/b] Only supported when using the Forward+ or Mobile rendering methods.
+		</constant>
 		<constant name="DEFAULT_CANVAS_ITEM_TEXTURE_FILTER_NEAREST" value="0" enum="DefaultCanvasItemTextureFilter">
 			The texture filter reads from the nearest pixel only. This makes the texture look pixelated from up close, and grainy from a distance (due to mipmaps not being sampled).
 		</constant>