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

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

描述

The LightmapGI node is used to compute and store baked lightmaps. Lightmaps are used to provide high-quality indirect lighting with very little light leaking. LightmapGI can also provide rough reflections using spherical harmonics if directional is enabled. Dynamic objects can receive indirect lighting thanks to light probes, which can be automatically placed by setting generate_probes_subdiv to a value other than GENERATE_PROBES_DISABLED. Additional lightmap probes can also be added by creating LightmapProbe nodes. The downside is that lightmaps are fully static and cannot be baked in an exported project. Baking a LightmapGI node is also slower compared to VoxelGI.

Procedural generation: Lightmap baking functionality is only available in the editor. This means LightmapGI is not suited to procedurally generated or user-built levels. For procedurally generated or user-built levels, use VoxelGI or SDFGI instead (see Environment.sdfgi_enabled).

Performance: LightmapGI provides the best possible run-time performance for global illumination. It is suitable for low-end hardware including integrated graphics and mobile devices.

Note: Due to how lightmaps work, most properties only have a visible effect once lightmaps are baked again.

Note: Lightmap baking on CSGShape3Ds and PrimitiveMeshes is not supported, as these cannot store UV2 data required for baking.

Note: If no custom lightmappers are installed, LightmapGI can only be baked when using the Vulkan backend (Forward+ or Mobile), not OpenGL. Additionally, LightmapGI rendering is not currently supported when using the OpenGL backend (Compatibility).

教程

属性

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_count 和 ProjectSettings.rendering/lightmapping/bake_quality/low_quality_probe_ray_count 来调整此预设的质量。

BakeQuality BAKE_QUALITY_MEDIUM = 1

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

BakeQuality BAKE_QUALITY_HIGH = 2

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

BakeQuality BAKE_QUALITY_ULTRA = 3

最高的烘焙质量（最慢的烘焙时间）。可以通过更改 ProjectSettings.rendering/lightmapping/bake_quality/high_quality_ray_count 和 ProjectSettings.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_mode 为 GeometryInstance3D.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_color 和 environment_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_denoiser 为 true 且 ProjectSettings.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_mode 为 ENVIRONMENT_MODE_CUSTOM_COLOR 时有效。

float environment_custom_energy

  • void set_environment_custom_energy ( float value )

  • float get_environment_custom_energy ( )

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

Sky environment_custom_sky

  • void set_environment_custom_sky ( Sky value )

  • Sky get_environment_custom_sky ( )

用作环境照明光源的天空。仅在 environment_mode 为 ENVIRONMENT_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 的值时才有效。