Gfx GX Fn GXInitTlutRegion - wowjinxy/libPorpoise GitHub Wiki

GXInitTlutRegion

  • Category: Texture
  • Matrix Status: Partial
  • Matrix Notes: SDK-style TLUT region register packing and input normalization are implemented (512B TMEM alignment + size clamping); TMEM hardware semantics remain approximate on PC backend.
  • Matrix Link: Gfx-GX-API-Matrix

Official SDK (Reference)

  • Manual page: reference/man/gfx/gx/Texture/GXInitTlutRegion.html
  • SDK source: reference/ACGC-PC-Port/src/static/dolphin/gx/GXTexture.c (GXInitTlutRegion)
  • SDK behavior:
    • Signature: void GXInitTlutRegion(GXTlutRegion* region, u32 tmem_addr, GXTlutSize tlut_size).
    • Requires tmem_addr aligned to 512 bytes.
    • Requires tlut_size <= 0x400 (16 KB max in 16-entry units).
    • Packs loadTlut1 register:
      • bits 0..9: (tmem_addr - 0x80000) >> 9
      • bits 10..20: tlut_size
      • bits 24..31: command tag 0x65

libPorpoise Implementation

  • Public API declaration: include/dolphin/gx/GXTexture.h
  • Runtime implementation: src/gx/pc_gx_texture.c (GXInitTlutRegion)
  • Behavior:
    • Signature now matches SDK type (GXTlutSize).
    • Fail-soft parity handling:
      • null region returns
      • tmem_addr masked to 512-byte alignment and clamped to valid TLUT TMEM window
      • tlut_size clamped to <= 0x400
    • Region layout:
      • r[0]: packed loadTlut1-equivalent word
      • r[1]: normalized tlut_size units (used by PC callback-side bounds checks)
      • r[2]: normalized raw TMEM address for diagnostics

SDK vs Porpoise Diff

  • Signature parity:
    • SDK: GXInitTlutRegion(GXTlutRegion*, u32, GXTlutSize)
    • Porpoise: same
  • Behavioral parity:
    • SDK: assert-validated alignment/range + packed register fields.
    • Porpoise: matching packed representation with fail-soft masking/clamping.
  • Known divergence:
    • PC backend does not emulate physical TMEM allocator conflicts/overlap behavior.
    • SDK CHECK_GXBEGIN assert behavior is not mirrored as hard-assert in PC runtime.

Validation Checklist

  • GX demo coverage checked
  • Pikmin usage path checked
  • Matrix status updated if needed
  • Notes updated with concrete file/function references

Working Notes

  • This pass aligns region encoding behavior without changing higher-level TLUT upload flow.