# Division Renderer Collaboration Log

Shared working doc for the two renderer efforts against the VPX/Division
hardware interface:

- **In-process renderer** — GL HLE inside the DOSBox-X fork's VPX device
  (`src/src/hardware/vpxlog.cpp`, commit-copy `vpx-device/vpxlog.cpp`).
  Maintained by Cyd + Claude (this repo's sessions).
- **External renderer** — separate approach by the graphics developer +
  their Claude instance. *(Fill in your section below.)*

**How to use this file:** each session (human or Claude) reads it at start,
appends to its own section and the Log, and commits. Don't rewrite the other
team's sections — append questions/answers instead. Commit messages prefixed
`collab:` so both sides can `git log --grep=collab:` for changes.

---

## Ground-truth sources (in priority order)

1. `sda4/DPL3/LIBDPL/DPLTYPES.H` + `DPL.H` — the dVS/DPL node structs and API.
2. `sda4/DPL3/VRENDER/` — Division's own i860 renderer source (rasterizer
   semantics; the ramp/texture/light questions below should be settled here).
3. `ALPHA_1/REL410/BT/BTDPL.INI` — per-arena ground truth the game actually
   loads: `fog=start end r g b`, `light=r g b pitch yaw roll`, `ambient=`,
   `clip=`, `objectpath=` (arena content dirs), keyed by egg map/time/weather.
4. `restoration/` — WebGL re-render of the on-disk scene formats
   (`divformats.py` parsers, `gallery_template.html` shading model). Proven
   against 26 recovered scenes; its mesh shader is the reference shading
   model (see below).
5. Live wire captures: `VPXLOG=<file>` logs every port I/O; scratch tooling
   (`dump_nodes.py`-style parsers) has decoded node flushes from fifodumps.

## VPX board interface — verified on live captures

Register offsets (host side of the i860 board FIFO link):
`0` inputData (board→host), `1` outputData (host→board), `2` inputStatus
(bit0 = byte available), `3` outputStatus (always ready), `4/5` FIFO data
port link B low/high bytes, `16` resetRoot, `17` analyseRoot.

### Action codes (FIFO message stream)

| action | meaning |
|---|---|
| 1  | create `[type][name]` |
| 3  | flush `[name][type][struct]` — struct offsets below are into the payload `d`, where `d+8` = struct offset 0 |
| 7  | dcs_link `[parent][child]` — articulation tree |
| 9  | draw_scene — frame commit |
| 11 | list_add `[parent][child]` |
| 23 | set_geom_verts header `[name][0][n_verts][stride_floats]` + vertex bursts; stride 3..16 floats/vert: xyz, +uv at 3 (stride 5) or 6 (stride ≥8), +normal at 3 when stride ≥8 |
| 25 | set_geom_conns header `[name][n_polys][loop_len][0]` + index words (closing duplicate dropped) |
| 26 | texel upload header `[node][nbytes][w][h]` + texel bursts (4/8/16 bpp, bpp inferred from byte/texel ratio) |
| 31 | per-frame camera `[?][view][3x3 rows][eye]` |

### Node types (create/flush `type` field)

| type | node | verified layout (flush payload `d`) |
|---|---|---|
| 2  | zone | raw-logged only |
| 3  | view | win l/b/r/t/dist `d+24..40`, vw/vh `d+44/48`, near/far `d+52/56`, back_color `d+60..68`, **fog enable/mode `d+72`, near `d+76`, far `d+80`, rgb `d+84..92`** (mode 5 = linear; game ANIMATES fog and re-flushes ~27×; boot flushes carry heap garbage — sanity-check floats) |
| 4  | instance | object ref scanned at `d+8..` (resolves to a type-7 node) |
| 5  | dcs | 4×4 row-major at floats 4..19 (`d+16..`); row 3 = translation; world = local × parent (row-vector convention) |
| 6  | lmodel | raw-logged only |
| 7  | **object** (instance target in the scene-graph walker) — **CONFLICT:** the flush handler currently raw-dumps `t==7` as a *light* candidate ("t7 light=" lines in the tex log). Both can't be right; the real dpl_LIGHT wire type is still unidentified. Reconcile against DPLTYPES.H + a live dump. |
| 9  | geogroup | material ref at `d+64` |
| 11 | material | texture ref `d+8`, ramp ref `d+20`, emissive `d+24..32`, ambient `d+36..44`, diffuse `d+48..56`, opacity `d+60`, specular `d+72..80`, shininess `d+84` (84-byte struct; refs resolve lazily — a ref may precede its create) |
| 12 | dpl_TEXTURE params | texmap ref `d+8`, then minify/magnify/alpha/wrap_u/wrap_v/detail (u32s) + u0/v0/du/dv/anim_time (floats) + anim_bhv — logged (`t12` lines), **semantics not yet applied** |
| 13 | texmap header | texels ptr, u_size, v_size, bits_per_texel (+ hwareSize/hwareOffs/bilinear) |
| 14 | ramp | lo RGB `d+8..16`, hi RGB `d+20..28`; texels are intensities colorized through the material's ramp |

