Repository navigation
[Feature] Engine performance on macOS, iOS and visionOS #1224
Description
Goal
The engine holds its frame budget on all three platforms, and we can prove it. On Apple Vision Pro the compositor gives one display period at 90 Hz, about 11 ms, for CPU submission and GPU work back to back; a missed deadline is a dropped frame the user feels as judder, and the headset has two eyes at 2048 × 1984 to fill. On iPhone and iPad the budget is 16.7 ms at 60 Hz with thermal headroom over a twenty-minute session; on macOS the main thread must stay free for the editor. The provisional budgets are under 8 ms of GPU, 3 ms of update and 2 ms of submission per frame on the headset, and under 0.5 ms of GPU and 0.3 ms of CPU for any new feature, or a written justification.
That needs three things the engine did not have: counters that work in release builds on device (compositor deadline margins, per-system CPU time, GPU time per pass, hitches, thermal state and memory), a benchmark that runs the same scenes on macOS, iOS and visionOS and compares against stored baselines, and a working rule that every feature pull request carries its numbers. With those in place, the bottlenecks get fixed in order of measured gain.
The timing matters as much as the tooling. A large set of features is about to land on the engine (GPU deformation, particles, fluids, fog, destruction, virtualized geometry, audio, visual scripting, the visionOS levers), and each one adds passes, systems and per-entity work to the frame. Performance has to stay in sight while they arrive, not be recovered afterwards: the benchmark runs on every feature pull request, a pass or system that costs more than its budget is caught in the PR that introduces it, and the baselines move only when a change is understood. Finding a bottleneck at the beginning costs a day; finding it after ten features have built on top of it costs a refactor. The first headset run already set the direction: every benchmark scene missed the deadline; light scenes are GPU-bound on the fixed full-screen passes at two eyes, heavy scenes are CPU-bound on encode (about 9 µs per draw, the render graph built and executed twice per frame), so the visionOS levers (foveation, layered stereo) and the per-entity CPU overhead come first.
Status
| Step | Plan | Status |
|---|---|---|
| A. Counters | Compositor deadline accounting, per-system CPU time, GPU timer on every pass, hitch histogram, JSON Lines recorder, thermal and memory, runtime switch (on in debug, off in release, UNTOLD_STATS=1) |
In review on the fork (miolabs#53) |
| B. Benchmark | Examples/PerfBench (macOS, iOS, visionOS, seven scenes), run and compare scripts, baselines for Mac16,5 and Vision Pro |
In review (miolabs#53) |
| C. Workflow docs | How to run the benchmark and what a pull request must report | Not started |
| Batch one, done | Animation pause flag read directly, lazy error names, unfair lock on component ids, skip the Gaussian pass with no splats, XR frame pacer | In review (miolabs#54) |
| Batch one, open | Scene access without lock-and-copy, render-graph cache, lock-free scene-channel checks, animation gated on visibility | Waiting for decision (borrow API or Scene as a class) |
| visionOS levers | Split the XR frame into several command buffers, merge pre-composite + look + output transform, foveation with render quality, layered stereo with vertex amplification | Not started |
| Batch two | Per-frame draw list, persistent AABB buffer for culling, scene-graph index with a dirty queue, query caching, packed lights with culling, physics fetch once per body | Not started |
| GPU | Light culling, shadow filtering per platform, submission ordering, HZB depth copy, position from depth, SSAO on visionOS | Not started |
Next steps
- Review Added mouse support #53 and Fixed the changeState method for the iOS controller #54 on the fork; pull requests come here per phase once the numbers hold.
- Decide the scene-access refactor shape, then finish batch one.
- visionOS levers next: they are the largest GPU gain and the prerequisite for virtualized geometry.
Draft
- PerformanceMeasurementResearch.md (measurement stack, candidates with file references, budgets, open decisions)
Activity