<?xml version="1.0" encoding="UTF-8" ?>
<class name="AreaLight3D" inherits="Light3D" api_type="core" 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 two-dimensional area, in the shape of a rectangle. The light is attenuated throughout 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 and Compatibility renderers. In the Mobile renderer, the size of the penumbra doesn't vary as it should with PCSS. In Compatibility, area lights cannot cast shadows.
		[b]Warning:[/b] Shadows cast by an area light may look incorrect if the object casting shadows doesn't have enough subdivisions and it's very close to the area light. This is the same limitation as the Dual Paraboloid shadow mode on an [OmniLight3D].
		[b]Performance:[/b] Area lights are more demanding on the GPU compared to omni and spot lights. In Forward+, there is an additional GPU cost on [i]all[/i] rendered objects as soon as one area light is present in the view frustum (due to the nature of clustered lighting). Consider using them only for cinematics or when targeting high-end devices.
	</description>
	<tutorials>
		<link title="3D lights and shadows">$DOCS_URL/tutorials/3d/lights_and_shadows.html#area-light</link>
	</tutorials>
	<members>
		<member name="area_attenuation" type="float" setter="set_param" getter="get_param" default="1.0">
			Controls the distance attenuation function for this area light.
			A value of [code]0.0[/code] will maintain a constant brightness through most of the range, but will 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 when 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 values 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="is_area_normalizing_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 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 from any point on the area at which the area can still emit light.
		</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.
			[b]Note:[/b] Area light textures are only supported in the Forward+ and Mobile rendering methods, not Compatibility. To reduce the performance impact of switching textures at runtime, make sure each dimension of an area texture is either a multiple of 128 pixels, or a power of two. This removes the need for a scaling pass, which slows down texture changes. The textures don't necessarily have to be square to be optimal. Examples of optimal texture sizes include 32x64, 128x128, and 256x384.
		</member>
		<member name="light_size" type="float" setter="set_param" getter="get_param" overrides="Light3D" default="0.5" />
		<member name="shadow_normal_bias" type="float" setter="set_param" getter="get_param" overrides="Light3D" default="1.0" />
	</members>
</class>