### Scene assembly & conventions

- Draw hierarchy: DCS (type 5) children (via list_add) → instance (4) →
  object (7) → **first LOD child** (host keeps active LOD at list head; the
  wire carries no switch distances) → geogroups (9) → geometry.
- World is **y-down** (DCS matrices carry reflections); Division screen x is
  mirrored vs GL eye x (flip x after projection).
- Vertices reach the renderer already in world space; the modelview holds
  only the camera (action 31: row-major world→eye rotation + eye pos,
  `eye_p = R·(p − e)`).
- Frustum from view win[]: `glFrustum(win[l/r/b/t] · near / win[4], …)`.
- **The camera only goes live after the first analog (throttle/stick)
  input** — until then the game submits no worklist and the screen is the
  back_color clear. Hands-off runs look like "solid sky"; check the radar
  head (win0 BMP dump) to confirm the mission actually loaded.

## In-process renderer — status (2026-07-04)

The device now runs the restoration gallery's shading model verbatim as a
GLSL 1.10 program (fixed-function fallback; stderr prints
`VPX render: gallery shading model active (GLSL)`):

```
acc = Σ_i lightCol_i · max(dot(N, −lightDir_i), 0)        (world space, 2 dir lights)
lit = mix(ramp.lo, ramp.hi, clamp(acc, 0, 1))
c   = (matAmb·sceneAmb + matDiff·lit) · tex + matEmis
out = mix(fogColor, c, max(clamp((fogEnd−d)/(fogEnd−fogStart), 0, 1), immune))
```

Interim until the light node is decoded: hardcoded sun + sceneAmb 0.45,
overridable via `VPX_AMBIENT="r,g,b"` / `VPX_SUN="r,g,b,pitch,yaw"` (deg,
y-down). Fog comes from the type-3 view flush. Opacity/specular parsed but
not applied. Polys without wire normals get Newell flat face normals.

**Ramp interpretation (open):** wire textures are intensity texels baked
through the material ramp at upload; the gallery applies the ramp to *light*
(disk textures are RGB). The device currently avoids double-application by
using an identity light-ramp on textured polys. VRENDER source should settle
whether Division ramps texels, light, or both.

## Data taps available to an external renderer (today)

- `VPXLOG=<path>` (host env): full port-I/O log incl. every FIFO byte —
  replayable; parse with the action/type tables above.
- `VPX_DUMPDIR=<dir>` + touch `<dir>/DUMP`: per-head BMP dumps (`win<g>.bmp`,
  g=0 radar, 3/4 MFD heads, 5-9 exploded singles).
- Device tex log: `t7`/`t12`/`t13` raw flush lines for undecoded nodes.
- `RIO_TAP=<path>`: serial wire tap (not renderer-relevant, but proves rig
  liveness).
- **Offer:** if a structured per-frame scene export (JSON/binary worklist
  after graph assembly, i.e. post-DCS world-space polys + materials) would
  feed your renderer better than raw FIFO, ask here — straightforward to add
  behind an env var.

## Open questions (either side, answer in place with date)

1. Real dpl_LIGHT wire type + layout (type 7 conflict above). BTDPL.INI
   `light=` lines give expected values to match against.
2. Type-12 texture param semantics (wrap/clamp/uv-window/animate) — cause of
   smeared wall textures?
3. Ramp on texel vs ramp on light (VRENDER).
4. Terrain + sky in arena missions: what content/nodes carry them? (Live
   arena1 renders structures but almost no ground; sky is back_color only.)
5. Opacity blending order/mode (glass cockpits, effects).
6. Scene ambient: which node carries it at runtime (lmodel type 6?).

## External renderer — approach & status

*(Yours — please fill in: approach, inputs consumed, what you need from the
device side, decisions taken. Append, date-stamp.)*

## Log

- **2026-07-04 (Claude, in-process side):** doc created. Gallery shading
  model ported into the device and verified live in arena1 (lit faces,
  plausible wire fog). Full material parse landed. Next in-process steps:
  light node decode, type-12 params, restoration-toolkit reference render of
  arena1 content.

