[Lighting Overhaul][Phase 2] Rewrite cascaded shadows and caster submission

[MichaelFisher1997]

Parent

Part of #898.

Depends on

#900. Phase 1 (#899) may proceed in parallel after Phase 0.

Goal

Replace the contradictory CSM math and sampling path while preserving the existing Vulkan shadow resource ownership and reverse-Z convention.

Scope

• Compute practical/logarithmic cascade splits from camera near/far and configured shadow distance.
• Fit exact frustum-slice corners or correctly sized stable spheres rather than the current camera-origin far-corner radius.
• Use positive view-space depth consistently for fitting, selection, overlap, and final fade.
• Stabilize X/Y translation to the real shadow texel grid and control rotational swimming from the moving sun.
• Define explicit cascade overlap bands contained by both cascades.
• Derive map-edge margins from the active PCF kernel radius.
• Express caster/receiver bias in world and texel units with per-cascade scaling.
• Build caster candidates from receiver volumes extruded toward the light instead of a camera-centered square.
• Keep caster distance independent from receiver distance and include a chunk safety margin.
• Implement atlas-aware alpha testing for cutout shadows; stop discarding diagonal vegetation wholesale.
• Include supported entities in the shadow scene.
• Replace misleading PCF settings with coherent hard/4/9/16-tap tiers.
• Enable batched shadow submission by default once parity and overflow tests pass.
• Repair shadow-map debug previews and retain useful cascade/caster/seam channels.

Acceptance criteria

• Every frustum slice corner lies inside its cascade projection.
• Reverse-Z near/far endpoints and comparisons are covered by tests.
• Sub-texel camera motion does not move shadow edges.
• Cascade transitions are continuous and no filter tap samples outside valid overlap.
• Shadow distance/fade behavior matches settings without hidden 128/160-unit caps.
• Low-sun off-screen casters remain represented.
• Cutout vegetation casts alpha-correct shadows and entities cast supported shadows.
• No visible acne, peter-panning, cascade lines, or detached voxel contacts in deterministic scenes.
• High-preset shadow GPU time is targeted below 2.5 ms at 1080p on designated hardware.

Required tests

• Frustum-corner containment and overlap containment.
• Reverse-Z endpoint mapping.
• Translation stability below one texel.
• View-depth cascade selection.
• Bias scaling across cascades.
• Alpha-cutout discard behavior.
• Caster extrusion and boundary chunk coverage.

Verification

nix develop --command zig fmt modules/engine-graphics/src modules/world-runtime/src
nix develop --command zig build test
nix develop --command zig build -Dskip-present
nix develop --command zig build test-robustness
nix develop --command zig build run -Dskip-present -Dshadow-test-scene -Dscreenshot-path=screenshots/lighting-phase2-shadow.png -Dscreenshot-frame=180
nix develop --command zig build benchmark -Doptimize=ReleaseFast -Dbenchmark-preset=high -Dbenchmark-duration=60 -Dbenchmark-output=lighting-phase2-high.json

[github-actions]

Triage: Feature Request (rewrite of an audited-high subsystem)

Classification. Feature request — well-scoped rewrite of the CSM/caster subsystem. Not a new feature in isolation; the umbrella #898 already catalogues the underlying CSM math as High severity (audit row: "CSM fitting uses frustum depth while shader selection uses radial distance and a hard-coded 72–128 unit fade"). This child issue is the implementation tracker for that finding.

No duplicate or competing work. I checked open/closed PRs and issues touching CSM, shadow maps, and cascade coverage. The only open shadow-related PR is #701, which only adds 8 unit tests around validateCascades/ShadowParams/rhi_shadow_bridge (getShadowMapHandle indexing, UBO offset checks); it does not implement any of the Phase 2 behavior. There is no in-flight Phase 2 PR.

