GXLoadTexObj

• Category: Texture
• Matrix Status: Partial
• Matrix Notes: Verified against docs/source: callback path and texmap load semantics are implemented; PC backend now applies full GX sampler state (min/mag filter + LOD/aniso), with remaining TMEM/HW approximation limits.
• Matrix Link: Gfx-GX-API-Matrix

Official SDK (Reference)

• Manual page: reference/man/gfx/gx/Texture/GXLoadTexObj.html
• SDK source: reference/ACGC-PC-Port/src/static/dolphin/gx/GXTexture.c (GXLoadTexObj)
• SDK behavior:
  • Signature: void GXLoadTexObj(GXTexObj* obj, GXTexMapID id).
  • Valid id range is GX_TEXMAP0..GX_TEXMAP7.
  • Calls texture region callback (GXSetTexRegionCallBack) and, for CI formats, TLUT region callback.
  • Loads texture object state to the selected texmap register set.

libPorpoise Implementation

• Public API declaration: include/dolphin/gx/GXTexture.h
• Runtime implementation: src/gx/pc_gx_texture.c (GXLoadTexObj)
• Behavior:
  • Signature matches SDK.
  • Fail-soft validation:
    • null obj returns
    • invalid texmap IDs (>= GX_MAX_TEXMAP) return
  • Callback behavior:
    • texture and TLUT callbacks are invoked per SDK path
    • if callback pointer/result is null, default callback fallback is used
  • Sampler state now maps GX texture object state to GL sampler params:
    • wrap S/T (GX_CLAMP/REPEAT/MIRROR)
    • min filter (all 6 GX modes, with mip-safe fallback when mipchain unavailable)
    • mag filter (GX_NEAR/GX_LINEAR)
    • LOD state (MIN_LOD, MAX_LOD, LOD_BIAS)
    • anisotropy (GX_ANISO_1/2/4) when GL extension is present
  • Mip behavior:
    • generated on upload for decoded internal textures when a mip min-filter is requested
    • external/packed textures stay non-mip unless explicitly generated in cache path

SDK vs Porpoise Diff

• Signature parity:
  • SDK: GXLoadTexObj(GXTexObj*, GXTexMapID)
  • Porpoise: same
• Behavioral parity:
  • SDK: callback-driven tex region/TLUT selection + texmap load.
  • Porpoise: callback path implemented and texture/sampler state bound to the requested texmap.
• Known divergence:
  • No real TMEM/register upload on PC backend (mapped to GL texture objects/samplers).
  • Some hardware details remain approximate (exact TMEM region semantics, edge-LOD/bias-clamp hardware nuances).
  • Mip levels are generated/approximated in GL for decoded textures rather than read from native GC mip chains.

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 fixed a concrete parity bug where min filter was previously treated as boolean and mag filter was ignored.