- **2026-07-06 (Claude): actions 0x29/0x2b DECODED — the 2D HUD layer
  (dpl2d display lists).** The game draws its out-the-window HUD (targeting
  reticle, twist/pitch tick ladders, carets, weapon lamps, torso-twist dial)
  through DPL's 2D overlay API (`dpl2d_*`, see CODE/RP/MUNGA_L4/libDPL/dpl/
  DPL_2D.H + vpx/DPL2DTAG.H; game-side builder = L4VIDRND.CPP
  ReticleRenderable etc.), NOT as scene-graph instances.
  - `0x29` = dpl2d_NewDisplayList: `[remote handle][0]`, fire-and-forget.
  - `0x2b` = dpl2d_FlushDisplayList: the host streams the `dpl2d_DISPLAY`
    chunk structs verbatim (`remote, next, tail, size, open, data[30]`,
    WORDS_PER_DISPLAY_CHUNK=30 → the fixed 140B payload). First chunk:
    `remote`=handle, `tail`=total chunk count; continuations have remote=0.
    Data words CONCATENATE across chunks (tag args split freely at chunk
    boundaries); a flush REPLACES the list.
  - Data = tag stream per DPL2DTAG.H (0=open_polyline … 22=set_alpha).
    Arg words are float32 except call_displaylist (handle) and the
    circle/clip mode/filled flags. `open_lines` points come in PAIRS
    (independent segments); polygon = filled convex; matrix = 6-float 2D
    affine, state push/pop covers matrix+color+alpha+linewidth.
  - View binding (dpl2d_SetViewDisplayList) = one word appended after the
    96B view struct in full-length view flushes (wire-payload word 25).
    Root list in BT = a wrapper that calls the real HUD list; two sub-lists
    re-flush ~10 Hz (the live carets).
  - Coordinates are view-rect space (x0..x1/y0..y1 from the view struct,
    y up); colors 0..1, composited over the frame (board video-out mix).
  - Implemented in vrboard.py (`dl2d` store) + vrview.py/vrview_gl.py
    (overlay pass, both backends) — validated on a live BT mission capture:
    reticle centered, heading tape + yellow caret, pitch ladder, weapon
    lamps, twist dial all render. Open question 0x29/0x2b in the protocol
    spec §13 “fire-and-forget unknowns” can be closed.
  - Related negative result for subsystem debugging: in a 25-min live
    weapons-test capture the game emitted ZERO `0x23` fire/pick actions
    while all four trigger buttons were pressed repeatedly (RIO tap
    confirms delivery) — the fire path never reached the renderer; weapon
    triggers are dying game-side (control-mode/mapping or weapon power
    gating), not render-side.

- **2026-07-10 (Claude, in-process side): RED PLANET now runs the full pod +
  ONE OPEN RENDERER ITEM FOR DAVID.** RP 4.10 (RPL4OPT) now drives the whole
  cockpit through the same stack (shared MUNGA engine): networking, RIO, dual-
  AWE sound, plasma, and — as of today — the VDB cockpit gauges (radar + all
  4-quadrant MFDs, operator-verified). So the external renderer's live inputs
  now include RP content (Mars race tracks, `speck`/racer vehicles), not just
  BT. The RP gauge fix was NOT renderer-related (it was an SVGA bank-
  granularity mismatch in RP's L4GAUGE.INI, 4KB vs BT's 64KB, mishandled by
  DOSBox-X's CL-GD5434 bank emu — fixed by matching to 64KB; see VDB-NOTES.md).
  - **OPEN, renderer-side (Dave's domain):** RP's out-the-window view FLICKERS
    = Z-FIGHTING on the co-planar TRACK DECALS (checkered start/finish + road
    markings laid exactly on the track surface). BT mech-arenas don't have
    stacked co-planar surfaces so it never showed. Confirmed NOT frame-drops
    (bridge skipped=0) and NOT texture aliasing (mipmaps didn't fix) and NOT
    scene-graph churn (stable). Fix is a polygon DEPTH-OFFSET / small depth
    bias on the decal surfaces in the GL mesh draw. If your latest drop already
    added polyoffset or a decal path, great — flag it and we'll re-verify.
  - **Heads-up: local edits to vrview_gl.py you may collide with on a new
    drop** (all in this repo's dpl3-revive/patha copy): (a) `_tex()` gained
    `VRVIEW_MIPMAP=1` (build_mipmaps + trilinear/aniso, default OFF, keeps
    point-sample look otherwise) for RP's checkerboard-floor shimmer; (b) HUD
    shader got a `u_scale` uniform (`VRVIEW_HUDSCALE`) + the dpl2d Y-down flip;
    (c) fog moved per-FRAGMENT (v_fog varying + u_fog_on/u_fogrange in the FS)
    to stop terrain/cloud escaping fog. Merge points if your drop rewrites
    `_tex()` / HUD / fog shaders.
  - **Offer:** when your update lands, I'll diff it against our dpl3-revive/,
    reconcile the above, and re-verify live through the bridge on BOTH games
    (BT arena + RP race) so nothing regressed and we see if it fixed the RP
    z-fighting. Ping via a `collab:` commit or just drop the files.