Table of Contents

Class VoxelGI

Namespace
Godot
Assembly
GodotSharp.dll

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 SdfgiEnabled).

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 ProjectSettings.rendering/global_illumination/voxel_gi/quality and enable ProjectSettings.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 GIMode set to Static. These temporary nodes can then be hidden after baking the VoxelGI node.

public class VoxelGI : VisualInstance3D, IDisposable
Inheritance
VoxelGI
Implements
Inherited Members

Constructors

VoxelGI() 

public VoxelGI()

Properties

CameraAttributes

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.

public CameraAttributes CameraAttributes { get; set; }

Property Value

CameraAttributes

Data

The VoxelGIData resource that holds the data for this VoxelGI.

public VoxelGIData Data { get; set; }

Property Value

VoxelGIData

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.

public Vector3 Size { get; set; }

Property Value

Vector3

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.

public VoxelGI.SubdivEnum Subdiv { get; set; }

Property Value

VoxelGI.SubdivEnum

Methods

Bake(Node, bool)

Bakes the effect from all GeometryInstance3Ds marked with Static and Light3Ds marked with either Static or Dynamic. If createVisualDebug 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: Bake(Node, bool) 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 Bake(Node, bool) 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 Bake(Node, bool) directly.

public void Bake(Node fromNode = null, bool createVisualDebug = false)

Parameters

fromNode Node
createVisualDebug bool

DebugBake()

Calls Bake(Node, bool) with create_visual_debug enabled.

public void DebugBake()

HasGodotClassMethod(in godot_string_name)

Check if the type contains a method with the given name. This method is used by Godot to check if a method exists before invoking it. Do not call or override this method.

protected override bool HasGodotClassMethod(in godot_string_name method)

Parameters

method godot_string_name

Name of the method to check for.

Returns

bool

HasGodotClassSignal(in godot_string_name)

Check if the type contains a signal with the given name. This method is used by Godot to check if a signal exists before raising it. Do not call or override this method.

protected override bool HasGodotClassSignal(in godot_string_name signal)

Parameters

signal godot_string_name

Name of the signal to check for.

Returns

bool

InvokeGodotClassMethod(in godot_string_name, NativeVariantPtrArgs, out godot_variant)

Invokes the method with the given name, using the given arguments. This method is used by Godot to invoke methods from the engine side. Do not call or override this method.

protected override bool InvokeGodotClassMethod(in godot_string_name method, NativeVariantPtrArgs args, out godot_variant ret)

Parameters

method godot_string_name

Name of the method to invoke.

args NativeVariantPtrArgs

Arguments to use with the invoked method.

ret godot_variant

Value returned by the invoked method.

Returns

bool
Edit this page