Light3D

继承： VisualInstance3D < Node3D < Node < Object

派生： DirectionalLight3D, OmniLight3D, SpotLight3D

为不同类型的光节点提供基类。

描述

Light3D 是灯光节点的抽象基类。由于无法实例化，所以不应直接使用。其他类型的灯光节点继承自它。Light3D 包含用于照明的常见变量和参数。

教程

• 3D 灯光与阴影

• 伪造全局光照

• 第三人称射击（TPS）演示

属性

方法

枚举

enum Param: 🔗

Param PARAM_ENERGY = 0

用于访问 light_energy 的常量。

Param PARAM_INDIRECT_ENERGY = 1

用于访问 light_indirect_energy 的常量。

Param PARAM_VOLUMETRIC_FOG_ENERGY = 2

用于访问 light_volumetric_fog_energy 的常量。

Param PARAM_SPECULAR = 3

用于访问 light_specular 的常量。

Param PARAM_RANGE = 4

用于访问 OmniLight3D.omni_range 或 SpotLight3D.spot_range 的常量。

Param PARAM_SIZE = 5

用于访问 light_size 的常量。

Param PARAM_ATTENUATION = 6

用于访问 OmniLight3D.omni_attenuation 或 SpotLight3D.spot_attenuation 的常量。

Param PARAM_SPOT_ANGLE = 7

用于访问 SpotLight3D.spot_angle 的常量。

Param PARAM_SPOT_ATTENUATION = 8

用于访问 SpotLight3D.spot_angle_attenuation 的常量。

Param PARAM_SHADOW_MAX_DISTANCE = 9

用于访问 DirectionalLight3D.directional_shadow_max_distance 的常量。

Param PARAM_SHADOW_SPLIT_1_OFFSET = 10

用于访问 DirectionalLight3D.directional_shadow_split_1 的常量。

Param PARAM_SHADOW_SPLIT_2_OFFSET = 11

用于访问 DirectionalLight3D.directional_shadow_split_2 的常量。

Param PARAM_SHADOW_SPLIT_3_OFFSET = 12

用于访问 DirectionalLight3D.directional_shadow_split_3 的常量。

Param PARAM_SHADOW_FADE_START = 13

用于访问 DirectionalLight3D.directional_shadow_fade_start 的常量。

Param PARAM_SHADOW_NORMAL_BIAS = 14

用于访问 shadow_normal_bias 的常量。

Param PARAM_SHADOW_BIAS = 15

用于访问 shadow_bias 的常量。

Param PARAM_SHADOW_PANCAKE_SIZE = 16

用于访问 DirectionalLight3D.directional_shadow_pancake_size 的常量。

Param PARAM_SHADOW_OPACITY = 17

用于访问 shadow_opacity 的常量。

Param PARAM_SHADOW_BLUR = 18

用于访问 shadow_blur 的常量。

Param PARAM_TRANSMITTANCE_BIAS = 19

用于访问 shadow_transmittance_bias 的常量。

Param PARAM_INTENSITY = 20

用于访问 light_intensity_lumens 和 light_intensity_lux 的常量。只在 ProjectSettings.rendering/lights_and_shadows/use_physical_light_units 为 true 时使用。

Param PARAM_MAX = 21

代表 Param 枚举的大小。

enum BakeMode: 🔗

BakeMode BAKE_DISABLED = 0

烘焙时灯光将被忽略。这是最快的模式，但是在烘焙全局照明时仍会考虑该灯光。该模式通常应用于快速变化的动态灯光，因为全局照明的效果在这些灯光上不太明显。

注意：将灯光隐藏，不影响烘焙 LightmapGI。但将灯光隐藏，仍会影响烘焙 VoxelGI 和 SDFGI（请参阅 Environment.sdfgi_enabled）。

BakeMode BAKE_STATIC = 1

