trid3d 0.1.1 → 0.3.0

package/trid/render/webglRenderer.js

@@ -1,27 +1,28 @@
 import { DEFAULT_FOV, DEFAULT_NEAR } from "../math/transform.js";
-import { clear, edgeSegments } from "./draw.js";
+import { normalMatrix, determinantMat4 } from "../math/matrix.js";
+import { worldObjects } from "../sceneGraph.js";
+import { clear, edgeSegments, wireEdges } from "./draw.js";
 import { parseColor } from "./color.js";
-import { DEFAULT_LIGHT, DEFAULT_AMBIENT } from "./canvasRenderer.js";
+import { DEFAULT_LIGHT, DEFAULT_AMBIENT, materialsOf } from "./canvasRenderer.js";
+import { uvsFor, uvTransform, mappingKey } from "./uvMapping.js";
 import { newell, cornerNormals, creaseOf } from "./normals.js";
 import { SURFACE_GLSL, buildEffects, effectsKey } from "./effects.js";
-import { textureReady, textureSize, textureIsLive } from "../loaders/texture.js";
+import { textureReady, textureSize, textureIsLive, textureVersion } from "../loaders/texture.js";
 
 /** Farthest distance drawn by the WebGL renderer, unless the camera sets `far`. */
 export const DEFAULT_FAR = 1000;
 
-// Trid's transform pipeline, written in GLSL. It matches localToWorld,
-// worldToCamera and project() exactly, so tools and picking line up.
+// Trid's transform pipeline, written in GLSL. It matches the objects' world
+// matrices, worldToCamera and project() exactly, so tools and picking line up.
 const COMMON = `
-uniform vec3 uPos, uRot, uScale;
+uniform mat4 uModel; // the object's world matrix (its parents' transforms included)
 uniform vec3 uCamPos;
 uniform vec2 uCamRot; // yaw, pitch
 uniform float uF, uAspect, uNear, uFar;
 
 vec3 rotX(vec3 p, float a) { float c = cos(a), s = sin(a); return vec3(p.x, p.y * c - p.z * s, p.y * s + p.z * c); }
 vec3 rotY(vec3 p, float a) { float c = cos(a), s = sin(a); return vec3(p.x * c - p.z * s, p.y, p.x * s + p.z * c); }
-vec3 rotZ(vec3 p, float a) { float c = cos(a), s = sin(a); return vec3(p.x * c - p.y * s, p.x * s + p.y * c, p.z); }
-vec3 rotXYZ(vec3 p) { return rotZ(rotY(rotX(p, uRot.x), uRot.y), uRot.z); }
-vec3 toWorld(vec3 v) { return rotXYZ(v * uScale) + uPos; }
+vec3 toWorld(vec3 v) { return (uModel * vec4(v, 1.0)).xyz; }
 vec3 toCamera(vec3 p) { return rotX(rotY(p - uCamPos, uCamRot.x), uCamRot.y); }
 vec4 toClip(vec3 p) {
   float a = (uFar + uNear) / (uFar - uNear);
@@ -38,11 +39,13 @@ varying vec3 vNormal;
 varying vec3 vWorld;
 varying vec3 vLocal;
 varying vec2 vUV;
+uniform mat3 uUVTransform; // textureRepeat, textureOffset, textureRotation
+uniform mat3 uNormalMatrix; // keeps normals right on stretched and mirrored objects
 ${COMMON}
 void main() {
-  vNormal = rotXYZ(aNormal / uScale); // inverse scale keeps normals right on stretched objects
+  vNormal = uNormalMatrix * aNormal;
   vLocal = aPos;
-  vUV = aUV;
+  vUV = (uUVTransform * vec3(aUV, 1.0)).xy;
   vWorld = toWorld(aPos);
   gl_Position = toClip(toCamera(vWorld));
 }
@@ -106,7 +109,7 @@ ${fx.calls}
   return { source, uniforms: fx.uniforms };
 }
 
-const FACE_UNIFORMS = ["uLight", "uAmbient", "uShade", "uTime", "uBackground", "uCamWorld", "uTexture", "uUseTexture"];
+const FACE_UNIFORMS = ["uUVTransform", "uNormalMatrix", "uLight", "uAmbient", "uShade", "uTime", "uBackground", "uCamWorld", "uTexture", "uUseTexture"];
 
 // Each line segment is a thin rectangle facing the screen, `uWidth` pixels wide
 const LINE_VS = `
