GXInitSpecularDir

• Category: Lighting
• Matrix Status: Implemented
• Matrix Notes: Verified half-vector setup and effectively-infinite light position behavior.
• Matrix Link: Gfx-GX-API-Matrix

Official SDK (Reference)

• Manual page: reference/man/gfx/gx/Lighting/GXInitSpecularDir.html
• Reference source: reference/gx/GXLight.c (GXInitSpecularDir)
• SDK behavior:
  • Signature: void GXInitSpecularDir(GXLightObj* lt_obj, f32 nx, f32 ny, f32 nz).
  • Computes half-angle vector assuming eye vector (0,0,1):
    • v = (-nx, -ny, -nz + 1), normalize if non-zero.
  • Stores half-angle in light direction fields (ldir).
  • Sets light position to effectively infinite distance along -n:
    • lpos = (nx, ny, nz) * -1.0e18.
  • Intended only for specular lights (GX_AF_SPEC); mixing with GXInitLightDir/Pos overwrites this setup.

libPorpoise Implementation

• Public API declaration: include/dolphin/gx/GXLighting.h
• Runtime implementation: src/gx/pc_gx.c (GXInitSpecularDir)
• Behavior:
  • Uses the same half-angle construction and singularity handling (mag != 0 check).
  • Uses the same infinite-position constant magnitude (-1.0e18) and sign convention.
  • Writes only the light object; register load is deferred to GXLoadLightObjImm/Indx.

SDK vs Porpoise Diff

• Signature parity:
  • SDK: typed GXLightObj*.
  • Porpoise: typed in public header; runtime definition uses void* internal ABI-equivalent pointer.
• Behavioral parity:
  • SDK: compute normalized half-angle, set infinite-position vector.
  • Porpoise: same algorithm and constants.
• Known divergence:
  • None identified for function 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

• Verified manual guidance on spec-only usage (GX_AF_SPEC) in GXInitSpecularDir.html.
• Verified reference implementation math and constants in reference/gx/GXLight.c (lines around BIG_NUMBER and GXInitSpecularDir).