goldeneye-pc-port/docs/dev/TEXTURE-GLITCH-ANALYSIS.md

# Texture Glitch Analysis — PC Port

**Original diagnosis:** 2026-08-29 (read-only) · **Status table refreshed:** 2026-08-31 (M-31)
Companion artifacts: `<local-path>` (outside repo).

---

## 0. Current status (M-31) — READ THIS FIRST

> **M-33 overlay (D168):** every `GE_PCDUMP` / F12 screenshot this doc's
> analysis relied on was **vertically flipped** — the PPM writer never reversed
> `glReadPixels` rows. This is what the D114/D116 "HUD/text X-mirror" finding
> actually was (now closed, not a bug). It also contaminates the **RC1** row
> below: the wallet-Bond photo's "180°-rotated / mis-transformed" description
> was made from an upside-down capture, so at least the vertical component is
> the capture bug, not the model transform. Re-judge RC1 from a fresh
> right-way-up capture before doing any more work on it. Writer fixed
> (`port/fast3d/gfx_opengl.cpp`).

The 2026-08-29 body below is the original diagnosis. Several root causes have
since been fixed or retracted. Authoritative current state:

| RC / bug | 2026-08-29 verdict | Current status (M-31) | Where |
|---|---|---|---|
| **RC2** — mip-chain contamination (LOD rows uploaded as image rows) | open | **FIXED** — `import_texture()` clips a full-width LOD block to the SETTILESIZE base height; GL builds correct mips. Knob `Video.FixMipTextures` (**default on**; `=0` = old byte-identical-to-golden behaviour). | `port/fast3d/gfx_pc.cpp`; §F RC2 |
| **RC4** — palette "off-by-one" in `palette_to_rgba32` | proposed 1-line fix | **RETRACTED** — the current decode is correct **RGBA5551**; the "spec" line in §2 was ARGB1555. Applying the "fix" rotates every channel + moves alpha. **Do not touch.** | `gfx_pc.cpp:~835`; §2 RC4, §F |
| **D159** ("interlaced" / venetian-blind textures, esp. front-end photos) | not yet identified | **FIXED** — `texSwapAltRowBytes` (N64 RDP odd-line TMEM XOR compensation, which fast3d does not emulate) is a `#ifdef PORT` no-op. This was the user's "interlaced textures" report. | `src/game/image.c`; §F D159 |
| **D161** — Depot (`-level_30`) ceiling blue speckle + radial rays (was §3 "blue ground" / B2) | attributed to RC2+RC3+RC4+fog | **FIXED** — a 16×16 **CI8 tile drawn with `G_TT_NONE`** (TLUT disabled) was palette-looked-up against a stale `rdp.palette`. fast3d now routes CI+`G_TT_NONE` → I (intensity). Not RC2/RC3/RC4/filtering. | `port/fast3d/gfx_pc.cpp import_texture()`; §F D161, porting-notes.md §D |
| **RC1** — wallet-Bond photo (mode-select / folder screen) garble | "implement G_SETTEX" | **PARTIALLY OPEN.** The *interlace comb* is gone (D159). The photo now renders as a recognisable grayscale portrait but is still **180°-rotated / mis-transformed** → **D75 front-end-model family** (model-GDL transform, not a fast3d opcode gap — `texLoadFromGdl` already expands G_SETTEX on PC, see §6b). Parked, cosmetic, below crash work. | §6b; GRAPHICS-BACKLOG D149; §F D75/D80/D82/D83 |
| **RC3** — wrap-period mismatch (non-PoT dims "repeat oddly") | open | **IN PROGRESS.** The dead D74 pre-wrap block is now opt-in as `Video.WrapFix` (M-29, **not default** — the naive one-liner activates never-run code and boot-crashes `-level_09`; needs the hoist-out-of-vertex-loop rework + per-level visual check). | `gfx_pc.cpp`; GRAPHICS-BACKLOG B1; §F D74 |
| RC1 (original) — G_SETTEX (0xc0) is `G_NOOP` in fast3d | "implement the command" | **NOT the blocker.** `src/game/tex.c texLoadFromGdl` already expands every G_SETTEX into a standard load sequence under `#ifdef PORT`; fast3d normally never sees raw 0xc0. See §6b. | §6b |

