User Guide (Version 1.14)

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 Amazon 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.

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 these 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 these 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 these 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 these 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.

To enable voxel global illumination

  1. In the Rollup Bar, on the Terrain tab, choose Environment.

  2. In the Environment panel, under Total Illumination v2, adjust the following settings as needed.

    Parameter Description

    Activate voxel GI for the level.

    Injection multiplier

    Modulate light injection by controlling the intensity of bounce light.

    Sky color multiplier

    Control the amount of the sky light. You can multiply this value with the Time of Day fog color.

    Saturation Control the color saturation of propagated light.
    Diffuse bias Add constant ambient value to GI to prevent completely black areas. Set this parameter to negative to modulate the ambient value with near-range ambient occlusion and prevent constant ambient light in completely occluded indoor areas.
    Cone max length Set the maximum length, in meters, of the tracing rays. Shorter rays work faster.
    Update geometry Enable this parameter to force single complete revoxelization of the scene. This is required if terrain, brushes, or vegetation are modified.
    Low spec mode Set this parameter to a value greater than 0 to simplify shaders and scale down internal render targets. Set this parameter to –2 to initialize the mode by the value specified in the sys_spec_Shading.cfg file when the level is loaded.
    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.

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

    1. Click Tools, Material Editor.

    2. Select your material.

    3. In the lower pane, click Advanced.

    4. 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:

  • e_svoDebug=6 – Visualizes the voxels. Voxelize all important objects in the scene; otherwise, they will not cast occlusion and secondary shadows. Exclude all unwanted and unnecessary occluders from voxelization.

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

  • r_profiler 1 | 2 – Retrieves GPU profiling information.

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.

Configure your settings in the Total Illumination panel in Lumberyard Editor. To enable the extended total illumination settings in the editor, click Edit, Editor Settings, Global Preferences. In the Preferences window, choose Experimental Features, Lighting and select Total Illumination. Click OK to save your selection.

Current Limits

The following limitations exist for the voxel GI system:

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