LightmapGI

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 数据。

注意：如果没有安装自定义光照贴图器，则只能从支持 Forward+ 或 Mobile 渲染后端的设备烘焙 LightmapGI。

教程

使用光照贴图全局光照

属性

float	bias	`0.0005`
float	bounce_indirect_energy	`1.0`
int	bounces	`3`
CameraAttributes	camera_attributes
int	denoiser_range	`10`
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`
float	texel_scale	`1.0`
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

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

BakeError BAKE_ERROR_LIGHTMAP_TOO_SMALL = 10

Lightmap baking failed as the lightmap is too small.

BakeError BAKE_ERROR_ATLAS_TOO_SMALL = 11

Lightmap baking failed as the lightmap was unable to fit into an atlas.

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(value: float)
float get_bias()

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

float bounce_indirect_energy = 1.0 🔗

void set_bounce_indirect_energy(value: float)
float get_bounce_indirect_energy()

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

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

int bounces = 3 🔗

void set_bounces(value: int)
int get_bounces()

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

CameraAttributes camera_attributes 🔗

void set_camera_attributes(value: CameraAttributes)
CameraAttributes get_camera_attributes()

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

int denoiser_range = 10 🔗

void set_denoiser_range(value: int)
int get_denoiser_range()

降噪器采样的像素距离。较低的值会保留更多细节，但如果光照贴图质量不够高，则可能会产生斑点结果。仅当 use_denoiser 为 true 且 ProjectSettings.rendering/lightmapping/denoising/denoiser 被设置为 JNLM 时有效。

float denoiser_strength = 0.1 🔗

void set_denoiser_strength(value: float)
float get_denoiser_strength()

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

bool directional = false 🔗

void set_directional(value: bool)
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(value: Color)
Color get_environment_custom_color()

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

float environment_custom_energy 🔗

void set_environment_custom_energy(value: float)
float get_environment_custom_energy()

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

Sky environment_custom_sky 🔗

void set_environment_custom_sky(value: Sky)
Sky get_environment_custom_sky()

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

EnvironmentMode environment_mode = 1 🔗

void set_environment_mode(value: EnvironmentMode)
EnvironmentMode get_environment_mode()

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

GenerateProbes generate_probes_subdiv = 2 🔗

void set_generate_probes(value: GenerateProbes)
GenerateProbes get_generate_probes()

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

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

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

bool interior = false 🔗

void set_interior(value: bool)
bool is_interior()

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

LightmapGIData light_data 🔗

void set_light_data(value: LightmapGIData)
LightmapGIData get_light_data()

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

int max_texture_size = 16384 🔗

void set_max_texture_size(value: int)
int get_max_texture_size()

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

BakeQuality quality = 1 🔗

void set_bake_quality(value: BakeQuality)
BakeQuality get_bake_quality()

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

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

float texel_scale = 1.0 🔗

void set_texel_scale(value: float)
float get_texel_scale()

缩放当前烘焙的所有网格的光照贴图纹素密度。这是一个基于每个导入的 3D 场景中定义的已有光照贴图纹素大小、以及每个网格密度乘数（设计用于在不同缩放使用相同网格时使用）的乘数。较低的值将导致更快的烘焙时间。

bool use_denoiser = true 🔗

void set_use_denoiser(value: bool)
bool is_using_denoiser()

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

bool use_texture_for_bounces = true 🔗

void set_use_texture_for_bounces(value: bool)
bool is_using_texture_for_bounces()

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

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