IG-SHADING-MODEL.md: document tonight's ground-truth findings for BT411

Extends the existing shading-model reference (already the established pattern
for this cross-check) with tonight's live-pod findings, explicitly framed for
the BT411 modernization team's consumption per the user's stated purpose for
this whole pipeline: a hardware-grounded source of truth where the software
renderer has open or hard-to-fix questions.

Added: a cross-reference index into BT411's context/ docs (rendering.md,
open-questions.md, combat-damage.md); the lit-color-plane finding (real
mechanism, confirmed values, wrong when used as a texture tint -- reverted
same session); fog (BT411's complete model, not yet ported here); and honest
open/uninvestigated status for HUD, weapon-fire rendering, and cockpit-cage,
each pointing at where BT411 has probably already solved the adjacent
question so it isn't re-derived from scratch.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

emulator/firmware-decomp/IG-SHADING-MODEL.md

@@ -137,3 +137,103 @@ firmware texmap→descriptor allocation and map the select word to an upload han
 texel-format misread (§3a). With SVT decode fixed, most arena surfaces are
 grayscale metal, so the frame reads correctly *despite* the placeholder binding;
 the binding now only mis-tints the handful of coloured decals. Much lower priority.
+
+**Escalation (2026-07-20, live-pod session):** with the reconstructed renderer
+running live behind the actual game (not just replaying a static capture), this
+binding gap became visually severe on **vehicles** ("trucks look like they were
+painted with skittles" — user report). Vehicles are exactly the ~150
+normal-bearing (LIT) BGF files that carry authored PAINT/decal materials
+(rendering.md §"Per-pilot mech PAINT" — warning-stripe/badge/patch layers), so a
+wrong-texture assignment here is far more visible than on a flat metal wall.
+**No longer low priority — this is the top open item for texture correctness.**
+Path forward (not yet done): live-instrument the firmware (we run the actual
+i860 code via emu860c, so we can WATCH memory writes during `set_texmap_texels`
+processing rather than guess from wire order) to find the real texid→handle
+table the firmware builds, instead of the `tid % len(texlist)` placeholder.
+
+---
+
+## 6. Purpose of this pipeline — hardware ground truth for BT411 (2026-07-20)
+
+This renderer's job is **not** to look good — it is to give the BT411
+modernization-port developers a hardware-grounded, independently-verified
+answer wherever the software renderer (`dpl3-revive`, the D3D9 port) has open
+or hard-to-fix questions. Where this doc and BT411's `context/rendering.md`
+overlap, treat agreement as cross-validation (two independent
+reconstructions — firmware-level here, decomp-level there — agreeing) and
+disagreement as a lead worth chasing on BOTH sides.
+
+**Cross-reference index (BT411 `context/`):**
+- `rendering.md` — the authoritative D3D9-port model: vertex-type shading
+  select (§1 above), material ramp (§2), fog (per-map/time/weather via
+  `BTDPL.INI`, per-pixel linear on W — NOT yet implemented in this renderer),
+  weapon beams (`ermlaser.bgf` TUBE geometry, muzzle-anchored, NOT a special
+  ray-trace primitive), mech skins (BSL bit-slice), per-pilot PAINT.
+- `open-questions.md` — living list of everything BT411 has NOT yet resolved;
+  check before re-deriving something they've already nailed down (or vice
+  versa: this firmware pipeline may resolve one of THEIR opens).
+- `combat-damage.md` — target acquisition (torso-boresight pick ray, auto-lock)
+  is RECONSTRUCTED and working in BT411's port; if our live session shows "no
+  weapon fire," suspect input/session state (fire button not reaching the
+  emulated RIO, or simply not fired yet this session) before suspecting a
+  missing render mechanism — the port's evidence is that firing itself works.
+
+### 6a. The lit-color plane (r24/g24/b24) — REAL, mechanism confirmed, exact use UNRESOLVED
+Verified live from the actual wire + firmware source (`sda4/DPL3/VRENDER/PXPL5SUP/`):
+- `DIVPXMAP.H` defines `dvpx_r24/g24/b24` (addr 117/125/133, 8 bits each) as
+  scan-conversion-time fields; `EOF.C` (lines ~1456, 1742) copies them
+  straight into `dvpx_eofr/g/b` (184/192/200 — the final screen color) via a
+  24-bit `IGC_CPY` in the simple (unfogged) case.
+- Confirmed present in the live per-draw coefficient program: `TREEclmpintoMEM`
+  (op 0x5a) at addr 118/126/134 (one bit off from the header's 117/125/133 —
+  this bytecode's own addressing, taken empirically), a 3-word instruction
+  whose 3rd word is a clamped float — REAL per-polygon values observed
+  (~49..395, not the same everywhere, roughly B > R > G — a genuine signal,
+  not noise).
+- **What's still open:** applying this as a flat-poly color (§ current
+  gpu_raster.py) is a reasonable, low-risk use since flat polys had no real
+  data before (a placeholder gray). Applying it as a TEXTURE TINT is WRONG
+  (§5 caveat: textures arrive pre-colourised) — tried live 2026-07-20,
+  reverted same session (commit 0527022e) after the user reported "more
+  colors but neither correct." The exact relationship between this
+  BOARD-INTERNAL scan-conversion value and BT411's GAME-LEVEL ramp/lighting
+  model (§1-2) is NOT yet established — they may be the SAME quantity
+  (the board-side result of the ramp/lighting the game already computed and
+  is now shipping per-polygon) or a DIFFERENT one (e.g. a fog term). Next
+  step: cross-check a KNOWN lit vs unlit polygon (from BT411's vertex-type
+  rule) against its r24/g24/b24 value to see if unlit polys show the
+  material ramp's actual endpoint colors.
+
+### 6b. Fog — NOT YET IMPLEMENTED in this renderer
+BT411 (`rendering.md` §Fog) has the complete, verified model: per-map/time/
+weather leaf in `content/BTDPL.INI` (`fog=<near> <far> <r> <g> <b>`), per-pixel
+LINEAR fog on perspective W (not the nonlinear z-buffer). This renderer already
+computes the per-pixel `tz` (perspective W-ish denominator) for every polygon
+(the M5 divide), so the mechanism to blend by depth already exists — what's
+missing is (a) reading the CURRENT mission's resolved BTDPL.INI fog leaf
+(map+time+weather → near/far/rgb) and (b) the blend itself
+(`out = mix(surface_color, fog_rgb, clamp((depth-near)/(far-near), 0, 1))`
+applied after texture/flat-color resolution). Not yet attempted.
+
+### 6c. HUD — not rendering at all, cause NOT YET INVESTIGATED
+No wire-level investigation done yet. BT411's `gauges-hud.md` /
+`cockpit-view.md` should be checked first for the mechanism (a separate
+draw pass? a different coordinate space/orthographic projection? a distinct
+wire action type?) before searching the firmware blind.
+
+### 6d. Weapon-fire rendering — not observed, cause NOT YET INVESTIGATED
+Per BT411 `rendering.md` §"Weapon beams": beams are ordinary TUBE geometry
+(`ermlaser.bgf`), muzzle-anchored every frame — i.e. on the wire this should
+look like ordinary create/list_add/draw_scene traffic for a thin, elongated
+object, NOT a special ray-trace primitive. Per `combat-damage.md`, the
+original game's fire/target-lock mechanism is fully reconstructed and working
+in BT411's port, so a live session showing no fire is more likely an input/
+session-state gap (RIO fire button not reaching this DOSBox session) than a
+missing render path — check that before assuming a rendering gap.
+
+### 6e. Cockpit cage — intermittent, NOT YET CROSS-CHECKED
+See `emulator/render-bridge/COCKPIT-CAGE-NOTES.md` (the OTHER renderer's
+findings: PUNCH-texel windows, CAGE_TWIST_SIGN calibration, GLANCE_DCS
+opt-in) and BT411's `cockpit-view.md` (the canopy stencil-cut kit, solved
+there). Not yet cross-checked against what this firmware pipeline receives
+on the wire for cockpit-frame geometry.