Everything from `## 1.` down is the original 2026-08-29 text, left intact for
the reasoning trail. Cross-check any "open / pending / proposed" wording there
against this table.

## 1. Reported symptoms

1. **In general:** textures repeat oddly with weird artifacting.
2. **Depot (`-level_30`):** loads "completely wrong" textures — the ground is drawn a
   glitched **blue** that is not right (visible in attract mode).
3. **Character models:** obvious texture artifacts during the credits roll.

## 2. Root causes (confirmed by code + ROM evidence)

> **M-31 status overlay** (see §0): RC2 **FIXED** (`Video.FixMipTextures`), RC4 **RETRACTED**,
> RC1 superseded — the "interlaced" symptom was **D159** (`texSwapAltRowBytes`), now **FIXED**;
> the Depot "blue ground" was **D161** (CI8 + `G_TT_NONE`), now **FIXED**. RC3 in progress
> (`Video.WrapFix`, opt-in). RC1 residual = 180°-rotated front-end photo = D75 family, open.

| # | Cause | Location | Explains | Fix class |
|---|-------|----------|----------|-----------|
| RC1 | `G_SETTEX` (0xc0) is a **no-op** in fast3d | `port/fast3d/gfx_pc.cpp:2443` (`case G_NOOP`) | #3 character/model artifacts | ~~implement the command~~ — **not the blocker**: `texLoadFromGdl` already expands it on PC (§6b); residual = D75 model transform |
| RC2 | **Mip-chain contamination**: base + all LODs uploaded as one GL image | `src/game/tex.c:330` (`texGetDepthAndSize` sums all LODs) → `gfx_dp_load_block`/`import_texture_*` | #1, #2 noise bands, wrong scale, minification garbage | **FIXED** — clip LOD block to base-tile height; `Video.FixMipTextures` default on |
| RC3 | **Wrong wrap period**: N64 wraps at `2^ceil(log2(dim))`, GL wraps at uploaded image size; D74 pre-wrap block is dead (`G_TX_WRAP == 0`, `include/PR/gbi.h:391`) | `port/fast3d/gfx_pc.cpp` UV math in `gfx_sp_tri1` + D74 guard | #1 "repeats oddly", squash/stretch on non-PoT dims | **DONE (D167), behind `Video.WrapFix` default OFF** — mask-based wrap period in the hoisted pre-wrap block; needs a human eyeball on Depot before default-on. See §6d |
| RC4 | ~~**Palette off-by-one** in `palette_to_rgba32`~~ — **RETRACTED (M-30)**: current decode is correct RGBA5551 | `port/fast3d/gfx_pc.cpp:835` | nothing — the "spec" line was ARGB1555 | **do not change** |

### RC1 — G_SETTEX no-op (character artifacts)

- GE's `gbi_extension.h` defines opcode 0xc0 as `G_SETTEX` (`gsSPUseTexture`):
  `w0[3:0]=type, [9:6]=shiftt, [13:10]=shifts, [17:16]=tile, [19:18]=cmt, [21:20]=cms`;
  `w1 = minlevel<<24 | detail_id<<12 | texture_id`.
- **Full ROM scan: 508 of 512 model files contain G_SETTEX — 43,314 commands total**
  (top emitters: `PwalletbondZ` 2830, `CbaronsamediZ` 976, `GautoshotZ` 975).
- Worked example `CheadbrosnanZ`: 47 G_SETTEX commands; texture_ids (1624–1626 = 32×64,
  1607 = 64×32, 1608 = 1×1 null) exactly match the model's `Textures[]` table; the GDL
  interleaves them per mesh part. All use tile=2 (`G_TX_RENDERTILE`).
- On N64, gmain.s dispatches 0xc0 via the jump table at offset 0xbc (top-2-bits bucket 3);
  it rebinds the render tile to the texture identified by `texture_id`.
- Our fast3d hits `case G_NOOP: break;` — **every mesh part renders with stale tile state**
  → wrong/shifted textures on characters. This is why the credits roll (many models, many
  texture switches) shows obvious artifacts.
