GXSetNumTevStages

• Category: Texture Environment
• Matrix Status: Implemented
• Matrix Notes: Parity-checked 1..16 stage semantics (SDK assert vs PC fail-soft clamp) and active-stage count propagation to TEV/z-texture runtime path.
• Matrix Link: Gfx-GX-API-Matrix

Official SDK (Reference)

• Manual page: reference/man/gfx/gx/Tev/GXSetNumTevStages.html
• SDK source: reference/gx/GXTev.c (GXSetNumTevStages, around lines 1187+)
• Verified SDK behavior:
  • Valid range is 1..16.
  • Writes (nStages - 1) into GEN_MODE NTEV.
  • At least one stage must be enabled.
  • Z-texture lookup (if enabled) is sourced from last active stage.

libPorpoise Implementation

• Runtime implementation area: src/gx
• Public API surface: include/dolphin/gx
• Current implementation:
  • src/gx/pc_gx.c: GXSetNumTevStages flushes pending begin state, marks TEV stage state dirty, and clamps count to [1, PC_GX_MAX_TEV_STAGES].
  • PC_GX_MAX_TEV_STAGES is 16 (src/gx/pc_gx_internal.h), so full hardware stage count is supported in backend state/shader arrays.
  • Shader/runtime use u_num_tev_stages as loop bound and z-texture-last-stage source (default.frag), matching documented stage-count behavior.

SDK vs Porpoise Diff

• Signature parity:
  • SDK: void GXSetNumTevStages(u8 nStages)
  • Porpoise: same
• Behavioral parity:
  • SDK: asserts on out-of-range nStages, sets GEN_MODE stage count.
  • Porpoise: fail-soft clamps to valid range and updates shader/runtime stage count.
• Known divergence:
  • Out-of-range handling is clamp-based in PC path (release-friendly) instead of SDK debug assert.

Validation Checklist

• GX demo coverage checked (state-only behavior; no regression expected)
• Pikmin usage path checked (stage count + z-stage selection path already used)
• Matrix status updated if needed
• Notes updated with concrete file/function references

Working Notes

• No runtime code patch required for parity; wiki/matrix corrected to reflect 16-stage support.