MCP perf tooling: CPU-scope profiling, GPU-timing accuracy under load, overdraw debug view

[drsnuggles8]

Follow-up to #306 and #316, surfaced by two live MCP perf-diagnosis sessions (2026-07-02,
Sponza CSM/atrium, Dist build) run against the real-GPU-timings tooling from #517. Tracks
the remaining perf-diagnostics gaps that are neither scriptable-repro-setup (#316 Part 5)
nor part of #306's now-complete write-consent epic.

New tool wanted

• olo_perf_cpu_scopes — expose PerformanceProfiler per-scope CPU timings (every
  system in Scene.cpp is wrapped in OLO_PERF_SCOPE) over MCP, read-only. Today this
  data only reaches the editor Statistics panel, and OLO_PERF_SCOPE is compiled out
  entirely in Dist, so a Dist session has zero CPU-scope visibility (frame totals only).
  Shipped in Add olo_perf_cpu_scopes MCP tool for per-scope CPU timings (#519, first slice) #537.

Accuracy bugs in the #517 GPU-timing tooling (diagnosed, not fixed)

Root-caused during a heavy-GPU-load session (frame >250 ms, Sponza atrium, Dist, maximized
viewport) — surfaced in the #316 comment thread (2026-07-02/07-03 live perf sessions):

• cpuMs exceeds frameTimeMs at saturation (e.g. cpu 905 ms vs frame 519 ms).
  Root cause: RendererProfiler measures m_FrameTime at BeginFrame (previous
  frame-boundary delta) but m_CPUTime at EndFrame (current bracket), and the MCP
  snapshot reads m_CurrentFrame mid-frame — the two numbers describe different
  frames whenever frame times swing.
• gpuWaitMs reads 0.00 even when the GPU is the bottleneck by ~100x. Only the
  FrameResourceManager::BeginFrame fence wait is attributed; under deep GPU backlogs
  the real stall lands in SwapBuffers, outside the profiler bracket entirely (and the
  editor's over-budget render throttle further suppresses fence waits).
• Per-pass GPU numbers get erratic on very long frames (ShadowPass read 13.9 ms at
  native vs 0.59 ms at 1080p vs 4.3 ms at 4K with a fixed camera — shadow cost cannot
  depend on viewport resolution). GPUPassTimerPool has a 4-slot timestamp ring; when
  the GPU falls more than 3 frames behind, slots are dropped rather than awaited and
  published results go stale. gpuResultsAgeFrames (already in the payload) is the
  honesty signal to check before trusting numbers on very long frames — worth
  surfacing more prominently (e.g. a warning flag) rather than requiring the caller to
  know to check it.

Missing debug view

• No overdraw debug view (shipped in feat(mcp): add overdraw debug view (#519) #558) in olo_render_set_debug_view (only ssao/gtao/ssr/ssgi
  exist today). An overdraw heatmap mode (per-fragment counting target + heatmap
  composite) would make "how many layers deep is this frame" measurable directly
  instead of inferred from A/B toggling passes. Deliberately scoped out of the
  overdraw work's own PR to keep it reviewable — it's a real renderer feature, not
  a tooling patch.

Smaller findings

• Boot inconsistency: the settings-derived depth-prepass value (on, because
  ForwardPlusAutoSwitch defaults true) disagrees with the live boot state (off) —
  ApplyRendererSettings never runs at startup, so setting depthprepass=auto
  immediately after boot changes the state instead of no-oping.
• First perf-lever write right after scene load doesn't take effect on the GPU
  (repeatable A/B afterwards) — likely an editor-settle/render-throttle transient;
  worth a beat of settle time after load before trusting the first A/B reading.

Status — updated 2026-07-07

olo_perf_cpu_scopes (#537), the overdraw debug view (#558), and all three GPU-timing
accuracy bugs (#571) have shipped. The feature/mcp-perf-scenepass-tooling branch
referenced in earlier updates landed through those same PRs and no longer exists as a
separate branch. Remaining scope is just the two "Smaller findings" above (boot
inconsistency, first-write-after-load not taking effect) — everything else in this issue
is done.

Refs: #306, #316, #517.

Score

capability: 3
craft: 1
stability: 2
decay: 1
effort: 2
confidence: 0.8
learning: 3
fun: 3
kano: table-stakes
blocked_by: []
blocks: []

_{Rated per issue-scoring · score = confidence × (capability + craft + stability + decay) / effort, derived by the picker.}

[coderabbitai]

🔗 Related PRs

#331 - feat(mcp): camera control, viewport sizing, and render-target capture… [merged]
#352 - feat(mcp): add olo_render_frame_breakdown per-command frame breakdown… [merged]
#517 - feat(mcp): real GPU timings end-to-end — whole-frame timer, gpuWaitMs… [merged]
#518 - feat(mcp): ScenePass sub-pass GPU timings, depthprepass/softshadows p… [merged]
#571 - fix(renderer): align RendererProfiler frame/CPU/GPU-wait measurements [merged]

---

🧪 Issue enrichment is currently in open beta.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[drsnuggles8]

Fresh evidence for olo_perf_cpu_scopes from the perf stress battery (feature/perf-stress-scenes, Dist, RTX 4090 — full numbers in docs/guides/perf-stress-scenes.md + findings report on that branch):

• \�cs_static_100000\ (100k transform-only entities, Play mode): 19.0 ms frame, gpu 2.8 ms, snapshot cpuMs 0.73 — ~16 ms/frame of CPU (spatial-index rebuild / editor bookkeeping) is completely invisible over MCP; RendererProfiler's cpuMs only covers render submission.
• \physics_sleeping_10000: 214 ms frame, of which ~189 ms is (stale) ShadowPass GPU — the sleeping-body Jolt→ECS writeback cost the scene was built to isolate cannot be separated from draw submission without per-system scopes.
• \�nim_crowd_128\ (below the 4096-bone-matrix cap): 12.2 ms frame at 84 fps with gpu 4.1 ms — ~8 ms of AnimationSystem CPU per frame for 128 characters, again unattributable over MCP in Dist.

Also hit while running the battery — physics runtime stats over MCP: \olo_physics_contacts\ gives an active contact-pair count, but there is no active/sleeping body count and no Jolt step ms (the 10k pile ran at 0.6 fps CPU-bound with no way to see the step cost over MCP; had to infer from frame minus gpu). A read-only \olo_physics_stats\ (bodies active/sleeping/total, step ms, update-error flags — the battery hit \ContactConstraintsFull) would make physics scenes diagnosable.

[drsnuggles8]

First shippable slice shipped in #537: `olo_perf_cpu_scopes` — a read-only MCP tool exposing `PerformanceProfiler`'s per-scope CPU timings (every system in `Scene.cpp` wrapped in `OLO_PERF_SCOPE`/`OLO_PERF_SCOPE_AUTO`), mirroring the editor's PerformanceLayer CPU Scopes table. Reports an explicit `"unavailable"` status in Distribution builds instead of a misleadingly empty list, since the macro compiles out there.

Remaining scope, deferred to follow-up PRs to keep this one reviewable:

• GPU-timing accuracy bugs (`cpuMs` > `frameTimeMs` at saturation, `gpuWaitMs` reading 0 under GPU-bound load, erratic per-pass numbers on long frames) — touches `RendererProfiler`.

• Overdraw debug view — a real renderer feature, not a tooling patch, per this issue's own scoping note.

• `olo_perf_cpu_scopes` MCP tool (Add olo_perf_cpu_scopes MCP tool for per-scope CPU timings (#519, first slice) #537)

[drsnuggles8]

First shippable slice delivered by #537 (merged 2026-07-03, worktree removed): olo_perf_cpu_scopes MCP tool exposing per-scope CPU timings. Remaining scope per the PR: GPU-timing accuracy under load (cpuMs > frameTimeMs, gpuWaitMs reading 0, erratic per-pass numbers), and the overdraw debug view. Leaving open.

[drsnuggles8]

Second shippable slice delivered by #558: overdraw debug view — olo_render_set_debug_view { mode: "overdraw" } heat-maps per-pixel fragment count (black → blue → green → yellow → red) by replaying ScenePass's batched opaque bucket into an additive, depth-test-off accumulation target, then compositing through a heatmap shader. Pinned by a CPU contract test (OverdrawHeatmapMathTest) and a GPU visual-evidence test (OverdrawVisualEvidenceTest.StackedGeometryReadsHotter) — screenshot at OloEditor/assets/tests/visual/Overdraw_Heatmap.png.

Remaining scope, left open:

• GPU-timing accuracy bugs (cpuMs > frameTimeMs at saturation, gpuWaitMs reading 0 under GPU-bound load, erratic per-pass numbers on long frames) — touches RendererProfiler.

• olo_perf_cpu_scopes MCP tool (Add olo_perf_cpu_scopes MCP tool for per-scope CPU timings (#519, first slice) #537)

• Overdraw debug view (feat(mcp): add overdraw debug view (#519) #558)

[drsnuggles8]

Fixed the three GPU-timing accuracy bugs on feature/renderer-profiler-timing (this is
that same branch — olo_perf_cpu_scopes #537 and the overdraw debug view #558 were
already done):

Bug 1 — cpuMs > frameTimeMs at saturation. Root cause confirmed: RendererProfiler::BeginFrame()
computed frame time from the wall-clock delta since the previous BeginFrame() — which
is actually the previous frame's duration — but stamped it onto the record for the frame
that was only just starting. So GetCurrentFrameData() read mid-frame paired frame N-1's
frameTimeMs with frame N's cpuMs/gpuMs. Fixed by patching FrameTime (and GPUWaitTime,
see bug 2) into the previous frame's already-recorded data at the start of the next
BeginFrame(), once both are fully known, and exposing that via a new
RendererProfiler::GetLastCompletedFrameData() — every field describes the same completed
frame, ≤1 frame of latency. GetCurrentFrameData() stays as a live/approximate accessor for
UI display; the MCP olo_perf_snapshot / olo_perf_pass_timings handlers now read the
completed-frame accessor instead.

Bug 2 — gpuWaitMs reads ~0 even when clearly GPU-bound. Only the
FrameResourceManager::BeginFrame fence wait was attributed. The real GPU-bound stall for a
windowed app is Window::SwapBuffers() (vsync / driver throttling), which runs in
Application::Run after RendererProfiler::EndFrame() already finalized the frame inside
the render layer's OnUpdate — so it was invisible to the profiler entirely. Fixed by timing
SwapBuffers() and feeding it through a new RendererProfiler::AddPostFrameGPUWaitTime(),
patched into the previous frame alongside the fix above.

Bug 3 — erratic per-pass GPU numbers on long frames. Investigated GPUPassTimerPool:
it's already a correctly non-blocking, N-frame-in-flight timestamp ring
(GL_QUERY_RESULT_AVAILABLE polled before GL_QUERY_RESULT, ages tracked via
GpuResultsAgeFrames) — found no additional root cause beyond bug 1 making the whole
snapshot look inconsistent even when the per-pass GPU numbers themselves were fine. Per this
issue's own suggestion, made the staleness signal explicit instead of implicit: added a
gpuResultsStale boolean to olo_perf_pass_timings' output (true once
gpuResultsAgeFrames reaches the timer pool's slot count, meaning a slot was dropped rather
than resolved) so a caller doesn't have to know to compare the age against the pool's slot
count itself.

Verification:

• Added OloEngine/tests/Debug/RendererProfilerTest.cpp (unit layer) pinning the
  frame-alignment invariant with synthetic BeginFrame/EndFrame/AddPostFrameGPUWaitTime
  sequences, plus a gpuResultsStale test in McpPassTimingsTest.cpp.
• Live-verified against a running Debug editor (FoliageGenerationTest.olo, RTX 4090) over
  the MCP olo_perf_snapshot / olo_perf_pass_timings tools: cpuMs ≤ frameTimeMs held
  across every sampled frame (e.g. cpu 3.37–3.97 ms vs frame 5.42–7.42 ms), and gpuWaitMs
  now reads a small non-zero value (~0.06–0.24 ms, real vsync/present wait) instead of a
  hard 0.00.

Leaving this issue open — the olo_perf_cpu_scopes box above isn't ticked yet even though
#537 should have covered it (worth a follow-up look), and the "Smaller findings" /
"overlapping in-progress work" items are untouched by this PR.