- The in-code comment at `gfx_pc.cpp:2443` ("the game never emits it") is **wrong for GE** —
  presumably inherited from PD assumptions. The PD port also no-ops 0xc0, so there is no
  reference implementation to copy; implement from gmain.s + gbi_extension.h.

### RC2 — Mip-chain contamination (floor/room noise)

- `texGetDepthAndSize()` (`src/game/tex.c:330`) sums **all** LOD levels, so one
  `gDPLoadBlock` carries base + full mip chain. fast3d uploads that as a single GL image:
  a 65×65 floor texture becomes ~65×134, rows below the base being raw mip bytes.
- GL then wraps at the *uploaded* size and `glGenerateMipmap` + the never-disabled
  `GL_LINEAR_MIPMAP_LINEAR` min-filter (`gfx_opengl.cpp:59`) sample **mips of a
  garbage-stacked image**. Distant surfaces (attract-mode camera!) minify into noise.
- ~75% of Depot's textures carry full mip chains (lod 6–7), so this is maximal there.
- N64 per-LOD tile selection is already emulated by the D107 rule (always base tile,
  offset 0) — GL mips are pure poison in this port; disable them.

### RC3 — Wrap period mismatch ("repeats oddly")

- N64 wraps at the tile mask period `2^ceil(log2(dim))` (`texDimensionToMask`,
  `src/game/tex.c:361`). GL `GL_REPEAT` wraps at actual image size.
- Depot's large room surfaces are **non-power-of-two**: 65×65, 56×56, 96×48, 128×32
  (I4/IA4, non-zlib). E.g. 65 wide: N64 period 128 vs GL period 65 → pattern squashed 2×
  horizontally; with RC2 the vertical period is ~2× too long and half of it is noise.
- The D74 pre-wrap UV block never runs: guard tests `cms & G_TX_WRAP` but
  `G_TX_WRAP == 0` (`include/PR/gbi.h:391`) — dead code (already parked in
  `docs/dev/GRAPHICS-BACKLOG.md`).

### RC4 — Palette off-by-one — **RETRACTED (M-30): the current code is correct.**

The "N64 RGBA16 spec" line below is **ARGB1555**, which is *not* what the N64 uses.
N64 `G_IM_FMT_RGBA` / `G_IM_SIZ_16b` is **RGBA5551**: `RRRRR GGGGG BBBBB A`
(R = bits 15-11, G = 10-6, B = 5-1, A = bit 0).

```c
// fast3d (current, CORRECT): r = v>>11; g = (v>>6)&0x1f; b = (v>>1)&0x1f; a = v&1
// the "spec" line here was wrong: r = (v>>10)&0x1f; g = (v>>5)&0x1f; b = v&0x1f; a = v>>15
```

Both `palette_to_rgba32` (`gfx_pc.cpp:~835`) and `import_texture_rgba16`
(`~651`) use the same RGBA5551 decode and agree with each other. The palette is
`PD_BE16`-swapped at load (`gfx_dp_load_tlut`), so `palentry` is already
correctly ordered. **Applying the "fix" would rotate every channel and move
alpha to the wrong bit — do not do it.** If a hue problem is ever confirmed
in-game, it is upstream (TLUT byte order at the converter, or a wrong
`rdp.palette_fmt`), not this function.

## 3. Depot-specific analysis ("why blue ground, only there?")

**Depot is not special — it is the worst case of RC2+RC3+RC4.**

- **Ruled out with data:**
  - *Texpool exhaustion / D85 placeholder path:* a real Depot load (env-gated log) shows
    342 unique texture loads, ~326 KB compressed into the 450 KB stage pool, **zero**
    `D85TEX pool-full` events. The floor is not sampling a garbage pointer.
  - *Broken decompression:* `texInflateZlib`/`texInflateNonZlib` are faithful decompilations;
    the format was independently re-derived offline (§4) and decodes byte-exact.
- **What Depot's floor actually is** (decoded from ROM): non-zlib **I4/IA4 grayscale with
  full 7-level mip chains and non-PoT dimensions** (texnums incl. 85/86, 508, 618, 631,
  779–782, 836, 909–911, 989–996). Exactly the class RC2+RC3 mangle hardest.
