Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

LightmapGI

继承: VisualInstance3D < Node3D < Node < Object

计算并存储烘焙光照贴图,以实现快速全局照明。

描述

LightmapGI 节点用于计算和存储烘焙的光照贴图。光照贴图用于提供高质量的间接照明,并且漏光很少。如果启用 directionalLightmapGI 还可以使用球谐函数,以提供粗略的反射。由于光照探针,动态物体可以接收间接光照,可以通过将 generate_probes_subdiv 设置为 GENERATE_PROBES_DISABLED 以外的值,来自动放置光照探针。也可以通过创建 LightmapProbe 节点,来添加额外的光照贴图探针。缺点是光照贴图是完全静态的,不能在导出的项目中烘焙。与 VoxelGI 相比,烘焙 LightmapGI 节点也更慢。

程序生成:光照贴图烘焙功能仅在编辑器中可用。这意味着 LightmapGI 不适合程序生成或用户构建的关卡。对于程序生成或用户构建的关卡,请改用 VoxelGI 或 SDFGI(请参阅 Environment.sdfgi_enabled)。

性能:LightmapGI 为全局照明提供最佳的运行时性能。它适用于包括集成显卡和移动设备在内的低端硬件。

注意:由于光照贴图的工作方式,大多数属性只有在光照贴图被再次烘焙后,才会产生可见效果。

注意:不支持在 CSGShape3DPrimitiveMesh 上烘焙光照贴图,因为它们无法存储烘焙所需的 UV2 数据。

注意:如果没有安装自定义光照贴图,LightmapGI 只能在使用 Vulkan 后端(Forward+ 或 Mobile)时进行烘焙,而不能在使用 OpenGL 时烘焙。

教程

属性

float

bias

0.0005

float

bounce_indirect_energy

1.0

int

bounces

3

CameraAttributes

camera_attributes

float

denoiser_strength

0.1

bool

directional

false

Color

environment_custom_color

float

environment_custom_energy

Sky

environment_custom_sky

EnvironmentMode

environment_mode

1

GenerateProbes

generate_probes_subdiv

2

bool

interior

false

LightmapGIData

light_data

int

max_texture_size

16384

BakeQuality

quality

1

bool

use_denoiser

true

bool

use_texture_for_bounces

true


枚举

enum BakeQuality:

BakeQuality BAKE_QUALITY_LOW = 0

较低的烘焙质量(最快的烘焙时间)。可以通过更改 ProjectSettings.rendering/lightmapping/bake_quality/low_quality_ray_countProjectSettings.rendering/lightmapping/bake_quality/low_quality_probe_ray_count 来调整此预设的质量。

BakeQuality BAKE_QUALITY_MEDIUM = 1

中等的烘焙质量(较快的烘焙时间)。可以通过更改 ProjectSettings.rendering/lightmapping/bake_quality/medium_quality_ray_countProjectSettings.rendering/lightmapping/bake_quality/medium_quality_probe_ray_count 来调整此预设的质量。

BakeQuality BAKE_QUALITY_HIGH = 2

较高的烘焙质量(较慢的烘焙时间)。可以通过更改 ProjectSettings.rendering/lightmapping/bake_quality/high_quality_ray_countProjectSettings.rendering/lightmapping/bake_quality/high_quality_probe_ray_count 来调整此预设的质量。

BakeQuality BAKE_QUALITY_ULTRA = 3

最高的烘焙质量(最慢的烘焙时间)。可以通过更改 ProjectSettings.rendering/lightmapping/bake_quality/high_quality_ray_countProjectSettings.rendering/lightmapping/bake_quality/ultra_quality_probe_ray_count 来调整此预设的质量。


enum GenerateProbes:

GenerateProbes GENERATE_PROBES_DISABLED = 0

不要为光照动态对象生成光照贴图探针。

GenerateProbes GENERATE_PROBES_SUBDIV_4 = 1

最低级别的细分(烘焙时间最快,文件大小最小)。

GenerateProbes GENERATE_PROBES_SUBDIV_8 = 2

较低级别的细分(烘焙时间较快,文件大小较小)。

GenerateProbes GENERATE_PROBES_SUBDIV_16 = 3

较高级别的细分(烘焙时间较慢,文件大小较大)。

GenerateProbes GENERATE_PROBES_SUBDIV_32 = 4

