GXSetTexCoordGen2 (HW2)

• Category: Texture Coordinate Generation
• Matrix Status: Partial
• Matrix Notes: Implemented HW2 state path for normalize + postmtx on regular texgens, argument-domain validation, HW2 GX_TG_MTX2x4 fast-path behavior (normalize suppression + Qt' skip), per-vertex TEXnMTXIDX overrides, SRTG raster-color sourcing, and emboss-style bump offsets; remaining non-bit-exact edge cases are documented below.
• Matrix Link: Gfx-GX-API-Matrix

Official SDK (Reference)

• Manual page: reference/man/gfx/gx/Geometry/GXSetTexCoordGen2.html
• Reference source: reference/gx/GXAttr.c (GXSetTexCoordGen2)
• SDK behavior:
  • Signature: void GXSetTexCoordGen2(GXTexCoordID dst_coord, GXTexGenType func, GXTexGenSrc src_param, u32 mtx, GXBool normalize, u32 postmtx).
  • First four args mirror GXSetTexCoordGen.
  • normalize and postmtx are HW2 options that apply to regular texgens (GX_TG_MTX2x4, GX_TG_MTX3x4).
  • Bump/light texgens ignore those HW2 extras.

libPorpoise Implementation

• Public API declaration: include/dolphin/gx/GXGeometry.h
• Runtime implementation: src/gx/pc_gx.c (GXSetTexCoordGen2) + src/gx/shaders/default.vert
• Behavior:
  • Validates func/src_param/mtx combinations against the documented accepted-value matrix before applying state.
  • For non-regular texgens (GX_TG_BUMP*, GX_TG_SRTG), runtime behavior treats HW2 extras as ignored in shader execution while preserving caller-provided state fields.
  • Stores per-texgen func/src/mtx/normalize/postmtx state for all 8 texgens when arguments are valid.
  • Supports per-vertex tex matrix index overrides (GX_VA_TEXnMTXIDX) for texgens by uploading tex matrix arrays and selecting per-vertex slots in shader.
  • Uploads first-pass tex matrix rows 0/1/2 and post-transform rows 0/1/2 to shader uniforms.
  • Shader applies:
    • first-pass matrix transform,
    • optional normalization,
    • optional post-transform matrix for regular texgens.
  • For texture-coordinate source attributes (GX_TG_TEX*), backend now follows XF AB01 input-form semantics ([S,T,0,1]) before first-pass matrix math.
  • HW2 special case implemented: if texgen is GX_TG_MTX2x4 and current vertex descriptor is position + exactly one texcoord only, normalization is suppressed even when requested.
  • GX_TG_SRTG path now sources from raster-color style channel values instead of raw texture coordinates.
  • GX_TG_BUMP* path applies emboss-style offsets from eye-space light direction (dS=dot(ldir,binormal), dT=dot(ldir,tangent-like)), normalizes the bump basis vectors, uses generated texcoord chaining, and outputs ST-projection style coordinates (q=1.0).
  • GX_TG_SRTG path quantizes raster channel values to 8-bit-equivalent precision before writing generated S/T.
  • TEV texcoord source routing for implemented shader stages now accepts GX_TEXCOORD0..7 (no longer clamped to 0..3 on the PC path).

SDK vs Porpoise Diff

• Signature parity:
  • SDK: same 6-argument function on HW2 paths.
  • Porpoise: same callable function signature.
• Behavioral parity:
  • SDK: regular texgens support normalize + post-transform.
  • Porpoise: same high-level pipeline now implemented for regular texgens, including the documented HW2 fast-path normalization exception.
• Known divergence:
  • Full hardware emboss/bump behavior is not guaranteed bit-exact across all basis-handedness/content edge cases.
  • Functional ordering/sequential texcoord requirements from the manual are treated as caller contract (not explicitly rejected at API-call time).
  • SDK includes strict argument validation/assert paths; Porpoise is generally fail-soft.

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 docs note that HW2 options apply only to regular texgens.
• Implemented postmtx plumb-through end-to-end (API state -> GL uniforms -> vertex shader).
• Expanded texgen uniform upload from 4 to 8 coords for consistency with API limits.