GXSetNumChans

• Category: Lighting
• Matrix Status: Implemented
• Matrix Notes: Verified SDK range semantics (0..2) and added runtime clamp for out-of-range values.
• Matrix Link: Gfx-GX-API-Matrix

Official SDK (Reference)

• Manual page: reference/man/gfx/gx/Lighting/GXSetNumChans.html
• Reference source: reference/gx/GXLight.c (GXSetNumChans)
• SDK behavior:
  • Signature: void GXSetNumChans(u8 nChans).
  • Valid values are 0..2 (GX_COLOR0A0 and GX_COLOR1A1 path).
  • SDK debug path asserts when nChans > 2.
  • Updates XF color-channel count state that feeds rasterized channel evaluation.

libPorpoise Implementation

• Public API declaration: include/dolphin/gx/GXLighting.h
• Runtime implementation: src/gx/pc_gx.c (GXSetNumChans)
• Behavior:
  • Uses matching API signature.
  • Flushes pending primitive begin state before mutating lighting state.
  • Stores channel count in backend state (g_gx.num_chans) and marks lighting dirty.
  • Clamps nChans to 2 for out-of-range inputs (release-style fail-soft behavior).

SDK vs Porpoise Diff

• Signature parity:
  • SDK: void GXSetNumChans(u8 nChans).
  • Porpoise: same signature.
• Behavioral parity:
  • SDK: accepts 0..2, asserts on invalid values in debug builds.
  • Porpoise: accepts input and clamps to 2 when input exceeds SDK range.
• Known divergence:
  • SDK debug build asserts invalid values; Porpoise does not assert and instead fail-soft clamps.
  • SDK writes XF registers directly; Porpoise updates renderer shadow state.

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 manual argument section states max value 2.
• Confirmed reference/gx/GXLight.c has ASSERTMSG((nChans <= 2), "GXSetNumChans: nChans > 2").
• Updated Porpoise runtime to enforce range in release path via clamp.