.. _doc_using_voxel_gi: Using Voxel global illumination =============================== VoxelGI is a form of fully real-time global illumination, intended to be used for small/medium-scale 3D scenes. VoxelGI is fairly demanding on the GPU, so it's best used when targeting dedicated graphics cards. .. important:: VoxelGI is only supported when using the Forward Plus rendering backend, not the Forward Mobile or Compatibility backends. .. seealso:: Not sure if VoxelGI is suited to your needs? See :ref:`doc_introduction_to_global_illumination_comparison` for a comparison of GI techniques available in Godot 4. Visual comparison ----------------- .. figure:: img/gi_none.webp :alt: VoxelGI disabled. VoxelGI disabled. .. figure:: img/gi_voxel_gi.webp :alt: VoxelGI enabled. VoxelGI enabled. Setting up VoxelGI ------------------ 1. Make sure your static level geometry is imported with the Light Baking option set to **Static** or **Static Lightmaps** in the Import dock. For manually added MeshInstance3D nodes, make sure the **Global Illumination > Mode** property is set to **Static** in the inspector. 2. Create a VoxelGI node in the Scene tree dock. 3. Move the VoxelGI node to the center of the area you want it to cover by dragging the manipulation gizmo in the 3D viewport. Then adjust the VoxelGI's extents by dragging the red points in the 3D viewport (or enter values in the inspector). Make sure the VoxelGI's extents aren't unnecessarily large, or quality will suffer. 4. Select the VoxelGI node and click **Bake** at the top of the 3D editor viewport. This will take at least a few seconds to complete (depending on the number of VoxelGI subdivisions and scene complexity). If at least one mesh contained within the VoxelGI's extents has its global illumination mode set to **Static**, you should see indirect lighting appear within the scene. .. note:: To avoid bloating text-based scene files with large amounts of binary data, make sure the VoxelGIData resource is *always* saved to an external binary file. This file must be saved with a ``.res`` (binary resource) extension instead of ``.tres`` (text-based resource). Using an external binary resource for VoxelGIData will keep your text-based scene small while ensuring it loads and saves quickly. VoxelGI node properties ----------------------- The following properties can be adjusted in the VoxelGI node inspector before baking: - **Subdiv:** Higher values result in more precise indirect lighting, at the cost of lower performance, longer bake times and increased storage requirements. - **Extents:** Represents the size of the box in which indirect lighting should be baked. Extents are centered around the VoxelGI node's origin. The following properties can be adjusted in the VoxelGIData *resource* that is contained within a VoxelGI node after it has been baked: - **Dynamic Range:** The maximum brightness that can be represented in indirect lighting. Higher values make it possible to represent brighter indirect light, at the cost of lower precision (which can result in visible banding). If in doubt, leave this unchanged. - **Energy:** The indirect lighting's overall energy. This also effects the energy of direct lighting emitted by meshes with emissive materials. - **Bias:** Optional bias added to lookups into the voxel buffer at run time. This helps avoid self-occlusion artifacts. - **Normal Bias:** Similar to **Bias**, but offsets the lookup into the voxel buffer by the surface normal. This also helps avoid self-occlusion artifacts. Higher values reduce self-reflections visible in non-rough materials, at the cost of more visible light leaking and flatter-looking indirect lighting. To prioritize hiding self-reflections over lighting quality, set **Bias** to ``0.0`` and **Normal Bias** to a value between ``1.0`` and ``2.0``. - **Propagation:** The energy factor to use for bounced indirect lighting. Higher values will result in brighter, more diffuse lighting (which may end up looking too flat). When **Use Two Bounces** is enabled, you may want to decrease **Propagation** to compensate for the overall brighter indirect lighting. - **Use Two Bounces:** If enabled, lighting will bounce twice instead of just once. This results in more realistic-looking indirect lighting, and makes indirect lighting visible in reflections as well. Enabling this generally has no noticeable performance cost. - **Interior:** If enabled, environment sky lighting will not be taken into account by VoxelGI. This should be enabled in indoor scenes to avoid light leaking from the environment. VoxelGI interaction with lights and objects ------------------------------------------- To ensure correct visuals when using VoxelGI, you must configure your meshes and lights' global illumination properties according to their *purpose* in the scene (static or dynamic). There are 3 global illumination modes available for meshes: - **Disabled:** The mesh won't be taken into account for VoxelGI baking. The mesh will *receive* indirect lighting from the scene, but it will not *contribute* indirect lighting to the scene. - **Static (default):** The mesh will be taken into account for VoxelGI baking. The mesh will both receive *and* contribute indirect lighting to the scene. If the mesh is changed in any way after baking, the VoxelGI node must be baked again. Otherwise, indirect lighting will look incorrect. - **Dynamic:** The mesh won't be taken into account for VoxelGI baking, but it will still receive *and* contribute indirect lighting to the scene in real-time. This option is much slower compared to **Static**. Only use the **Dynamic** global illumination mode on large meshes that will change significantly during gameplay. Additionally, there are 3 bake modes available for lights (DirectionalLight3D, OmniLight3D and SpotLight3D): - **Disabled:** The light won't be taken into account for VoxelGI baking. The light won't contribute indirect lighting to the scene. - **Static:** The light will be taken into account for VoxelGI baking. The light will contribute indirect lighting to the scene. If the light is changed in any way after baking, the VoxelGI node must be baked again or indirect lighting will look incorrect. If in doubt, use this mode for level lighting. - **Dynamic (default):** The light won't be taken into account for VoxelGI baking, but it will still contribute indirect lighting to the scene in real-time. This option is slower compared to **Static**. Only use the **Dynamic** global illumination mode on lights that will change significantly during gameplay. .. note:: The amount of indirect energy emitted by a light depends on its color, energy *and* indirect energy properties. To make a specific light emit more or less indirect energy without affecting the amount of direct light emitted by the light, adjust the **Indirect Energy** property in the Light3D inspector. .. seealso:: See :ref:`doc_introduction_to_global_illumination_gi_mode_recommendations` for general usage recommendations. Adjusting VoxelGI performance and quality ----------------------------------------- Since VoxelGI is relatively demanding, it will perform best on systems with recent dedicated GPUs. On older dedicated GPUs and integrated graphics, tweaking the settings is necessary to achieve reasonable performance. In the Project Settings' **Rendering > Global Illumination** section, VoxelGI quality can also be adjusted in two ways: - **Voxel Gi > Quality:** If set to **Low** instead of **High**, voxel cone tracing will only use 4 taps instead of 6. This speeds up rendering at the cost of less pronounced ambient occlusion. - **Gi > Use Half Resolution:** If enabled, both VoxelGI and SDFGI will have their GI buffer rendering at halved resolution. For instance, when rendering in 3840×2160, the GI buffer will be computed at a 1920×1080 resolution. Enabling this option saves a lot of GPU time, but it can introduce visible aliasing around thin details. Note that the **Advanced** toggle must be enabled in the project settings dialog for the above settings to be visible. Additionally, VoxelGI can be disabled entirely by hiding the VoxelGI node. This can be used for comparison purposes or to improve performance on low-end systems. Reducing VoxelGI light leaks and artifacts ------------------------------------------ After baking VoxelGI, you may notice indirect light is leaking at some spots in your level geometry. This can be remedied in several ways: - For both light leaking and artifacts, try moving or rotating the VoxelGI node then bake it again. - To combat light leaking in general, ensure your level geometry is fully sealed. This is best done in the 3D modeling software used to design the level, but primitive MeshInstance3D nodes with their global illumination mode set to **Static** can also be used. - To combat light leaking with thin geometry, it's recommended to make the geometry in question thicker. If this is not possible, then add a primitive MeshInstance3D node with its global illumination mode set to **Static**. Bake VoxelGI again, then hide the primitive MeshInstance3D node (it will still be taken into account by VoxelGI). For optimal results, the MeshInstance3D should have a material whose color matches the original thin geometry. - To combat artifacts that can appear on reflective surfaces, try increasing **Bias** and/or **Normal Bias** in the VoxelGIData resource as described above. Do not increase these values too high, or light leaking will become more pronounced.