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
被繼承： AreaLight3D, 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
Light is ignored when baking. This is the fastest mode, but the light will not be taken into account when baking global illumination. This mode should generally be used for dynamic lights that change quickly, as the effect of global illumination is less noticeable on those lights.
Note: Hiding a light does not affect baking LightmapGI. Hiding a light will still affect baking VoxelGI and SDFGI (see Environment.sdfgi_enabled).
BakeMode BAKE_STATIC = 1
Light is taken into account in static baking (VoxelGI, LightmapGI, SDFGI (Environment.sdfgi_enabled)). The light can be moved around or modified, but its global illumination will not update in real-time. This is suitable for subtle changes (such as flickering torches), but generally not large changes such as toggling a light on and off.
Note: The light is not baked in LightmapGI if editor_only is true.
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 時有效。
If true, the light only appears in the editor and will not be visible at runtime. If true, the light will never be baked in LightmapGI regardless of its light_bake_mode.
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 🔗
The light's bake mode. This will affect the global illumination techniques that have an effect on the light's rendering.
Note: Meshes' global illumination mode will also affect the global illumination rendering. See GeometryInstance3D.gi_mode.
Color light_color = Color(1, 1, 1, 1) 🔗
The light's color in nonlinear sRGB encoding. An overbright color can be used to achieve a result equivalent to increasing the light's light_energy.
int light_cull_mask = 4294967295 🔗
The light will affect objects in the selected layers.
Note: The light cull mask is ignored by VoxelGI, SDFGI, LightmapGI, and volumetric fog. These will always render lights in a way that ignores the cull mask. See also VisualInstance3D.layers.
燈光的強度乘數（不是物理單位）。對於 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。
The simulated size of the light in Godot units, affecting shading and shadows. For OmniLight3Ds and SpotLight3Ds, increasing this value simulates a spherical area light, expanding the size of specular highlights. If shadows are enabled, a penumbra is rendered, making shadows appear blurrier. For AreaLight3Ds, only the shadows are affected. Penumbras are simulated with percentage-closer soft shadows, or PCSS, which has a noticeable performance cost for values above 0.0.
Note: light_size is not affected by Node3D.scale (the light's scale or its parent's scale).
Note: PCSS for positional lights is only supported in the Forward+ and Mobile rendering methods, not Compatibility.
受燈光影響的對象中鏡面反射斑點的強度。在 0 處，燈光變成純漫反射燈光。當不烘焙發射時，這可用於在發光表面上方放置燈光時避免不真實的反射。
設定光源的色溫，測量單位為開爾文。這用於計算對 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。
用於調整陰影表現。值太小會導致自陰影（“陰影失真”），而值太大會導致陰影與之分離（“陰影懸浮”）。根據需要進行調整。
模糊陰影的邊緣。可用於隱藏低解析度陰影貼圖中的圖元偽影。高值會影響性能，使陰影看起來有顆粒感，並可能導致其他不需要的偽影。儘量保持接近預設值。
int shadow_caster_mask = 4294967295 🔗
The light will only cast shadows using objects in the selected layers.
如果為 true，則燈光將投射即時陰影。這具有顯著的性能成本。僅當陰影算繪對場景外觀產生明顯影響時，才啟用陰影算繪，並考慮在遠離 Camera3D 時使用 distance_fade_enabled 隱藏該燈光。
float shadow_normal_bias = 2.0 🔗
通過物件的法線，將搜尋偏移到陰影貼圖中。這可用於在不使用 shadow_bias 的情況下，減少自身陰影偽影。在實踐中，這個值應該與 shadow_bias 一起調整，以盡可能減少偽影。
算繪燈光的陰影貼圖時使用的不透明度。低於 1.0 的值會使光線透過陰影出現。這可以用於以較低的性能成本，偽造全域照明。
bool shadow_reverse_cull_face = false 🔗
如果為 true，則反轉網格的背面剔除。可用於一個背後有燈光的平面網格。如果需要在該網格的兩側投射陰影，請使用 GeometryInstance3D.SHADOW_CASTING_SETTING_DOUBLE_SIDED，將該網格設定為使用雙面陰影。
float shadow_transmittance_bias = 0.05 🔗
There is currently no description for this property. Please help us by contributing one!
方法說明
返回給定 light_temperature 下的理想化黑體的 Color。該值是根據 light_temperature 在內部計算得出的。該 Color 在被發送到 RenderingServer 之前，將乘以 light_color。
float get_param(param: Param) const 🔗
返回指定的 Param 參數的值。
void set_param(param: Param, value: float) 🔗
設定指定的 Param 參數的值。