GXSetChanMatColor

• Category: Lighting
• Matrix Status: Implemented
• Matrix Notes: Verified channel material color updates including packed GX_COLOR0A0/GX_COLOR1A1 handling.
• Matrix Link: Gfx-GX-API-Matrix

Official SDK (Reference)

• Manual page: reference/man/gfx/gx/Lighting/GXSetChanMatColor.html
• Reference source: reference/gx/GXLight.c (GXSetChanMatColor)
• SDK behavior:
  • Signature: void GXSetChanMatColor(GXChannelID chan, GXColor mat_color).
  • Updates material channel register for selected selector:
    • GX_COLOR0/GX_COLOR1: RGB only (preserve alpha).
    • GX_ALPHA0/GX_ALPHA1: alpha only (preserve RGB).
    • GX_COLOR0A0/GX_COLOR1A1: RGBA all components.
  • Invalid channel ID asserts in SDK debug path.

libPorpoise Implementation

• Public API declaration: include/dolphin/gx/GXLighting.h
• Runtime implementation: src/gx/pc_gx.c (GXSetChanMatColor)
• Behavior:
  • Maps channel selector to channel group index and applies same component-selective writes.
  • Converts GXColor bytes to normalized float state (0..1) for backend lighting.
  • Flushes pending begin/vertex state before updating lighting state.

SDK vs Porpoise Diff

• Signature parity:
  • SDK: typed GXChannelID.
  • Porpoise: typed in public header; runtime definition uses internal u32 (ABI-equivalent).
• Behavioral parity:
  • SDK: per-selector component update semantics (RGB-only, A-only, RGBA).
  • Porpoise: same selector/component behavior.
• Known divergence:
  • SDK invalid-channel path asserts; Porpoise fail-soft ignores invalid channels.
  • SDK writes XF registers directly; Porpoise updates backend shadow state and marks lighting dirty.

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 component-selective channel behavior in reference/gx/GXLight.c and src/gx/pc_gx.c.
• Material color is used when GXSetChanCtrl(... mat_src = GX_SRC_REG) per manual.