Issue is well-defined — no missing info from the reporter. Scope, acceptance criteria, required tests, and the verification command set are all explicit. The reporter (MichaelFisher1997, the lighting architect) has documented the parent and the dependency on Phase 0 (#900) and parallel-eligibility with Phase 1 (#899). No reproduction steps needed; the math is fully specified in the body.

Validation against current code — every problem called out in scope is reproducible in the tree:

• Camera-origin far-corner radius: modules/engine-graphics/src/csm.zig:99-106 builds radius = sqrt(xf² + yf² + far_v²) from the cascade split and tan(fov/2), then snaps radius to a sixteenth-block grid. This is exactly the "camera-origin far-corner radius" called out. It is not a frustum-corner nor a stable sphere fit.
• Hidden 120/80-unit caps: csm.zig:89-90 defines depth_padding_front = 120.0, depth_padding_back = 80.0 (env-overridable but not driven by shadow_distance or per-cascade). These are the literal "128/160-unit caps" the acceptance criteria forbid once removed.
• Non-practical split scheme: csm.zig:77-85 uses constant ratios [0.25, 0.50, 0.75, 1.0] scaled by far; there is no near term in the split formula. No log/practical blend (lambda) despite the doc-comment claim at line 65.
• Diagonal vegetation wholesale discard: assets/shaders/vulkan/shadow.vert:50-52 flags any face with |normal.y| < 0.001 && |normal.x| > 0.1 && |normal.z| > 0.1 as vSkipShadow = 1, then shadow.frag:8 unconditional discard. This is exactly the stop discarding diagonal vegetation wholesale bullet.
• No atlas-aware cutout alpha test: shadow.frag body is literally if (vSkipShadow != 0) discard; — no texture sample, no alpha test (9 lines, all of it at lines 7-9). There is no PCF tier system in either shader.
• Phase 2 hasn't started: umbrella [Lighting Overhaul][Umbrella] Rebuild voxel lighting, shadows, and scene composition #898 has sub-issues-completed: 0/6; Phase 0 ([Lighting Overhaul][Phase 0] Establish visual baselines and repair pipeline contracts #900) is still open. Per the dependency note in [Lighting Overhaul][Umbrella] Rebuild voxel lighting, shadows, and scene composition #898 ("Child issues are ordered dependencies and should land as small PR series targeting dev"), Phase 0 must land before Phase 2's contracts are guaranteed.

Scope and PR slicing recommendation. The scope is tight to one subsystem (CSM math/sampling/caster submission), but the body lists 15 behavior bullets with 9 acceptance criteria and 7 mandatory tests — too large for a single reviewable PR against dev. The umbrella already prescribes a "small PR series", so I recommend this child issue stay open as the integration tracker and the implementation land as a sub-PR series branched from dev, one per cohesive concern:

1. PR-A — Cascade splits & stable frustum fit: replace split_ratios/env-only front/back padding with a true practical/log blend driven by real near/far/shadow_distance; compute the ortho frustum from the exact 8 frustum slice corners (positive view-Z), fall back to a stable bounding sphere only when needed. Removes the hidden 120/80 caps. Resolves bullets 1–4 of scope partially. Required tests: frustum-corner containment, reverse-Z endpoint mapping.
2. PR-B — Texel-grid stability & overlap bands: snap to texel grid in light space using actual published resolution (depends on Phase 0 publishing real resolution); define explicit per-cascade overlap min/max constants; derive map-edge margins from the active PCF kernel radius. Resolves remaining stability/overlap bullets. Required tests: translation stability below one texel, overlap containment.
3. PR-C — Bias remap (world/texel units): express caster/receiver bias in world and texel units with per-cascade scaling; remove the bias_params packing expressed in mixed units. Required test: bias scaling across cascades.
4. PR-D — Caster bounds & chunk safety: build caster candidates from receiver volumes extruded toward the light (not a camera-centered square); decouple caster distance from receiver distance; add the chunk safety margin. Required test: caster extrusion and boundary chunk coverage. Should be merged alongside the GPU instance_buf model path already wired in shadow.vert:25-27.
5. PR-E — Atlas-aware cutout alpha test + entity casters: rewrite shadow.frag to sample the cutout atlas and alpha-discard in-shader; remove the diagonal-billboard wholesale discard in shadow.vert; include supported entities via the existing instance buffer path. Required test: alpha-cutout discard behavior.
6. PR-F — Coherent PCF tiers + batched submission + debug previews: replace the misleading PCF tier labeling with hard/4/9/16-tap; re-enable batched shadow submission by default once overflow tests pass (Phase 0 must expose overflow tracking); repair debug_shadow.frag and keep cascade/caster/seam channels. Acceptance: continuous transitions, no out-of-overlap tap samples.

Each PR should run the full Phase 2 verification command set locally; the umbrella's acceptance criteria and benchmarks only finalize once PR-F merges. If the maintainer prefers sub-issues per PR instead of branches only, I can file them — say the word.

Verification already on the issue matches the umbrella's prescribed sequence (zig fmt, zig build test, zig build -Dskip-present, zig build test-robustness, -Dshadow-test-scene screenshot, -Dbenchmark-preset=high). No additional reporter info needed.

[github-actions]

Comment posted on issue #903: #903 (comment)

Triage summary:

• Classification: Feature Request (rewrite of audited-high CSM/caster subsystem; umbrella [Lighting Overhaul][Umbrella] Rebuild voxel lighting, shadows, and scene composition #898 categories it as High severity)
• Validation: Every problem cited is reproducible in the current tree — csm.zig:99-106 builds the exact "camera-origin far-corner radius" called out, csm.zig:89-90 hardcodes the 120/80 padding the AC forbids, shadow.vert:50-52 + shadow.frag:8 confirm the wholesale diagonal-vegetation discard, and the empty shadow.frag confirms there is no atlas-aware alpha test
• No competing work: only related open PR is 8 shadow tests added, all pass #701, which only adds 8 unit tests — no Phase 2 rewrite in flight
• No missing reporter info: scope/AC/tests/verification are all explicit and aligned with the umbrella's prescribed dev PR-series plan
• No information requested from user — the issue is complete
• Scope recommendation: stay open as the integration tracker; land as a 6-PR sub-series (PR-A splits/fit → PR-B stability/overlap → PR-C bias remap → PR-D caster bounds → PR-E cutout+entities → PR-F PCF tiers/batched submit/debug), each mergeable against dev after Phase 0 lands the contracts# Comment Posted Successfully

Posted triage comment on issue #903 (view comment) — classification, validation against current code, no-competing-work check, and PR slicing recommendation.

opencode session  |  github run