GXInitTlutObj

• Category: Texture
• Matrix Status: Implemented
• Matrix Notes: Verified against docs/source: initializes TLUT object pointer/format/entry-count with SDK-compatible limits.
• Matrix Link: Gfx-GX-API-Matrix

Official SDK (Reference)

• Manual page: reference/man/gfx/gx/Texture/GXInitTlutObj.html
• SDK source: reference/ACGC-PC-Port/src/static/dolphin/gx/GXTexture.c (GXInitTlutObj)
• SDK behavior:
  • Signature: void GXInitTlutObj(GXTlutObj* tlut_obj, void* lut, GXTlutFmt fmt, u16 n_entries).
  • Initializes TLUT descriptor state with LUT pointer, format, and entry count.
  • Constrains maximum entry count to 16384 (0x4000).
  • Requires 32-byte LUT alignment (asserted in SDK debug path).

libPorpoise Implementation

• Public API declaration: include/dolphin/gx/GXTexture.h
• Runtime implementation: src/gx/pc_gx_texture.c (GXInitTlutObj)
• Behavior:
  • Signature matches SDK style (void* lut).
  • Initializes TLUT object storage (pointer/format/entry-count).
  • PC fail-soft guards:
    • null object returns safely
    • invalid format clamps to GX_TL_IA8
    • n_entries clamps to 0x4000

SDK vs Porpoise Diff

• Signature parity:
  • SDK: GXInitTlutObj(GXTlutObj*, void*, GXTlutFmt, u16)
  • Porpoise: same
• Behavioral parity:
  • SDK: initializes TLUT descriptor state and enforces entry/align constraints via asserts.
  • Porpoise: initializes equivalent state and applies fail-soft entry/format bounds.
• Known divergence:
  • SDK debug asserts LUT alignment (32B); PC path does not hard-fail on misalignment.

Validation Checklist

• GX demo coverage checked
• Pikmin usage path checked
• Matrix status updated if needed
• Notes updated with concrete file/function references

Working Notes

• TLUT pointer alignment is less strict on PC because data is consumed by CPU decode/upload rather than direct GC TMEM DMA.