Gfx GX Fn GXSetTexRegionCallBack - wowjinxy/libPorpoise GitHub Wiki

GXSetTexRegionCallBack

  • Category: Texture
  • Matrix Status: Partial
  • Matrix Notes: Added compatibility alias + callback registration/return-old behavior; NULL restores default callback and callback is invoked from GXLoadTexObj, but TMEM region policy is approximated on PC backend.
  • Matrix Link: Gfx-GX-API-Matrix

Official SDK (Reference)

  • Manual page: reference/man/gfx/gx/Texture/GXSetTexRegionCallback.html
  • SDK source: reference/ACGC-PC-Port/src/static/dolphin/gx/GXTexture.c (GXSetTexRegionCallback)
  • SDK behavior:
    • Signature: GXTexRegionCallback GXSetTexRegionCallback(GXTexRegionCallback f).
    • Stores callback pointer f into GX global texture-region callback slot.
    • Returns previously configured callback pointer.
    • Callback is consumed by GXLoadTexObj to choose a GXTexRegion.

libPorpoise Implementation

  • Public API declaration: include/dolphin/gx/GXTexture.h
  • Runtime implementation: src/gx/pc_gx_texture.c (GXSetTexRegionCallback)
  • Behavior:
    • Canonical symbol implemented as GXSetTexRegionCallback(...).
    • Compatibility name GXSetTexRegionCallBack is provided via macro alias for SDK spelling variants.
    • Returns previous callback pointer.
    • Callback is used in GXLoadTexObj; if callback is NULL or returns NULL, runtime falls back to internal default region allocator.

SDK vs Porpoise Diff

  • Signature parity:
    • SDK: GXSetTexRegionCallback(GXTexRegionCallback)
    • Porpoise: same canonical signature + alias macro GXSetTexRegionCallBack
  • Behavioral parity:
    • SDK: stores callback pointer verbatim and returns prior callback.
    • Porpoise: same return/registration model, with additional fail-soft default fallback when callback is null/unset.
  • Known divergence:
    • SDK does not automatically substitute a default callback on null registration; Porpoise intentionally does for robustness.
    • TMEM region assignment is compatibility metadata on PC backend, not hardware TMEM policy.

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 page documents the intentional fail-soft null-callback fallback used by the PC backend.