GXInvalidateTexRegion

• Category: Texture
• Matrix Status: Partial
• Matrix Notes: Implemented region-aware PC texture-cache invalidation by TMEM-region overlap; remains approximate versus hardware tag invalidation.
• Matrix Link: Gfx-GX-API-Matrix

Official SDK (Reference)

• Manual page: reference/man/gfx/gx/Texture/GXInvalidateTexRegion.html
• SDK source: reference/ACGC-PC-Port/src/static/dolphin/gx/GXTexture.c (GXInvalidateTexRegion)
• SDK behavior:
  • Signature: void GXInvalidateTexRegion(GXTexRegion* region).
  • Invalidates TMEM cache tags for the provided region (hardware register path).
  • Used when CPU updates texture data in main memory that may already be cached in TMEM.
  • Manual notes emulator caveat: classic emulator implementation effectively maps to broad invalidation behavior.

libPorpoise Implementation

• Public API declaration: include/dolphin/gx/GXTexture.h
• Runtime implementation: src/gx/pc_gx_texture.c (GXInvalidateTexRegion)
• Behavior:
  • Signature matches SDK.
  • Runtime now tracks TMEM-region metadata per cached texture entry (captured from GXSetTexRegionCallback path in GXLoadTexObj).
  • GXInvalidateTexRegion decodes region ranges (cached/preload layouts) and evicts cache entries whose TMEM ranges overlap the target region.
  • Eviction unbinds matching GL textures from active texmap slots and deletes owned GL textures.
  • External texture-pack entries are intentionally not deleted in this path.

SDK vs Porpoise Diff

• Signature parity:
  • SDK: GXInvalidateTexRegion(GXTexRegion*)
  • Porpoise: same (const-qualified parameter accepted by implementation)
• Behavioral parity:
  • SDK: hardware TMEM tag invalidation for specified region.
  • Porpoise: software texture-cache eviction based on region-overlap approximation.
• Known divergence:
  • No hardware tag/timing semantics (GP clock behavior) on PC backend.
  • Region tracking depends on callback-provided region metadata from load path.
  • External texture-pack objects are preserved.

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 replaces stub behavior with deterministic region-based cache eviction, improving correctness for CPU-updated texture data.