Module lighting 

Up-to-3-directional-light rig, rendered via the GTE’s hardware lighting pipeline (NCCS / NCDS / NCS ops).

Model

Each Light is a directional light – a direction vector

• an RGB intensity. The PSX GTE evaluates lighting as:

  IR   = LLM * V0                         (N dot each light direction)
  IR   = [BK] * 0x1000 + LCM * IR         (mix light colours + ambient)
  MAC  = IR * RGBC                        (modulate by material/vertex colour)
  RGB2 = MAC                              (push to RGB FIFO, readable as u32)

• LLM (light direction matrix, 3×3): each row is one light’s direction vector.
• LCM (light colour matrix, 3×3): each column is one light’s RGB contribution (so LCM * IR mixes light colours weighted by the corresponding dot-product magnitudes).
• BK (background colour, 3×i32): ambient term added before the material multiply.
• RGBC (data reg 6): per-vertex material / palette tint – the GTE multiplies the lit colour by this before emitting.

Object-local vs world-space lights

The GTE operates on normals in their native mesh space (typically object-local). Lights packed into LLM therefore also need to be in object-local space for the dot products to come out right. Use LightRig::for_object once per object per frame to pre-rotate world-space lights into its local frame.

Cost

• Rig upload (load): ~20 CTC2 writes per frame (cheap).
• Per-object rotate: 9 integer multiplies × 3 lights = 27 mul
  • 9 adds on the CPU – still cheap next to projection cost.
• Per vertex: 2 MTC2 + 1 RTPS + 2 MTC2 + 1 MTC2 + 1 NCCS + 3 MFC2 ≈ 10 GTE ops, ~30-40 cycles total.
• Batched projection: project_lit_triangle uses RTPT for three positions, then NCCS per normal/material. This keeps per-vertex lighting identical while replacing three RTPS ops with one RTPT. If the three material tints match, it also uses NCCT to batch the three NCCS lighting ops.

Structs

FoggedTri

Result of project_triangle_fogged: three projected + lit + fogged vertices, plus the AVSZ3 OT-slot key and the hardware- NCLIP back-face flag.

Light

A single directional light in some reference frame (caller’s choice of world / object / eye space).

LightRig

A rig of up to 3 directional lights – the maximum the PSX GTE supports natively.

ProjectedLit

Result of project_lit: screen-space vertex + its computed lit colour.

Functions

project_lit

Project a vertex AND compute its lit colour in one call.

project_lit_triangle

Project three vertices via RTPT, then compute each vertex’s lit colour with NCCS.

project_triangle_fogged

Run the full PS1-commercial triangle pipeline with per-vertex fog. Three interleaved RTPS + NCDS pairs give each vertex its own IR0 (its own depth-cue weight), then NCLIP + AVSZ3 finish the bookkeeping.