LightmapGI

继承： VisualInstance3D < Node3D < Node < Object

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

描述

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

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

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

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

注意：不支持在 CSGShape3D 和 PrimitiveMesh 上烘焙光照贴图，因为它们无法存储烘焙所需的 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_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 的值时才有效。

Previous Next

© 版权所有 2014-present Juan Linietsky, Ariel Manzur and the Godot community (CC BY 3.0). Revision b1c660f7.

Built with Sphinx using a theme provided by Read the Docs.