在静态烘焙（VoxelGI、LightmapGI、SDFGI（Environment.sdfgi_enabled））时，考虑了灯光。灯光可以四处移动或修改，但其全局照明不会实时更新。这适用于细微的变化（例如闪烁的手电筒），但通常不适用于大的变化，例如打开和关闭灯光。

注意：如果 editor_only 为 true，则灯光不会在 LightmapGI 中烘焙。

BakeMode BAKE_DYNAMIC = 2

在动态烘焙（仅 VoxelGI 和 SDFGI（Environment.sdfgi_enabled））时，考虑了灯光。灯光可以四处移动或修改，而且全局照明会实时更新。与 BAKE_STATIC 相比，灯光的全局照明外观会略有不同。与 BAKE_STATIC 相比，这具有更大的性能成本。使用 SDFGI 时，动态灯光的更新速度受 ProjectSettings.rendering/global_illumination/sdfgi/frames_to_update_lights 的影响。

属性说明

float distance_fade_begin = 40.0 🔗

• void set_distance_fade_begin(value: float)

• float get_distance_fade_begin()

光线开始逐渐消失时与相机的距离（单位为 3D 单位）。

注意：仅对 OmniLight3D 和 SpotLight3D 有效。

bool distance_fade_enabled = false 🔗

• void set_enable_distance_fade(value: bool)

• bool is_distance_fade_enabled()

如果为 true，从 distance_fade_begin 开始，当远离活动的 Camera3D 时，灯光会平滑地消失。这充当了一种多细节层次（LOD）形式。灯光将在 distance_fade_begin + distance_fade_length 之外淡出，之后它将被剔除并且根本不会被发送到着色器。使用它可以减少场景中的活动灯光数量，从而提高性能。

注意：仅对 OmniLight3D 和 SpotLight3D 有效。

float distance_fade_length = 10.0 🔗

• void set_distance_fade_length(value: float)

• float get_distance_fade_length()

灯光及其阴影消失的距离。灯光的能量和阴影的不透明度，在此距离内逐渐降低，最终完全不可见。

注意：仅对 OmniLight3D 和 SpotLight3D 有效。

float distance_fade_shadow = 50.0 🔗

• void set_distance_fade_shadow(value: float)

• float get_distance_fade_shadow()

灯光阴影截止处与相机的距离（单位为 3D 单位）。将该属性设置为低于 distance_fade_begin + distance_fade_length 的值，以进一步提高性能，因为阴影渲染通常比光线渲染本身更昂贵。

注意：仅对 OmniLight3D 和 SpotLight3D 有效，且仅在 shadow_enabled 为 true 时有效。

bool editor_only = false 🔗

• void set_editor_only(value: bool)

• bool is_editor_only()

如果为 true，灯光只在编辑器中出现，在运行时将不可见。如果为 true，则无论其 light_bake_mode 如何，灯光都不会在 LightmapGI 中进行烘焙。

float light_angular_distance = 0.0 🔗

• void set_param(param: Param, value: float)

• float get_param(param: Param) const

灯光的角度大小，单位是度。增加此值将使阴影在更远的距离处更柔和（也称为百分比更近的柔和阴影，或 PCSS）。仅适用于 DirectionalLight3D。作为参考，太阳距离地球大约是 0.5。对于启用了阴影的灯光，将此值增加到 0.0 以上，将由于 PCSS 而产生明显的性能成本。

注意：light_angular_distance 不受 Node3D.scale（灯光的缩放或其父级的缩放）的影响。

注意：定向光的 PCSS 仅支持 Forward+ 渲染方式，不支持 Mobile 或 Compatibility。

BakeMode light_bake_mode = 2 🔗

• void set_bake_mode(value: BakeMode)

• BakeMode get_bake_mode()

灯光的烘焙模式。会影响对灯光渲染有影响的全局照明技术。见 BakeMode。

注意：网格的全局照明模式也会影响全局照明渲染。见 GeometryInstance3D.gi_mode。

Color light_color = Color(1, 1, 1, 1) 🔗

• void set_color(value: Color)

• Color get_color()

