The GS TEX0 register set, and why TBP0 is region-relative

Picking up "the GS register set the level load builds from the texture entry"
from level-assets.md, for a renderer that emulates the GS rather than resolving
texture addresses on the host.

gc_formats::gs gains tex0_of (TBP0, TBW, TW, TH, PSM), texture_slot_bytes and
clut_base. Three measurements back them, over all 27 levels and 1,595 textures.

Every dimension is a power of two: 1,595 textures, zero exceptions, in four
classes -- 128x128 (1,249), 64x64 (303), 256x256 (22), 32x32 (21). The GS
addresses textures by exponent, so TW and TH are log2 of the dimensions, and a
texture that was not a power of two could not be addressed at all. That the
whole population is one is the measurand for the decode.

TBP0 is region-relative. 19 of 27 levels have a textures_base only 64-byte
aligned -- mod 256 reads 0, 64, 128 or 192 -- while every entry's own
data_offset is 256-aligned on all 1,595. A base pointer computed from core_data
would therefore not be a whole number of 256-byte blocks on those levels. The
first version of tex0_of took textures_base + data_offset and rejected 1,168 of
1,595 textures for exactly this reason, which is how the finding surfaced.

The slot is level 0 plus one mip level: the stride between consecutive entries
is w*h + (w/2)*(h/2) on 1,560 of the 1,564 ascending gaps -- 32x32 gives 1,280,
64x64 gives 5,120, 128x128 gives 20,480, 256x256 gives 81,920. One byte per
texel. `ty` reads 3 on all 1,595, so it is not the stored level count.

Four gaps break the rule and four more run backwards. Both are reported as
bounded exceptions rather than folded into an average: the four ascending
outliers are 712,960 to 1,064,960 bytes, two orders of magnitude past any slot
the game allocates, so they are boundaries the slot rule does not describe
rather than slots that came out different. The four reverse gaps mean the table
is not sorted by data_offset, which a consumer walking the region in table order
would trip over.

The CLUT address is the established palette * 0x100, restated as clut_base
because a GS emulator asks for it as TEXCLUT's CBP.

Still open after this: TEXCLUT's own fields, MIPTBP1/2 wiring, and how the
ad-gifs' A+D values relate to this base.

Suite with the disc: 70 disc tests, 160 gc-formats, 22 gc-trace, 23
gc-engine, 19 gc-game. Clippy clean.

crates/gc-extract/tests/disc.rs

@@ -5051,6 +5051,163 @@ fn occ(hay: &[u8], needle: &[u8]) -> Vec<usize> {
         .collect()
 }
 
