Gfx GX Fn GXLoadLightObjImm - wowjinxy/libPorpoise GitHub Wiki

GXLoadLightObjImm

  • Category: Lighting
  • Matrix Status: Implemented
  • Matrix Notes: Verified immediate light-object load into selected hardware light slot/state.
  • Matrix Link: Gfx-GX-API-Matrix

Official SDK (Reference)

  • Manual page: reference/man/gfx/gx/Lighting/GXLoadLightObjImm.html
  • Reference source: reference/gx/GXLight.c (GXLoadLightObjImm)
  • SDK behavior:
    • Signature: void GXLoadLightObjImm(const GXLightObj* lt_obj, GXLightID light).
    • Expects a single valid GXLightID bit (GX_LIGHT0..GX_LIGHT7).
    • Converts light ID to XF slot and writes full light register block into FIFO/XF state.
    • Provides CPU-cache-coherent immediate path via write-gather mechanism (hardware detail).

libPorpoise Implementation

  • Public API declaration: include/dolphin/gx/GXLighting.h
  • Runtime implementation: src/gx/pc_gx.c (GXLoadLightObjImm)
  • Behavior:
    • Flushes pending begin/vertex work before light-state update for ordering.
    • Validates light as exactly one bit among 8 supported lights and maps to slot 0..7.
    • Copies light object fields (pos/dir/a/k/color) into backend light slot state.
    • Marks lighting state dirty for backend update.

SDK vs Porpoise Diff

  • Signature parity:
    • SDK: const GXLightObj* + typed GXLightID.
    • Porpoise: typed in public header; runtime definition uses internal void*/u32 ABI-equivalent args.
  • Behavioral parity:
    • SDK: immediate load of selected light object into selected hardware light slot.
    • Porpoise: immediate load of selected light object into selected backend light slot.
  • Known divergence:
    • SDK debug path asserts on invalid light IDs; Porpoise fail-soft returns without update.
    • Porpoise calls pc_gx_lightobj_sanitize before loading; SDK reference writes raw object fields.
    • Hardware FIFO/XF write details are emulated as backend state updates on PC.

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 slot selection rules against ConvLightID2Num + GXLoadLightObjImm in reference/gx/GXLight.c.
  • Verified backend slot copy path in src/gx/pc_gx.c.