diff --git a/docs/research/2026-06-10-flap-outdoor-fullworld-CLOSED-depthmask-leak.md b/docs/research/2026-06-10-flap-outdoor-fullworld-CLOSED-depthmask-leak.md new file mode 100644 index 00000000..f9196319 --- /dev/null +++ b/docs/research/2026-06-10-flap-outdoor-fullworld-CLOSED-depthmask-leak.md @@ -0,0 +1,114 @@ +# CLOSED — §4 outdoor FULL-WORLD flap: EnvCellRenderer DepthMask(false) leak no-oped the frame depth clear + +**Date:** 2026-06-10. **Branch:** `claude/thirsty-goldberg-51bb9b`. +**Commits:** `682cba3` ([clip-route] probe apparatus), `c4df241` (the fix). +**Status:** FIXED — user visual gate passed + probe-verified (0 leaked frames in the +38k-line verification capture). Closes the investigation opened by +`2026-06-09-flap-outdoor-fullworld-building-flood-merge-handoff.md`. + +--- + +## 1. Root cause + +`EnvCellRenderer.RenderModernMDIInternal` established the Transparent pass state — +`Enable(GL_BLEND)` + `glDepthMask(false)` — **before** the batch pass-filter loop. A +flooded cell whose batches are **all opaque** (a plain cottage interior: walls only, no +transparent surfaces) produced `totalDraws == 0` in the Transparent pass and hit the +early `return` **without ever reaching the end-of-pass restore**. The frame ended with +`dmask=0 blend=1`. + +The kill is one GL semantic away: **`glClear(GL_DEPTH_BUFFER_BIT)` honors +`glDepthMask`.** With the mask left false, the next frame's depth clear silently no-oped. +The depth buffer kept the previous frame's values, and every world fragment — terrain, +entities, the player, the sky — z-tested `GL_LESS` against its **own previous-frame +ghost** at virtually identical depths → never strictly closer → rejected. The screen +showed only the color clear, which is set to the fog color. Hence: whole world replaced +by fog-tinted clear. + +A second early-out of the same shape (`globalVao == 0`, after the SSBO uploads) could +leak identically; it was fixed in the same commit. + +This is the **4th instance** of the `feedback_render_self_contained_gl_state` bug class — +in the **same function** that carried the 1st (the U.4 blend/depth-mask establish was +itself the fix for instance #3; its early-out paths were the gap). + +## 2. Why the symptoms looked the way they did + +| Symptom | Mechanism | +|---|---| +| Onset frame-exact at the building-flood merge | The merge is the first frame the flooded building shell draws → first run of the empty Transparent pass → leak arms. | +| Strobes at onset | The flood flickers in/out at the boundary while the eye settles → alternating no-op / working depth clears. | +| HOLDS (one capture: 145,238 consecutive frames) | The leak re-arms every merged frame; the depth buffer stays stale indefinitely. | +| Camera rotation recovers instantly | The doorway clips out of view → cell drops from the flood → the leaking pass stops running → frame ends `dmask=1` → next clear works. | +| Whole world INCLUDING sky | Sky also depth-tests; old-sky pixels hold depth 1.0 and `1.0 < 1.0` fails `GL_LESS`. Everything dies uniformly. | +| "Parts of the screen flash while running past cottages" / cottage enter–exit artifacts | Same family: every brief merge = a 1-frame no-op depth clear. | +| The 9×21 px doorway scissor box in `[gl-state]` | Fingerprint only — `DrawRetailPViewCellParticles`' `BeginDoorwayScissor` leftover (test off, harmless). It marked "cell passes ran this frame", never the kill. | + +## 3. The evidence chain (one probe run decided it) + +The `[clip-route]` apparatus (`682cba3`, gate `ACDREAM_PROBE_CLIPROUTE=1`) instrumented +all three surviving suspects from the 2026-06-09 handoff in one repro run +(`flap-cliproute-capture.log`, user walk-through at the Holtburg south-slope anchor): + +- **`[clip-route]`** — outside slice slot + NDC AABB + planes, CellIdToSlot, region-SSBO + bytes decoded at the routed slot, terrain-UBO head as uploaded: **full-screen planes on + both sides of every merge transition** (slot repacks 2↔3 with correct content). Suspect + (b) UBO content — exonerated. +- **`[clip-route-disp]`** — per-slot instance histogram as staged for binding=3: all + 41,373 instances tracked the repacked outdoor slot exactly, `cullEnt=0` throughout. + Suspect (a) clip-slot routing — exonerated. +- **`[clip-route-scis]`** — actual GL scissor box for the landscape pass: full-screen the + entire run (printed once). Scissor — exonerated. +- **`[gl-state]`** — the answer: frames entered with `dmask=0 blend=1` for **exactly** the + merged stretches (armed at frame 239 ≈ the cottage shell finishing its streaming after + spawn-in, stable 145,238 frames through the held window, flipping in lockstep with each + end-of-run strobe/recover cycle). + +Draw inputs provably correct + fragments not landing ⇒ the GPU rejected them at the +depth test ⇒ the only anomaly (`dmask=0` entering frames) was the cause. Code reading +then pinned the exact early-out: `RenderModernMDIInternal`'s `totalDraws == 0` return +between the state-set and the restore. + +## 4. The fix (`c4df241`) — all paths root-cause + +1. **EnvCellRenderer:** the pass-state establish moved **below** the `totalDraws == 0` + early-out; the `globalVao == 0` check hoisted above the state-set. Mutated GL state is + now established only on a path that always reaches the end-of-pass restore — + set→restore is return-free. +2. **GameWindow frame clear:** asserts `glDepthMask(true)` immediately before the + `glClear` — the clear *depends on* the depth write mask, so per the project's + self-contained-GL-state rule it sets the state it consumes rather than inheriting it. + The `[gl-state]` tripwire still detects any future leak (blend etc.). + +## 5. Verification + +- Build green; 218 app-layer tests green (294+218+420 suite baseline unchanged). +- **Probe gate:** `flap-fix-gate-capture.log` (38,116 lines, same spawn-by-the-cottage + conditions): **zero** `dmask=0` `[gl-state]` frames — vs the broken run where the leak + armed by frame 239. Frames stay `dmask=1 blend=0` with the cottage shell drawing. +- **Visual gate (user, 2026-06-10):** forward walk through the trigger zone + running + past cottages — no strobe, no fog hold; "seems to work." + +## 6. What remains in §4 + apparatus inventory + +- **(2a) edge-on doorway grey** and **(2b) corner camera-seal** remain open as the §4 + siblings — **re-validate both against this fixed baseline first**: the no-op depth + clear may have inflated their apparent severity (any 1-frame merge during those repros + produced full-frame artifacts unrelated to their own mechanisms). +- Probes kept in-tree (env-gated, zero cost when off): + `ACDREAM_PROBE_CLIPROUTE` → `[clip-route]` / `[clip-route-disp]` / `[clip-route-scis]`; + `ACDREAM_PROBE_GLSTATE` → `[gl-state]` tripwire; `ACDREAM_PROBE_PVINPUT` → `[pv-input]`. + Strip once §4 (2a)/(2b) are resolved. +- Captures (worktree root, untracked): `flap-cliproute-capture.log` (the deciding run), + `flap-fix-gate-capture.log` (the verification run). + +## 7. Durable lessons (memory updated) + +- `feedback_render_self_contained_gl_state` — instance #4 recorded, with two new + corollaries: (a) GL-state ownership includes **exit paths** — establish mutated state + as late as possible, after every early-out; (b) **`glClear` is a state consumer** — + depth clears are gated by `glDepthMask`, so clear sites must assert the masks they + depend on. +- New symptom→cause mapping: *whole world drops to the clear color at an event boundary, + holds, recovers when the event stops* → leaked `DepthMask(false)` no-oping the frame + depth clear.