Work in progress
Godot documentation is being updated to reflect the latest changes in version
4.0. Some documentation pages may
still state outdated information. This banner will tell you if you're reading one of such pages.
The contents of this page are up to date. If you can still find outdated information, please open an issue.
Signed distance field global illumination (SDFGI)¶
Signed distance field global illumination (SDFGI) is a novel technique available in Godot 4.0. It provides semi-real-time global illumination that scales to any world size and works with procedurally generated levels.
SDFGI supports dynamic lights, but not dynamic occluders or dynamic emissive surfaces. Therefore, SDFGI provides better real-time ability than baked lightmaps, but worse real-time ability than VoxelGI.
From a performance standpoint, SDFGI is one of the most demanding global illumination techniques in Godot. Like with VoxelGI, there are still many settings available to tweak its performance requirements at the cost of quality.
SDFGI is only supported when using the Forward Plus rendering backend, not the Forward Mobile or Compatibility backends.
Not sure if SDFGI is suited to your needs? See Which global illumination technique should I use? for a comparison of GI techniques available in Godot 4.
Setting up SDFGI¶
In Godot, SDFGI is the global illumination technique with the fewest required steps to enable:
Make sure your MeshInstance nodes have their Global Illumination > Mode property set to Static in the inspector.
For imported 3D scenes, the bake mode can be configured in the Import dock after selecting the 3D scene file in the FileSystem dock.
Add a WorldEnvironment node and create an Environment resource for it.
Edit the Environment resource, scroll down to the SDFGI section and unfold it.
Enable SDFGI > Enabled. SDFGI will automatically follow the camera when it moves, so you do not need to configure extents (unlike VoxelGI).
Environment SDFGI properties¶
In the Environment resource, there are several properties available to adjust SDFGI appearance and quality:
Use Occlusion: If enabled, SDFGI will throw additional rays to find and reduce light leaks. This has a performance cost, so only enable this property if you actually need it.
Read Sky Light: If enabled, the environment lighting is represented in the global illumination. This should be enabled in outdoor scenes and disabled in fully indoor scenes.
Bounce Feedback: By default, indirect lighting only bounces once when using SDFGI. Setting this value above
0.0will cause SDFGI to bounce more than once, which provides more realistic indirect lighting at a small performance cost. Sensible values are usually between
1.0depending on the scene. Note that in some scenes, values above
0.5can cause infinite feedback loops to happen, causing the scene to become extremely bright in a few seconds' time. If your indirect lighting looks "splotchy", consider increasing this value above
0.0to get more uniform-looking lighting. If your lighting ends up looking too bright as a result, decrease Energy to compensate.
Cascades: Higher values result in more detailed GI information (and/or greater maximum distance), but are significantly more expensive on the CPU and GPU. The performance cost of having more cascades especially increases when the camera moves fast, so consider decreasing this to
4or lower if your camera moves fast.
Min Cell Size: The minimum SDFGI cell size to use for the nearest, most detailed cascade. Lower values result in more accurate indirect lighting and reflection at the cost of lower performance. Adjusting this setting also affects Cascade 0 Distance and Max Distance automatically.
Cascade 0 Distance: The distance at which the nearest, most detailed cascade ends. Greater values make the nearest cascade transition less noticeable, at the cost of reducing the level of detail in the nearest cascade. Adjusting this setting also affects Min Cell Size and Max Distance automatically.
Max Distance: Controls how far away the signed distance field will be computed (for the least detailed cascade). SDFGI will not have any effect past this distance. This value should always be set below the Camera's Far value, as there is no benefit in computing SDFGI past the viewing distance. Adjusting this setting also affects Min Cell Size and Cascade 0 Distance automatically.
Y Scale: Controls how far apart SDFGI probes are spread vertically. By default, vertical spread is the same as horizontal. However, since most game scenes aren't highly vertical, setting the Y Scale to
50%can provide better quality and reduce light leaks without impacting performance.
Energy: The brightness multiplier for SDFGI's indirect lighting.
Normal Bias: The normal bias to use for SDFGI's probe ray bounces. Unlike Probe Bias, this only increases the value in relation to the mesh's normals. This makes the bias adjustment more nuanced and avoids increasing the bias too much for no reason. Increase this value if you notice striping artifacts in indirect lighting or reflections.
Probe Bias: The bias to use for SDFGI's probe ray bounces. Increase this value if you notice striping artifacts in indirect lighting or reflections.
SDFGI interaction with lights and objects¶
The amount of indirect energy emitted by a light is governed by 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.
To ensure correct visuals when using SDFGI, 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 in SDFGI generation. 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 in SDFGI generation. The mesh will both receive and contribute indirect lighting to the scene. If the mesh is changed in any way after SDFGI is generated, the camera must move away from the object then move back close to it for SDFGI to regenerate. Alternatively, SDFGI can be toggled off and back on. If neither is done, indirect lighting will look incorrect.
Dynamic (not supported with SDFGI): The mesh won't be taken into account in SDFGI generation. The mesh will receive indirect lighting from the scene, but it will not contribute indirect lighting to the scene. This acts identical to the **Disabled* bake mode when using SDFGI.*
Additionally, there are 3 bake modes available for lights (DirectionalLight3D, OmniLight3D and SpotLight3D):
Disabled: The light won't be taken into account for SDFGI baking. The light won't contribute indirect lighting to the scene.
Static: The light will be taken into account for SDFGI baking. The light will contribute indirect lighting to the scene. If the light is changed in any way after baking, indirect lighting will look incorrect until the camera moves away from the light and back (which causes SDFGI to be baked again). will look incorrect. If in doubt, use this mode for level lighting.
Dynamic (default): The light won't be taken into account for SDFGI 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.
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.
See Which global illumination mode should I use on meshes and lights? for general usage recommendations.
Adjusting SDFGI performance and quality¶
Since SDFGI 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, SDFGI quality can also be adjusted in several ways:
Sdfgi > Probe Ray Count: Higher values result in better quality, at the cost of higher GPU usage. If this value is set too low, this can cause surfaces to have visible "splotches" of indirect lighting on them due to the number of rays thrown being very low.
Sdfgi > Frames To Converge: Higher values result in better quality, but GI will take more time to fully converge. The effect of this setting is especially noticeable when first loading a scene, or when lights with a bake mode other than Disabled are moving fast. If this value is set too low, this can cause surfaces to have visible "splotches" of indirect lighting on them due to the number of rays thrown being very low. If your scene's lighting doesn't have fast-moving lights that contribute to GI, consider setting this to
30to improve quality without impacting performance.
Sdfgi > Frames To Update Light: Lower values result in moving lights being reflected faster, at the cost of higher GPU usage. If your scene's lighting doesn't have fast-moving lights that contribute to GI, consider setting this to
16to improve performance.
Gi > Use Half Resolution: If enabled, both SDFGI and VoxelGI 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.
SDFGI rendering performance also depends on the number of cascades and the cell size chosen in the Environment resource (see above).
SDFGI has some downsides due to its cascaded nature. When the camera moves, cascade shifts may be visible in indirect lighting. This can be alleviated by adjusting the cascade size, but also by adding fog (which will make distant cascade shifts less noticeable).
Additionally, performance will suffer if the camera moves too fast. This can be fixed in two ways:
Ensuring the camera doesn't move too fast in any given situation.
Temporarily disabling SDFGI in the Environment resource if the camera needs to be moved at a high speed, then enabling SDFGI once the camera speed slows down.
When SDFGI is enabled, it will also take some time for global illumination to be fully converged (25 frames by default). This can create a noticeable transition effect while GI is still converging. To hide this, you can use a ColorRect node that spans the whole viewport and fade it out when switching scenes using an AnimationPlayer node.
The signed distance field is only updated when the camera moves in and out of a cascade. This means that if geometry is modified in the distance, the global illumination appearance will be correct once the camera gets closer. However, if a nearby object with a bake mode set to Static or Dynamic is moved (such as a door), the global illumination will appear incorrect until the camera moves away from the object.