Gfx GX Fn GXLoadTlut - wowjinxy/libPorpoise GitHub Wiki

GXLoadTlut

  • Category: Texture
  • Matrix Status: Implemented
  • Matrix Notes: Verified against docs/source: callback-driven TLUT load path implemented, with fail-soft region-size safety clamp on PC backend.
  • Matrix Link: Gfx-GX-API-Matrix

Official SDK (Reference)

  • Manual page: reference/man/gfx/gx/Texture/GXLoadTlut.html
  • SDK source: reference/ACGC-PC-Port/src/static/dolphin/gx/GXTexture.c (GXLoadTlut)
  • SDK behavior:
    • Signature: void GXLoadTlut(GXTlutObj* tlut_obj, u32 tlut_name).
    • Requires TLUT-region callback (GXSetTlutRegionCallBack) and uses it to resolve destination region.
    • Loads TLUT metadata/data source for the selected TLUT name.
    • Validates TLUT object size against target TLUT region size (SDK assert path).

libPorpoise Implementation

  • Public API declaration: include/dolphin/gx/GXTexture.h
  • Runtime implementation: src/gx/pc_gx_texture.c (GXLoadTlut)
  • Behavior:
    • Signature uses GXTlutObj* and GXTlut name enum.
    • Fail-soft guards for null object and invalid TLUT index (0..19).
    • Invokes TLUT-region callback and falls back to default callback if needed.
    • Stores resolved TLUT source pointer/format/entry-count into backend TLUT slot for later CI decode use.
    • Applies region-size safety clamp (GXTlutSize units -> entry count) to prevent oversized TLUT use in PC path.

SDK vs Porpoise Diff

  • Signature parity:
    • SDK: GXLoadTlut(GXTlutObj*, u32 tlut_name)
    • Porpoise: GXLoadTlut(GXTlutObj*, GXTlut idx) (equivalent name domain)
  • Behavioral parity:
    • SDK: callback-resolved TLUT region and TLUT load/state update.
    • Porpoise: callback path is honored and TLUT state is updated for CI texture decode path.
  • Known divergence:
    • No real TMEM DMA/register transfer on PC backend; TLUT data is kept in backend CPU-side state for palette decode/upload.
    • SDK uses asserts for invalid callback/size conditions; Porpoise uses fail-soft fallback/clamp.

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 function is a key dependency for CI4/CI8/C14X2 correctness in GXLoadTexObj decode paths.