- **The blue:** nothing in Depot's texture set is actually blue (decoded color stats are all
  industrial grays/browns, e.g. avg rgb 107/107/108, 147/117/112). The perceived blue =
  garbage I4 values sampled under minification (attract camera is far → mip-filtered noise)
  + Depot's fog table (`src/game/bgfog.c`, LEVELID_DEPOT entry) tinting distant surfaces
  cold. RC4 then shifts whatever hue survives.
- BUNKER1 "renders recognisably" because its surfaces hit the same bugs less severely
  (PoT dims / fewer visible garbage rows at typical camera distances).

## 4. Texture pipeline reference (learned during this investigation)

Useful ground truth for whoever implements the fixes:

- **ROM layout:** `g_Textures[N]` = segment offset; texture N occupies
  `[g_Textures[N], g_Textures[N+1])` in the images segment (`_imagesSegmentRomStart`,
  ROM file offset 0x8F7DF0 in the NTSC dump). `assets/images.def` cumulative sizes match the
  logged runtime offsets **exactly (0/342 mismatch)** — verified against the D66 log.
- `texLoad` (`src/game/image.c:~2450`) copies from `(thisoffset & ~15)` and re-points
  `compptr += (thisoffset & 7)`; empirically every blob decodes at the listed offset (+0).
- **Blob header byte:** `u(1) z(1) lod(6)`. `z=1` → zlib path, else per-image
  format(4)/w(8)/h(8)/comp(4) + Huffman/RLE/lookup payloads.
- **Zlib path** (`texInflateZlib`, `image.c:169`): MSB-first bitstream —
  format(8), numcolours(8)+1, palette nc×16; per image: width(8), height(8), then a
  **rarezip stream = 2-byte header `0x11 0x72` + raw deflate** (GE's `src/game/zlib.c` is
  stock gzip-1.2.4 inflate). Output rows are stored **tight**; `texAlignIndices`
  (`image.c:340`) repacks to 8-byte-aligned rows (CI8: 1 B/px; CI4: 1 B/2 px, high nibble
  first).
- **`texSwapAltRowBytes`** (`image.c:2191`) is applied to **every level of every texture on
  every code path** (calls at 260, 300, 312, 316): odd rows get adjacent u32 groups pairwise
  swapped. The post-swap RAM buffer is what gets uploaded — any offline tool or dump must
  account for this.
- Palette is appended to the buffer big-endian after all images; `G_LOADTLUT` uploads it.
- `u=0` + lod≥2: mips are generated at load by `texShrinkPaletted` (2×2 palette average).

## 5. Open questions / hypotheses

- **H-A (high confidence):** Depot blue ground = RC2+RC3+RC4+fog, per §3. Confirm in-game
  after fixes; the before/after capture is the test.
- **H-B (high confidence):** credits-roll model artifacts = RC1. Confirm by implementing
  G_SETTEX and re-capturing the roll.
- **H-C (unresolved, non-blocking):** the offline contact sheet "still looks off" to the
  reviewer despite stage-by-stage verification of the decoder (§4; exact byte-count matches,
  verbatim function copies, clean odd/even row-boundary statistics). Possible explanations:
  32×32 CI8 textures are inherently noisy at native res; small-cell presentation; or a
  residual misunderstanding of the final layout. Fallback if it ever matters: a standalone C
  harness running GE's actual `texInflateZlib` on the ROM, byte-diffed against the Python
  decoder. **Not on the critical path** — the in-game fixes don't depend on it.

## 6. Fix plan — ORIGINAL (2026-08-29); see §0 for what actually shipped

> **M-31 outcome:** item 2 (mip) shipped as `Video.FixMipTextures`; item 4 (palette)
> retracted; the "interlace" was `texSwapAltRowBytes` not on this list (D159, fixed);
> the Depot roof was CI8+`G_TT_NONE` not this list (D161, fixed); item 5 (dump hook)
> shipped as `GE_DTEX` + `GE_TEXDUMP`. Items 1 (G_SETTEX) and 3 (wrap) not done as
> written — see §0 / §6b.

