Gfx GX Fn GXSetChanAmbColor - wowjinxy/libPorpoise GitHub Wiki

GXSetChanAmbColor

  • Category: Lighting
  • Matrix Status: Implemented
  • Matrix Notes: Verified channel ambient 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/GXSetChanAmbColor.html
  • Reference source: reference/gx/GXLight.c (GXSetChanAmbColor)
  • SDK behavior:
    • Signature: void GXSetChanAmbColor(GXChannelID chan, GXColor amb_color).
    • Updates ambient channel register for the selected channel 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 (GXSetChanAmbColor)
  • Behavior:
    • Resolves channel group index (0/1) and applies component-selective writes matching SDK selector semantics.
    • Converts 8-bit channel values to normalized float (0..1) for backend lighting state.
    • Flushes pending vertex begin state first to preserve GX-like state ordering.

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 (idx < 0 path).
    • SDK writes XF registers immediately; Porpoise updates backend state shadow 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 selector-specific field updates in reference/gx/GXLight.c and src/gx/pc_gx.c.
  • Manual confirms ambient source dependency on GXSetChanCtrl(... amb_src = GX_SRC_REG).