Voxel-based Global Illumination (SVOGI) - Lumberyard User Guide

Voxel-based Global Illumination (SVOGI)

This topic references tools and features that are legacy. If you want to use legacy tools in Lumberyard Editor, disable the CryEntity Removal gem using the Project Configurator or the command line. To learn more about legacy features, see the Lumberyard Legacy Reference.

Sparse voxel octree global illumination (SVOGI), also known as voxel GI, is a global illumination solution based on voxel ray tracing. It does not require prebaking or manual setup of bounce lights or light volumes. This solution is experimental and may be memory intensive.

Voxel GI provides the following effects:

  • Dynamic indirect light bounce from static objects and many dynamic objects.

  • Large-scale ambient occlusion (AO) and indirect shadows from static objects such as brushes, terrain, and vegetation.

For every frame, thousands of rays are traced through voxels and shadow maps to gather occlusion and in-directional lighting.

            Example global illumination enabled and disabled.

To use this feature, you must enable the SVOGI gem for your project.

You must also enable SVOGI per level.

To enable SVOGI for your level

  1. In Lumberyard Editor, choose Edit, Editor Settings, Global Preferences.

  2. In the Preferences window, under Experimental Features, select Lighting.

  3. In the right pane, under Options, select the Total Illumination check box.

  4. Click OK.

Integration Modes

You can apply voxel GI through several modes.

Mode 0

With mode 0, only opacity is voxelized. The bounced light is sampled directly from shadow maps—extended to reflective shadow maps—and compute shaders are not used.

Mode 0 has the following advantages:

  • GPU memory usage is small (~16 MB).

  • Indirect lighting is completely dynamic; moving sun does not cause any slowdown.

  • Dynamic objects can bounce indirect lighting.

Mode 0 has the following disadvantages:

  • Indirect lighting can have low quality (more noise), especially for small point lights.

  • Only single bounce is possible.

  • Only diffuse GI is possible.

  • Environment probes are needed for specular highlights.

Modes 1, 2

With modes 1 and 2, albedo, normals, and several layers of radiance are voxelized together with opacity. Direct lighting is also injected into voxelization, where it is propagated within the voxelization and then sampled during the ray-tracing pass.

Modes 1 and 2 have the following advantages:

  • Modes 1 and 2 support multiple bounces. The light source can be semi-static with multibounce support or be fully dynamic with single bounce support.

  • Mode 2 supports traced speculars.

  • They provide higher quality, smoother indirect lighting.

Modes 1 and 2 have the following disadvantages:

  • Modes 1 and 2 use more GPU memory (64 MB+).

  • Large semi-static multibounce lights cannot be moved freely, but moving sun may work fine.

  • Dynamic objects cannot affect GI, but can receive it.


If you receive a message that the display driver has stopped responding and has recovered, try this workaround from Microsoft.

Voxel GI Parameters

The following parameters are global for an entire level. You can use normal ambient lights to modulate or tint indirect light intensity locally.

Global illumination uses the sun and the seven largest static lights in the scene and the eight dynamic lights closest to the camera.

To enable voxel global illumination

  1. In Lumberyard Editor, choose Tools, Terrain Tool, Environment.

  2. In the Environment panel, under Total_Illumination_v2, adjust the following settings as needed.

    Parameter Description

    Activate voxel GI for the level.

    Integration mode

    Set to 0, 1, or 2:

    • 0 – AO + Sun bounce

    • 1 – Diffuse GI mode (experimental)

    • 2 – Full GI mode (experimental)

    For more information, see Integration Modes.

    Number of bounces Set the maximum number of indirect bounces. The first indirect bounce is completely dynamic. The remaining bounces are cached in SVO and are mostly static.
    Diffuse cone width

    Controls the width of the diffuse cone. Wider cones work faster but may cause overocclusion and increase light leaking.

    Cone max length Set the maximum length, in meters, of the tracing rays. Shorter rays work faster.
    Use light probes For integration mode 0, enable this parameter to multiply environment probes lighting with GI. Disable this parameter to replace diffuse contribution of environment probes with GI.

    For integration modes 1 and 2, enable this parameter to use global environment probe for sky light instead of Time Of Day fog color.

    Injection multiplier Modulate light injection by controlling the intensity of bounce light.
    Ambient offset red Controls the amount of red in the environment. Higher values show more red in the level.
    Ambient offset green Controls the amount of green in the environment. Higher values show more green in the level.
    Ambient offset blue Controls the amount of blue in the environment. Higher values show more blue in the level.
    Ambient offset bias Controls the strength of the light in the environment. Higher values contribute to a brighter environment.
    Saturation Controls the color saturation of propagated light.
    SSAO amount

    Scales down screen space ambient occlusion (SSAO) or screen space directional occlusion (SSDO) amount and radius when GI is active.

  3. (Optional) Use the Voxel Coverage advanced parameter on each material:

    1. Click Tools, Material Editor.

    2. Select your material.

    3. Under Advanced, modify the Voxel Coverage parameter to control the transparency of voxels for each material and manually fix overoccluded areas. The default value is 1.


    This parameter takes effect only when voxel global illumination is enabled.


You can use the following console variables to help debug voxel GI issues:

  • r_ShowRenderTarget svo_fin – Displays the output of the voxel GI system.

  • r_profiler 1 | 2 – Retrieves GPU profiling information.

  • svoToggleShowVoxels – Shows voxellation of the scene, which shows which voxels are on CPU memory and which are on GPU memory.

  • svoReset – Performs hard reset of the system and recomputes all values.


Do not use the e_svoTI_* console variables (for example, e_svoTI_IntegrationMode) to configure the voxel GI system. Any changes to these console variables in the configuration file will be overwritten by the individual level environment settings file. Instead, configure your settings in the Total Illumination pane in Lumberyard Editor.

Current Limits

The following limitations exist for the voxel GI system:

  • The GI code doesn’t have a mechanism for detecting light modifications directly, but is constantly updating to capture changes to the lighting. This may introduce delay in the GI response to lights changing.

  • Large-scale ambient occlusion and indirect shadows are properly cast only by static geometry.

  • Voxel GI does not function on some forward-rendering components like particles or water.

  • Some artifacts like ghosting, aliasing, light leaking, and noise may be noticeable.

  • Procedural vegetation and merged vegetation do not cast occlusion or secondary shadows.

  • If a camera is moved to a new location, it may take several seconds until occlusion works properly.

  • Only objects and materials with shadow map casting enabled will generate correct bounced light.

  • For dynamic objects, indirect light bounce will function only in areas near voxelized static geometry.

  • Bounce light may have a noticeable delay of 1 to 2 frames.

  • Use of the r_Supersampling=2 console variable may adversely affect the appearance of the voxel GI. You can set the LowSpecMode value two times lower to restore the appearance of the voxel GI. Temporal AA using r_AntialiasingMode 2/3 works correctly as well.