Up to date
This page is up to date for Godot 4.2.
If you still find outdated information, please open an issue.
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 时有效。
bool editor_only = false
如果为 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
灯光将影响所选图层中的对象。
float light_energy = 1.0
灯光的强度乘数（不是物理单位）。对于 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 流明。
float light_intensity_lux
当 ProjectSettings.rendering/lights_and_shadows/use_physical_light_units 为 true 时，由 DirectionalLight3D 使用。设置光源的强度，测量单位为勒克斯（Lux）。勒克斯是对单位面积内光通量的度量，等于每平方米一流明。勒克斯是衡量在给定时间有多少光照射到一个表面。
在晴朗的晴天，阳光直射下的表面可能约为 100,000 勒克斯，家中的一个典型房间可能约为 50 勒克斯，而月光下的地面可能约为 0.1 勒克斯。
bool light_negative = false
如果为 true，则光线的效果会逆转，使区域变暗并投射明亮的阴影。
Texture2D light_projector
Texture2D 由灯光投影。shadow_enabled 必须打开，投影仪才能工作。灯光投影仪使光线看起来像是透过彩色但透明的物体照射，几乎就像光线透过彩色玻璃照射一样。
注意：不像 BaseMaterial3D 的过滤器模式可以在每个材质的基础上进行调整，灯光投影仪纹理的过滤器模式是通过 ProjectSettings.rendering/textures/light_projectors/filter 全局设置的。
注意：灯光投影仪纹理仅支持 Forward+ 和 Mobile 渲染方法，不支持 Compatibility。
float light_size = 0.0
灯光的大小，使用 Godot 的单位。仅适用于 OmniLight3D 和 SpotLight3D。增加此值将使光线淡出速度变慢，并且阴影看起来更模糊（也称为百分比接近软阴影或 PCSS）。这可用于在一定程度上模拟区域光。对于启用了阴影的灯光，将此值增加到 0.0 以上，将由于 PCSS 而产生明显的性能成本。
注意：light_size 不受 Node3D.scale（灯光的缩放或其父级的缩放）的影响。
注意：定位光的 PCSS 仅支持 Forward+ 和 Mobile 渲染方法，不支持 Compatibility。
float light_specular = 0.5
受灯光影响的对象中镜面反射斑点的强度。在 0 处，灯光变成纯漫反射灯光。当不烘焙发射时，这可用于在发光表面上方放置灯光时避免不真实的反射。
float light_temperature
设置光源的色温，测量单位为开尔文。这用于计算对 light_color 着色的相关色温。
阴天的太阳温度约为 6500 开尔文，晴天的太阳温度在 5500 到 6000 开尔文之间，晴天日出或日落时的太阳温度范围为 1850 开尔文左右。
float light_volumetric_fog_energy = 1.0
与 light_energy 相乘的次级乘数，然后与 Environment 的体积雾（如果启用）一起使用。如果设置为 0.0，将用于该灯的体积雾计算将被跳过，这可以在启用体积雾时提高大量灯光的性能。
注意：除非 Environment.volumetric_fog_temporal_reprojection_enabled 被禁用（或者除非重投影的量显著降低），否则为防止短暂的动态光效与体积雾的互动性差，这些效果中使用的光应将 light_volumetric_fog_energy 设置为 0.0。
float shadow_bias = 0.1
用于调整阴影表现。值太小会导致自阴影（“阴影失真”），而值太大会导致阴影与之分离（“阴影悬浮”）。根据需要进行调整。
float shadow_blur = 1.0
模糊阴影的边缘。可用于隐藏低分辨率阴影贴图中的像素伪影。高值会影响性能，使阴影看起来有颗粒感，并可能导致其他不需要的伪影。尽量保持接近默认值。
bool shadow_enabled = false
如果为 true，则灯光将投射实时阴影。这具有显著的性能成本。仅当阴影渲染对场景外观产生明显影响时，才启用阴影渲染，并考虑在远离 Camera3D 时使用 distance_fade_enabled 隐藏该灯光。
float shadow_normal_bias = 2.0
通过对象的法线，将查找偏移到阴影贴图中。这可用于在不使用 shadow_bias 的情况下，减少自身阴影伪影。在实践中，这个值应该与 shadow_bias 一起调整，以尽可能减少伪影。
float shadow_opacity = 1.0
渲染灯光的阴影贴图时使用的不透明度。低于 1.0 的值会使光线透过阴影出现。这可以用于以较低的性能成本，伪造全局照明。
bool shadow_reverse_cull_face = false
如果为 true，则反转网格的背面剔除。可用于一个背后有灯光的平面网格。如果需要在该网格的两侧投射阴影，请使用 GeometryInstance3D.SHADOW_CASTING_SETTING_DOUBLE_SIDED，将该网格设置为使用双面阴影。
float shadow_transmittance_bias = 0.05
目前没有这个属性的描述。请帮我们贡献一个！
方法说明¶
返回给定 light_temperature 下的理想化黑体的 Color。该值是根据 light_temperature 在内部计算得出的。该 Color 在被发送到 RenderingServer 之前，将乘以 light_color。
float get_param ( Param param ) const
返回指定的 Param 参数的值。
void set_param ( Param param, float value )
设置指定的 Param 参数的值。