Rendering quality roadmap: layered PBR and renderer foundations

[proggeramlug]

Status

Draft cumulative rendering-quality branch. The branch is intentionally kept reviewable, continuously pushed, and regression-gated while the remaining roadmap work is completed. Parent roadmap: #126.

Included so far

• layered glTF PBR material import and rendering paths
• compiled render graph, capability-aware material/texture indirection, and GPU-driven retained-rendering foundations
• data-driven baseline/modern/high-end renderer tiers with real lower-tier forcing, validated documentation, structured quality snapshots, and bounded native/Linux device negotiation ([Platform] Define renderer capability tiers and validate every fallback #138)
• transparency, refraction, reactive coverage, transmitted shadows, and virtual-shadow work
• iridescence-aware SSR metadata transport with ordinary paths kept lazy
• solid-angle/PDF-selected HDR environment prefiltering to remove thin-film fireflies
• restored Hi-Z SSGI indirect lighting and corrected WSRC octahedral corner wrapping
• merged compatibility with PRs fix: unblock main CI + audit follow-ups (RT-safety, silent-drop FFI, docs) #124, feat(apple): gamepad on macOS/iOS + iOS AVAudioSession #125, and fix(linux): make Bloom actually run on Linux — device limits, screenshots, window close #146
• truthful named local/PR/web/hardware CI lanes, strict lint/contract gates, failure evidence, exact-tag-SHA release gating, and a complete canonical-example inventory

Latest qualification

Head 21f73d8 passes every required hosted check:

• 306 shared unit tests passed (1 ignored), the production negotiated-device integration passed, 44 renderer goldens passed (2 ignored), and 3 render-target tests passed
• strict formatting/clippy, FFI/schema parity, file ratchets, wasm compile/build, and quality-governance tests pass
• macOS, Ubuntu Linux, and Windows release builds pass
• dependent macOS Chrome passes the real WebGPU known-frame/compositor-pixel smoke against the exact Ubuntu-built package
• production renderer construction passes locally in automatic high-end, forced baseline, and forced modern modes
• all 20 canonical package/main examples pass Perry code generation locally; their inventory is completeness-checked in PR CI
• exact Damaged Helmet A/B: SSIM 0.98803, luminance RMSE 0.01653 (pass)
• ordinary steady-state rendering has no new per-frame pass or CPU work; capability detection/device planning is startup work only

Remaining before ready

• finish [Platform] Define renderer capability tiers and validate every fallback #138 migration of direct Windows/mobile device paths, full public capability API, setter-result parity, and platform qualification coverage
• finish public API/debug/transport parity and closure evidence for other active rendering issues
• archive linked-native canonical-example and hardware quality runs before closing the combined [CI] Make local, PR, hardware, and release quality gates truthful #140 criterion
• add release package-install/startup smoke after [Platform] Package shader runtime dependencies and enforce UTF-8 end to end #145 supplies the Windows shader-runtime dependency manifest and packaged DXC files

This draft does not auto-close remaining roadmap issues; issue checklists are updated only when their evidence is complete.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 227a28b6-d594-4ed1-999c-2a88509a9902

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/rendering-wip-integrated-20260727

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[proggeramlug]

Issue #132 capability-fallback checkpoint is complete and pushed.

Code: c34743e
Evidence/docs: d306164

Forced baseline/modern VSM requests now select canonical CSM before shader/resource construction, report the exact reason, and allocate/submit zero VSM work. A 120/120-frame forced-baseline request is byte-identical to its CSM control (SHA-256 596a8b611496b56b9f2e5747f95b706effa2b85e136e84e481afb1d0bc987d6f). The qualified high-tier VSM hash remains unchanged at 81c6d840a275ee4fe3ff9fbeb87a5a1e21b23bb1c087a4e24c024c2f778b0bde.

The full quick lane, supported Web crate check, iOS aarch64, and Android aarch64 all pass. Five counterbalanced performance pairs show a 0.000288 ms median shadow-CPU difference within noise; both lower-tier modes execute the same frame path.

Evidence: https://github.com/Bloom-Engine/engine/blob/d306164/docs/evidence/issue-132-capability-fallback-v1.md

Issue #132 now marks the forced web/mobile/constrained fallback criterion complete.

[proggeramlug]

Issue #132 checkpoint: alpha-tested and skinned VSM caster coverage is now automated and qualified.

• Implementation: 862981f
• Evidence/docs: 3015dcb
• Real oracle: Sponza MASK caster isolated by a no-cast control; animated Fox isolated by an 8-frame same-jitter pose delta in a ground-only ROI.
• Result: 19,931 alpha-shadow pixels and 4,465 skinned-shadow pixels changed with strong contrast; 4 cutout + 4 skinned VSM draws were observed and all hard page/draw budgets held.
• Repeat capture stayed within 1/255 with SSIM 1.0.
• Exact pushed state passed the full quick lane, including FFI, Web/WASM, strict Clippy, 348 shared tests, 59 GPU goldens, 4 render-target tests, 25 quality tests, and 20 examples.

Evidence: https://github.com/Bloom-Engine/engine/blob/3015dcb/docs/evidence/issue-132-caster-coverage-v1.md

[proggeramlug]

Issue #132 full-scene motion checkpoint is complete and qualified.

• Implementation: 2ee8903, opt-in cleanup: aa36327, evidence: 91e7843.
• Full Sponza and governed 96-unique-mesh Bistro paths return to the same camera after repeated clipmap crossings.
• Matched VSM/CSM controls isolate the shadow-backend transition from exposure and temporal history.
• Residual RMSE: 0.002120 Sponza, 0.004746 Bistro; no long page seam/clip-ring component and no broad missing/stale-shadow region.
• Page preservation and fallback stayed bounded with zero denials/evictions and fixed 19,951,824-byte allocation.
• Seven fault/control tests and the complete quick lane pass.
• No production renderer path was modified; fixture work is opt-in only.

Evidence: https://github.com/Bloom-Engine/engine/blob/91e7843/docs/evidence/issue-132-full-scene-motion-v1.md

[proggeramlug]

VSM debug-view checkpoint completed and pushed:

• implementation: 840eb49 (Complete VSM debug capture views)
• evidence: 20ac21e (Record VSM debug view evidence)

Adds capture-only virtual-page, physical-occupancy, miss, invalidation, clip-level, legend, and same-frame per-light cost diagnostics, plus a fail-closed offline validator. Three live Metal captures and the full local quick lane pass. No production shader/pass/resource/binding/draw/page/sampling path changed.

Issue #132's debug-view checkbox is now complete; the issue has one remaining acceptance item: 100 shadow-requesting local lights with visibility/budget-bounded, reported cost.

[proggeramlug]

Local-light VSM milestone is pushed and qualified.

Head includes bounded shadow-required point lights (a01cf8a), an inert no-request shader path (630cb23), file-size-compliant test extraction (93ebdc3, 6a70ca7), and evidence (e27793e). Hardware result: 128 visible submissions -> 5 admitted -> 30 shared pages; cold rendering obeys the existing 8-page budget, warm cache has all five active with zero page renders, and 123 suppressed lights never enter shading loops. The controlled A/B shows localized occlusion without page/cube artifacts.

./scripts/ci-check.sh --quick passes at the pushed head. Full evidence is in docs/evidence/issue-132-local-lights-v1.{md,json}. Issue #132 is updated; it remains open only for the explicitly scoped spot-light projection.

[proggeramlug]

Issue #132 is now complete and closed.

Final spot-light commits: 0bcd2c7, d91d9c6, 69b7403.

Result: 128 visible spot requests -> 5 admitted one-page projections / 123 fail-closed suppressions; 5 clean resident pages; zero warm renders; no new persistent GPU allocation or graph pass. The same-cone caster A/B is localized (RMSE 0.01644, SSIM 0.98078) with no page/cone/frame artifacts. Full quick lane and native Web crate check pass, including exact ordinary many-point-light goldens.

Evidence: docs/evidence/issue-132-spot-lights-v1.{md,json}. Epic #126 has been updated.

[proggeramlug]

Issue #131 offline vertex-compression checkpoint is now pushed:

• implementation: 2c51d09
• evidence/docs: a9f0135
• default v1 leaf and hierarchy hashes remain byte-exact
• opt-in v2 cuts the Damaged Helmet hierarchy payload/root prefix by 53.56%/53.86%
• Sponza qualifies non-zero tangent packing and reports large-range UV error explicitly
• 21 focused tests plus the complete local scripts/ci-check.sh --quick lane pass
• no runtime renderer, pixels, passes, draws, buffers, or shader branches changed

#131 and #136 are updated. No runtime acceptance criterion is claimed by this cooker-only milestone. Current hosted checks are still running; FFI parity and CodeRabbit are already green.

[proggeramlug]

First #136 asset-database checkpoint is pushed:

• implementation: 289ba31
• evidence/docs: 16c58b0
• canonical geometry recipe keys and logical manifests
• immutable SHA-256 chunks with cross-ID deduplication
• strict standalone inspection and fail-closed corruption handling
• Damaged Helmet: 0.88 s miss -> 0.05 s verified hit, zero hit writes
• two clean stores are byte-identical
• 23 focused tests and full local scripts/ci-check.sh --quick pass
• zero shipping renderer/pixel/frame-path delta

#136 and its #131 dependency handoff are updated. Only the specific #136 cluster/LOD metadata criterion is checked; the complete multi-asset/runtime database remains open.

[proggeramlug]

Second #136 checkpoint is pushed:

• deterministic asset index: 2effe1e
• evidence/docs: 9ad5ca9
• sorted logical-ID lookup with manifest and immutable-chunk hashes
• full manifest/chunk revalidation before generation
• exact stale-index detection and zero-write unchanged rebuild
• two IDs / one deduplicated chunk; clean-store index hash abab52af...
• 25 focused tests plus full local scripts/ci-check.sh --quick pass
• no runtime renderer or pixel-path changes

#136 and the #131 lookup handoff are updated. No additional acceptance item is overclaimed.