Renderer

At a glance

Retail renderer

One TMD routine in the main executable (plus a light-source sibling used only by the world map), steered by a six-row descriptor table.

Lighting

None on the field path. GPU rule: out = texel × colour / 128, after one GTE depth-cue op.

Screen

320×224 drawn, 228 lines displayed; projection origin OFX 160, OFY 114 - dead centre of the display window.

Depth

No depth buffer. Primitives are binned by mean Z into an ordering table and painted back to front.

Port defaults

Shading retail (baked colour, no light); rasterisation clean (vertex snap + dither opt-in); affine UVs always on; semi-transparency always blended.

Engine

crates/engine-render (wgpu, native), site/js/webgl-shaders.js (browser); shared kernels in legaia-tmd and engine-ui.

Confidence

Confirmed - disassembly of the GTE op stream, save-state register files, GP0 draw-list pins (how we know).

One primitive's journey

A town is a few hundred small meshes - houses, fences, terrain tiles, the party. For each primitive group the game asks the GTE to rotate, translate and project the corners, wraps the result in a GPU packet, and drops it into an ordering-table bucket chosen by depth. When the frame is complete the GPU walks the table far to near and paints. Textures and palettes live as rectangles inside video memory, addressed by their top-left corner.

The descriptor table

A mesh can mix flat and smooth-shaded, textured and plain polygons. Each group's 8-byte header [count][flags][olen][ilen][flag][mode] is followed by count × ilen × 4 bytes of prims; the row ((flags >> 1) − 8) >> 1 of a six-row table says how each prim is laid out and which packet to build.

Bit (flags >> 1) & 1 picks quad over triangle; 0x20..0x27 re-use the same rows. Typed lookup: legaia_tmd::descriptor::Descriptor::for_flags. Byte layouts per mode: TMD format.

Lighting: painted, not computed

Legaia's towns look lit - shadowed alleys, bright plazas, a glow around lamps - but none of it is computed at run time. The artists painted a brightness into every polygon, and the console multiplies the texture by it. Any "helpful" light a renderer adds makes the game look wrong.

• One colour op. The two TMD renderers issue exactly one GTE colour instruction, DPCS (depth cue). No NC* op ever runs on the field path, and the light matrices - which are populated - are read by exactly four routines in the whole game. A disc-wide census of GTE opcodes settles the set rather than leaving it open: five normal-colour instructions across 84 images, every one inside those four NC* prim handlers, and no MVMVA anywhere selecting the light matrix (29 select the rotation matrix). Those four handlers exist in the executable and do not run: exec breakpoints on all four catch nothing executing across two kingdom overworlds, an ordinary field scene or a battle - in a run where a control breakpoint on the handlers the overworld does use fires on the same frames. The world map was the presumed consumer and is not one.
• The colour word. Every prim carries [R][G][B][GP0 code]; gouraud prims carry one per corner. 0x80 is neutral, lower darkens, higher brightens up to 2×. Across the field environment packs roughly four fifths of components sit below 0x80 - that headroom is why retail has more contrast than an unlit render.
• Depth cue. DPCS blends the colour toward the far colour by IR0; an unfogged field scene passes IR0 = 0, so the cue is the identity and a capture's corner colours leave the op byte-unchanged.

The trap that keeps a synthetic light alive in a port: an unbound colour attribute defaults to white, and white is texel × 255/128 - a missing colour stream reads as "too bright", not as "unlit". Both site shader paths upload the packet colour for exactly this reason.

The screen

All four hold across field, battle, battle load and the dance minigame, on both buffer halves - unlike H, which is written per phase (256 in battle, 512 in the field). OFY = 114 is 228 / 2: centre of the display window, not an offset. It reads as "six pixels above centre" only against a 240-line frame, which retail never draws.

The port keeps a 320×240 logical screen because every 2D rect is a retail draw-area coordinate copied verbatim, and puts the GTE origin on row 114 via a constant bias on clip y (GTE_OFY_NDC_BIAS) in both hosts. The residual is the frame height itself: retail's picture fills 224/240 of the port's, so everything reads about 7% smaller.

