Repository navigation

Occlusion culling (#108) - #346

Open

markwpearce wants to merge 27 commits into

mainfrom

feature/issue-108-occlusion-culling

Open

Occlusion culling (#108)#346
markwpearce wants to merge 27 commits into
mainfrom
feature/issue-108-occlusion-culling

markwpearce commented Oct 17, 2026

Owner

Closes #108
Closes #342

Static drawables can now be marked isOccluder and hide what's behind them (span map per screen band, conservative test - anything uncertain still draws). isOnScreen() is backed by a BGE.VisibilityState enum now. Design is in specs/2026-10-16-occlusion-culling-design.md.

Also in here:

Oriented SceneObjectModel/SceneObjectPolygon measure depth from the world origin #342 - oriented models/polygons take their depth from their own centre
fixed the back-face test for 3D models, which was inverted (outward-wound OBJ/STL faces drew only their back faces)
Renderer.occluderDrawPolicy - fastShrink (default), exact, fastExactClaim
cached Camera3d.getLevelUpVector() and stopped computing the camera-facing quad twice - ~7ms off every moving frame, occlusion or not
terrain gets an occluding chapel (OK toggles occlusion, --param profile=1 runs a scripted profile), rendererTest gets two occlusion benchmarks

Numbers (Roku Ultra, ms per moving frame): terrain is about break-even, off 85 vs on 83-85, since what it hides are cheap tree blits. The occlusion-heavy rendererTest scene is a real win, ~120 on vs 129-135 off.

Things to decide / known issues:

the chapel "bounces" while the camera moves - occluders now take the model fast paths (whole-model stretch until it's 64px off, per-face reuse). exact should stop it, at a cost. Is the default policy right, or should it be fastExactClaim for the extra speed?
the model's stretch claim only checks the 4 extreme points, so a non-convex model (the chapel's tower vs. nave) can over-claim near its silhouette for a few frames while panning
the chapel disappearing when mostly off screen is mostly pre-existing model culling, but the Oriented SceneObjectModel/SceneObjectPolygon measure depth from the world origin #342 centre-depth change can make it worse - Large 3D models disappear when partly off screen or close to the camera #344
slow adaptive quality step-up in terrain is pre-existing, more perf ideas in More 3D renderer performance ideas #345
the chapel is untextured until Support multiple materials/textures per .obj model (usemtl) #341

🤖 Generated with Claude Code

markwpearce and others added 27 commits

October 16, 2026 23:25


          Add occlusion culling design (#108)

b485579

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>


          Add occlusion culling implementation plan (#108)

7a8d5ea

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>


          Measure oriented model/polygon depth from the object, not the origin (#…

ec8e421

…342)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>


          Use object centre for depth in every non-screen-aligned draw mode (#342)

c0b0a34

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>


          Add screen-space span occlusion map (#108)

b4e81bb

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>


          Never hide an empty or inverted box in the span map (#108)

ba5b809

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>


          Merge coplanar model faces into occluder panels (#108)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>


          Report visibility as an enum; keep GameEntity.isOnScreen() as a wrapp…

9137bd0

…er (#108)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>


          Register static drawables flagged isOccluder (#108)

e7dc8fb

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>


          Fix occluder auto-registration and doc comment placement (#108)

47e564c

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>


          Project occluders to canvas polygons and draw them exactly (#108)

8253b2a

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>


          Draw Image occluders without the fast path; document occluder opacity (…

748dbb3

…#108)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>


          Cull objects hidden behind static occluders (#108)

3623cac

Renderer.updateOcclusion() runs after updateSceneObjects(): it rebuilds the
span map only when the camera, projection, canvas, an occluder or an
occlusion setting changed, then re-tests each candidate whose verdict is
stale. Both draw loops skip an occluded object via markSkippedOccluded().

A screen-aligned billboard is tested by the camera-facing quad directScaled
draws, never in the fixed-pixel-size modes; particles are never tested.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>


          Add occlusion debug overlay (#108)

c943314

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>


          Add occlusion benchmarks to rendererTest (#108)

3c65df3

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>


          Time-box span benchmark checks; drop unused startScene param (#108)

c91bcff

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>


          Add an occluding chapel to terrain (#108)

22bea23

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>


          Document occlusion culling and visibility (#108)

7b404b9

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>


          Fix occlusion review findings: popping and stale reveals (#108)

2ae186f

- An unfilled rectangle stops contributing, so toggling filled rebuilds the map
- A billboard revealed after being hidden re-rasterizes its temp bitmap
- No static-BSP warning for a static model occluder
- Text is never occluded; AnimatedImage frame size changes invalidate geometry
- A culled object isn't an occlusion candidate, so its latch holds
- Debug overlay only draws spans while occlusion is active
- Direct OcclusionTypes imports, doc comment and docs fixes

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>


          Fix chapel winding and draw it without back faces (#108)

a5c1fde

The back gable's three triangles were wound inward and the cross was
single-sided, so the chapel only looked right with solidDrawBackFace.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>


          Use plain solid in the occluder docs example (#108)

6a75d28

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>


          Let occluders use fast-path drawing, shrinking their claim (#108)

36ca153

Occluders now take temp-bitmap reuse, the image fast path, model per-face
reuse/whole-model stretch and coarse triangle fills like anything else.
While an approximate path may run, each occluder polygon is inset by that
path's worst error (BGE.Occlusion.insetConvexPolygon); an image on the fast
path claims the rectangle it paints, 1px in. A change in inset or quality
rebuilds the occlusion map, so the claim grows back when motion stops.
Model per-face raster reuse now only happens while moving.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>


          Add Renderer.occluderDrawPolicy (#108)

8782f28

BGE.OccluderDrawPolicy picks how occluders trade exactness for speed:
exact (no fast paths, exact claim), fastShrink (the default: fast paths,
claim shrunk by their worst error) or fastExactClaim (fast paths, exact
claim). A policy change bumps qualityVersion so cached drawings redraw.
Model per-face raster reuse is limited to moving frames only for a
fastShrink occluder again; other models reuse on still frames as before.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>


          Add a scripted occlusion profile to the terrain example (#108)

5aacdd9

--param profile=1 flies a fixed, frame-indexed camera path past the chapel
once per configuration (occlusion off, then each occluder draw policy) at
a pinned quality level, and prints and shows the frame times, occluded
counts and draw calls for the moving and still segments.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>


          Fix inverted back-face test for 3D models (#108)

caa5741

Model faces have outward normals (counter-clockwise from outside, as .obj
and .stl files are wound), but isNormalFacingCamera() treated a normal
pointing away from the camera as front-facing. So solid/oriented/wireFrame
models drew their inside faces, shading was inverted, and occluder panels
were gated the wrong way. Models now use their own outward-normal helpers;
billboards are unchanged. The occlusion spec cube is wound normally again.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>


          Cut the occlusion pass's per-frame cost (#108)

85d903c

In examples/terrain on a Roku Ultra the pass cost ~19ms per moving frame,
which made occlusion a net loss. It's now ~7ms, about break-even there.

- Rule objects out before the full test by their depth position: nearer
  than every span, or not under a nearer span in their band. Only the
  objects actually behind an occluder get the full test (23 -> 8 a frame).
- Camera3d.projectPointsWithDepth() projects points with the same results
  as worldPointToCanvasPoint()/distanceFromCameraFront(), much cheaper.
- Model occluders cache their world-space panels until they move.
- Oriented images, rectangles and circles are tested by the worldPoints
  update() already placed, instead of recomputing them.
- Camera3d.getLevelUpVector() is cached by orientation, and a directScaled
  quad no longer computes the camera vectors twice. This sped up every
  moving frame in terrain by ~7ms, occlusion or not.
- Renderer.getOcclusionMsLastFrame()/getOcclusionTestsLastFrame(), shown
  by the terrain profile and the occlusion scene benchmark.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>


          Soften occluder doc claims about over-claiming (#108)

2bab7f5

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

This branch has not been deployed

No deployments

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet