Gfx GX Fn GXLoadLightObjIndx - wowjinxy/libPorpoise GitHub Wiki

GXLoadLightObjIndx

  • Category: Lighting
  • Matrix Status: Partial
  • Matrix Notes: Added indexed load via GXSetArray(GX_LIGHT_ARRAY, ...) source; cache-coherency/hardware fetch semantics are approximated on PC.
  • Matrix Link: Gfx-GX-API-Matrix

Official SDK (Reference)

  • Manual page: reference/man/gfx/gx/Lighting/GXLoadLightObjIndx.html
  • Reference source: reference/gx/GXLight.c (GXLoadLightObjIndx)
  • SDK behavior:
    • Signature: void GXLoadLightObjIndx(u32 lt_obj_indx, GXLightID light).
    • Uses indexed XF-load command to fetch light object from the array set by GXSetArray(... light array ...).
    • Expects a valid single GXLightID target (GX_LIGHT0..GX_LIGHT7).
    • Data path is direct from array memory/GPU fetch, so cache coherency is caller responsibility (DCStoreRange before call).

libPorpoise Implementation

  • Public API declaration: include/dolphin/gx/GXLighting.h
  • Runtime implementation: src/gx/pc_gx.c (GXLoadLightObjIndx)
  • Behavior:
    • Reads light object pointer from configured light array base/stride (GX_LIGHT_ARRAY slot in GXSetArray state).
    • Computes base + index * stride, then forwards to GXLoadLightObjImm.
    • Inherits light-ID validation and state update behavior from GXLoadLightObjImm.

SDK vs Porpoise Diff

  • Signature parity:
    • SDK: typed GXLightID and index.
    • Porpoise: typed in public header; runtime definition uses internal u32 light argument (ABI-equivalent).
  • Behavioral parity:
    • SDK: indexed load from light array into selected hardware light register block.
    • Porpoise: indexed load from configured light array into selected backend light slot.
  • Known divergence:
    • SDK issues an indexed XF command (GPU-side fetch); Porpoise performs CPU pointer math and immediate backend copy.
    • SDK docs call out cache-coherency responsibility; Porpoise path effectively reads current CPU-visible memory directly.
    • SDK debug path asserts invalid IDs; Porpoise fail-soft returns through GXLoadLightObjImm path when invalid.

Validation Checklist

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

Working Notes

  • Verified manual semantics and cache note in reference/man/gfx/gx/Lighting/GXLoadLightObjIndx.html.
  • Verified indexed XF-load behavior in reference/gx/GXLight.c.
  • Verified current PC approximation path in src/gx/pc_gx.c.