Gfx GX Fn GXInitTexCacheRegion - wowjinxy/libPorpoise GitHub Wiki

GXInitTexCacheRegion

  • Category: Texture
  • Matrix Status: Partial
  • Matrix Notes: SDK-style cache-region packing/normalization is now implemented (alignment masking + size-domain mapping), while TMEM hardware semantics remain approximated on PC backend.
  • Matrix Link: Gfx-GX-API-Matrix

Official SDK (Reference)

  • Manual page: reference/man/gfx/gx/Texture/GXInitTexCacheRegion.html
  • SDK source: reference/ACGC-PC-Port/src/static/dolphin/gx/GXTexture.c (GXInitTexCacheRegion)
  • SDK behavior:
    • Signature: void GXInitTexCacheRegion(GXTexRegion* region, GXBool is_32b_mipmap, u32 tmem_even, GXTexCacheSize size_even, u32 tmem_odd, GXTexCacheSize size_odd).
    • Requires tmem_even and tmem_odd to be 32-byte aligned.
    • Accepts cache sizes:
      • even: GX_TEXCACHE_32K, GX_TEXCACHE_128K, GX_TEXCACHE_512K
      • odd: same + GX_TEXCACHE_NONE
    • Packs region state into internal image1/image2 words and sets cached flags (is32bMipmap, isCached).

libPorpoise Implementation

  • Public API declaration: include/dolphin/gx/GXTexture.h
  • Runtime implementation: src/gx/pc_gx_texture.c (GXInitTexCacheRegion)
  • Behavior:
    • Signature matches SDK.
    • Fail-soft parity handling added:
      • null region returns
      • tmem_even/tmem_odd are masked to 32-byte alignment
      • invalid size_even clamps to GX_TEXCACHE_32K
      • invalid size_odd clamps to GX_TEXCACHE_NONE
    • Region layout now mirrors SDK semantics in compact form:
      • r[0]: packed image1 (even cache register fields)
      • r[1]: packed image2 (odd cache register fields)
      • r[2]: is32bMipmap
      • r[3]: isCached
    • Normalized raw values are retained in r[4..7] for PC-side inspection/debugging.

SDK vs Porpoise Diff

  • Signature parity:
    • SDK: GXInitTexCacheRegion(..., GXBool, u32, GXTexCacheSize, u32, GXTexCacheSize)
    • Porpoise: same
  • Behavioral parity:
    • SDK: strict asserts on alignment/size-domain and packed region register setup.
    • Porpoise: same packed setup and domain mapping, implemented fail-soft (clamp/mask) instead of assert-fail.
  • Known divergence:
    • PC backend does not emulate real TMEM banking/overlap hazards; region data is compatibility state.
    • SDK CHECK_GXBEGIN assert behavior is not mirrored as a 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 focused on SDK field parity and input-domain handling without changing PC TMEM emulation scope.