LOD GPU roadmap Phase 0: establish profiling and quality baselines

[MichaelFisher1997]

Goal

Establish trustworthy LOD-specific measurements before changing CPU/GPU ownership. This phase is the dependency for every later optimization.

Current evidence

The current benchmark aggregates the whole renderer, while LOD work spans LODManager.update, worker generation/meshing, LODRenderer, Vulkan uploads, cache I/O, and deferred destruction. We cannot yet attribute frame time or memory specifically to distant terrain.

Parallel workstreams

• Add CPU timings for scheduling/state scans, terrain sampling, mesh construction, visibility/coverage checks, cache load/store, upload preparation, and lock wait/hold time.
• Add GPU timestamp scopes for LOD opaque terrain and LOD water, separate from normal chunks.
• Track LOD regions by state/level, draws, vertices, visible/rejected counts, coverage checks, upload bytes, pending CPU bytes, GPU pool/direct-buffer bytes, deferred deletion bytes, and pool growth/compaction.
• Count and identify runtime waitIdle calls and staging-pressure events.
• Define reproducible stationary, traversal, rapid-turn, and teleport/eviction scenarios.
• Capture visual baselines for seams, transitions, water, fog, and full-detail handoff.

Relevant code

• modules/world-lod/src/lod_manager_core_ops.zig
• modules/world-lod/src/lod_manager_generation_ops.zig
• modules/world-lod/src/lod_renderer.zig
• modules/world-lod/src/lod_manager_upload_ops.zig
• modules/world-lod/src/lod_manager_eviction_ops.zig
• modules/engine-graphics/src/vulkan/
• src/lod_bench_main.zig

Acceptance criteria

• A benchmark artifact reports LOD CPU and GPU timings independently.
• p50/p95/p99 frame time and worst-frame attribution are available.
• Metrics distinguish CPU generation/meshing, submission, GPU shading, transfer, synchronization, and memory pressure.
• All scenarios are bounded, headless, documented, and repeatable.
• Instrumentation can be disabled or has negligible release overhead.

Validation

Run nix develop --command zig build test, nix develop --command zig build lod-bench, and bounded zig build benchmark scenarios. Record hardware, preset, render distance, seed, duration, and build mode.

[github-actions]

Comment Draft

I'm an automated agent analyzing this issue. Here's my classification and analysis:

---

Classification: Feature request (roadmap). This is the documented Phase 0 of a multi-phase LOD GPU roadmap and is explicitly the dependency for #920 (Phase 1).

Not a duplicate — distinct from #900 (Lighting Phase 0, closed by merged PR #905), which followed the same convention and serves as a useful precedent.

Codebase state (verified):

1. Partial coverage already exists:

   • LODStats (modules/world-lod/src/lod_stats.zig) already tracks per-level state counts, queue depths, cache/store hit rate, evictions, and drawn/instances/fluid counts.
   • RenderDiag (modules/world-lod/src/lod_renderer.zig:65-75) tracks frustum/covered/drawn counters at runtime.
   • LODManager.updateStats() (modules/world-lod/src/lod_manager.zig:573) exposes snapshots.

2. Gap that motivates this issue: GPU timestamp scopes (modules/engine-graphics/src/vulkan/rhi_timing.zig:5-20) only enumerate ShadowPass0..3, GPass, SSAO, LPV, Sky, Opaque, Bloom, FXAA, PostProcess. There is no LODTerrainPass or LODWaterPass in the GpuPass enum, so rhi_timing.processTimingResults cannot attribute GPU time to LOD — confirming the issue's claim that "the current benchmark aggregates the whole renderer."

3. No waitIdle counting: vkDeviceWaitIdle is invoked from ≥10 sites (rhi_state_control.zig:7,83,90, frame_manager.zig:80,236, transfer_queue.zig:252,343, resource_manager.zig:106, swapchain_presenter.zig:98, rhi_frame_orchestration.zig:15,55, rhi_resource_setup.zig:579, rhi_pass_orchestration.zig:20, rhi_init_deinit.zig:188). None are counted or attributed to LOD.

4. Benchmark harness is ready to extend: BenchmarkRunner (modules/game-core/src/benchmark.zig:77) and BenchmarkResults JSON schema (benchmark.zig:61-75) already collect FrameSample (cpu_ms, fps, gpu_shadow_ms, gpu_opaque_ms, gpu_total_ms, draw_calls, vertices, chunks_rendered, gpu_memory_mb). Adding LOD fields (lod_cpu_ms, lod_gpu_ms, lod_visible, lod_rejected, lod_upload_bytes, lod_pending_bytes, lod_pool_bytes, lod_deferred_bytes, wait_idle_count, staging_pressure_count) and corresponding Summary percentiles (p50/p95/p99/worst) extends rather than duplicates this. BENCH_PATH waypoints (benchmark.zig:15-22) already provide traversal poses — the new "stationary / rapid-turn / teleport-eviction" scenarios can layer on as additional waypoint arrays or scripted camera inputs.

5. lod_bench_main.zig already covers the CPU heightmap-only case (src/lod_bench_main.zig:74), so Phase 0 can focus on the GPU, scheduling, and submission paths rather than re-measuring generation alone.

Scope assessment: The 6 parallel workstreams are independently sizeable. Each is a reasonable standalone PR, and the parallel-workstream framing already implies decomposition. Concretely:

• Workstream 1 (CPU timings) → one PR scoped to lod_manager_*_ops.zig instrumentation + stats fields
• Workstream 2 (GPU timestamp scopes) → one PR extending rhi_timing.zig GpuPass enum + LODRenderer begin/end hooks + render_graph.zig:204-206 wiring
• Workstream 3 (memory/region counters) → one PR extending LODStats and RenderDiag
• Workstream 4 (waitIdle/staging counters) → one PR adding an rhi_state_control counter and a transfer_queue staging-pressure hook
• Workstreams 5 & 6 (scenarios + visual baselines) → documentation + new waypoint arrays / -Dscreenshot-* invocations analogous to lighting-phase0-high.json (PR fix: establish lighting phase zero baselines #905)

Suggestion: keep #921 as the umbrella issue with acceptance criteria and link each PR/follow-up issue to the specific workstream bullet. No follow-up issues need to be created up-front — they can be opened as each workstream is picked up.

No info requested: the issue is self-contained and references the exact code locations.

I'm not opening a PR — only commenting as instructed.

opencode session  |  github run