Renderingen-US

Experimental through version 1. Version 0 was alpha. This is the first language release: the interface is relatively stable, not frozen. Nothing is promised stable until version 2.

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. For local development, point the compiler at a checkout with --library-home <DIR> or [paths] library_home in faber.toml; without either, only the Norma library embedded in the binary is available.

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

Modules#

Each triga:<stem> import resolves to src/<stem>.fab, and a nested triga:<pkg>/<leaf> import resolves to src/<pkg>/<leaf>.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. The top-level graph, geometry, lighting, material, primitives and renderable modules are facades that point at their leaves.

ImportOwns
triga:mathBox<N>, Quaternion, Euler, Color, Sphere, Plane, Ray, transform payload, face-code tables, vector and matrix helpers over the language's vector<f32, size N> and matrix<f32, [R, C]>
triga:graph/objectObject, Scene
triga:graph/cameraPerspectiveCamera, OrthographicCamera, projection facts
triga:lighting/lightLight, AmbientLight, DirectionalLight, PointLight
triga:material/baseMaterial, TextureDescriptor, pipeline facts
triga:material/basic, lit, standardUnlitMaterial, PhongMaterial, StandardMaterial
triga:renderable/meshMesh: an Object, a geometry and an optional material
triga:faceFaceQuad + unit/colored quad builders
triga:geometry/dataGeometry, PrimitiveTopology, ColoredQuadMesh
triga:geometry/attribute, layout, bounds, batchVertex attributes, vertex layout, bounding volumes, draw batches
triga:primitives/basicDeterministic mesh generators (plane, box, sphere, cylinder, cone, torus, …)
triga:sceneSceneStore, SceneHandle, node kinds, traversal, visibility queries
triga:resourceResourceHandle + lifecycle operations
triga:shaderOpaque Texture2D and Sampler types and their bound functions
triga:trigaFacade / module map only (no classes)
import from "triga:math" math
import from "triga:geometry/data" data
import from "triga:primitives/basic" basic
import from "triga:lighting/light" light
import from "triga:material/base" base
import from "triga:resource" resource

API shape#

Public operations on Triga's own classes are receiver methods with an implicit self receiver. Free functions cover constructors (quaternion, box_from_min_max, matrix_perspective), pure scalar helpers, primitive generators, and graphics-domain work on the language's own vector and matrix types, which cannot grow receivers.

The math carriers are the language types vector<f32, size N> and matrix<f32, [R, C]>; Triga has no Vector3 or Matrix4 class. Faber morphologia governs receiver posture: the scene store is mutated in place on a mut receiver, while math values return a new value and leave the receiver alone.

import from "triga:math" math

fn demo() → math.Quaternion {
    # Free function: a constructor, no receiver exists yet
    let vector<f32, size 3> lo ← [0.0, 0.0, 0.0] ↦ vector<f32, size 3>
    let vector<f32, size 3> hi ← [2.0, 2.0, 2.0] ↦ vector<f32, size 3>
    let math.Box<3> ∪ none bounds ← math.box_from_min_max(lo, hi)

    # Receiver method: returns a new Quaternion, receiver unchanged
    let math.Quaternion turn ← math.quaternion(0.0, 0.0, 0.0, 2.0)
    return turn.normalized()
}

Names are English: carrier nouns (Quaternion, Box, Object, Geometry, f32, WebGPU) and operation methods (insert, attach, take, find, contains, set_visible). The material constructor is material_from_name(name), and Attribute values carry a float32_values() payload projection for host upload.

Design#

  • Structure-of-arrays layout: vertex attributes use flat list<f32> payloads, not interleaved arrays. This maps directly to WGSL storage buffers and GPU buffer uploads.
  • Composition over inheritance: PerspectiveCamera.base contains an Object rather than using type inheritance; StandardMaterial.base contains a Material; Mesh.base contains an Object.
  • Three.js field alignment: field names use Faber's snake_case convention while the structural hierarchy follows three.js (Object → Mesh, Material → StandardMaterial).
  • Module seams: Norma-style flat leaves — math, face, scene, resource, shader — with nested package dirs (graph/, geometry/, lighting/, material/, primitives/, renderable/) where a directory holds several 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 (vector / matrix 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.

DemoWhereWhat it pressures
webgl-geometriestriga/corpus/Every triga:primitives generator (plane, box, circle, sphere, cylinder, cone, torus), per-mesh colors, Geometry → interleaved host payload
webgl-geometry-terraintriga/corpus/Procedural mesh generation at scale (48² heightfield, ~4.6k triangles), value noise, central-difference normals, elevation color ramp
webgl-animation-orbit, webgl-animation-water, webgl-animation-terraintriga/corpus/Animated scenes: delta-driven frame updates, camera travel, shader-driven wave displacement, animated heightmap terrain
Triga Budapestexamples/triga-budapest/Stylized Budapest Chain Bridge: Danube plane, bridge deck, portal towers, suspension chains, skyline blocks — scene facts, many meshes, camera projection, material intent by object color
Triga Drift Cityexamples/triga-drift-city/Deterministic arcade-driving simulation: bounded city circuit, drift dynamics, collision response, chase camera, renderer-neutral Triga scene facts drawn by the WebGPU host

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.

Triga owns the source contracts. Each demo's public/ JavaScript is the browser transport: it acquires the WebGPU adapter and device, creates resources, and encodes commands from compiled Faber WGSL and reflection metadata. The browser seam for the DOM and Canvas2D is Tela (tela:dom, tela:canvas2d).

Status#

LayerState
Math / transformsNative Faber (vector<f32, size N>, matrix<f32, [R, C]>, quaternions, …)
Scene storeHandles, graph edits, world transforms
Buffer geometrySoA attributes, draw batches, vertex-layout reflection
Primitive generatorsDeterministic plane/box/sphere/… mesh builders
Browser WebGPU pathThe demos' own public/ JavaScript consumes compiled graphics artifacts; Triga owns source contracts, not the browser runtime