Gfx GX Fn GXSetTlutRegionCallBack - wowjinxy/libPorpoise GitHub Wiki

GXSetTlutRegionCallBack

  • Category: Texture
  • Matrix Status: Partial
  • Matrix Notes: Implemented callback registration/return-old behavior with default fallback; callback is invoked from TLUT/CI load paths, while TMEM region semantics remain approximate.
  • Matrix Link: Gfx-GX-API-Matrix

Official SDK (Reference)

  • Manual page: reference/man/gfx/gx/Texture/GXSetTlutRegionCallback.html
  • SDK source: reference/ACGC-PC-Port/src/static/dolphin/gx/GXTexture.c (GXSetTlutRegionCallback)
  • SDK behavior:
    • Signature in SDK source: GXTlutRegionCallback GXSetTlutRegionCallback(GXTlutRegionCallback f).
    • Manual C spec uses GXSetTlutRegionCallBack(...) spelling variant.
    • Stores callback pointer into GX global TLUT-region callback slot.
    • Returns previously configured callback pointer.
    • Callback is used by GXLoadTexObj (CI formats) and GXLoadTlut.

libPorpoise Implementation

  • Public API declaration: include/dolphin/gx/GXTexture.h
  • Runtime implementation: src/gx/pc_gx_texture.c (GXSetTlutRegionCallBack)
  • Behavior:
    • Canonical exported symbol in Porpoise: GXSetTlutRegionCallBack(...).
    • Compatibility alias #define GXSetTlutRegionCallback GXSetTlutRegionCallBack is provided for SDK naming variant.
    • Returns previous callback pointer.
    • Callback is consumed in both GXLoadTexObj (CI path) and GXLoadTlut; null callback or null return falls back to internal default allocator.

SDK vs Porpoise Diff

  • Signature parity:
    • SDK: GXSetTlutRegionCallback(GXTlutRegionCallback) (manual also documents CallBack spelling)
    • Porpoise: GXSetTlutRegionCallBack(GXTlutRegionCallback) + alias macro for Callback
  • Behavioral parity:
    • SDK: stores callback pointer verbatim and returns prior callback.
    • Porpoise: same callback registration/return model, with fail-soft default fallback when callback is null/unset.
  • Known divergence:
    • SDK does not force a default callback on null registration; Porpoise intentionally does for robustness.
    • TLUT region mapping remains compatibility metadata on PC backend rather than real TMEM allocation.

Validation Checklist

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

Working Notes

  • Naming variant (Callback vs CallBack) is handled via header alias to preserve source compatibility.