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-formats/src/gs.rs

@@ -180,6 +180,97 @@ impl BlendMode {
     }
 }
 
+/// GS TEX0_1, the texture-setup register, decoded from a level texture entry.
+///
+/// The GS stores a texture by *exponents*, not by dimensions: TW and TH hold
+/// `log2(width)` and `log2(height)`, which is why every retail texture in this
+/// game is a power of two -- **all 1,595 across the 27 levels, measured**. That
+/// is the measurand behind this struct: `tex0_of` returning a TW that is not an
+/// exact log2 would mean the entry was not a texture this register can address.
+///
+/// TBP0 is a **256-byte** block number, and it is relative to the start of the
+/// level's texture region, not to the level's data: **19 of the 27 levels have
+/// a `textures_base` that is only 64-byte aligned** (mod 256 reads 0, 64, 128
+/// or 192), so a `core_data`-relative base pointer would not be a whole number
+/// of blocks on those levels. Every entry's own `data_offset` *is* 256-aligned,
+/// which is what the region-relative reading requires -- the slots advance by
+/// `w*h + (w/2)*(h/2)` bytes, a multiple of 256 for every power-of-two
+/// dimension the game uses.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct TEX0 {
+    /// Texture base pointer, in 256-byte blocks.
+    pub tbp0: i32,
+    /// Texture buffer width, in 64-texel blocks.
+    pub tbw: i32,
+    /// Pixel storage method. Every level texture is 8-bit indexed, so this is
+    /// the same constant everywhere; it is a field rather than a constant
+    /// because a renderer that emulates the GS needs it in the register.
+    pub psm: i32,
+    /// `log2(width)`.
+    pub tw: i32,
+    /// `log2(height)`.
+    pub th: i32,
+}
+
+/// The one PSM this game's level textures use: 8-bit indices, texel-swizzled.
+pub const PSM_PSMT8: i32 = 0x14;
+
+/// Build TEX0 for a level texture entry.
+///
+/// `data_offset` is the entry's offset **within the texture region**. It is
+/// passed rather than the region's own base because the base pointer is
+/// region-relative -- see the note on [`TEX0`]. Returns `None` when the
+/// dimensions are not powers of two, or when the offset is not a whole
+/// 256-byte block, which are the two conditions this register cannot express.
+#[must_use]
+pub fn tex0_of(data_offset: i32, width: i16, height: i16) -> Option<TEX0> {
+    let tw = log2_exact(width)?;
+    let th = log2_exact(height)?;
+    // TBP0 is a 256-byte block count, so an unaligned base is not a base.
+    if data_offset < 0 || data_offset % 256 != 0 {
+        return None;
+    }
+    Some(TEX0 {
+        tbp0: data_offset / 256,
+        tbw: (width as i32) / 64,
+        psm: PSM_PSMT8,
+        tw,
+        th,
+    })
+}
+
+/// `log2(x)` when `x` is a power of two, else `None`.
+#[must_use]
+pub fn log2_exact(x: i16) -> Option<i32> {
+    if x <= 0 || (x & (x - 1)) != 0 {
+        return None;
+    }
+    Some(x.trailing_zeros() as i32)
+}
+
+/// Bytes one level-texture slot occupies: level 0 plus one mip level.
+///
+/// Measured over all 1,595 textures on the 27 levels: the stride between
+/// consecutive entries is `w*h + (w/2)*(h/2)` on every dimension class, where
+/// the classes are 32, 64, 128 and 256 square. The game stores the base image
+/// and one mip; `ty` reads 3 on all 1,595, so it is not the stored level count.
+#[must_use]
+pub fn texture_slot_bytes(width: i16, height: i16) -> i32 {
+    let w = width as i64;
+    let h = height as i64;
+    (w * h + (w / 2) * (h / 2)) as i32
+}
+
+/// The CLUT's byte offset in GS RAM: `palette * 0x100`.
+///
+/// The established reading (`gc_formats::texture`) is that the level texture's
+/// CLUT lives at exactly that address. Restated here because a GS emulator asks
+/// for it as TEXCLUT's CBP rather than as a lookup address.
+#[must_use]
+pub fn clut_base(palette: i16) -> i32 {
+    palette as i32 * 0x100
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -293,6 +384,40 @@ mod tests {
         );
     }
 
+    #[test]
+    fn tex0_needs_powers_of_two() {
+        let t = tex0_of(0, 128, 128).expect("128 is a power of two");
+        assert_eq!(t.tw, 7, "log2(128)");
+        assert_eq!(t.th, 7);
+        assert_eq!(t.tbw, 2, "128 texels is two 64-texel blocks");
+        assert_eq!(t.psm, PSM_PSMT8);
+        assert_eq!(t.tbp0, 0);
+        assert!(tex0_of(0, 96, 128).is_none(), "96 is not a power of two");
+    }
+
+    #[test]
+    fn tex0_base_pointer_is_256_byte_blocks() {
+        let t = tex0_of(512, 64, 64).expect("aligned");
+        assert_eq!(t.tbp0, 2, "512 bytes is two blocks");
+        assert_eq!(t.tbw, 1);
+        assert!(tex0_of(255, 64, 64).is_none(), "255 is not a block");
+    }
+
+    #[test]
+    fn texture_slots_carry_one_mip_level() {
+        // Measured strides: 32 -> 1280, 64 -> 5120, 128 -> 20480, 256 -> 81920.
+        assert_eq!(texture_slot_bytes(32, 32), 1280);
+        assert_eq!(texture_slot_bytes(64, 64), 5120);
+        assert_eq!(texture_slot_bytes(128, 128), 20480);
+        assert_eq!(texture_slot_bytes(256, 256), 81920);
+    }
+
+    #[test]
+    fn the_clut_base_is_the_texture_module_s_address() {
+        assert_eq!(clut_base(8), 2048);
+        assert_eq!(clut_base(0), 0);
+    }
+
     #[test]
     fn clamp_keeps_the_far_edge() {
         assert_eq!(clamp01(1.0), 1.0, "1.0 is the edge, not a wrap to 0");