Triangles

Author: bobcao3

README.md

@@ -101,6 +101,7 @@ download menu, and the rAF render loop inside `mount`. Returns a controller:
 - `bar(key, a, b, radius, color, alpha)` — oriented cylinder a→b.
 - `sphere(key, pos, radius, color, alpha)` — a sphere.
 - `quad(key, verts, color, alpha)` — a filled quad (`verts`: 4 positions).
+- `triangles(key, tris, color, alpha)` — a filled triangle list (soup); `tris` is an array of triangles, each `[a, b, c]` of positions. Non-indexed geometry, DoubleSide; `color` is a `ColorArg` (static or per-frame `(f) => Color`), `alpha` per-frame; sig-rebuilds when any vertex moves. Use instead of `draw` + a hand-built tri mesh.
 - `label(key, pos, text, opts?)` — a 3D-anchored, screen-fixed text label with a rounded-rect backdrop pill. Sits on a 3D point (`pos`, resolved each frame so it follows the anchor) and stays a CONSTANT on-screen size by compensating the Sprite scale for the OrbitCam dolly (`baseSize / camera.zoom`). `opts`: `{ color?, backdrop?=true, backdropColor?, size?=0.14, alpha? }`.
 - `draw(key, object: THREE.Object3D, alpha)` — **custom primitive**: you supply any
   THREE object (Group/Mesh/LineSegments you built); the library retains it by key

src/core.ts

@@ -239,6 +239,18 @@ export function createFigure(
       g.setIndex([0, 1, 2, 0, 2, 3]);
       return g;
     };
+    const trisGeo = (tris: THREE.Vector3[][]): THREE.BufferGeometry => {
+      const g = new THREE.BufferGeometry();
+      const arr = new Float32Array(tris.length * 9);
+      tris.forEach((t, i) => {
+        for (let j = 0; j < 3; j++) {
+          const p = t[j], k = (i * 3 + j) * 3;
+          arr[k] = p.x; arr[k + 1] = p.y; arr[k + 2] = p.z;
+        }
+      });
+      g.setAttribute("position", new THREE.BufferAttribute(arr, 3));
+      return g;
+    };
 
     // ctx BUFFERS during draw(): nodes and draw calls are recorded and only
     // reconciled AFTER draw returns, because positions may be node keys
@@ -254,6 +266,7 @@ export function createFigure(
       | { kind: "line"; key: string; a: FigPos; b: FigPos; color: ColorArg; alpha: number }
       | { kind: "bar"; key: string; a: FigPos; b: FigPos; radius: number; color: ColorArg; alpha: number }
       | { kind: "quad"; key: string; verts: FigPos[]; color: ColorArg; alpha: number }
+      | { kind: "triangles"; key: string; tris: FigPos[][]; color: ColorArg; alpha: number }
       | { kind: "draw"; key: string; factory: () => THREE.Object3D; pos: FigPos; alpha: number; colorFn?: (f: Frame) => THREE.Color }
       | { kind: "label"; key: string; pos: FigPos; text: string; color: THREE.Color; backdrop: boolean; backdropColor: THREE.Color; size: number; alpha: number };
     const nodePlaces = new Map<string, NodePlace>();
@@ -385,6 +398,28 @@ export function createFigure(
         const m = e.mat!;
         m.color.copy(col); m.opacity = clamp01(dc.alpha); m.transparent = true;
         e.obj.visible = dc.alpha > 0.001;
+      } else if (dc.kind === "triangles") {
+        const tris = dc.tris.map((t) => t.map(resolveFigPos));
+        if (tris.some((t) => t.some((v) => !v))) return;
+        const flat = tris as THREE.Vector3[][];
+        drawnThisFrame.add(dc.key);
+        const col = evalColor(dc.color, f);
+        const s = sig(flat.flat());
+        let e = retained.get(dc.key);
+        if (!e) {
+          const mat = new THREE.MeshBasicMaterial({ color: col.clone(), transparent: true, opacity: 0, side: THREE.DoubleSide });
+          const obj = new THREE.Mesh(trisGeo(flat), mat);
+          scene.add(obj);
+          e = { obj, mat, kind: "triangles", ownsGeo: true, sig: s };
+          retained.set(dc.key, e);
+        } else if (e.sig !== s) {
+          (e.obj as THREE.Mesh).geometry.dispose();
+          (e.obj as THREE.Mesh).geometry = trisGeo(flat);
+          e.sig = s;
+        }
+        const m = e.mat!;
+        m.color.copy(col); m.opacity = clamp01(dc.alpha); m.transparent = true;
+        e.obj.visible = dc.alpha > 0.001;
       } else if (dc.kind === "label") {
         // 3D-anchored, screen-fixed text label: position is the resolved 3D
         // anchor (follows the corner); apparent on-screen SIZE is held
@@ -451,6 +486,7 @@ export function createFigure(
       line(key, a, b, color, alpha) { drawCalls.push({ kind: "line", key: full(key), a, b, color, alpha }); },
       bar(key, a, b, radius, color, alpha) { drawCalls.push({ kind: "bar", key: full(key), a, b, radius, color, alpha }); },
       quad(key, verts, color, alpha) { drawCalls.push({ kind: "quad", key: full(key), verts, color, alpha }); },
+      triangles(key, tris, color, alpha) { drawCalls.push({ kind: "triangles", key: full(key), tris, color, alpha }); },
       draw(key, factory, pos, alpha, colorFn) { drawCalls.push({ kind: "draw", key: full(key), factory, pos, alpha, colorFn }); },
       label(key, pos, text, opts) { drawCalls.push({ kind: "label", key: full(key), pos, text, color: opts?.color ?? LABEL_DEFAULT_COLOR, backdrop: opts?.backdrop ?? true, backdropColor: opts?.backdropColor ?? LABEL_DEFAULT_BACKDROP, size: opts?.size ?? LABEL_DEFAULT_SIZE, alpha: opts?.alpha ?? 1 }); },
       scope(prefix, fn) { stack.push(prefix); fn(); stack.pop(); },

src/types.ts

@@ -55,6 +55,14 @@ export type FigCtx = {
   line(key: string, a: FigPos, b: FigPos, color: ColorArg, alpha: number): void;
   bar(key: string, a: FigPos, b: FigPos, radius: number, color: ColorArg, alpha: number): void;
   quad(key: string, verts: FigPos[], color: ColorArg, alpha: number): void;
+  /** Filled triangle list (a triangle soup): each triangle is 3 {@link FigPos}
+   *  (a vector or a node key). One non-indexed BufferGeometry (3 verts/tri, no
+   *  vertex sharing), MeshBasicMaterial DoubleSide transparent; `color` is a
+   *  {@link ColorArg} (static or per-frame `(f) => Color`), `alpha` is per-frame.
+   *  The geometry sig-rebuilds when any vertex moves (like {@link quad}); the
+   *  library disposes the geometry on sig-change/drop. Use this instead of
+   *  `draw` + a hand-built tri mesh for filled triangle lists. */
+  triangles(key: string, tris: FigPos[][], color: ColorArg, alpha: number): void;
   /** Custom primitive: the library calls `factory()` once on first draw to build
    *  a THREE.Object3D, retains it by `key`, and each frame resolves `pos` (a vector
    *  or a node key), sets `object.position`, `object.visible = alpha > 0.001`, and