# Occlusion culling

a Hi-Z GPU cull drops objects hidden behind a near wall.

```{raw} html
<span class="example-docs-badge">📄 Docs only</span>

```

**Tags:** `3d` `culling` `performance`

A large wall stands close to the camera. Directly behind it sits a dense field of
cubes that are almost entirely hidden, plus a few cubes off to the sides that the
wall does NOT cover. With occlusion culling ON (``WorldEnvironment
.occlusion_culling_enabled = True``) the renderer rejects the instances the wall
occludes against the previous frame's depth pyramid, so the hidden field is never
drawn. Toggle it OFF and every frustum-visible cube is submitted again.

The on-screen overlay reads ``App.last_telemetry`` and reports, live:
    drawn   -- instances that survived the cull and were drawn this frame
    total   -- frustum-visible instances submitted to the cull (pre-cull)
    culled  -- total - drawn (the objects the wall hid)

The camera slowly orbits a small arc in front of the wall (and can be nudged with
A/D) so the occlusion is observable as the hidden field pops in/out at the wall's
edges.

Controls:
    C     : Toggle occlusion culling on/off
    A/D   : Orbit the camera left / right
    ESC   : Quit

Usage:
    uv run python examples/features/3d/occlusion_culling.py
    uv run python examples/features/3d/occlusion_culling.py --test

## Source

```{literalinclude} ../../examples/features/3d/occlusion_culling.py
:language: python
:linenos:
```