goldeneye-pc-port/docs/dev/D176a-SKY-NOTES.md

# D176(a) Sky — consolidated research notes (read-only)

Companion to `GRAPHICS-BACKLOG.md` D176(a) and findings.md M-37/M-47.
Purpose: make the next implementation session mechanical. No code changed by
this doc.

## State of play

- **Root cause (M-37):** `skyRenderTri`/`skyRenderFull` emit geometry only as
  `G_RDPHALF_*` immediates; `gfx_pc.cpp:2901-2903` deliberately no-ops them
  (same in the PD port) → solid black sky on every cloud-sky level. Clean
  headless repro: `-level_22` (Statue), frame ~360.
- **M-47 draft (Path B)** — `scratchpad/sky.patch`: `#ifdef PORT` hooks in
  both functions re-emit the sky as ordinary screen-space GBI via
  `skyPortRenderPoly` (ortho pixel projection + `gSPVertex`/triangles).
  Geometry reaches GL and textures (top-half luma 0.1 → ~174 on `-level_22`).
  Two open defects (below). Draft, not shippable.
- **Path A** (decode RDPHALF in fast3d) is the backlog's original suggestion;
  the wire format is now fully decoded (next section), so it is a viable
  fallback if Path B's units can't be pinned.

## RDPHALF wire format (decoded from `src/game/sky.c` + `include/PR/gbi.h`)

- Opcodes (`gbi.h:102-164,216-223`): `G_RDPHALF_1 = 0xe1`,
  `G_RDPHALF_2 = 0xf1` (final word of a stream), `G_RDPHALF_CONT`
  (= `G_IMMFIRST-13`). Tri ops: `G_TRI_FILL 0xc8`, `G_TRI_FILL_ZBUFF 0xc9`,
  `G_TRI_SHADE_TXTR 0xce`, `G_TRI_SHADE_TXTR_ZBUFF 0xcf`.
- **All payload values are S15.1 fixed point** — converter is
  `sub_GAME_7F094298` (`sky.c:218`): `clamp(x, ±32767.9) × 65536`, u32.
- **Packing:** each `(G_RDPHALF_1, G_RDPHALF_CONT)` pair carries four
  halfwords = **two S15.1 values**: `valueA = (w1.hi16, w2.lo16)`,
  `valueB = (w1.lo16, w2.hi16)`. Multi-value groups are streamed in two
  passes — all high halves first, then all low halves (see the explicit
  `(x & 0xffff0000) | (y & 0xffff0000) >> 16` packing at `sky.c:1854-1870`).
- **`skyRenderTri` header** (`sky.c:1725-1728`): first word =
  `(op << 24) | (winding/sign flag bit23) | lo16(first value)`; the stream
  then carries screen-space positions (`unk28×0.25` = pixel X, `unk2c` = Y×4
  family) plus per-vertex attributes. The RSP ucode reassembles and DMAs a
  real edge-walked RDP tri command (per the M-46 comment in sky.patch).
- **Vertex attribute vectors are 8 components** (`sky.c:1759-1776`):
  `(r, g, b, a, S·w′, T·w′, 32767·w′, z)` with perspective weight
  `w′ = unk34 × min(unk0c)/2` — i.e. color + perspective-corrected S/T +
  depth. `SkyRelated38` fields: `unk28 = screenX×4`, `unk2c = screenY×4`,
  `unk30 = z (0..0x7fff)`, `unk34 = 1/w`, `unk20/unk24 = S/T`.
- GE emits RDPHALF **nowhere except sky.c** — the command surface is closed
  and small.

## Defect 1 — texcoord shear (clouds smeared into streaks)

`skyPortRenderPoly` uses `tc = unk20 × 32.0f` — a magic number.

### M-82 update — the scale is right, the magnitude is the bug

- **Cloud texture is `s_skywaterimages[0]` = `IMAGE_CLOUDS_GRAYSCALE`,
  `0x40 × 0x40` (64×64), `G_IM_FMT_IA` / `G_IM_SIZ_8b`, `G_TX_WRAP`/`G_TX_WRAP`**
  (`assets/oddtextures.c:646`). Not a fraction-indexed texture — it *tiles*.
