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...
Light3D¶
继承： VisualInstance3D < Node3D < Node < Object
派生： DirectionalLight3D, OmniLight3D, SpotLight3D
为不同类型的光节点提供基类。
描述¶
Light3D 是灯光节点的抽象基类。由于无法实例化，所以不应直接使用。其他类型的灯光节点继承自它。Light3D 包含用于照明的常见变量和参数。
教程¶
属性¶
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
方法¶
get_correlated_color() const |
|
void |
枚举¶
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 🔗
光线开始逐渐消失时与相机的距离（单位为 3D 单位）。
注意：仅对 OmniLight3D 和 SpotLight3D 有效。
bool distance_fade_enabled = false 🔗
如果为 true，从 distance_fade_begin 开始，当远离活动的 Camera3D 时，灯光会平滑地消失。这充当了一种多细节层次（LOD）形式。灯光将在 distance_fade_begin + distance_fade_length 之外淡出，之后它将被剔除并且根本不会被发送到着色器。使用它可以减少场景中的活动灯光数量，从而提高性能。
注意：仅对 OmniLight3D 和 SpotLight3D 有效。
float distance_fade_length = 10.0 🔗
灯光及其阴影消失的距离。灯光的能量和阴影的不透明度，在此距离内逐渐降低，最终完全不可见。
注意：仅对 OmniLight3D 和 SpotLight3D 有效。
float distance_fade_shadow = 50.0 🔗
灯光阴影截止处与相机的距离（单位为 3D 单位）。将该属性设置为低于 distance_fade_begin + distance_fade_length 的值，以进一步提高性能，因为阴影渲染通常比光线渲染本身更昂贵。
注意：仅对 OmniLight3D 和 SpotLight3D 有效，且仅在 shadow_enabled 为 true 时有效。
如果为 true，灯光只在编辑器中出现，在运行时将不可见。如果为 true，则无论其 light_bake_mode 如何，灯光都不会在 LightmapGI 中进行烘焙。
float light_angular_distance = 0.0 🔗
灯光的角度大小，单位是度。增加此值将使阴影在更远的距离处更柔和（也称为百分比更近的柔和阴影，或 PCSS）。仅适用于 DirectionalLight3D。作为参考，太阳距离地球大约是 0.5。对于启用了阴影的灯光，将此值增加到 0.0 以上，将由于 PCSS 而产生明显的性能成本。
注意：light_angular_distance 不受 Node3D.scale（灯光的缩放或其父级的缩放）的影响。
注意：定向光的 PCSS 仅支持 Forward+ 渲染方式，不支持 Mobile 或 Compatibility。
BakeMode light_bake_mode = 2 🔗
灯光的烘焙模式。会影响对灯光渲染有影响的全局照明技术。见 BakeMode。
注意：网格的全局照明模式也会影响全局照明渲染。见 GeometryInstance3D.gi_mode。
Color light_color = Color(1, 1, 1, 1) 🔗
光的颜色。过亮的颜色可用于实现与增加光的 light_energy 相等价的结果。
int light_cull_mask = 4294967295 🔗
灯光将影响所选图层中的对象。
灯光的强度乘数（不是物理单位）。对于 OmniLight3D 和 SpotLight3D，更改此值只会更改灯光颜色的强度，而不会更改灯光的半径。
float light_indirect_energy = 1.0 🔗
与间接光（光反射）一起使用的辅助乘数。与 VoxelGI 和 SDFGI 一起使用（参见 Environment.sdfgi_enabled）。
注意：如果 light_energy 等于 0.0，则该属性将被忽略，因为在 GI 着色器中，该灯光根本不存在。
float light_intensity_lumens 🔗
当 ProjectSettings.rendering/lights_and_shadows/use_physical_light_units 为 true 时，由定位灯（OmniLight3D 和 SpotLight3D）使用。设置光源的强度，测量单位为流明。流明是对光通量的一种度量，它是光源在单位时间内发出的可见光总量。
对于 SpotLight3D，我们假设可见锥体之外的区域将被完美的光吸收材质包围。因此，锥体区域的表观亮度不会随着锥体大小的增大和减小而改变。
一只典型的家用灯泡的流明范围从 600 流明到 1,200 流明不等，一支蜡烛的流明约为 13 流明，而一盏路灯的流明约为 60,000 流明。
当 ProjectSettings.rendering/lights_and_shadows/use_physical_light_units 为 true 时，由 DirectionalLight3D 使用。设置光源的强度，测量单位为勒克斯（Lux）。勒克斯是对单位面积内光通量的度量，等于每平方米一流明。勒克斯是衡量在给定时间有多少光照射到一个表面。
在晴朗的晴天，阳光直射下的表面可能约为 100,000 勒克斯，家中的一个典型房间可能约为 50 勒克斯，而月光下的地面可能约为 0.1 勒克斯。
如果为 true，则光线的效果会逆转，使区域变暗并投射明亮的阴影。
Texture2D 由灯光投影。shadow_enabled 必须打开，投影仪才能工作。灯光投影仪使光线看起来像是透过彩色但透明的物体照射，几乎就像光线透过彩色玻璃照射一样。
注意：不像 BaseMaterial3D 的过滤器模式可以在每个材质的基础上进行调整，灯光投影仪纹理的过滤器模式是通过 ProjectSettings.rendering/textures/light_projectors/filter 全局设置的。
注意：灯光投影仪纹理仅支持 Forward+ 和 Mobile 渲染方法，不支持 Compatibility。
灯光的大小，使用 Godot 的单位。仅适用于 OmniLight3D 和 SpotLight3D。增加此值将使光线淡出速度变慢，并且阴影看起来更模糊（也称为百分比接近软阴影或 PCSS）。这可用于在一定程度上模拟区域光。对于启用了阴影的灯光，将此值增加到 0.0 以上，将由于 PCSS 而产生明显的性能成本。
注意：light_size 不受 Node3D.scale（灯光的缩放或其父级的缩放）的影响。
注意：定位光的 PCSS 仅支持 Forward+ 和 Mobile 渲染方法，不支持 Compatibility。
受灯光影响的对象中镜面反射斑点的强度。在 0 处，灯光变成纯漫反射灯光。当不烘焙发射时，这可用于在发光表面上方放置灯光时避免不真实的反射。
设置光源的色温，测量单位为开尔文。这用于计算对 light_color 着色的相关色温。
阴天的太阳温度约为 6500 开尔文，晴天的太阳温度在 5500 到 6000 开尔文之间，晴天日出或日落时的太阳温度范围为 1850 开尔文左右。
float light_volumetric_fog_energy = 1.0 🔗
与 light_energy 相乘的次级乘数，然