GXSetChanCtrl

• Category: Lighting
• Matrix Status: Implemented
• Matrix Notes: Verified channel control state (enable/src/mask/diffuse/attenuation) update path.
• Matrix Link: Gfx-GX-API-Matrix

Official SDK (Reference)

• Manual page: reference/man/gfx/gx/Lighting/GXSetChanCtrl.html
• Reference source: reference/gx/GXLight.c (GXSetChanCtrl)
• SDK behavior:
  • Signature: void GXSetChanCtrl(GXChannelID chan, GXBool enable, GXColorSrc amb_src, GXColorSrc mat_src, GXLightID light_mask, GXDiffuseFn diff_fn, GXAttnFn attn_fn).
  • For selected channel control register(s), stores:
    • enable, amb_src, mat_src, light-mask bits.
    • diffuse term forced to GX_DF_NONE when attn_fn == GX_AF_SPEC.
    • attenuation mode flags derived from attn_fn (AF_NONE vs AF_SPOT/AF_SPEC paths).
  • GX_COLOR0A0 / GX_COLOR1A1 target both color and alpha control registers.

libPorpoise Implementation

• Public API declaration: include/dolphin/gx/GXLighting.h
• Runtime implementation: src/gx/pc_gx.c (GXSetChanCtrl)
• Behavior:
  • Maps channel selectors to channel group 0/1 and updates color/alpha control slots accordingly.
  • For combined selectors (GX_COLOR0A0, GX_COLOR1A1) updates both color and alpha slots with same control data.
  • Forces diff_fn to GX_DF_NONE when attn_fn == GX_AF_SPEC, matching SDK behavior.
  • Stores raw attn_fn and light-mask state for shader/backend lighting evaluation.

SDK vs Porpoise Diff

• Signature parity:
  • SDK: typed enums (GXChannelID, GXColorSrc, GXDiffuseFn, GXAttnFn).
  • Porpoise: typed in public header; runtime definition uses internal u32 parameters (ABI-equivalent on C side).
• Behavioral parity:
  • SDK: channel control register setup including specular-diffuse override and combined-channel mirroring.
  • Porpoise: same control-state setup/mirroring rules.
• Known divergence:
  • SDK invalid-channel path asserts; Porpoise fail-soft ignores invalid channel IDs.
  • SDK writes XF channel-control registers directly; Porpoise updates backend shadow state and marks lighting dirty.
  • PC shader backend approximates parts of alpha-lighting evaluation, so not all channel-control combinations are fully hardware-identical at runtime.

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 spec-path override (attn_fn == GX_AF_SPEC => diff_fn = GX_DF_NONE) in both reference and Porpoise code.
• Verified combined-channel write behavior (GX_COLOR0A0 / GX_COLOR1A1) in both reference and Porpoise code.