光的颜色。过亮的颜色可用于实现与增加光的 light_energy 相等价的结果。

int light_cull_mask = 4294967295 🔗

• void set_cull_mask(value: int)

• int get_cull_mask()

灯光将影响所选图层中的对象。

float light_energy = 1.0 🔗

• void set_param(param: Param, value: float)

• float get_param(param: Param) const

灯光的强度乘数（不是物理单位）。对于 OmniLight3D 和 SpotLight3D，更改此值只会更改灯光颜色的强度，而不会更改灯光的半径。

float light_indirect_energy = 1.0 🔗

• void set_param(param: Param, value: float)

• float get_param(param: Param) const

与间接光（光反射）一起使用的辅助乘数。与 VoxelGI 和 SDFGI 一起使用（参见 Environment.sdfgi_enabled）。

注意：如果 light_energy 等于 0.0，则该属性将被忽略，因为在 GI 着色器中，该灯光根本不存在。

float light_intensity_lumens 🔗

• void set_param(param: Param, value: float)

• float get_param(param: Param) const

当 ProjectSettings.rendering/lights_and_shadows/use_physical_light_units 为 true 时，由定位灯（OmniLight3D 和 SpotLight3D）使用。设置光源的强度，测量单位为流明。流明是对光通量的一种度量，它是光源在单位时间内发出的可见光总量。

对于 SpotLight3D，我们假设可见锥体之外的区域将被完美的光吸收材质包围。因此，锥体区域的表观亮度不会随着锥体大小的增大和减小而改变。

一只典型的家用灯泡的流明范围从 600 流明到 1,200 流明不等，一支蜡烛的流明约为 13 流明，而一盏路灯的流明约为 60,000 流明。

float light_intensity_lux 🔗

• void set_param(param: Param, value: float)

• float get_param(param: Param) const

当 ProjectSettings.rendering/lights_and_shadows/use_physical_light_units 为 true 时，由 DirectionalLight3D 使用。设置光源的强度，测量单位为勒克斯（Lux）。勒克斯是对单位面积内光通量的度量，等于每平方米一流明。勒克斯是衡量在给定时间有多少光照射到一个表面。

在晴朗的晴天，阳光直射下的表面可能约为 100,000 勒克斯，家中的一个典型房间可能约为 50 勒克斯，而月光下的地面可能约为 0.1 勒克斯。

bool light_negative = false 🔗

• void set_negative(value: bool)

• bool is_negative()

如果为 true，则光线的效果会逆转，使区域变暗并投射明亮的阴影。

Texture2D light_projector 🔗

• void set_projector(value: Texture2D)

• Texture2D get_projector()

Texture2D 由灯光投影。shadow_enabled 必须打开，投影仪才能工作。灯光投影仪使光线看起来像是透过彩色但透明的物体照射，几乎就像光线透过彩色玻璃照射一样。

注意：不像 BaseMaterial3D 的过滤器模式可以在每个材质的基础上进行调整，灯光投影仪纹理的过滤器模式是通过 ProjectSettings.rendering/textures/light_projectors/filter 全局设置的。

注意：灯光投影仪纹理仅支持 Forward+ 和 Mobile 渲染方法，不支持 Compatibility。

float light_size = 0.0 🔗

• void set_param(param: Param, value: float)

• float get_param(param: Param) const

灯光的大小，使用 Godot 的单位。仅适用于 OmniLight3D 和 SpotLight3D。增加此值将使光线淡出速度变慢，并且阴影看起来更模糊（也称为百分比接近软阴影或 PCSS）。这可用于在一定程度上模拟区域光。对于启用了阴影的灯光，将此值增加到 0.0 以上，将由于 PCSS 而产生明显的性能成本。

注意：light_size 不受 Node3D.scale（灯光的缩放或其父级的缩放）的影响。

注意：定位光的 PCSS 仅支持 Forward+ 和 Mobile 渲染方法，不支持 Compatibility。

