GXGetLightPos

• Category: Lighting
• Matrix Status: Implemented
• Matrix Notes: Verified light position getter returns x/y/z directly from light object state.
• Matrix Link: Gfx-GX-API-Matrix

Official SDK (Reference)

• Manual page: reference/man/gfx/gx/Lighting/GXGetLightPos.html
• Reference source: reference/gx/GXLight.c (GXGetLightPos)
• SDK behavior:
  • Signature (manual): void GXGetLightPos(GXLightObj* lt_obj, f32* x, f32* y, f32* z).
  • Reference source uses const GXLightObj* input and writes all three outputs from lpos[0..2].
  • Getter only; no GX/XF register writes.

libPorpoise Implementation

• Public API declaration: include/dolphin/gx/GXGet.h
• Runtime implementation: src/gx/pc_gx.c (GXGetLightPos)
• Behavior:
  • Reads internal light-object position members (px/py/pz) and writes x/y/z.
  • Does not mutate renderer state.
  • Companion vector macro GXGetLightPosv is provided in GXGet.h (SDK-style macro surface).

SDK vs Porpoise Diff

• Signature parity:
  • SDK manual: GXLightObj*; SDK source: const GXLightObj*.
  • Porpoise header: GXLightObj*; runtime uses internal void* ABI-compatible implementation.
• Behavioral parity:
  • SDK: *x = lpos[0]; *y = lpos[1]; *z = lpos[2];.
  • Porpoise: *x = px; *y = py; *z = pz; (same mapping).
• Known divergence:
  • SDK debug build uses internal check macros for input assumptions.
  • Porpoise does not perform explicit null-check guards for this getter path (same strict output-pointer expectation as SDK source behavior).

Validation Checklist

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

Working Notes

• Confirmed output-axis order is x,y,z in both SDK reference and Porpoise runtime.
• GXGetLightPosv remains macro-based in public header (no standalone symbol), matching SDK-style API shape.