Gfx GX Fn GXNormal family - wowjinxy/libPorpoise GitHub Wiki

GXNormal[n][t]

  • Category: Geometry and Vertex
  • Matrix Status: Partial
  • Matrix Notes: SDK/manual parity reviewed for direct+indexed normal paths; S8/S16 implied scaling (6/14 fractional bits) verified. Added direct-NBT phase handling to preserve primary normal (N) in single-normal shader path. Full NBT/NBT3 vector fidelity remains incomplete.
  • Matrix Link: Gfx-GX-API-Matrix

Official SDK (Reference)

  • Manual page: E:/GPT5/Porpoise_SDK/libPorpoise/reference/man/gfx/gx/Geometry/GXNormal.html
  • Related pages:
    • E:/GPT5/Porpoise_SDK/libPorpoise/reference/man/gfx/gx/Geometry/GXBegin.html
    • E:/GPT5/Porpoise_SDK/libPorpoise/reference/man/gfx/gx/Geometry/GXSetVtxDesc.html
    • E:/GPT5/Porpoise_SDK/libPorpoise/reference/man/gfx/gx/Geometry/GXSetVtxAttrFmt.html
    • E:/GPT5/Porpoise_SDK/libPorpoise/reference/man/gfx/gx/Geometry/GXSetArray.html
  • SDK source parity check area: E:/GPT5/ACGC-PC-Port-Debug-Stuff/src/static/dolphin/gx/GXVert.c
  • Notes:
    • Signature family matches manual (GXNormal3f32/s16/s8, GXNormal1x16/1x8).
    • Manual confirms direct NBT submission uses three normal calls (N/B/T).
    • Manual confirms indexed NBT submission uses one index (HW2 GX_NRM_NBT3 extends this behavior).

libPorpoise Implementation

  • Runtime implementation area: E:/GPT5/Porpoise_SDK/libPorpoise/src/gx/pc_gx.c
  • Public API surface: E:/GPT5/Porpoise_SDK/libPorpoise/include/dolphin/gx/GXVert.h
  • Notes:
    • API signatures match manual family.
    • Direct S8/S16 normal conversions use implied fixed-point fractions (1/64, 1/16384).
    • Indexed normal reads use current VAT NRM type and same implied fixed-point behavior for signed integer formats.
    • Added per-vertex NBT direct-call phase tracking so first normal (N) is retained instead of being overwritten by B/T in single-normal pipeline.

SDK vs Porpoise Diff

  • Signature parity:
    • SDK: GXNormal3f32/s16/s8, GXNormal1x16/1x8.
    • Porpoise: matching function family.
  • Behavioral parity:
    • SDK: supports NRM and NBT conventions; direct NBT expects N/B/T sequence.
    • Porpoise: NRM direct/indexed behavior aligns; direct NBT now keeps first normal vector in lighting path.
  • Known divergence:
    • PC shader vertex format stores one normal vector; binormal/tangent are not represented as full independent attributes.
    • HW2 GX_NRM_NBT3 individually indexed N/B/T vectors are not fully emulated end-to-end.

Validation Checklist

  • GX demo coverage checked
  • Pikmin usage path checked
  • Matrix status updated if needed
  • Notes updated with concrete file/function references

Working Notes

  • Runtime functions around GXNormal3f32/GXNormal1x* in pc_gx.c; NBT phase state tracked in PCGXState.