GXLoadTexObjPreLoaded

• Category: Texture
• Matrix Status: Partial
• Matrix Notes: Implemented explicit-region load path with SDK-aligned texture-region callback bypass and retained TLUT callback path for CI textures; underlying TMEM preload semantics remain approximated.
• Matrix Link: Gfx-GX-API-Matrix

Official SDK (Reference)

• Manual page: reference/man/gfx/gx/Texture/GXLoadTexObjPreLoaded.html
• SDK source: reference/ACGC-PC-Port/src/static/dolphin/gx/GXTexture.c (GXLoadTexObjPreLoaded)
• SDK behavior:
  • Signature: void GXLoadTexObjPreLoaded(GXTexObj* obj, GXTexRegion* region, GXTexMapID id).
  • Uses explicitly provided region (does not invoke tex-region allocator callback).
  • For CI textures, still resolves TLUT region callback path to write TLUT state for selected texmap.
  • Valid id is GX_TEXMAP0..GX_TEXMAP7.

libPorpoise Implementation

• Public API declaration: include/dolphin/gx/GXTexture.h
• Runtime implementation: src/gx/pc_gx_texture.c (GXLoadTexObjPreLoaded)
• Behavior:
  • Signature matches SDK.
  • Fail-soft guards: return on null obj/region or invalid id.
  • Temporarily forces texture-region selection to explicit region during GXLoadTexObj dispatch.
  • Keeps TLUT callback path active (CI formats) while bypassing only texture-region callback selection.
  • Region metadata is still tracked on the uploaded cache entry for later GXInvalidateTexRegion overlap eviction.

SDK vs Porpoise Diff

• Signature parity:
  • SDK: GXLoadTexObjPreLoaded(GXTexObj*, GXTexRegion*, GXTexMapID)
  • Porpoise: same
• Behavioral parity:
  • SDK: explicit texture-region path + CI TLUT callback usage.
  • Porpoise: same high-level callback routing with software texture upload/binding backend.
• Known divergence:
  • No hardware register/TMEM preload semantics on PC backend (mapped to software cache/GL binding path).
  • SDK assert behavior is represented as fail-soft returns in Porpoise 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 narrows callback bypass to texture-region selection only, matching SDK callback routing more closely.