Triga — graphics and geometry

Triga is Faber's native graphics and geometry library: the typed contract between compiled Faber output and a GPU runtime host. It provides math, scene-graph, material, geometry, primitive, and resource types as public triga:* modules.

Shapes model the three.js abstractions for LLM familiarity and migration ease, but Triga is not a binding to three.js — these are native Faber types that define the same structural domain. In normal projects, declare Triga as a Cista package dependency in faber.toml; Cista records the resolved source in faber.lock and the compiler resolves it from the package store. FABER_LIBRARY_HOME is a resolver override for local development when set.

Triga is not part of Norma. It is an optional dependency that packages opt into when they need graphics or geometry work. The current package version is 0.2.0.

Modules#

Each triga:<stem> import resolves to src/<stem>.fab. The layout follows Norma's flat-leaf pattern; there is no type re-export, so consumers import the leaf that owns the class they use.

import from "triga:math" math
import from "triga:graph" graph
import from "triga:material" material
import from "triga:geometry" geometry
import from "triga:primitives" primitives
import from "triga:scene" scene
import from "triga:resource" resource

API shape#

Public operations on Triga's classes are receiver methods with an implicit self receiver. Free functions survive only as constructors (vector3, box_from_min_max, matrix_perspective), pure scalar helpers, and primitive generators.

Faber morphologia applies: Imperativus mutates a var receiver in place, while Perfectum returns a new value and leaves the receiver alone.

import from "triga:math" math

# Perfectum — returns a new Box3, receiver unchanged
const math.Box3 bounds ← math.Box3 { min = math.vector3(0.0, 0.0, 0.0), max = math.vector3(2.0, 2.0, 2.0) }
const math.Box3 expanded ← bounds.inflata(1.0)

# Imperativus — mutates the var receiver in place
var math.Box3 mutable ← math.Box3 { min = math.vector3(0.0, 0.0, 0.0), max = math.vector3(1.0, 1.0, 1.0) }
mutable.infla(2.0)

Vocabulary keeps the standard identity where that is the point: carrier nouns stay English (Vector3, Matrix4, Quaternion, Box3, Ray, BufferGeometry, f32, WebGPU), and operation methods are English verbs (normalized3 normalize, dot dot product, cross cross product, insert insert, attach attach, take get, find find, contains contains, set_visible visibility). The material constructor is material_from_name(name), and BufferGeometry attributes carry float32_values() payload projection for host upload.

Design#

• Structure-of-arrays layout: vertex attributes and matrix storage use flat list<f32>, not interleaved arrays. This maps directly to WGSL storage buffers and GPU buffer uploads.
• Composition over inheritance: PerspectiveCamera.base contains an Object3D rather than using type inheritance; MeshStandardMaterial.base contains a Material.
• Three.js field alignment: field names use Faber's snake_case convention while the structural hierarchy mirrors three.js (Object3D → Mesh → Scene, Material → MeshStandardMaterial).
• Module seams: Norma-style flat leaves — math / graph / material / face / geometry / primitives / scene / resource — with nested package dirs only when a directory holds 2–3+ modules.

Exempla#

Instructional demos live under triga/exempla/: triga-scene-store.fab (stable heterogeneous scene store with insert / attach / take / visibility queries), triga-transforms.fab (Vector3 / Matrix4 transform chains), triga-geometry-attributes.fab, triga-basics.fab, plus three Hello Voxel fixtures that exercise the @vertex / @fragment shader-surface path end to end.

Browser demos#

Triga ships browser-rendered demo scenes that exercise the triga:* surface end-to-end: Faber scene facts → faber build --package . browser product → direct WebGPU.

Run the corpus demos with cd triga/corpus && ./serve.sh (builds every demo and serves them at http://127.0.0.1:8780/). The Budapest and Drift City apps live under examples/ and serve locally via ./serve.sh from each directory. Each demo is a browser-app package whose public/*.js owns WebGPU transport only — no simulation constants or draw policy.

The sibling hosts/webgpu-browser repository is the browser-first WebGPU product boundary: it acquires the adapter/device, creates resources, encodes commands, and reads results back, consuming compiled Faber WGSL and MIR reflection metadata. Triga owns the source contracts; the host owns the browser runtime.

Status#