+/// Every level texture decodes to a GS TEX0 register.
+///
+/// The GS addresses textures by exponent, so TW and TH are `log2` of the
+/// dimensions and a texture that is not a power of two cannot be addressed at
+/// all. Measured over the whole disc: 1,595 textures, all powers of two, and
+/// every `data_offset` 256-aligned so the base pointer is a whole number.
+#[test]
+fn every_level_texture_decodes_to_a_gs_tex0() {
+    let Some(data) = extracted_root() else {
+        eprintln!("skipped: unpack the disc first");
+        return;
+    };
+    require_disc!();
+
+    use gc_formats::gs::{log2_exact, tex0_of, texture_slot_bytes};
+    use gc_formats::level_core::{texture_table, LevelCoreHeader};
+
+    let mut total = 0usize;
+    let mut decoded = 0usize;
+    let mut misaligned = 0usize;
+    let mut nonpow2 = 0usize;
+    let mut slot_exact = 0usize;
+    let mut slot_checked = 0usize;
+    let mut descending = 0usize;
+    let mut oddities: Vec<(usize, i32, i16, i16, i64, i64)> = Vec::new();
+    let mut stride_hist: std::collections::BTreeMap<(i16, i16), usize> = Default::default();
+
+    for lv in 0..27usize {
+        let Ok(idx) = std::fs::read(data.join(format!("level{lv}/core_index.bin"))) else {
+            continue;
+        };
+        let Ok(h) = LevelCoreHeader::parse(&idx) else {
+            continue;
+        };
+        let Ok(entries) = texture_table(&idx, h.tfrag_textures) else {
+            continue;
+        };
+        // The region's own base is deliberately unused: TBP0 is
+        // region-relative, and 19 of 27 levels are only 64-byte aligned at
+        // `core_data`, so a data-relative base pointer would not be a whole
+        // 256-byte block. Asserted below.
+        let _ = h.textures_base;
+        for (k, e) in entries.iter().enumerate() {
+            if e.width <= 0 || e.height <= 0 {
+                continue;
+            }
+            total += 1;
+            // The power-of-two requirement, stated before the decode.
+            if log2_exact(e.width).is_none() || log2_exact(e.height).is_none() {
+                nonpow2 += 1;
+                continue;
+            }
+            match tex0_of(e.data_offset, e.width, e.height) {
+                Some(t) => {
+                    decoded += 1;
+                    let expected_tbw = (e.width as i32) / 64;
+                    assert_eq!(
+                        t.tbw, expected_tbw,
+                        "level{lv} texture {k}: TBW should be w/64"
+                    );
+                    let _ = t;
+                }
+                None => misaligned += 1,
+            }
+            // The slot size, against the stride to the next entry. Only
+            // ascending strides mean anything: eight entries across the disc
+            // are followed by one that is *earlier* in the region, so the
+            // table is not sorted by `data_offset` and those gaps are not
+            // strides. They are counted, not silently skipped.
+            if k + 1 < entries.len() {
+                let d = entries[k + 1].data_offset as i64 - e.data_offset as i64;
+                if d > 0 {
+                    let want = texture_slot_bytes(e.width, e.height) as i64;
+                    slot_checked += 1;
+                    if d == want {
+                        slot_exact += 1;
+                    } else if oddities.len() < 12 {
+                        oddities.push((lv, e.data_offset, e.width, e.height, d, want));
+                    }
+                } else {
+                    descending += 1;
+                }
+            }
+            *stride_hist.entry((e.width, e.height)).or_default() += 1;
+        }
+    }
+
+    // The level's own `textures_base` is 64-byte aligned on most levels, which
+    // is why TBP0 is region-relative rather than data-relative: a base pointer
+    // taken from `core_data` would not be a whole 256-byte block there.
+    let mut aligned64 = 0usize;
+    let mut levels = 0usize;
+    for lv in 0..27usize {
+        let Ok(idx) = std::fs::read(data.join(format!("level{lv}/core_index.bin"))) else {
+            continue;
+        };
+        let Ok(h) = LevelCoreHeader::parse(&idx) else {
+            continue;
+        };
+        let Ok(entries) = texture_table(&idx, h.tfrag_textures) else {
+            continue;
+        };
+        if entries.first().is_none_or(|e| e.data_offset < 0) {
+            continue;
+        }
+        levels += 1;
+        if h.textures_base % 256 != 0 {
+            aligned64 += 1;
+        }
+    }
+    assert!(
+        levels >= 20,
+        "expected most levels to carry textures, got {levels}"
+    );
+    assert!(
+        aligned64 * 2 > levels,
+        "the majority of levels should be unaligned at 256, which is why TBP0 is region-relative: \
+         {aligned64} of {levels}"
+    );
+
+    // Bounds: 1,595 textures, 0 non-power-of-two, 0 unaligned.
+    assert_eq!(total, 1_595, "the disc's level texture count");
+    assert_eq!(nonpow2, 0, "every dimension should be a power of two");
+    assert_eq!(decoded, total, "every texture should decode");
+    assert_eq!(
+        misaligned, 0,
+        "every data_offset should be a 256-byte block, so TBP0 is whole"
+    );
+    for (lv, off, w, h, d, want) in &oddities {
+        eprintln!("  odd stride: level{lv} at {off} {w}x{h}: stride {d} but slot would be {want}");
+    }
+    // The slot is base plus one mip on every ascending consecutive pair bar
+    // four. Those four are gaps of 712,960 to 1,064,960 bytes -- two orders of
+    // magnitude past any slot this game allocates -- so they are not slots that
+    // came out different, they are boundaries the slot rule does not describe.
+    // Reported as a bounded exception rather than folded into an average.
+    assert_eq!(
+        slot_exact + oddities.len(),
+        slot_checked,
+        "every ascending stride should be either a slot or one of the four boundaries"
+    );
+    assert!(
+        oddities.len() <= 4,
+        "more than four non-slot gaps appeared: {:?}",
+        oddities
+    );
+    assert_eq!(
+        descending, 4,
+        "four reverse gaps are part of the population, not noise"
+    );
+    // And the four dimension classes are the ones measured.
+    assert!(
+        stride_hist.contains_key(&(128, 128)) && stride_hist.contains_key(&(64, 64)),
+        "the dominant classes should be 128 and 64 square"
+    );
+}
+
 /// The tfrag's clip cube lives at `+0x38`, and `+0x2e` is the mini-sphere
 /// array.
 ///