Up to date
This page is up to date for Godot 4.0.
If you still find outdated information, please open an issue.
Occlusion culling¶
In a 3D rendering engine, occlusion culling is the process of performing hidden geometry removal.
On this page, you'll learn:
What are the advantages and pitfalls of occlusion culling.
How to set up occlusion culling in Godot.
Troubleshooting common issues with occlusion culling.
See also
You can see how occlusion culling works in action using the Occlusion Culling and Mesh LOD demo project.
Why use occlusion culling¶
In this example scene with hundreds of rooms stacked next to each other, a dynamic object (red sphere) is hidden behind the wall in the lit room (on the left of the door):
Example scene with an occlusion culling-friendly layout¶
With occlusion culling disabled, all the rooms behind the lit room have to be rendered. The dynamic object also has to be rendered:
Example scene with occlusion culling disabled (wireframe)¶
With occlusion culling enabled, only the rooms that are actually visible have to be rendered. The dynamic object is also occluded by the wall, and therefore no longer has to be rendered:
Example scene with occlusion culling enabled (wireframe)¶
Since the engine has less work to do (fewer vertices to render and fewer draw calls), performance will increase as long as there are enough occlusion culling opportunities in the scene. This means occlusion culling is most effective in indoor scenes, preferably with many smaller rooms instead of fewer larger rooms. Combine this with Mesh level of detail (LOD) and Visibility ranges (HLOD) to further improve performance gains.
Note
When using the Clustered Forward rendering backend, the engine already performs a depth prepass. This consists in rendering a depth-only version of the scene before rendering the scene's actual materials. This is used to ensure each opaque pixel is only shaded once, reducing the cost of overdraw significantly.
The greatest performance benefits can be observed when using the Forward Mobile rendering backend, as it does not feature a depth prepass for performance reasons. As a result, occlusion culling will actively decrease shading overdraw with that rendering backend.
Nonetheless, even when using a depth prepass, there is still a noticeable benefit to occlusion culling in complex 3D scenes. However, in scenes with few occlusion culling opportunities, occlusion culling may not be worth the added setup and CPU usage.
How occlusion culling works in Godot¶
Note
"occluder" refers to the shape blocking the view, while "occludee" refers to the object being hidden.
In Godot, occlusion culling works by rasterizing the scene's occluder geometry to a low-resolution buffer on the CPU. This is done using the software raytracing library Embree.
The engine then uses this low-resolution buffer to test occludees' AABB against the occluder shapes. The occludee's AABB must be fully occluded by the occluder shape to be culled.
As a result, smaller objects are more likely to be effectively culled than larger objects. Larger occluders (such as walls) also tend to be much more effective than smaller ones (such as decoration props).
Setting up occlusion culling¶
The first step to using occlusion culling is to enable the Rendering > **Occlusion Culling > Use Occlusion Culling project setting. (Make sure the Advanced toggle is enabled in the Project Settings dialog to be able to see it.)
This project setting applies immediately, so you don't need to restart the editor.
After enabling the project setting, you still need to create some occluders. For performance reasons, the engine doesn't automatically use all visible geometry as a basis for occlusion culling. Instead, the engine requires a simplified representation of the scene with only static objects to be baked.
There are two ways to set up occluders in a scene: