ENG2-P2-12: O(visible) validation on S1/S2; fix residual per-object frame costs; close #678

[aram-devdocs]

Parent

• Program: ENG2 — GoudEngine v2 Rebuild (see the pinned master tracking issue)
• Phase / Milestone: Phase 2 — Render Core v2 (eng2-p2-render-core)
• Batch / Group: Batch 2.4 — Scene-scale primitives & gate validation, Group B (Phase 2 gate)
• Runbook spec: docs/src/runbook/phases/phase-2.md (committed with the roadmap)

Summary

Validate O(visible) per-frame cost on the S1/S2 scripted scenes at the raised super-high-FPS gate numbers, fix any residual per-object frame costs the P0 phase counters surface, and close #678 with a satisfying capture report.

Architecture Context

Layer: Layer 2 (Libs) — libs/graphics/renderer3d/ and libs/graphics/backend/wgpu_backend/ (whichever residual costs the capture surfaces) (see tools/lint_layers.rs — downward-only deps).
Modules/types touched:

• Whatever renderer3d/backend files the S1/S2 capture reports show as still carrying per-object (not per-visible) cost — this issue's scope is discovered by running the gate, not predetermined.
• scripts/perf-capture (ENG2-P0-07) — used to run S1/S2 and produce the 3-run-median report.

Boundary constraints (only those that apply):

• Raw GPU calls stay in libs/graphics/backend/ — no wgpu:: outside it.

Pattern to follow: docs/src/runbook/perf-dod.md perf definition-of-done: a perf issue is closed only when the named scene hits the number AND the phase counter attributes the cost.

Scope

• Run S1 (throne-baseline: 55k objects/10k visible, shadows OFF) via scripts/perf-capture, 3-run median.
• Run S2 (throne-target: 100k objects/30k visible, shadows ON) via scripts/perf-capture, 3-run median.
• Run the cull_scaling bench (fixed 5k visible, total 10k→100k).
• Run the 40k-plane draw-call bench.
• Attribute any remaining cost that scales with total (not visible) object count using the ENG2-P0-01/P0-02 phase counters; fix stragglers (per-object hash-map touches, per-frame allocations) found during this validation.
• Post the capture report on perf: BeginFrame + EndFrame scale with scene object count (not just draw calls) — ~20 ms per 10k sub-meshes #678 and close it.
• Tests: spec test at goud_engine/tests/spec/ + unit/isolation coverage for the new code paths.

Acceptance Criteria

• S1: BeginFrame+EndFrame ≤ 2 ms combined; sustained ≥ 120 FPS. (raised gate — design-expansion.md §A; supersedes the earlier ≤4ms/≥60FPS number)
• S2 (100k objects, 30k visible, shadows ON): ≥ 120 FPS average; p99 frame ≤ 12 ms; no frame > 20 ms. (raised gate — design-expansion.md §A; supersedes the earlier 10k-visible/≥60FPS/p99≤33ms number)
• cull_scaling (CI-gated): fixed 5k visible, total 10k→100k ⇒ frame-time increase ≤ 10%.
• Draw-call bench: 40k CreatePlane tiles ⇒ ≤ 64 draw calls.
• Shadows: S2 shadows-ON vs OFF total-frame delta ≤ 25%; gpu_shadow ≤ 4 ms and non-zero.
• perf: BeginFrame + EndFrame stall 300-600ms when shadows enabled with 1.4k+ scene instances (macOS Metal) #677, perf: BeginFrame + EndFrame scale with scene object count (not just draw calls) — ~20 ms per 10k sub-meshes #678, perf: CreatePlane() primitives bypass instancing — 40k terrain planes = 11k draw calls, only 43 instanced #679 closed with capture links satisfying the perf definition-of-done.
• cargo check && cargo fmt --all -- --check && cargo clippy -- -D warnings clean; cargo test green; ./codegen.sh && git diff --exit-code (drift gate)

Breaking Change & Throne Follow-up

None — this is a validation/gate issue; any fixes it makes to residual per-object costs are internal unless a fix requires a breaking change, in which case split that fix into its own breaking-change issue rather than smuggling it into the gate closure.

Blocked By

ENG2-P2-01, ENG2-P2-02, ENG2-P2-04, ENG2-P2-05, ENG2-P2-06, ENG2-P2-07, ENG2-P2-08, ENG2-P2-09, ENG2-P2-10, ENG2-P2-11, ENG2-P2-13 (this is the Phase 2 gate — it validates every other Phase 2 deliverable together, including the SoA transform store).

Files Likely Touched

• New/Modified/Generated: Discovered during gate validation — likely candidates are whichever renderer3d/backend files still show non-zero per-object cost in the P0 phase-counter capture.

Agent Notes

• This is the type:gate issue that closes Phase 2 — it does not add a new feature, it validates the sum of ENG2-P2-01 through P2-11 and P2-13 against the scripted S1/S2 scenes and fixes whatever residual per-object cost the P0 instrumentation (ENG2-P0-01/P0-02) surfaces.
• Gate numbers are the RAISED super-high-FPS numbers from design-expansion.md §A, not the original design-technical.md §Phase 2 Gate numbers — S1 is ≤2ms/≥120FPS (was ≤4ms/≥60FPS), S2 is 30k visible (was 10k visible) at ≥120FPS avg/p99≤12ms/no frame>20ms (was ≥60FPS/p99≤33ms). Do not use the older numbers if referencing an outdated cached copy of the phase doc.
• Closing PR posts the capture report on perf: BeginFrame + EndFrame scale with scene object count (not just draw calls) — ~20 ms per 10k sub-meshes #678 per design-technical.md's disposition map (perf: BeginFrame + EndFrame scale with scene object count (not just draw calls) — ~20 ms per 10k sub-meshes #678 → ENG2-P2-02 + ENG2-P2-12, closed at the Phase 2 gate).

Verification

cargo check && cargo fmt --all -- --check && cargo clippy -- -D warnings
cargo test
./codegen.sh && git diff --exit-code
# perf gate: python3 scripts/bench-gate.py (per perf-dod.md), scene capture (S1, S2, cull_scaling, draw-call bench) attached to #678