1. **G_SETTEX** (`gfx_pc.cpp` dispatch): rebind render tile to the texpool entry for
   `texture_id` per gmain.s semantics. Biggest single visual win (characters).
2. **Mip contamination:** upload base level only in `gfx_dp_load_block`/`import_texture_*`;
   drop `glGenerateMipmap` and the `MIPMAP_LINEAR` min-filter default. Fixes Depot floor noise.
3. **Wrap period:** wrap at the N64 mask period (`texDimensionToMask`) — fix the dead D74
   guard (`cms == G_TX_WRAP`), extend to the T axis and non-PoT dims.
4. **Palette off-by-one** (`gfx_pc.cpp:835`): one-line-class fix per channel.
5. **Verification hook:** env-gated dump of the actual uploaded GL image + tile setup for
   the first N texLoads (~10 lines in fast3d) → one Depot run gives true ground truth and a
   before/after reference (also settles H-C if it ever resurfaces).

Each item gets its own Dxx entry in `docs/internals.md` §F/§H at commit time
(proposed: next free labels after D126 — check the §F index first; a stray "D160" appears
once in the doc and may need reconciling).

## 6b. M-30 follow-up — implementation notes (before you touch RC2)

Re-checked against the current tree while chasing the user's "interlaced
textures" screenshot (`screenshots/interlaced texture example.jpg` — main menu,
wallet-Bond photo + right panel show alternating-row tearing).

- **RC1 (G_SETTEX) is not a simple `case` add.** `src/game/tex.c texLoadFromGdl`
  already *expands* every G_SETTEX (opcode 0xc0 == `G_NOOP` slot) in a model GDL
  into a full standard load sequence (`texLoadFromTextureNum` + `texFindInPool` +
  `texWriteTextureCmd`) written into a replacement GDL, and
  `src/game/objecthandler_2.c` (`~line 82`) drives that per display list at model
  load + `modelNodeReplaceGdl`s the node. It **is** `#ifdef PORT`-ported. So on PC
  the RSP/fast3d should normally *not* see raw G_SETTEX. The user's crash log
  showed fast3d walking into `0xfafbfbfc…` garbage (opcode 0x00, **not** 0xc0) —
  i.e. the model GDL pointer / expansion is broken for the front-end wallet
  models, not "an opcode is missing." This is the **D75 front-end-model family**
  (D80/D82/D83 model-GDL relocation, `objecthandler_2.c`), not a fast3d opcode
  gap. Implementing G_SETTEX in fast3d would be a fallback that only helps models
  that reach it with an otherwise-intact DL.