@@ -142,7 +145,7 @@ void main() {
 }
 `;
 
-const UNIFORMS = ["uPos", "uRot", "uScale", "uCamPos", "uCamRot", "uF", "uAspect", "uNear", "uFar", "uColor"];
+const UNIFORMS = ["uModel", "uCamPos", "uCamRot", "uF", "uAspect", "uNear", "uFar", "uColor"];
 
 /**
  * Draws a scene with WebGL, on the graphics card.
@@ -158,6 +161,12 @@ const UNIFORMS = ["uPos", "uRot", "uScale", "uCamPos", "uCamRot", "uF", "uAspect
  *
  * Meshes are sent to the graphics card once and reused. After changing
  * a mesh's vertices, edges or faces in place, set `mesh.dirty = true`.
+ * Textures are sent once too (videos every frame): after redrawing a canvas,
+ * call `updateTexture(canvas)`.
+ *
+ * Meshes and textures that haven't been drawn for `releaseAfter` frames
+ * are freed from the graphics card, so replacing them (`obj.mesh = newMesh`)
+ * doesn't fill its memory. They're sent again if they come back.
  *
  * @example
  * const scene = new Scene(canvas, { renderer: new WebGLRenderer() });
@@ -176,9 +185,13 @@ export class WebGLRenderer {
   /**
    * @param {Object} [opts]
    * @param {boolean} [opts.antialias=true] - Smooth edges
+   * @param {number} [opts.releaseAfter=300] - Free meshes and textures not drawn for this many frames
+   *   (about 5 s at 60 fps). `Infinity` keeps everything until `dispose()`
    * @throws {Error} If WebGL isn't available (check `WebGLRenderer.isSupported()` first)
    */
-  constructor({ antialias = true } = {}) {
+  constructor({ antialias = true, releaseAfter = 300 } = {}) {
+    /** Frames a mesh or texture can go undrawn before it's freed (Infinity: never). */
+    this.releaseAfter = releaseAfter;
     /** The hidden canvas WebGL draws on. */
     this.canvas = document.createElement("canvas");
     this._options = { antialias, alpha: true, premultipliedAlpha: true, depth: true };
@@ -208,6 +221,9 @@ export class WebGLRenderer {
     this._buffers = new Set();
     this._textures = new WeakMap(); // image / canvas / video → GL texture
     this._glTextures = new Set();
+    // Last frame each mesh / texture source was drawn, to free the ones no longer used
+    this._meshUse = new Map();
+    this._textureUse = new Map();
     this._warned = new WeakSet();
     this._frame = 0;
 
@@ -264,20 +280,34 @@ export class WebGLRenderer {
 
     // Opaque things first; see-through ones after, without writing depth
     const opaque = [], clear2 = [];
-    for (const obj of scene.objects) {
+    // Every object with a mesh, groups' children included, with its world matrix
+    const drawn = worldObjects(scene).filter((o) => o.mesh);
+    for (const obj of drawn) {
       const geo = this._geometry(obj.mesh);
       const lineColor = this._color(ctx, obj.color ?? scene.color);
       const lineWidth = obj.lineWidth ?? scene.lineWidth;
-      const mat = obj.material;
-
-      if (mat) {
-        const fill = this._color(ctx, mat.fill ?? (mat.texture ? "#ffffff" : scene.color));
-        (fill[3] < 1 ? clear2 : opaque).push({ kind: "face", obj, geo, color: fill, mat });
-        if (mat.wireframe) {
-          (lineColor[3] < 1 ? clear2 : opaque).push({ kind: "line", obj, buf: geo.outlines, color: lineColor, width: lineWidth });
+      const mats = materialsOf(obj);
+
+      if (mats) {
+        // Normals turn with the object; a mirrored one has its faces' winding reversed
+        const place = { normals: normalMatrix(obj.world), mirrored: determinantMat4(obj.world) < 0 };
+        // One draw per group of faces sharing a material (mesh.faceMaterials)
+        const groups = geo.groups.map((g) => {
+          const k = g.index >= 0 && g.index < mats.length && mats[g.index] ? g.index : 0;
+          return { ...g, mat: mats[k] };
+        });
+        for (const g of groups) {
+          const fill = this._color(ctx, g.mat.fill ?? (g.mat.texture ? "#ffffff" : scene.color));
+          (fill[3] < 1 ? clear2 : opaque).push({ kind: "face", obj, geo, color: fill, mat: g.mat, first: g.first, count: g.count, place });
         }
+        const lines = (buf) => (lineColor[3] < 1 ? clear2 : opaque).push({ kind: "line", obj, buf, color: lineColor, width: lineWidth });
+        if (groups.every((g) => g.mat.wireframe)) lines(this._lineBuffer(geo, "outlines", () => outlinePairs(geo.faceList ?? [])));
+        else for (const g of groups) if (g.mat.wireframe) lines(this._outlineBuffer(geo, obj.mesh, g));
       } else {
-        (lineColor[3] < 1 ? clear2 : opaque).push({ kind: "line", obj, buf: geo.edges, color: lineColor, width: lineWidth });
+        (lineColor[3] < 1 ? clear2 : opaque).push({
+          kind: "line", obj, color: lineColor, width: lineWidth,
+          buf: this._lineBuffer(geo, "edges", () => edgeSegments(wireEdges(obj.mesh))),
+        });
       }
     }
 
@@ -288,7 +318,49 @@ export class WebGLRenderer {
     ctx.drawImage(this.canvas, 0, 0);
 
     // Meshes marked as changed have been sent again
-    for (const obj of scene.objects) if (obj.mesh.dirty) obj.mesh.dirty = false;
+    for (const obj of drawn) if (obj.mesh.dirty) obj.mesh.dirty = false;
+
+    if (this._frame % 60 === 0) this._sweep();
+  }
+
+  /**
+   * What the renderer keeps on the graphics card right now.
+   *
+   * @returns {{ meshes:number, buffers:number, textures:number }}
+   */
+  get memory() {
+    return { meshes: this._meshUse.size, buffers: this._buffers.size, textures: this._glTextures.size };
+  }
+
+  /**
+   * Frees a mesh's buffers or a texture's image on the graphics card now,
+   * instead of waiting for `releaseAfter`. If it's drawn again, it's sent again.
+   *
+   * @param {Object} item - A mesh, or a texture source (image, canvas, video)
+   */
+  release(item) {
+    if (!item || this._disposed) return;
+    const geo = this._meshes.get(item);
+    if (geo) {
+      for (const b of buffersOf(geo)) this._free(b);
+      this._meshes.delete(item);
+    }
+    this._meshUse.delete(item);
+    const t = this._textures.get(item);
+    if (t) {
+      this.gl.deleteTexture(t.tex);
+      this._glTextures.delete(t.tex);
+      this._textures.delete(item);
+    }
+    this._textureUse.delete(item);
+  }
+
+  /** Frees what hasn't been drawn for `releaseAfter` frames. */
+  _sweep() {
+    if (!(this.releaseAfter < Infinity)) return;
+    const oldest = this._frame - this.releaseAfter;
+    for (const [item, frame] of this._meshUse) if (frame < oldest) this.release(item);
+    for (const [item, frame] of this._textureUse) if (frame < oldest) this.release(item);
   }
 
   /** Frees the graphics card memory. The renderer can't be used afterwards. */
@@ -300,6 +372,8 @@ export class WebGLRenderer {
     for (const t of this._glTextures) gl.deleteTexture(t);
     this._glTextures.clear();
     this._buffers.clear();
+    this._meshUse.clear();
+    this._textureUse.clear();
     for (const p of new Set(this._faces.values())) gl.deleteProgram(p.program);
     gl.deleteProgram(this._line.program);
     gl.getExtension("WEBGL_lose_context")?.loseContext();
@@ -310,15 +384,15 @@ export class WebGLRenderer {
     const isFace = d.kind === "face";
     const effects = isFace ? d.mat.effects ?? [] : null;
     const prog = isFace ? this._faceProgram(effects) : this._line;
-    const buf = isFace ? this._faceBuffer(d.geo, d.obj.mesh, d.mat.shade === false ? null : creaseOf(d.mat.smooth)) : d.buf;
-    if (!buf.count) return;
+    const buf = isFace
+      ? this._faceBuffer(d.geo, d.obj.mesh, d.mat.shade === false ? null : creaseOf(d.mat.smooth), d.mat.mapping)
+      : d.buf;
+    const first = d.first ?? 0, count = d.count ?? buf.count;
+    if (!count) return;
 
     gl.useProgram(prog.program);
     const u = prog.uniforms;
-    const { pos, rot, scale } = d.obj;
-    gl.uniform3f(u.uPos, pos.x, pos.y, pos.z);
-    gl.uniform3f(u.uRot, rot.x, rot.y, rot.z);
-    gl.uniform3f(u.uScale, scale.x, scale.y, scale.z);
+    gl.uniformMatrix4fv(u.uModel, false, d.obj.world);
     gl.uniform3fv(u.uCamPos, view.camPos);
     gl.uniform2fv(u.uCamRot, view.camRot);
     gl.uniform1f(u.uF, view.f);
@@ -331,6 +405,10 @@ export class WebGLRenderer {
     const a = prog.attributes;
 
     if (isFace) {
+      const m = uvTransform(d.mat) ?? [1, 0, 0, 1, 0, 0];
+      gl.uniformMatrix3fv(u.uUVTransform, false, [m[0], m[1], 0, m[2], m[3], 0, m[4], m[5], 1]);
+      gl.uniformMatrix3fv(u.uNormalMatrix, false, d.place.normals);
+      gl.frontFace(d.place.mirrored ? gl.CCW : gl.CW);
       gl.uniform3fv(u.uLight, light);
       gl.uniform1f(u.uAmbient, ambient);
       gl.uniform1f(u.uShade, d.mat.shade === false ? 0 : 1);
@@ -346,7 +424,9 @@ export class WebGLRenderer {
       gl.vertexAttribPointer(a.aPos, 3, gl.FLOAT, false, 32, 0);
       if (a.aNormal >= 0) gl.vertexAttribPointer(a.aNormal, 3, gl.FLOAT, false, 32, 12);
       if (a.aUV >= 0) gl.vertexAttribPointer(a.aUV, 2, gl.FLOAT, false, 32, 24);
-      const tex = d.mat.texture ? this._texture(d.mat.texture, !!d.mat.pixelated, d.obj.mesh) : null;
+      const tex = d.mat.texture
+        ? this._texture(d.mat.texture, d.mat, d.obj.mesh, !!uvsFor(d.obj.mesh, d.mat.mapping).faceUVs)
+        : null;
       gl.activeTexture(gl.TEXTURE0);
       gl.bindTexture(gl.TEXTURE_2D, tex);
       gl.uniform1i(u.uTexture, 0);
@@ -363,7 +443,7 @@ export class WebGLRenderer {
     }
     const locs = Object.values(a).filter((loc) => loc >= 0);
     for (const loc of locs) gl.enableVertexAttribArray(loc);
-    gl.drawArrays(gl.TRIANGLES, 0, buf.count);
+    gl.drawArrays(gl.TRIANGLES, first, count);
     for (const loc of locs) gl.disableVertexAttribArray(loc);
   }
 
@@ -398,33 +478,53 @@ export class WebGLRenderer {
    * (canvases and videos: every frame). Null while it isn't ready,
    * or if the mesh has no texture coordinates.
    */
-  _texture(src, pixelated, mesh) {
+  _texture(src, mat, mesh, hasUVs) {
     const gl = this.gl;
+    const pixelated = !!mat.pixelated;
     if (!textureReady(src)) return null;
-    if (!mesh.faceUVs) {
+    if (!hasUVs) {
       if (!this._warned.has(mesh)) {
         this._warned.add(mesh);
-        console.warn("Trid: this mesh has no texture coordinates (uvs / faceUVs), so its texture isn't drawn");
+        console.warn("Trid: this mesh has no texture coordinates (uvs / faceUVs), so its texture isn't drawn. Set material.mapping to make some.");
       }
       return null;
     }
 
     let t = this._textures.get(src);
-    const live = textureIsLive(src);
-    if (!t || live || t.failed) {
+    const live = textureIsLive(src, mat);
+    const version = textureVersion(src);
+    this._textureUse.set(src, this._frame);
+    // Sent once, then again after updateTexture(src), or every frame when live
+    if (!t || live || t.version !== version || t.failed) {
       if (t?.failed) return null;
-      const { w, h } = textureSize(src);
+      let { w, h } = textureSize(src);
       if (!t) {
-        t = { tex: gl.createTexture(), frame: -1 };
+        t = { tex: gl.createTexture(), frame: -1, version: -1 };
         this._textures.set(src, t);
         this._glTextures.add(t.tex);
       }
       if (t.frame !== this._frame) {
+        const changed = t.version !== version;
         t.frame = this._frame;
+        t.version = version;
         gl.bindTexture(gl.TEXTURE_2D, t.tex);
+        // Bigger than the graphics card allows: upload a smaller copy
+        let pixels = src;
+        const max = gl.getParameter(gl.MAX_TEXTURE_SIZE);
+        if (w > max || h > max) {
+          const k = max / Math.max(w, h);
+          if (!t.small || live || changed) t.small = shrink(src, Math.floor(w * k), Math.floor(h * k), t.small);
+          if (!t.warned) {
+            t.warned = true;
+            console.warn(`Trid: a ${w} × ${h} texture is bigger than this graphics card allows (${max}), so it's drawn at ${t.small.width} × ${t.small.height}`);
+          }
+          pixels = t.small;
+          w = t.small.width;
+          h = t.small.height;
+        }
         gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, true); // images go top-down, v goes up
         try {
-          gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, src);
+          gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, pixels);
         } catch (err) {
           // Usually an image from another site without permission (CORS)
           console.warn("Trid: can't use this image as a texture: " + err.message);
@@ -463,61 +563,88 @@ export class WebGLRenderer {
 
   /** Graphics card buffers for a mesh, built once and rebuilt when it changes. */
   _geometry(mesh) {
+    this._meshUse.set(mesh, this._frame);
     let geo = this._meshes.get(mesh);
     const stale = !geo || mesh.dirty || geo.vertices !== mesh.vertices || geo.faceList !== mesh.faces
-      || geo.edgeList !== mesh.edges || geo.counts !== countsOf(mesh);
+      || geo.edgeList !== mesh.edges || geo.faceMats !== mesh.faceMaterials || geo.counts !== countsOf(mesh);
     if (!stale) return geo;
 
-    if (geo) {
-      for (const b of [geo.outlines, geo.edges, ...geo.faceBuffers.values()]) this._free(b);
-    }
-    const v = mesh.vertices;
+    if (geo) for (const b of buffersOf(geo)) this._free(b);
     const faces = mesh.faces ?? [];
 
-    // Outlines of the faces, each edge once
-    const outline = new Set();
-    const outlinePairs = [];
-    for (const f of faces) {
-      for (let k = 0; k < f.length; k++) {
-        const a = f[k], b = f[(k + 1) % f.length];
-        const key = a < b ? a + "," + b : b + "," + a;
-        if (!outline.has(key)) {
-          outline.add(key);
-          outlinePairs.push([a, b]);
-        }
-      }
+    // Faces grouped by material index, in the order the face buffers store them
+    const byIndex = new Map();
+    faces.forEach((f, fi) => {
+      if (f.length < 3) return;
+      const k = mesh.faceMaterials?.[fi] ?? 0;
+      if (!byIndex.has(k)) byIndex.set(k, []);
+      byIndex.get(k).push(fi);
+    });
+    const groups = [];
+    let first = 0;
+    for (const k of [...byIndex.keys()].sort((a, b) => a - b)) {
+      const list = byIndex.get(k);
+      const count = list.reduce((n, fi) => n + (faces[fi].length - 2) * 3, 0);
+      groups.push({ index: k, faces: list, first, count });
+      first += count;
     }
 
     geo = {
       vertices: mesh.vertices,
       faceList: mesh.faces,
       edgeList: mesh.edges,
+      faceMats: mesh.faceMaterials,
       counts: countsOf(mesh),
-      faceBuffers: new Map(), // one per shading mode, built when first needed
-      outlines: this._upload(lineData(v, outlinePairs), 8),
-      edges: this._upload(lineData(v, edgeSegments(mesh.edges ?? [])), 8),
+      groups,
+      groupOutlines: new Map(), // outlines of one group, when only some materials have `wireframe`
+      faceBuffers: new Map(), // one per shading mode and mapping, built when first needed
+      lines: new Map(), // "outlines" and "edges", built when first drawn (they're big on big models)
     };
     this._meshes.set(mesh, geo);
     return geo;
   }
 
+  /** A line buffer of the mesh, built the first time it's drawn. */
+  _lineBuffer(geo, name, pairs) {
+    let buf = geo.lines.get(name);
+    if (!buf) {
+      buf = this._upload(lineData(geo.vertices, pairs()), 8);
+      geo.lines.set(name, buf);
+    }
+    return buf;
+  }
+
+  /** Outlines of one group of faces (see `_geometry`), built when first needed. */
+  _outlineBuffer(geo, mesh, group) {
+    let buf = geo.groupOutlines.get(group.index);
+    if (!buf) {
+      const faces = mesh.faces ?? [];
+      buf = this._upload(lineData(mesh.vertices, outlinePairs(group.faces.map((fi) => faces[fi]))), 8);
+      geo.groupOutlines.set(group.index, buf);
+    }
+    return buf;
+  }
+
   /**
-   * Triangles of a mesh's faces, each corner with its own position and
-   * normal. Flat shading uses the face's normal at every corner; smooth
-   * shading uses the corner normals.
+   * Triangles of a mesh's faces, each corner with its own position,
+   * normal and texture coordinate, grouped by material (`geo.groups`).
+   * Flat shading uses the face's normal at every corner; smooth shading
+   * uses the corner normals. `mapping` picks the texture coordinates.
    */
-  _faceBuffer(geo, mesh, crease) {
-    const key = crease ?? "flat";
+  _faceBuffer(geo, mesh, crease, mapping) {
+    const key = (crease ?? "flat") + "|" + mappingKey(mapping);
     let buf = geo.faceBuffers.get(key);
     if (buf) return buf;
 
     const v = mesh.vertices;
     const faces = mesh.faces ?? [];
     const corners = crease ? cornerNormals(mesh, crease) : null;
-    const uvs = mesh.uvs, faceUVs = mesh.faceUVs;
-    const tri = [];
-    faces.forEach((f, fi) => {
-      if (f.length < 3) return;
+    const { uvs, faceUVs } = uvsFor(mesh, mapping);
+    const total = geo.groups.reduce((n, g) => n + g.count, 0);
+    const tri = new Float32Array(total * 8);
+    let o = 0;
+    for (const fi of geo.groups.flatMap((g) => g.faces)) {
+      const f = faces[fi];
       let ns;
       if (corners) {
         ns = corners[fi];
@@ -532,10 +659,12 @@ export class WebGLRenderer {
         for (const c of [0, k, k + 1]) {
           const p = v[f[c]], n = ns[c];
           const t = ts ? uvs[ts[c]] : null;
-          tri.push(p.x, p.y, p.z, n.x, n.y, n.z, t ? t.u : 0, t ? t.v : 0);
+          tri[o++] = p.x; tri[o++] = p.y; tri[o++] = p.z;
+          tri[o++] = n.x; tri[o++] = n.y; tri[o++] = n.z;
+          tri[o++] = t ? t.u : 0; tri[o++] = t ? t.v : 0;
         }
       }
-    });
+    }
 
     buf = this._upload(tri, 8);
     geo.faceBuffers.set(key, buf);
@@ -546,7 +675,7 @@ export class WebGLRenderer {
     const gl = this.gl;
     const buffer = gl.createBuffer();
     gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
-    gl.bufferData(gl.ARRAY_BUFFER, new Float32Array(data), gl.STATIC_DRAW);
+    gl.bufferData(gl.ARRAY_BUFFER, data instanceof Float32Array ? data : new Float32Array(data), gl.STATIC_DRAW);
     this._buffers.add(buffer);
     return { buffer, count: data.length / floatsPerVertex };
   }
@@ -568,18 +697,54 @@ export class WebGLRenderer {
   }
 }
 
+/** Every graphics card buffer of a mesh's geometry. */
+function buffersOf(geo) {
+  return [...geo.lines.values(), ...geo.faceBuffers.values(), ...geo.groupOutlines.values()];
+}
+
 /** A short string that changes when a mesh's arrays grow or shrink. */
 function countsOf(mesh) {
   return `${mesh.vertices.length}/${mesh.edges?.length ?? 0}/${mesh.faces?.length ?? 0}`;
 }
 
+/** A smaller copy of an image, drawn on a canvas (reused when given one). */
+function shrink(src, w, h, canvas = document.createElement("canvas")) {
+  canvas.width = w;
+  canvas.height = h;
+  canvas.getContext("2d").drawImage(src, 0, 0, w, h);
+  return canvas;
+}
+
+/** Each edge of the faces once, as [a, b] pairs. */
+function outlinePairs(faces) {
+  const seen = new Set();
+  const pairs = [];
+  for (const f of faces) {
+    for (let k = 0; k < f.length; k++) {
+      const a = f[k], b = f[(k + 1) % f.length];
+      const key = a < b ? a * 4294967296 + b : b * 4294967296 + a; // one number per edge
+      if (!seen.has(key)) {
+        seen.add(key);
+        pairs.push([a, b]);
+      }
+    }
+  }
+  return pairs;
+}
+
 /** Six corners (two triangles) per segment: A, B, then which corner. */
-function lineData(v, pairs) {
-  const out = [];
+function lineData(v, segments) {
+  const pairs = Array.isArray(segments) ? segments : [...segments]; // edgeSegments is a generator
+  const out = new Float32Array(pairs.length * 48);
   const corners = [[0, -1], [1, -1], [1, 1], [0, -1], [1, 1], [0, 1]];
+  let o = 0;
   for (const [i, j] of pairs) {
     const a = v[i], b = v[j];
-    for (const [cx, cy] of corners) out.push(a.x, a.y, a.z, b.x, b.y, b.z, cx, cy);
+    for (const [cx, cy] of corners) {
+      out[o++] = a.x; out[o++] = a.y; out[o++] = a.z;
+      out[o++] = b.x; out[o++] = b.y; out[o++] = b.z;
+      out[o++] = cx; out[o++] = cy;
+    }
   }
   return out;
 }

package/trid/scene.js

@@ -1,6 +1,8 @@
 import { CanvasRenderer, DEFAULT_LIGHT, DEFAULT_AMBIENT } from "./render/canvasRenderer.js";
 import { loop } from "./render/loop.js";
 import { ToolManager } from "./tools/manager.js";
+import { linkTree } from "./sceneGraph.js";
+import { screenshot, record } from "./export/capture.js";
 
 /**
  * Holds a canvas, a camera and a list of objects, and draws them.
@@ -70,27 +72,37 @@ export class Scene {
   }
 
   /**
-   * Adds an object to the scene, filling in missing transform fields.
+   * Adds an object to the scene, filling in missing transform fields
+   * (down its `children` too).
    *
-   * @param {{ mesh:{ vertices:{x:number,y:number,z:number}[], edges:number[][] } }} obj - Mesh instance
+   * An object can be a group: give it `children`, objects placed relative
+   * to it, and leave out `mesh` if it's only there to hold them. Moving it
+   * moves them all. See `trid/sceneGraph.js`.
+   *
+   * @example
+   * const car = scene.add({ children: [{ mesh: body }, { mesh: wheel, pos: { x: 0.4, y: -0.2, z: 0 } }] });
+   * car.pos.x += 0.1; // the body and the wheel move together
+   *
+   * @param {Object} obj - An object: `mesh` and/or `children`, plus pos, rot, scale, material...
    * @returns The same object, so it can be kept and animated
    */
   add(obj) {
-    obj.pos ??= { x: 0, y: 0, z: 0 };
-    obj.rot ??= { x: 0, y: 0, z: 0 };
-    obj.scale ??= { x: 1, y: 1, z: 1 };
+    linkTree(obj, null);
     this.objects.push(obj);
     return obj;
   }
 
   /**
-   * Removes an object from the scene. Does nothing if it isn't in it.
+   * Removes an object: from the scene's top level, or from its group's
+   * `children`. Its own children go with it. Does nothing if it isn't there.
    *
-   * @param {Object} obj - Object previously passed to `add`
+   * @param {Object} obj - Object previously added (or a child of one)
    */
   remove(obj) {
-    const i = this.objects.indexOf(obj);
-    if (i !== -1) this.objects.splice(i, 1);
+    const list = obj.parent ? obj.parent.children : this.objects;
+    const i = list?.indexOf(obj) ?? -1;
+    if (i !== -1) list.splice(i, 1);
+    if (obj.parent) obj.parent = null;
   }
 
   /**
@@ -150,6 +162,28 @@ export class Scene {
     this._stop = null;
   }
 
+  /**
+   * Draws a new frame and returns it as an image file (PNG by default).
+   * The page's canvas doesn't change. Save it with `download`.
+   *
+   * @param {import("./export/capture.js").ScreenshotOptions} [opts]
+   * @returns {Promise<Blob>}
+   */
+  screenshot(opts) {
+    return screenshot(this, opts);
+  }
+
+  /**
+   * Starts recording the canvas as a video. Call `stop()` on the result,
+   * or pass `duration`, then save `await recording.done` with `download`.
+   *
+   * @param {import("./export/capture.js").RecordOptions} [opts]
+   * @returns {import("./export/capture.js").Recording}
+   */
+  record(opts) {
+    return record(this, opts);
+  }
+
   /**
    * Stops the loop, removes every tool (and its event listeners) and
    * frees the renderer's resources. Use it when the scene is no longer needed.