GXGetLightDir

• Category: Lighting
• Matrix Status: Implemented
• Matrix Notes: Verified direction getter returns API-space direction (negated stored vector).
• Matrix Link: Gfx-GX-API-Matrix

Official SDK (Reference)

• Manual page: reference/man/gfx/gx/Lighting/GXGetLightDir.html
• Reference source: reference/gx/GXLight.c (GXGetLightDir)
• SDK behavior:
  • Signature (manual): void GXGetLightDir(GXLightObj* lt_obj, f32* nx, f32* ny, f32* nz).
  • Reference source stores direction internally with opposite sign in GXInitLightDir, then returns API-space direction by negating stored ldir.
  • Getter only; no GX/XF register writes.

libPorpoise Implementation

• Public API declaration: include/dolphin/gx/GXGet.h
• Runtime implementation: src/gx/pc_gx.c (GXGetLightDir)
• Behavior:
  • Reads internal stored direction and returns -stored per component (nx/ny/nz).
  • This matches SDK's API-space convention: caller sees the same direction originally passed to GXInitLightDir.
  • Performs per-output null checks (nx/ny/nz) before writing.

SDK vs Porpoise Diff

• Signature parity:
  • SDK manual: GXLightObj*; SDK source typically uses const GXLightObj*.
  • Porpoise header: GXLightObj*; runtime uses internal void* ABI-compatible implementation.
• Behavioral parity:
  • SDK: returns API-space direction via negated stored vector.
  • Porpoise: same sign convention (*n = -l->n).
• Known divergence:
  • SDK-style code assumes non-null output pointers; Porpoise fail-soft allows null outputs and skips those writes.
  • SDK debug build uses internal check macros for invalid inputs; Porpoise does not assert in this getter path.

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 sign behavior in reference GXLight.c: GXInitLightDir stores -nx/-ny/-nz; GXGetLightDir returns -(ldir[i]).
• Porpoise runtime mirrors the same logic in pc_gx.c.