Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

AreaLight3D

继承： Light3D < VisualInstance3D < Node3D < Node < Object

面光源，如霓虹灯管或屏幕。

描述

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, area_attenuation, and 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 Vector3.FORWARD and 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.

Note: 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.

Performance: Area lights are more demanding on the GPU compared to omni and spot lights. In Forward+, there is an additional GPU cost on all 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.

属性

float	area_attenuation	`1.0`
bool	area_normalize_energy	`true`
float	area_range	`5.0`
Vector2	area_size	`Vector2(1, 1)`
Texture2D	area_texture
float	light_size	`0.5` (overrides Light3D)
float	shadow_normal_bias	`1.0` (overrides Light3D)

属性说明

float area_attenuation = 1.0 🔗

void set_param(value: float)
float get_param()

控制面光源的距离衰减函数。

值为 0.0 将在大部分范围内保持恒定亮度，但将平滑地衰减范围边缘的光线。对于物理上准确的灯光，请使用值 2.0，因为它会产生正确的平方反比衰减。

注意：将衰减设置为 2.0 或更高可能会导致远处的物体接收到的光线最少，即使在范围内也是如此。例如，在 4096 的范围内，100 单位处的物体会衰减 0.0001 倍。默认亮度为 1，光线在该距离处不可见。

注意：使用负值或高于 10.0 的值可能会导致意外结果。

bool area_normalize_energy = true 🔗

void set_area_normalize_energy(value: bool)
bool is_area_normalizing_energy()

定义灯光的能量是否会按其表面积进行归一化（即除以表面积）。如果设为 true，改变灯光的大小不会影响其总能量输出，也不会剧烈改变场景的整体亮度。

float area_range = 5.0 🔗

void set_param(value: float)
float get_param()

该区域在米为单位下的范围。它决定了从该区域的任意一点出发，还能发射光线的最大距离。

Vector2 area_size = Vector2(1, 1) 🔗

void set_area_size(value: Vector2)
Vector2 get_area_size()

该面的范围（宽度和高度），单位为米。

Texture2D area_texture 🔗

void set_area_texture(value: Texture2D)
Texture2D get_area_texture()

一个可选的纹理，用于作为光源。在运行时（Runtime）更改纹理可能会影响性能，因为引擎需要将其绘制到面光源图集（area light atlas）中，并生成带有滤波的 Mipmap。

如果没有指定纹理，面光源将在其表面发射均匀的光线。

注意： 面光源纹理仅在 Forward+ 和 Mobile 渲染模式下受支持，在 Compatibility（兼容）模式下不受支持。为了减少在运行时切换纹理带来的性能开销，请确保面光源纹理的每个维度（宽度和高度）都是 128 像素的倍数，或者是 2 的幂次方。这样可以省去一个缩放（scaling）步骤，从而加快纹理的切换速度。为了达到最佳效果，纹理不一定非得是正方形的。最佳纹理尺寸的示例包括 32x64、128x128 和 256x384。