float light_specular = 0.5 🔗

• void set_param(param: Param, value: float)

• float get_param(param: Param) const

受灯光影响的对象中镜面反射斑点的强度。在 0 处，灯光变成纯漫反射灯光。当不烘焙发射时，这可用于在发光表面上方放置灯光时避免不真实的反射。

float light_temperature 🔗

• void set_temperature(value: float)

• float get_temperature()

设置光源的色温，测量单位为开尔文。这用于计算对 light_color 着色的相关色温。

阴天的太阳温度约为 6500 开尔文，晴天的太阳温度在 5500 到 6000 开尔文之间，晴天日出或日落时的太阳温度范围为 1850 开尔文左右。

float light_volumetric_fog_energy = 1.0 🔗

• void set_param(param: Param, value: float)

• float get_param(param: Param) const

与 light_energy 相乘的次级乘数，然后与 Environment 的体积雾（如果启用）一起使用。如果设置为 0.0，将用于该灯的体积雾计算将被跳过，这可以在启用体积雾时提高大量灯光的性能。

注意：除非 Environment.volumetric_fog_temporal_reprojection_enabled 被禁用（或者除非重投影的量显著降低），否则为防止短暂的动态光效与体积雾的互动性差，这些效果中使用的光应将 light_volumetric_fog_energy 设置为 0.0。

float shadow_bias = 0.1 🔗

• void set_param(param: Param, value: float)

• float get_param(param: Param) const

用于调整阴影表现。值太小会导致自阴影（“阴影失真”），而值太大会导致阴影与之分离（“阴影悬浮”）。根据需要进行调整。

float shadow_blur = 1.0 🔗

• void set_param(param: Param, value: float)

• float get_param(param: Param) const

模糊阴影的边缘。可用于隐藏低分辨率阴影贴图中的像素伪影。高值会影响性能，使阴影看起来有颗粒感，并可能导致其他不需要的伪影。尽量保持接近默认值。

bool shadow_enabled = false 🔗

• void set_shadow(value: bool)

• bool has_shadow()

如果为 true，则灯光将投射实时阴影。这具有显著的性能成本。仅当阴影渲染对场景外观产生明显影响时，才启用阴影渲染，并考虑在远离 Camera3D 时使用 distance_fade_enabled 隐藏该灯光。

float shadow_normal_bias = 2.0 🔗

• void set_param(param: Param, value: float)

• float get_param(param: Param) const

通过对象的法线，将查找偏移到阴影贴图中。这可用于在不使用 shadow_bias 的情况下，减少自身阴影伪影。在实践中，这个值应该与 shadow_bias 一起调整，以尽可能减少伪影。

float shadow_opacity = 1.0 🔗

• void set_param(param: Param, value: float)

• float get_param(param: Param) const

渲染灯光的阴影贴图时使用的不透明度。低于 1.0 的值会使光线透过阴影出现。这可以用于以较低的性能成本，伪造全局照明。

bool shadow_reverse_cull_face = false 🔗

• void set_shadow_reverse_cull_face(value: bool)

• bool get_shadow_reverse_cull_face()

如果为 true，则反转网格的背面剔除。可用于一个背后有灯光的平面网格。如果需要在该网格的两侧投射阴影，请使用 GeometryInstance3D.SHADOW_CASTING_SETTING_DOUBLE_SIDED，将该网格设置为使用双面阴影。

float shadow_transmittance_bias = 0.05 🔗

• void set_param(param: Param, value: float)

• float get_param(param: Param) const

该属性目前没有描述，请帮我们贡献一个吧！

方法说明

Color get_correlated_color() const 🔗

返回给定 light_temperature 下的理想化黑体的 Color。该值是根据 light_temperature 在内部计算得出的。该 Color 在被发送到 RenderingServer 之前，将乘以 light_color。

float get_param(param: Param) const 🔗

返回指定的 Param 参数的值。

void set_param(param: Param, value: float) 🔗

设置指定的 Param 参数的值。