Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

VoxelGI

继承： VisualInstance3D < Node3D < Node < Object

实时全局光照（GI）探测。

描述

VoxelGI 用于为场景提供高质量的实时的间接光照和反射。它们预先计算发光物体的效果和静态几何体的效果，以实时模拟复杂光线的行为。VoxelGI 需要经过烘焙才能产生可见的效果。然而，一旦烘焙，动态对象将接收来自它们的光。此外，灯光可以是完全动态的，也可以是烘焙的。

注意：VoxelGI 只支持 Forward+ 渲染方式，不支持 Mobile 或 Compatibility。

程序生成：VoxelGI 可以在导出的项目中烘焙，这使得它适用于程序生成或用户构建的关卡，只要所有几何体都预先生成即可。对于在游戏过程中随时生成几何图形的游戏，SDFGI 更合适（参见 Environment.sdfgi_enabled）。

性能：VoxelGI 对 GPU 要求比较高，不适合集成显卡等低端硬件（可以考虑改用 LightmapGI）。要提高性能，请在项目设置中，调整 ProjectSettings.rendering/global_illumination/voxel_gi/quality，并启用 ProjectSettings.rendering/global_illumination/gi/use_half_resolution。要为低端硬件提供后备方案，请考虑在项目的选项菜单中，添加一个选项，以禁用 VoxelGI。VoxelGI 节点可以通过隐藏而禁用。

注意：网格应该有足够厚的壁（避免单面墙）以避免漏光。对于内部关卡，请将关卡几何体封装在一个足够大的盒子中，并桥接循环边以闭合网格。为了进一步防止漏光，还可以策略性地放置临时 MeshInstance3D 节点，并将其 GeometryInstance3D.gi_mode 设置为 GeometryInstance3D.GI_MODE_STATIC。然后可以在烘焙 VoxelGI 节点后，隐藏这些临时节点。

教程

属性

CameraAttributes	camera_attributes
VoxelGIData	data
Vector3	size	`Vector3(20, 20, 20)`
Subdiv	subdiv	`1`

方法

void	bake(from_node: Node = null, create_visual_debug: bool = false)
void	debug_bake()

枚举

enum Subdiv: 🔗

Subdiv SUBDIV_64 = 0

使用 64 分区，这是最低的质量设置，但也是最快的。如果你能使用它，特别是在低端硬件上使用它。

Subdiv SUBDIV_128 = 1

使用 128 个分区。这是默认的质量设置。

Subdiv SUBDIV_256 = 2

使用 256 个分区。

Subdiv SUBDIV_512 = 3

使用 512 个分区。这是最高的质量设置，但也是最慢的。在低端硬件上，这可能会导致 GPU 停顿。

Subdiv SUBDIV_MAX = 4

代表 Subdiv 举的大小。

属性说明

CameraAttributes camera_attributes 🔗

void set_camera_attributes(value: CameraAttributes)
CameraAttributes get_camera_attributes()

指定烘焙所使用的曝光级别的 CameraAttributes 资源。自动曝光和非曝光属性会被忽略。曝光设置应当用于降低烘焙时的动态范围。如果曝光过高，VoxelGI 会产生色带问题，也可能出现过曝问题。

VoxelGIData data 🔗

void set_probe_data(value: VoxelGIData)
VoxelGIData get_probe_data()

为该 VoxelGI 存放数据的 VoxelGIData 资源。

Vector3 size = Vector3(20, 20, 20) 🔗

void set_size(value: Vector3)
Vector3 get_size()

VoxelGI 所覆盖区域的大小。如果你扩大了范围，但没有使用 subdiv 增加细分，则每个单元格的大小都将增加，导致照明细节下降。

注意：大小在每个轴上被限制为 1.0 或更多。

Subdiv subdiv = 1 🔗

void set_subdiv(value: Subdiv)
Subdiv get_subdiv()

对 VoxelGI 操作的栅格进行细分的次数。数字越大，细节越精细，因此视觉质量越高，而数字越小则性能越好。

方法说明

void bake(from_node: Node = null, create_visual_debug: bool = false) 🔗

烘焙来自所有标记为 GeometryInstance3D.GI_MODE_STATIC 的 GeometryInstance3D 以及标记为 Light3D.BAKE_STATIC 或 Light3D.BAKE_DYNAMIC 的 Light3D 的效果。如果 create_visual_debug 为 true，则烘焙光照后会生成一个 MultiMesh，用立方体代表各个实体单元格，每个立方体都使用对应单元格的反照率颜色着色。这样就对 VoxelGI 的数据进行了可视化，可以用来调试可能发生的问题。

注意：编辑器和导出后的项目中都可以使用 bake()。因此可用于程序式生成或用户构建的关卡。对于大多数场景，烘焙 VoxelGI 节点一般需要 5 到 20 秒。降低 subdiv 可以加速烘焙。

注意：GeometryInstance3D 和 Light3D 节点必须在调用 bake() 前完全就绪。如果这些节点是程序式生成的，而烘焙后的 VoxelGI 中缺失部分网格和灯光，请使用 call_deferred("bake")，不要直接调用 bake()。

void debug_bake() 🔗

在启用 create_visual_debug 的情况下调用 bake() 。