Gfx GX Fn GXPreLoadEntireTexture - wowjinxy/libPorpoise GitHub Wiki

GXPreLoadEntireTexture

  • Category: Texture
  • Matrix Status: Partial
  • Matrix Notes: Implemented API with PC approximation (forces upload path and now honors explicit preload region metadata for invalidation); true TMEM preloading is not emulated.
  • Matrix Link: Gfx-GX-API-Matrix

Official SDK (Reference)

  • Manual page: reference/man/gfx/gx/Texture/GXPreLoadEntireTexture.html
  • SDK source: reference/ACGC-PC-Port/src/static/dolphin/gx/GXTexture.c (GXPreLoadEntireTexture)
  • SDK behavior:
    • Signature: void GXPreLoadEntireTexture(GXTexObj* tex_obj, GXTexRegion* region).
    • Loads texture data from main memory into TMEM preload region.
    • Requires matching preload region configuration (GXInitTexPreLoadRegion).
    • Preload does not itself bind the texture for TEV use; GXLoadTexObjPreLoaded is required afterward.

libPorpoise Implementation

  • Public API declaration: include/dolphin/gx/GXTexture.h
  • Runtime implementation: src/gx/pc_gx_texture.c (GXPreLoadEntireTexture)
  • Behavior:
    • Signature matches SDK.
    • Fail-soft validation: returns if tex_obj or region is null.
    • Uses GXLoadTexObj(tex_obj, GX_TEXMAP0) with callback bypass to force upload path without changing callback policy.
    • Restores prior texmap-0 binding/state after upload, so preload call does not permanently alter active slot 0 binding.
    • Attaches explicit region metadata to the uploaded cache entry (for subsequent GXInvalidateTexRegion overlap handling).

SDK vs Porpoise Diff

  • Signature parity:
    • SDK: GXPreLoadEntireTexture(GXTexObj*, GXTexRegion*)
    • Porpoise: same
  • Behavioral parity:
    • SDK: true TMEM preload transfer path.
    • Porpoise: software approximation that guarantees upload and tracks preload-region metadata.
  • Known divergence:
    • No physical TMEM preload DMA/banking behavior on PC backend.
    • Uses temporary texmap-0 upload path internally instead of dedicated hardware preload op sequence.

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 improves region-aware invalidation behavior for preloaded textures without expanding TMEM emulation scope.