The battle backdrop is one TMD retail draws twice, the second copy under a per-stage transform; both hosts append the copy at build time, so a single draw call is not evidence of a single draw.

VRAM: choosing what to upload

The PS1 keeps every texture and palette in one shared 1 MB image. A polygon does not say "use texture X" - it says "read pixels from this rectangle and look them up in the palette at that row". Legaia's palettes are scattered across many PROT entries, and uploading every texture a scene owns lets one image overwrite another mesh's palette row: rainbow noise. Most of the port's VRAM work is deciding which bytes to write.

Image-then-CLUT ordering matters: a per-prim collision heuristic drops legitimate palette rows whenever any mesh's UV box brushes the row. The retail loader itself DMAs every scene TIM; the VRAM parity oracle switches to that (upload_all_tims) while the render path stays targeted.

Untextured prims (fences, crates, painted props) skip the VRAM path: their colour block becomes a ColorMesh drawn by the vertex-colour pipeline, and a mixed mesh draws both halves at one placement. The fragment shader decodes 4/8/15 bpp and the CLUT per pixel, so one draw call carries every texture mode.

Colour space

Every colour the engine handles is a PSX framebuffer value - display-referred, what the console clocks out. The swapchain is a UNORM view, never sRGB (an sRGB attachment would lift retail's mid-grey from 132 to 190); textures are Rgba8Unorm; the last shader stage quantises to 5 bits and expands (c5 << 3) | (c5 >> 2); semi-transparency blends in the same space.

Knobs: what is faithful, what is a choice

Shading - which polygon is which colour - is retail by default. The PS1's rasterisation artefacts are off by default and one switch away. "Faithful" and "default" are different axes, so each knob lists both.

Retail dithers. The GPU's dtd bit is stamped 0 by the draw-environment initialiser but re-stamped every frame from a global that boots at 1 and a script opcode can flip. The port's clean default is a project choice about the look, not a reading of the executable.

Semi-transparency. A prim is see-through when its ABE bit is set; the blend equation comes from the texpage ABR bits (0.5B+0.5F, B+F, B−F, B+0.25F). Textured prims decide per texel via the STP bit, so the engine runs an opaque pass then a per-mode blend pass, ordered far to near on the same mean-Z key retail bins on, later-submitted-first on ties.

Depth without a depth buffer

Retail sorts whole polygons by mean Z and paints far to near. Legaia's artists leaned on that: decals lying exactly on walls, floor tiles overlapping neighbours, walls modelled once per visible side. A depth-tested renderer turns each into flicker, so the port reproduces the painter's outcome without the painter's algorithm.

A disc census finds hundreds of double-sided pairs per cave or town pack, dozens of exactly-coplanar decals inside single meshes, and hundreds of overlapping terrain-tile pairs. Shared by the native renderer and the site's WebGL viewers.

No distance culling

There is no frustum cull, draw-distance heuristic or LOD: field draw lists are resolved once at scene load and submitted whole every frame. SCENE_FAR = 1e6 for every camera (the overworld composes a 6× world scale, so eye depth reaches ~140k); the near plane is distance × 0.005 clamped to [0.05, 8]. A segment-vs-AABB occluder cull exists and is disabled by design - placement boxes span whole tiles, so the lens-to-player segment blinks out neighbours.

Five surfaces, one engine

A rendering fix that lands on one surface and not the others is invisible in a code diff. engine-render links wgpu, so the browser cannot depend on it; kernels in engine-core, engine-vm or legaia-tmd are the ones every surface shares.

Placement rotation is three angles on every surface (Rx · Ry · Rz); a yaw-only builder loses the scene on maps like juui1, which tilts all nine placements a quarter turn about X.

How we know

Full write-up - the per-prim dispatch table, the 2D packet emitters, the billboard projector, the transition emitter and the GTE emulator: docs/subsystems/renderer.md.

Details

See also