最高级别的细分(烘焙时间最慢,文件大小最大)。


enum BakeError:

BakeError BAKE_ERROR_OK = 0

光照贴图烘焙成功。

BakeError BAKE_ERROR_NO_SCENE_ROOT = 1

光照贴图烘焙失败,原因是无法访问所编辑场景的根节点。

BakeError BAKE_ERROR_FOREIGN_DATA = 2

光照贴图烘焙失败,原因是光照贴图数据嵌入在外部资源之中。

BakeError BAKE_ERROR_NO_LIGHTMAPPER = 3

光照贴图烘焙失败,原因是这个 Godot 构建中没有可用的光照贴图器。

BakeError BAKE_ERROR_NO_SAVE_PATH = 4

光照贴图烘焙失败,原因是资源中没有配置 LightmapGIData 保存路径。

BakeError BAKE_ERROR_NO_MESHES = 5

光照贴图烘焙失败,原因是当前场景中没有 GeometryInstance3D.gi_modeGeometryInstance3D.GI_MODE_STATIC 且具有有效 UV2 映射的网格。可能需要在导入停靠面板中选择 3D 场景,并相应地更改它们的全局照明模式。

BakeError BAKE_ERROR_MESHES_INVALID = 6

光照贴图烘焙失败,原因是光照贴图器无法分析一些标记为静态的网格以进行烘焙。

BakeError BAKE_ERROR_CANT_CREATE_IMAGE = 7

光照贴图烘焙失败,原因是最终的图像无法保存,或保存后无法被 Godot 导入。

BakeError BAKE_ERROR_USER_ABORTED = 8

用户中止了光照贴图烘焙操作(通常通过点击进度对话框中的取消按钮)。

BakeError BAKE_ERROR_TEXTURE_SIZE_TOO_SMALL = 9

光照贴图烘焙失败,因为最大纹理尺寸太小,无法容纳某些被标记为烘焙的网格。


enum EnvironmentMode:

EnvironmentMode ENVIRONMENT_MODE_DISABLED = 0

烘焙光照贴图时忽略环境光照。

EnvironmentMode ENVIRONMENT_MODE_SCENE = 1

烘焙光照贴图时,使用场景的环境光照。

注意:如果在没有 WorldEnvironment 节点的场景中烘焙光照贴图,这将表现得像 ENVIRONMENT_MODE_DISABLED。在烘焙光照贴图时,LightmapGI 不会考虑编辑器的预览天空和太阳。

EnvironmentMode ENVIRONMENT_MODE_CUSTOM_SKY = 2

烘焙光照贴图时,使用 environment_custom_sky 作为环境光照来源。

EnvironmentMode ENVIRONMENT_MODE_CUSTOM_COLOR = 3

烘焙光照贴图时,使用 environment_custom_colorenvironment_custom_energy 相乘的结果作为环境光照的恒定来源。


属性说明

float bias = 0.0005

  • void set_bias ( float value )

  • float get_bias ( )

计算阴影时使用的偏置。增加 bias 可以修复生成的烘焙光照贴图上的阴影失真,但会引入阴影悬浮(阴影未连接到其障碍物)。实时 Light3D 阴影不受该 bias 属性的影响。


float bounce_indirect_energy = 1.0

  • void set_bounce_indirect_energy ( float value )

  • float get_bounce_indirect_energy ( )

每次反弹的能量乘数。较高的值将使间接照明更亮。值 1.0 代表物理上准确的行为,但较高的值可用于在使用少量反弹时使间接照明传播更明显。这可以通过减少 bounces 数量,然后增加 bounce_indirect_energy 来加速烘焙时间。

注意:bounce_indirect_energy 仅在 bounces 被设置为大于或等于 1 的值时才有效。


int bounces = 3

  • void set_bounces ( int value )

  • int get_bounces ( )

烘焙过程中考虑的光反弹次数。较高的值会产生更明亮、更逼真的光线,但代价是更长的烘焙时间。如果设置为 0,则仅烘焙环境光线、直接光线和自发光光线。


CameraAttributes camera_attributes

CameraAttributes 资源,指定要烘焙的曝光级别。自动曝光和非曝光属性将被忽略。应该使用曝光设置来减少烘焙时出现的动态范围。如果曝光度太高,LightmapGI 将出现带状伪影,或可能出现过度曝光伪影。


