Table of Contents

Class VoxelGI

Real-time global illumination (GI) probe.

Inheritance
VoxelGI

Remarks

VoxelGIs are used to provide high-quality real-time indirect light and reflections to scenes. They precompute the effect of objects that emit light and the effect of static geometry to simulate the behavior of complex light in real-time. VoxelGIs need to be baked before having a visible effect. However, once baked, dynamic objects will receive light from them. Furthermore, lights can be fully dynamic or baked.

Note: VoxelGI is only supported in the Forward+ rendering method, not Mobile or Compatibility.

Procedural generation: VoxelGI can be baked in an exported project, which makes it suitable for procedurally generated or user-built levels as long as all the geometry is generated in advance. For games where geometry is generated at any time during gameplay, SDFGI is more suitable (see sdfgi_enabled).

Performance: VoxelGI is relatively demanding on the GPU and is not suited to low-end hardware such as integrated graphics (consider LightmapGI instead). To improve performance, adjust rendering/global_illumination/voxel_gi/quality and enable rendering/global_illumination/gi/use_half_resolution in the Project Settings. To provide a fallback for low-end hardware, consider adding an option to disable VoxelGI in your project's options menus. A VoxelGI node can be disabled by hiding it.

Note: Meshes should have sufficiently thick walls to avoid light leaks (avoid one-sided walls). For interior levels, enclose your level geometry in a sufficiently large box and bridge the loops to close the mesh. To further prevent light leaks, you can also strategically place temporary MeshInstance3D nodes with their gi_mode set to GeometryInstance3D.GI_MODE_STATIC. These temporary nodes can then be hidden after baking the VoxelGI node.

See Also

Using Voxel global illumination
Third Person Shooter (TPS) Demo

Properties

camera_attributes

The CameraAttributes resource that specifies exposure levels to bake at. Auto-exposure and non exposure properties will be ignored. Exposure settings should be used to reduce the dynamic range present when baking. If exposure is too high, the VoxelGI will have banding artifacts or may have over-exposure artifacts.

var camera_attributes : CameraAttributes

Property Value

CameraAttributes

Remarks

data

The VoxelGIData resource that holds the data for this VoxelGI.

var data : VoxelGIData

Property Value

VoxelGIData

Remarks

size

The size of the area covered by the VoxelGI. If you make the size larger without increasing the subdivisions with subdiv, the size of each cell will increase and result in lower detailed lighting.

Note: Size is clamped to 1.0 unit or more on each axis.

var size : Vector3 = Vector3(20, 20, 20)

Property Value

Vector3

Remarks

subdiv

Number of times to subdivide the grid that the VoxelGI operates on. A higher number results in finer detail and thus higher visual quality, while lower numbers result in better performance.

var subdiv : int = 1

Property Value

int

Remarks

  • void set_subdiv(int value)
  • int get_subdiv

Methods

bake(Node, bool)

Bakes the effect from all GeometryInstance3Ds marked with GeometryInstance3D.GI_MODE_STATIC and Light3Ds marked with either Light3D.BAKE_STATIC or Light3D.BAKE_DYNAMIC. If create_visual_debug is true, after baking the light, this will generate a MultiMesh that has a cube representing each solid cell with each cube colored to the cell's albedo color. This can be used to visualize the VoxelGI's data and debug any issues that may be occurring.

Note: VoxelGI.bake works from the editor and in exported projects. This makes it suitable for procedurally generated or user-built levels. Baking a VoxelGI node generally takes from 5 to 20 seconds in most scenes. Reducing subdiv can speed up baking.

Note: GeometryInstance3Ds and Light3Ds must be fully ready before VoxelGI.bake is called. If you are procedurally creating those and some meshes or lights are missing from your baked VoxelGI, use call_deferred("bake") instead of calling VoxelGI.bake directly.

void bake(Node from_node, bool create_visual_debug)

Parameters

from_node Node
create_visual_debug bool

debug_bake

Calls VoxelGI.bake with create_visual_debug enabled.

void debug_bake