Lightmass

继承： VisualRender < Item3D < Item < Object

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

描述

Lightmass节点用于计算和存储烘焙光照贴图。光照贴图用于提供高质量的间接照明，漏光非常少。如果启用了directional，Lightmass还可以使用球面谐波提供粗略的反射。动态对象可以通过光探针接收间接照明，可以通过将generate_probes_subdiv设置为GENERATE_PROBES_DISABLED以外的值来自动放置。还可以通过创建LightProbe节点来添加额外的光照贴图探针。缺点是光照贴图是完全静态的，无法在导出的项目中烘焙。烘焙Lightmass节点与VoxelGI相比也更慢。

程序生成：Lightmap烘焙功能仅在编辑器中可用。这意味着Lightmass不适合程序生成或用户构建的级别。对于程序生成或用户构建的级别，请改用VoxelGI或SDFGI（参见Environment.sdfgi_enabled）。

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

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

注意：不支持ICSGShapeBase和PrimitiveMesh上的Lightmap烘焙，因为它们无法存储烘焙所需的UV2数据。

注意：如果没有安装自定义Lightmappers，则只能从支持Forward+或Mobile渲染器的设备烘焙Lightmass。

注意：Lightmass节点仅为其父节点的子节点烘焙轻数据。场景层次结构更高的节点不会被烘焙。

属性

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

Color(1, 1, 1, 1)

float

environment_custom_energy

1.0

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

ShadowmaskMode

shadowmask_mode

0

bool

supersampling

false

float

supersampling_factor

2.0

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/ultra_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

光照贴图烘焙失败，因为此i3D构建中没有可用的光照贴图。

BakeError BAKE_ERROR_NO_SAVE_PATH = 4

光照贴图烘焙失败，因为资源中未配置LightmapGIData保存路径。

BakeError BAKE_ERROR_NO_MESHES = 5

光照贴图烘焙失败，因为没有网格的GeometryRender.gi_mode是GeometryRender.GI_MODE_STATIC并且在当前场景中具有有效的UV2映射。您可能需要在导入扩展坞中选择3D场景并相应地更改其全局照明模式。

BakeError BAKE_ERROR_MESHES_INVALID = 6

光照贴图烘焙失败，因为光照贴图无法分析一些标记为静态烘焙的网格。

BakeError BAKE_ERROR_CANT_CREATE_IMAGE = 7

光照贴图烘焙失败，因为生成的图像在保存后无法由i3D保存或导入。

BakeError BAKE_ERROR_USER_ABORTED = 8

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

BakeError BAKE_ERROR_TEXTURE_SIZE_TOO_SMALL = 9

光照贴图烘焙失败，因为最大纹理大小太小，不适合某些标记为烘焙的网格。

BakeError BAKE_ERROR_LIGHTMAP_TOO_SMALL = 10

光照贴图烘焙失败，因为光照贴图太小。

BakeError BAKE_ERROR_ATLAS_TOO_SMALL = 11

光照贴图烘焙失败，因为光照贴图无法放入图集。

enum EnvironmentMode: 🔗

EnvironmentMode ENVIRONMENT_MODE_DISABLED = 0

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

EnvironmentMode ENVIRONMENT_MODE_SCENE = 1

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

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

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 🔗

计算阴影时使用的偏差。增加bias可以修复生成的烘焙光照贴图上的阴影粉刺，但可以引入彼得平移（阴影不连接到其施法器）。实时Light阴影不受此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 🔗

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

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，则烘焙光照贴图以将方向信息包含为球形谐波。这会导致更逼真的照明外观，尤其是对于法线贴图的材质和直射光烘焙的光源（Light.light_bake_mode设置为Light.BAKE_STATIC并将Light.editor_only设置为false）。方向信息还用于为静态和动态对象提供粗略的反射。这具有较小的运行时性能成本，因为着色器必须执行更多工作来解释来自光照贴图的方向信息。方向光照贴图也需要更长的时间来烘焙，并导致更大的文件大小。

注意：属性的名称与DirectionalLight没有关系。directional适用于所有光源类型。

Color environment_custom_color = Color(1, 1, 1, 1) 🔗

  • void set_environment_custom_color(value: Color)

  • Color get_environment_custom_color()

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

float environment_custom_energy = 1.0 🔗

  • 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 🔗

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

GenerateProbes generate_probes_subdiv = 2 🔗

自动生成用于动态对象照明的LightProbe时使用的细分级别。更高的值会导致动态对象上更准确的间接照明，但代价是更长的烘烤时间和更大的文件大小。

注意：自动生成的LightProbe在Scene树停靠中作为节点不可见，生成后不能这样修改。

注意：无论generate_probes_subdiv如何，始终使用Light节点实时应用动态对象的直接照明。

bool interior = false 🔗

  • void set_interior(value: bool)

  • bool is_interior()

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

LightmapGIData light_data 🔗

与此Lightmass节点关联的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 🔗

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

要进一步加快烘烤时间，请减少bounces、禁用use_denoiser和/或减少texel_scale。

要进一步提高质量，请启用supersampling和/或增加texel_scale。

ShadowmaskMode shadowmask_mode = 0 🔗

实验性： 未来版本中可能会修改或移除该属性。

用于使用此Lightmass实例烘焙的静态对象上的定向阴影的阴影掩蔽策略。

阴影遮罩允许DirectionalLight节点甚至在其DirectionalLight.directional_shadow_max_distance属性定义的范围之外投射阴影。这是通过烘焙包含定向光阴影贴图的纹理，然后根据当前阴影遮罩模式使用该纹理来完成的。

注意：仅当shadowmask_mode不是LightmapGIData.SHADOWMASK_MODE_NONE时才会创建阴影蒙版纹理。要查看差异，您需要在从LightmapGIData.SHADOWMASK_MODE_NONE切换到任何其他模式后再次烘焙光照贴图。

bool supersampling = false 🔗

  • void set_supersampling_enabled(value: bool)

  • bool is_supersampling_enabled()

如果true，则在保存光照贴图之前，使用与supersampling_factor相乘的texel比例烘焙光照贴图并进行下采样（因此有效的texel密度与禁用超级采样相同）。

超级采样提供了更高的光照贴图质量，同时噪音更少，阴影更平滑，物体中小规模特征的阴影更好。但是，在烘焙光照贴图时，它可能会导致烘焙时间和内存使用量显着增加。填充会自动调整以避免增加漏光。

float supersampling_factor = 2.0 🔗

  • void set_supersampling_factor(value: float)

  • float get_supersampling_factor()

超采样时纹理密度乘以的因子。为获得最佳结果，请使用整数值。虽然允许使用小数值，但它们可能会导致漏光增加和光照图模糊。

更高的值可能会导致更好的质量，但也会增加烘烤时间和烘烤时的内存使用。

有关详细信息，请参阅supersampling。

float texel_scale = 1.0 🔗

  • void set_texel_scale(value: float)

  • float get_texel_scale()

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

例如，加倍texel_scale将每个轴*上所有对象的光照贴图纹理分辨率加倍，因此它将*四倍的texel计数。

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的值时才有效。