float denoiser_strength = 0.1

  • void set_denoiser_strength ( float value )

  • float get_denoiser_strength ( )

应用于生成的光照贴图的去噪步骤的强度。仅当 use_denoisertrueProjectSettings.rendering/lightmapping/denoising/denoiser 被设置为 JNLM 时有效。


bool directional = false

  • void set_directional ( bool value )

  • bool is_directional ( )

如果为 true,烘焙光照贴图以包含作为球谐函数的方向信息。这会产生更逼真的光照外观,尤其是使用法线贴图材质和烘焙了直射光的灯光(Light3D.light_bake_mode 设置为 Light3D.BAKE_STATIC 并将 Light3D.editor_only 设置为 false)。方向信息还用于为静态和动态对象提供粗略的反射。这有一个小的运行时性能成本,因为着色器必须执行更多的工作,来解释来自光照贴图的方向信息。定向光照贴图也需要更长的时间来烘焙并产生更大的文件大小。

注意:属性的名称与 DirectionalLight3D 没有关系。directional 适用于所有灯光类型。


Color environment_custom_color

  • void set_environment_custom_color ( Color value )

  • Color get_environment_custom_color ( )

用于环境照明的颜色。仅在 environment_modeENVIRONMENT_MODE_CUSTOM_COLOR 时有效。


float environment_custom_energy

  • void set_environment_custom_energy ( float value )

  • float get_environment_custom_energy ( )

用于环境照明的颜色倍数。仅在 environment_modeENVIRONMENT_MODE_CUSTOM_COLOR 时有效。


Sky environment_custom_sky

  • void set_environment_custom_sky ( Sky value )

  • Sky get_environment_custom_sky ( )

用作环境照明光源的天空。仅在 environment_modeENVIRONMENT_MODE_CUSTOM_SKY 时有效。


EnvironmentMode environment_mode = 1

烘焙光照贴图时使用的环境模式。


GenerateProbes generate_probes_subdiv = 2

为动态对象照明自动生成 LightmapProbe 时使用的细分级别。较高的值会在动态对象上产生更准确的间接照明,但代价是更长的烘焙时间和更大的文件大小。

注意:自动生成的 LightmapProbe,不作为在场景树停靠面板中的节点可见,并且生成后无法通过这种方式修改。

注意:不管 generate_probes_subdiv,动态对象上的直接光照,总是使用 Light3D 节点实时应用。


bool interior = false

  • void set_interior ( bool value )

  • bool is_interior ( )

如果为 true,则会在烘焙光照贴图时忽略环境光照。


LightmapGIData light_data

与该 LightmapGI 节点关联的 LightmapGIData。该资源是在烘焙后自动创建的,并不意味着要手动创建。


int max_texture_size = 16384

  • void set_max_texture_size ( int value )

  • int get_max_texture_size ( )

生成的纹理图集的最大纹理大小。更高的值将导致生成的切片更少,但由于硬件对纹理大小的限制,可能无法在所有硬件上工作。如果不确定,请将 max_texture_size 保留为其默认值 16384


BakeQuality quality = 1

烘焙光照贴图时使用的质量预设。这会影响烘焙时间,但输出文件的大小在所有质量级别上基本相同。

要进一步加快烘焙时间,请在导入停靠面板中减少 bounces、禁用 use_denoiser、并增加 3D 场景的光照贴图纹素大小。


bool use_denoiser = true

  • void set_use_denoiser ( bool value )

  • bool is_using_denoiser ( )

如果为 true,则在生成的光照贴图上,使用基于 GPU 的降噪算法。这以更长的烘焙时间为代价,消除了生成的光照贴图中的大部分噪点。尽管无损压缩在压缩降噪图像方面可能做得更好,但使用降噪器通常不会显著影响文件大小。


bool use_texture_for_bounces = true

  • void set_use_texture_for_bounces ( bool value )

  • bool is_using_texture_for_bounces ( )

如果为 true,将生成带有照明信息的纹理,以加快间接照明的生成速度,但会牺牲一定的精度。当使用低分辨率光照贴图或在表面上显著拉伸光照贴图的 UV 时,几何体可能会出现额外的漏光伪影。如果不确定,请将 use_texture_for_bounces 保留为其默认值 true

注意:use_texture_for_bounces 仅在 bounces 被设置为大于或等于 1 的值时才有效。