- **GE's own screen-space textured-quad idiom is `tc = width << 5`**
  (`src/game/glass2.c:678,689` — `sImageTableEntry.width << 5` /
  `.height << 5`). `<< 5` = ×32 = the S10.5 texel fixed-point fast3d expects,
  and it divides `tc` by `tex_width` before GL_REPEAT. So the patch's `× 32.0f`
  **is the correct scale** — provided `unk20`/`unk24` are already in *texel*
  units (they are: the cloud-tiling math in `sub_GAME_7F097388` /
  `CloudRepeat(skyheight)=10000` produces texel coords in the thousands, and
  M-47 measured `unk20` reaching ±20 000 near the horizon).
- **The bug: `(s16)(20000 * 32)` overflows.** `Vtx.tc` is `s16` (±32767); a
  horizon vertex needs `tc` ≈ 640 000. It wraps/saturates → the streak.
- **Fix (no fast3d change, no grid needed for the near/mid sky):** phase-fold
  every vertex of *one primitive* by the **same** multiple of the tile period
  (64 texels), so inter-vertex deltas are preserved but magnitudes stay in
  s16 range:
  ```c
  s32 foldS = (s32)floorf(vmin_unk20 / 64.0f) * 64;   // vmin over this prim's verts
  s32 foldT = (s32)floorf(vmin_unk24 / 64.0f) * 64;
  tc[0] = (s16)((v[i]->unk20 - foldS) * 32.0f);
  tc[1] = (s16)((v[i]->unk24 - foldT) * 32.0f);
  ```
  This is exact wherever the S/T *span across a single triangle* is
  < ~1000 texels (s16 range ÷ 32). It holds for the corner-quad tessellation
  the current patch emits everywhere except triangles that straddle the
  horizon line, where the span diverges — those still need Defect-2's
  finer/adaptive tessellation. Land the fold first (fixes most of the frame),
  keep the grid as the horizon-band follow-up.

## Defect 2 — vertical coverage (band fills only top ~25%)

Leading hypothesis, from reading the N64 path: **the quad is not a plain
corner quad.** The N64 stream's four vertices are *perspective-interpolated*
points computed in the big interpolation block (`sky.c:1797-1813`, the
`sp210/sp290/sp2b0/sp230` vectors), not the raw TL/TR/BL/BR corners that
Path B's hook passes through. If those interpolated y-values differ from the
corner ys (they will, wherever w varies across the quad), the re-emitted
quad lands short.

Next steps (one focused session):
1. Per-call probe on `skyPortRenderPoly`: log nverts + each vertex's
   (x, y) + the tri op-header word; A/B against N64 reference footage of
   `-level_22`/`-level_36`.
2. If confirmed, either (a) replicate the interpolation block under PORT and
   emit the 4 computed vertices, or (b) drop to Path A with the decoder spec
   above (the ucode's own reassembly is then irrelevant — we decode the same
   values directly).

## Recommendation

Finish **Path B** first — geometry already works; both defects are unit/
vertex-set questions answerable in one render-iterate session. Keep Path A
as fallback; it is now fully specified by this doc if B stalls.

## Verification ask (M-82 — for the next session with a display)

The Defect-1 phase-fold is committed to PR #18 but **unverified visually**
(this session had no display). One check settles it:

1. `./build-pc/ge007.x86_64.exe -level_22` (Statue, night). At the intro the
   camera faces the horizon within a few seconds.
2. Look at the upper half of the frame:
   - **Black** → Path B still not emitting (regression from the rebase —
     check `skyPortRenderPoly` is reached; `GE_D176=1`).
   - **Clouds, but smeared into horizontal streaks** → the fold didn't take;
     re-check `unk20`/`unk24` really are texels (probe their range).
   - **Recognisable tiled cloud texture, correct near/mid, ragged or missing
     right at the horizon line** → fold works; that ragged band is Defect 2
     → adaptive tessellation is the next task.
   - **Looks right** → close Defect 1, mark PR #18 ready pending a
     `-level_36`/`-29`/Dam-exterior spot check.
3. A `GE_PCDUMP="330-390:30"` capture of that run attached to PR #18 is enough
   for a remote reviewer to make the same call.