Gfx GX Fn GXInitTexPreLoadRegion - wowjinxy/libPorpoise GitHub Wiki

GXInitTexPreLoadRegion

  • Category: Texture
  • Matrix Status: Partial
  • Matrix Notes: SDK-style preload-region packing/metadata is now implemented (aligned TMEM/size normalization + size-unit storage), 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/GXInitTexPreLoadRegion.html
  • SDK source: reference/ACGC-PC-Port/src/static/dolphin/gx/GXTexture.c (GXInitTexPreLoadRegion)
  • SDK behavior:
    • Signature: void GXInitTexPreLoadRegion(GXTexRegion* region, u32 tmem_even, u32 size_even, u32 tmem_odd, u32 size_odd).
    • Requires tmem_even/tmem_odd/size_even/size_odd to be 32-byte aligned.
    • Sets preload region fields:
      • image1 base from tmem_even with preload flag bit set (0x200000)
      • image2 base from tmem_odd
      • is32bMipmap = 0
      • isCached = 0
      • sizeEven/sizeOdd stored in 32-byte units.

libPorpoise Implementation

  • Public API declaration: include/dolphin/gx/GXTexture.h
  • Runtime implementation: src/gx/pc_gx_texture.c (GXInitTexPreLoadRegion)
  • Behavior:
    • Signature matches SDK.
    • Fail-soft parity handling:
      • null region returns
      • all TMEM/size inputs are masked to 32-byte alignment
    • Region layout now mirrors SDK semantics in compact form:
      • r[0]: packed preload image1 (tmem_even + preload flag)
      • r[1]: packed preload image2 (tmem_odd)
      • r[2]: is32bMipmap (0)
      • r[3]: isCached (0)
      • r[4]: sizeEven (32-byte units)
      • r[5]: sizeOdd (32-byte units)
    • Normalized raw preload sizes are also retained in r[6..7].

SDK vs Porpoise Diff

  • Signature parity:
    • SDK: GXInitTexPreLoadRegion(GXTexRegion*, u32, u32, u32, u32)
    • Porpoise: same
  • Behavioral parity:
    • SDK: strict assert checks for 32-byte alignment and preload-field packing.
    • Porpoise: matching packed preload fields/units with fail-soft alignment masking.
  • Known divergence:
    • PC backend does not emulate physical TMEM overlap/bank hazards; region is compatibility state.
    • 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 aligned region packing/state semantics without expanding TMEM emulation scope.