- **RC2 (mip contamination) — the naive height clamp was already tried and
  reverted.** `gfx_pc.cpp import_texture()` ~line 917 has a comment: a prior
  branch that set height = `line * tile.height` was removed because it "dropped
  mip chains" and "truncated sub-tiled textures" (Rare-logo `D_02005FF0` 20×3
  tile uploaded as 32×3). So the fix must distinguish "extra rows are mip levels"
  (drop) from "tile is a window into a larger image" (keep). The signal is
  `rdp.tex_lod` (passed to every `import_texture_*` as `gen_mipmaps`): when LOD is
  on and `size_bytes/row > tile_height`, the excess is mip data → clamp height to
  `((lrt-ult)>>2)+1` from `rdp.texture_tile[tile]` **and** pass `gen_mipmaps=false`
  (don't let GL build mips from the stacked image). When `rdp.tex_lod` is off,
  keep today's behaviour. Verify against the Rare logo (sub-tile case) + Depot
  floor (mip case) + BUNKER1 (regression).
- **The alternating-row look specifically** may also be `texSwapAltRowBytes`
  (`image.c:2191`, §4: applied to *every* level of *every* texture on *every*
  path — odd rows get adjacent u32 groups pairwise swapped). The game swaps the
  RAM buffer *before* upload, so fast3d should read the swapped bytes — confirm
  fast3d isn't reading a pre-swap copy, or double-swapping. This is the
  RenderDoc / §6-item-5 dump task; do that before editing.

**Bottom line (M-30):** #3 is not a grind-fix. Highest-leverage next step is
§6-item-5 (env-gated dump of the actual uploaded GL image + tile setup for the
first ~10 texLoads on the main menu and on Depot) to see whether the base image
is wrong (decode/swap) or just over-tall (RC2 height). Then RC2 per the
`rdp.tex_lod`-gated plan above. G_SETTEX / D75 front-end models are a separate,
larger track.

## 6c. B2 Depot ceiling — ROOT-CAUSED + FIXED (D161, M-31)

The blue-speckle + radial-ray roof was **not** RC2/RC3/RC4/filtering. `GE_TEXDUMP`
(PPM dump of every uploaded texture + a `fmt/siz/palfmt/palidx/pal[0..3]` log
line, both env-gated, in `gfx_pc.cpp`/`gfx_opengl.cpp`) identified the surface as
**one 16×16 CI8 texture uploaded with `rdp.palette_fmt == G_TT_NONE`** — every
other CI texture that frame had `palfmt == 0x8000` (RGBA16). GE draws the Depot
roof with `gsDPSetTextureLUT(G_TT_NONE)`: a CI-siz tile with the TLUT disabled is
a legit N64 idiom meaning "use the raw 8-bit texel as intensity" (≈ I8).
`import_texture()` ignored `palette_fmt` for `fmt==CI` and did a palette lookup
against a **stale `rdp.palette`** → 16×16 of blue/magenta noise; the "rays" were
that noise aliasing on the receding ceiling plane (hence filtering never helped).

**Fix:** `gfx_pc.cpp import_texture()` — `fmt_eff = (fmt==CI && palette_fmt==
G_TT_NONE) ? I : fmt`, dispatch on `fmt_eff` (CI4→I4, CI8→I8). Narrow (only
touches currently-garbage surfaces). Depot corridor + control-room ceilings now
render as clean dark/grey industrial roofs; `-level_09/-30/-34` sweep PASS.
Full write-up: §F D161.

## 6d. RC3 non-PoT wrap period — IMPLEMENTED (D167, M-31), default OFF

`gfx_dp_set_tile` now stores `masks`/`maskt` on the tile (was dropped). The
hoisted per-texunit pre-wrap block in `gfx_sp_tri1` (the reworked D74 block —
already lifted out of the vertex loop at M-30, indexed by texunit `t`) gained a
branch: when the render tile is WRAP (no CLAMP/MIRROR) and `1<<mask != tex_width`,
fold the UV at the N64 period `1<<mask`, then clamp the `[dim, 1<<mask)` overflow
band (no real texels — a TMEM smear on console) to the last texel. All behind the
existing `Video.WrapFix` knob (`GE_WRAPFIX` env overrides it for testing).

**Captures** (`-level_09/-30/-34/-20`, WrapFix OFF vs ON, `GE_PCDUMP` 6-frame
windows): no crashes, 6/6 frames each; Silo ~pixel-identical (phash 0–11),
Facility 180–260 pixel-identical, Depot shows small localized texel changes on
ceiling/wall cells (dmean 5–9, no structural break). Large per-run frame deltas
are all D117 intro-camera-pan nondeterminism.

**Default kept OFF** — no regression, but a headless structural diff can't confirm
the Depot ceiling looks *better*. To finish RC3: run Depot with `Video.WrapFix=1`
and eyeball the corrugated roof / repeating wall panels vs default; flip the
default in `port/src/video.c` (`cfgWrapFix = 1`) if clean. The overflow-band clamp
is an approximation of console TMEM-smear behaviour, not an exact emulation.

## 7. Artifacts (in `<local-path>`, outside repo)

| File | What it is |
|------|-----------|
| `depot_d85.log` | Full Depot run with `GE_D63=1 GE_D85TEX=1` — 342 texLoad records (texnum/thisoff/nextoff/size), zero pool-full events |
| `decode_depot_tex.py` | Offline rarezip/bitstream decoder (verified against §4) |
| `depot_texsheet.png` | Contact sheet, 342 tiles, labeled by texnum (zlib-decoded only; non-zlib I4/IA4 cells blank) |
| `depot_texstats.txt` | Per-texture format/size/lod/color stats for all 342 |
| `tiles_big.png`, `tile_*.png` | Individual full-size decodes (760, 313, 1283, 233, 1082, 21, 451, 7) |