trid3d 0.5.0 → 0.7.0

package/trid/render/canvasRenderer.js

@@ -7,7 +7,8 @@ import { newell, cornerNormals, creaseOf } from "./normals.js";
 import { textureReady, textureSize, textureIsLive, textureVersion } from "../loaders/texture.js";
 import { uvsFor, uvTransform, applyUVTransform } from "./uvMapping.js";
 import { DEFAULT_LIGHT, DEFAULT_AMBIENT, sceneLights, lightAt as lightOf, lightLevels } from "./lights.js";
-import { runCanvasPost } from "./post.js";
+import { runCanvasPost, activePost, maskedObjects } from "./post.js";
+import { shadowFlag, findGround, flattenOnGround } from "./shadows.js";
 
 export { newell };
 
@@ -125,7 +126,15 @@ export class CanvasRenderer {
     // For effects
     const camPos = { x: camera.x ?? 0, y: camera.y ?? 0, z: camera.z ?? 0 };
     const time = (performance.now() - this._start) / 1000;
-    const background = this._rgba(ctx, scene.background);
+    const background = this._rgba(ctx, scene.background ?? "transparent");
+    // Post effects drawn as lines along the meshes (outline()): silhouettes and creases
+    const contours = activePost(scene.post).filter((e) => e.contour).map((e) => ({ e, mask: maskedObjects(e) }));
+    const outlines = [];
+    // Ground shadows (see trid/render/shadows.js): the floor's faces, then the shadows, then the rest
+    const sun = lights.shadow && lights.shadow.dir.y > 0.01 ? lights.shadow : null;
+    const ground = sun ? sun.ground ?? findGround(drawn.filter((o) => materialsOf(o) && shadowFlag(o, "receiveShadow"))) : null;
+    const shadowing = ground !== null && (camera.y ?? 0) > ground;
+    const shadowPolys = [];
 
     for (const obj of drawn) {
       const mats = materialsOf(obj);
@@ -137,6 +146,18 @@ export class CanvasRenderer {
       const color = obj.color ?? scene.color;
       const lineWidth = obj.lineWidth ?? scene.lineWidth;
 
+      // Its faces flattened on the floor along the light
+      if (shadowing && mats && shadowFlag(obj, "castShadow")) {
+        for (const face of obj.mesh.faces ?? []) {
+          if (face.length < 3) continue;
+          const flat = flattenOnGround(face.map((i) => world[i]), sun.dir, ground);
+          if (flat.length < 3) continue;
+          const clipped = clipPolygon(flat.map((p) => worldToCamera(p, camera)), near);
+          if (clipped.length >= 3) shadowPolys.push(clipped.map(toScreen));
+        }
+      }
+      const onGround = shadowing && mats && shadowFlag(obj, "receiveShadow");
+
       if (!mats) {
         for (const [i, j] of edgeSegments(wireEdges(obj.mesh))) {
           const seg = clipNear(cam[i], cam[j], near);
@@ -213,11 +234,28 @@ export class CanvasRenderer {
         return (looks[k] ??= prepare(mats[k]));
       };
 
+      // Outline lines (outline()): placed in the drawing order once the faces are sorted
+      const lines = contours.length ? this._contours(obj, cam, flip, near, toScreen, contours) : null;
+      if (lines) outlines.push(lines);
+      let pendingF = -1, pendingStart = items.length, pendingGround = false;
+      // Marks the items of the last face with the face they come from, and whether it's floor
+      const attach = () => {
+        for (let k = pendingStart; k < items.length; k++) {
+          if (lines && pendingF >= 0) items[k].face = { lines, F: pendingF };
+          if (pendingGround) items[k].ground = true;
+        }
+      };
+
       const faces = split ? split.faces : sourceFaces;
       for (let f = 0; f < faces.length; f++) {
         const face = faces[f];
         if (face.length < 3) continue;
         const F = split ? split.origins[f] : f; // the mesh face this one comes from
+        attach();
+        pendingF = F;
+        pendingStart = items.length;
+        // Floor: lying on the ground level, facing up
+        pendingGround = onGround && face.every((i) => Math.abs(world[i].y - ground) < 1e-4) && newell(face.map((i) => world[i])).y * flip > 0;
         const L = lookOf(F);
         const { fill, shade, outline, corners } = L;
         const pts = face.map((i) => cam[i]);
@@ -333,11 +371,31 @@ export class CanvasRenderer {
           edges,
         });
       }
+      attach();
     }
 
     items.sort((a, b) => b.depth - a.depth);
 
-    for (const it of items) {
+    // Each outline line is drawn once every face around its two ends is: those
+    // faces don't cover it then, but nearer ones of other objects still do
+    const linesAfter = new Map(); // item index → lines to draw after it
+    if (outlines.length) {
+      items.forEach((it, k) => {
+        if (it.face) it.face.lines.last[it.face.F] = k;
+      });
+      for (const L of outlines) {
+        for (const ln of L.list) {
+          let k = -1;
+          for (const F of ln.faces) k = Math.max(k, L.last[F] ?? -1);
+          if (k < 0) continue;
+          if (!linesAfter.has(k)) linesAfter.set(k, []);
+          linesAfter.get(k).push(ln);
+        }
+      }
+    }
+
+    const drawItem = (n) => {
+      const it = items[n];
       ctx.beginPath();
       if (it.line) {
         ctx.moveTo(it.line[0].x, it.line[0].y);
@@ -345,7 +403,7 @@ export class CanvasRenderer {
         ctx.lineWidth = it.lineWidth;
         ctx.strokeStyle = it.color;
         ctx.stroke();
-        continue;
+        return;
       }
 
       if (it.texture) {
@@ -385,6 +443,31 @@ export class CanvasRenderer {
         ctx.strokeStyle = it.fill.css;
         ctx.stroke();
       }
+
+      const after = linesAfter.get(n);
+      if (after) {
+        ctx.save();
+        ctx.lineCap = "round";
+        for (const ln of after) {
+          ctx.beginPath();
+          ctx.moveTo(ln.p.x, ln.p.y);
+          ctx.lineTo(ln.q.x, ln.q.y);
+          ctx.lineWidth = ln.width;
+          ctx.strokeStyle = ln.color;
+          ctx.stroke();
+        }
+        ctx.restore();
+      }
+    };
+
+    const floor = shadowing && shadowPolys.length ? items.filter((it) => it.ground) : [];
+    if (floor.length) {
+      // Everything else stands on the floor, so it's in front of it: floor, shadows, then the rest
+      for (let n = 0; n < items.length; n++) if (items[n].ground) drawItem(n);
+      this._groundShadow(ctx, w, h, shadowPolys, floor, lights, sun, ground);
+      for (let n = 0; n < items.length; n++) if (!items[n].ground) drawItem(n);
+    } else {
+      for (let n = 0; n < items.length; n++) drawItem(n);
     }
 
     // Meshes marked as changed have been redrawn from their new data
@@ -394,6 +477,118 @@ export class CanvasRenderer {
     runCanvasPost(scene, scene.post, this._start);
   }
 
+  /**
+   * Darkens the floor where the shadows fall: the shadow shapes, blurred,
+   * kept only on the floor's faces, as dark as the light they take away.
+   */
+  _groundShadow(ctx, w, h, polys, floor, lights, sun, ground) {
+    const [shade, mask] = [0, 1].map((i) => {
+      const c = (this._scratch ??= [])[i] ??= document.createElement("canvas");
+      if (c.width !== w || c.height !== h) {
+        c.width = w;
+        c.height = h;
+      }
+      const g = c.getContext("2d");
+      g.clearRect(0, 0, w, h);
+      return { c, g };
+    });
+    // The shadows, all turned the same way so overlaps don't cancel out
+    if (typeof shade.g.filter === "string" && sun.softness > 0) shade.g.filter = `blur(${sun.softness}px)`;
+    shade.g.beginPath();
+    for (const poly of polys) {
+      const p = signedArea(poly) < 0 ? poly.slice().reverse() : poly;
+      shade.g.moveTo(p[0].x, p[0].y);
+      for (let k = 1; k < p.length; k++) shade.g.lineTo(p[k].x, p[k].y);
+      shade.g.closePath();
+    }
+    shade.g.fillStyle = "#000000";
+    shade.g.fill();
+    shade.g.filter = "none";
+    // Only on the floor
+    mask.g.beginPath();
+    for (const it of floor) {
+      mask.g.moveTo(it.poly[0].x, it.poly[0].y);
+      for (let k = 1; k < it.poly.length; k++) mask.g.lineTo(it.poly[k].x, it.poly[k].y);
+      mask.g.closePath();
+    }
+    mask.g.fillStyle = mask.g.strokeStyle = "#ffffff";
+    mask.g.fill();
+    mask.g.lineWidth = 1;
+    mask.g.stroke();
+    shade.g.globalCompositeOperation = "destination-in";
+    shade.g.drawImage(mask.c, 0, 0);
+    shade.g.globalCompositeOperation = "source-over";
+
+    // As dark as the share of the floor's light this light gives
+    const up = { x: 0, y: 1, z: 0 }, at = { x: 0, y: ground, z: 0 };
+    const all = Math.max(...lightOf(lights, up, at));
+    const without = Math.max(...lightOf({ ...lights, lights: lights.lights.filter((_, i) => i !== sun.index) }, up, at));
+    const alpha = all > 0 ? Math.min(1, Math.max(0, 1 - without / all)) : 0;
+    if (alpha <= 0) return;
+    ctx.save();
+    ctx.globalAlpha = alpha;
+    ctx.drawImage(shade.c, 0, 0);
+    ctx.restore();
+  }
+
+  /**
+   * Outline lines of one object, for post effects with `contour` (outline()):
+   * its silhouette (edges between a face seen from the front and one seen
+   * from behind, or with no other face) and its creases (two front faces
+   * meeting at more than the effect's `uCreaseAngle`).
+   *
+   * @returns {{ list: {p:Object, q:Object, faces:number[], color:string, width:number}[], last: number[] }|null}
+   *   `faces`: the mesh faces around the line's two ends. `last` is filled in after sorting
+   */
+  _contours(obj, cam, flip, near, toScreen, contours) {
+    const used = contours.filter((c) => !c.mask || c.mask.has(obj));
+    if (!used.length) return null;
+    const faces = obj.mesh.faces ?? [];
+    const { edges, spot, facesAt } = meshTopology(obj.mesh);
+    // Each face's normal in camera space, and whether it faces the camera
+    const info = faces.map((face) => {
+      if (face.length < 3) return null;
+      const pts = face.map((i) => cam[i]);
+      const n = normalize(newell(pts));
+      const c = centroid(pts);
+      const back = (n.x * c.x + n.y * c.y + n.z * c.z >= 0) !== (flip < 0);
+      return { n, front: !back };
+    });
+    const mats = materialsOf(obj);
+    const faceMats = obj.mesh.faceMaterials;
+    const shown = (F) => {
+      if (!info[F]) return false;
+      if (info[F].front) return true;
+      return !!(mats[faceMats?.[F] ?? 0] ?? mats[0])?.doubleSided;
+    };
+
+    const list = [];
+    for (const c of used) {
+      const u = c.e.uniforms ?? {};
+      const angle = u.uCreaseAngle ?? 180;
+      const cos = angle >= 180 ? -2 : Math.cos((angle * Math.PI) / 180);
+      const rgba = typeof u.uColor === "string" ? null : u.uColor;
+      const color = rgba ? `rgba(${Math.round(rgba[0] * 255)}, ${Math.round(rgba[1] * 255)}, ${Math.round(rgba[2] * 255)}, ${rgba[3] ?? 1})` : u.uColor ?? "#1a1a1a";
+      const width = u.uWidth ?? 2;
+      for (const { a, b, f1, f2 } of edges) {
+        let line;
+        if (f2 < 0) line = shown(f1); // open border
+        else {
+          const s1 = shown(f1), s2 = shown(f2);
+          if (s1 && s2) {
+            const p = info[f1].n, q = info[f2].n;
+            line = info[f1].front !== info[f2].front || p.x * q.x + p.y * q.y + p.z * q.z < cos;
+          } else line = s1 || s2; // the other one faces away
+        }
+        if (!line) continue;
+        const seg = clipNear(cam[a], cam[b], near);
+        if (!seg) continue;
+        list.push({ p: toScreen(seg[0]), q: toScreen(seg[1]), faces: [...new Set([...facesAt[spot[a]], ...facesAt[spot[b]]])], color, width });
+      }
+    }
+    return list.length ? { list, last: [] } : null;
+  }
+
   /**
    * Splits a mesh's big faces into triangles no longer than
    * maxFaceSize × the mesh's size. Cached until the mesh's faces change.
@@ -707,6 +902,74 @@ function withMidpoints(vertices, mids) {
   return out;
 }
 
+function signedArea(pts) {
+  let a = 0;
+  for (let i = 0; i < pts.length; i++) {
+    const p = pts[i], q = pts[(i + 1) % pts.length];
+    a += p.x * q.y - q.x * p.y;
+  }
+  return a;
+}
+
+const edgeCache = new WeakMap();
+
+/**
+ * Each edge of a mesh's faces once, with the (up to two) faces on its sides.
+ * Vertices at the same spot count as one, so seams (where a shape repeats
+ * vertices for its texture coordinates) aren't taken for open borders.
+ * Cached until the mesh's arrays change or `mesh.dirty` is set.
+ *
+ * @returns {{a:number, b:number, f1:number, f2:number}[]} `f2` is -1 on an open border
+ */
+export function meshEdges(mesh) {
+  return meshTopology(mesh).edges;
+}
+
+/**
+ * meshEdges, plus `spot` (vertex → id of its position) and `facesAt`
+ * (position id → the faces touching it).
+ */
+function meshTopology(mesh) {
+  const v = mesh.vertices, faces = mesh.faces ?? [];
+  const hit = edgeCache.get(mesh);
+  if (hit && !mesh.dirty && hit.v === v && hit.faces === faces && hit.counts === `${v.length}/${faces.length}`) return hit.topology;
+
+  // One id per spot
+  let size = 0;
+  for (const p of v) size = Math.max(size, Math.abs(p.x), Math.abs(p.y), Math.abs(p.z));
+  const step = (size || 1) * 1e-6;
+  const ids = new Map();
+  const spot = v.map((p) => {
+    const key = `${Math.round(p.x / step)},${Math.round(p.y / step)},${Math.round(p.z / step)}`;
+    let id = ids.get(key);
+    if (id === undefined) ids.set(key, (id = ids.size));
+    return id;
+  });
+
+  const byKey = new Map();
+  const edges = [];
+  const facesAt = Array.from({ length: ids.size }, () => []);
+  faces.forEach((f, F) => {
+    if (f.length < 3) return;
+    for (const i of f) if (facesAt[spot[i]].at(-1) !== F) facesAt[spot[i]].push(F);
+    for (let k = 0; k < f.length; k++) {
+      const a = f[k], b = f[(k + 1) % f.length];
+      const sa = spot[a], sb = spot[b];
+      if (sa === sb) continue;
+      const key = sa < sb ? sa * 4294967296 + sb : sb * 4294967296 + sa;
+      const e = byKey.get(key);
+      if (!e) {
+        const n = { a, b, f1: F, f2: -1 };
+        byKey.set(key, n);
+        edges.push(n);
+      } else if (e.f2 < 0 && e.f1 !== F) e.f2 = F;
+    }
+  });
+  const topology = { edges, spot, facesAt };
+  edgeCache.set(mesh, { v, faces, counts: `${v.length}/${faces.length}`, topology });
+  return topology;
+}
+
 function centroid(pts) {
   let x = 0, y = 0, z = 0;
   for (const p of pts) { x += p.x; y += p.y; z += p.z; }
@@ -719,7 +982,7 @@ function normalize(v) {
 }
 
 /** Cuts a camera-space polygon at z = near, keeping the part in front. */
-function clipPolygon(pts, near) {
+export function clipPolygon(pts, near) {
   if (pts.every((p) => p.z >= near)) return pts;
   const out = [];
   for (let i = 0; i < pts.length; i++) {

package/trid/render/draw.js

@@ -2,19 +2,29 @@ import { localToWorld, worldToCamera, cameraToScreen, clipNear, DEFAULT_NEAR } f
 import { transformPoint } from "../math/matrix.js";
 
 /**
- * Clears the entire canvas with a solid background color.
+ * Clears the entire canvas, then paints it with a background color.
  * This should usually be called once per frame before drawing.
  *
+ * A see-through color (`"transparent"`, or `rgba(...)` with an alpha below 1),
+ * or no color (`null`), lets the page behind the canvas show through.
+ *
  * @param {CanvasRenderingContext2D} ctx - Canvas 2D context
  * @param {number} w - Canvas width
  * @param {number} h - Canvas height
- * @param {string} color - Background color (CSS color)
+ * @param {string|null} [color] - Background color (CSS color); none: left see-through
  */
 export function clear(ctx, w, h, color) {
+  ctx.clearRect(0, 0, w, h);
+  if (!isVisible(color)) return;
   ctx.fillStyle = color;
   ctx.fillRect(0, 0, w, h);
 }
 
+/** Whether a background color paints anything (not null, empty or "transparent"). */
+function isVisible(color) {
+  return color != null && color !== "" && String(color).trim().toLowerCase() !== "transparent";
+}
+
 /**
  * Draws a square point centered at a given 2D position.
  * Useful for debugging or drawing vertices.

package/trid/render/lights.js

@@ -12,6 +12,7 @@
  * - `range`: a point light fades out smoothly and reaches nothing past it
  *   (default: no fading)
  * - `enabled: false` turns a light off without removing it
+ * - `shadows: true` (directional lights): it casts shadows, see trid/render/shadows.js
  *
  * Lights add up: a face gets the ambient lights, plus each other light
  * times how much the face turns toward it. Both renderers use at most
@@ -46,7 +47,10 @@ export function defaultLights(direction = DEFAULT_LIGHT, ambient = DEFAULT_AMBIE
   ];
 }
 
+import { shadowOptions } from "./shadows.js";
+
 let warnedTooMany = false;
+let warnedPointShadows = false;
 
 /**
  * A scene's lights, ready for shading: colors parsed and multiplied by
@@ -62,8 +66,10 @@ let warnedTooMany = false;
  *   ambientLevel: number,
  *   lights: { point:boolean, dir:{x,y,z}|null, pos:{x,y,z}|null, color:number[], range:number }[],
  *   mainDir: {x,y,z},
+ *   shadow: { index:number, dir:{x,y,z}, size:number, softness:number, bias:number, ground:number|null } | null,
  * }} `ambient` is the summed ambient color [r, g, b]; `ambientLevel` its brightest
- *   channel; `mainDir` the unit direction of the first directional light (for effects)
+ *   channel; `mainDir` the unit direction of the first directional light (for effects);
+ *   `shadow` the light casting shadows (`index` in `lights`) and its settings
  */
 export function sceneLights(scene, rgba) {
   const list = Array.isArray(scene.lights)
@@ -73,6 +79,7 @@ export function sceneLights(scene, rgba) {
   const ambient = [0, 0, 0];
   const lights = [];
   let mainDir = null;
+  let shadow = null;
   for (const l of list) {
     if (!l || l.enabled === false) continue;
     const k = l.intensity ?? 1;
@@ -90,11 +97,16 @@ export function sceneLights(scene, rgba) {
       continue;
     }
     if (l.type === "point") {
+      if (l.shadows && !warnedPointShadows) {
+        warnedPointShadows = true;
+        console.warn("Trid: point lights don't cast shadows yet, only directional ones");
+      }
       const p = l.position ?? { x: 0, y: 0, z: 0 };
       lights.push({ point: true, dir: null, pos: { x: p.x, y: p.y, z: p.z }, color, range: l.range > 0 ? l.range : 0 });
     } else {
       const dir = unit(l.direction ?? DEFAULT_LIGHT);
       mainDir ??= dir;
+      if (l.shadows && !shadow) shadow = { index: lights.length, dir, ...shadowOptions(l.shadows) };
       lights.push({ point: false, dir, pos: null, color, range: 0 });
     }
   }
@@ -103,6 +115,7 @@ export function sceneLights(scene, rgba) {
     ambientLevel: Math.max(...ambient),
     lights,
     mainDir: mainDir ?? unit(DEFAULT_LIGHT),
+    shadow,
   };
 }
 

package/trid/render/post.js

@@ -18,11 +18,23 @@
  * - `uniforms`: settings used by the code, like `{ uStrength: 0.5 }`. Same
  *   types as material effects; read every frame
  * - `enabled: false` turns the effect off without removing it
+ * - `geometry: true`: the effect also reads the scene's depth and normals
+ *   (WebGL renderer). Its GLSL can then call `depthAt(uv)`, `normalAt(uv)`
+ *   and `maskAt(uv)`, see below. The renderer draws them in one extra pass,
+ *   only while such an effect is on
+ * - `objects`: with `geometry`, the objects `maskAt` is 1 on (their children
+ *   too). Default: every object
  *
  * In GLSL, every pass can call:
  * - `frame(uv)`: the previous pass's picture (the first pass: the picture
  *   this effect starts from)
  * - `source(uv)`: the picture this effect starts from
+ * With `geometry: true`, also:
+ * - `depthAt(uv)`: distance from the camera, along its view (`f.far` or more
+ *   where nothing is drawn). Only opaque faces count, not lines
+ * - `normalAt(uv)`: the surface's normal, in camera space (z points away from
+ *   the camera, so faces seen from the front have z < 0)
+ * - `maskAt(uv)`: 1 on the effect's `objects`, else 0 (nothing drawn: 0)
  * Colors are premultiplied by alpha (the same as plain colors where the
  * picture is opaque, which it is when the scene has an opaque background).
  *
@@ -32,6 +44,7 @@
  */
 
 import { parseColor } from "./color.js";
+import { DEFAULT_NEAR } from "../math/transform.js";
 
 /**
  * What a post effect knows about the picture. GLSL fields and the canvas
@@ -44,6 +57,8 @@ import { parseColor } from "./color.js";
  * @property {{x:number,y:number}} texel - GLSL only: one pixel of the input picture, in uv units
  * @property {number} time - Seconds since the renderer started
  * @property {number[]} background - The scene's background color [r, g, b, a]
+ * @property {number} near - The camera's near distance
+ * @property {number} far - The camera's far distance (WebGL renderer: what's farther isn't drawn)
  */
 
 /** The GLSL declaration of `Frame`, and the `frame` / `source` helpers. */
@@ -54,6 +69,8 @@ struct Frame {
   vec2 texel;
   float time;
   vec4 background;
+  float near;
+  float far;
 };
 uniform sampler2D uFrame;
 uniform sampler2D uSource;
@@ -61,6 +78,52 @@ vec4 frame(vec2 uv) { return texture2D(uFrame, uv); }
 vec4 source(vec2 uv) { return texture2D(uSource, uv); }
 `;
 
+/**
+ * GLSL helpers for effects with `geometry: true`: `depthAt`, `normalAt` and
+ * `maskAt`. They read a picture where each pixel packs the surface's normal
+ * (red, green) and its distance on a log scale between near and far (blue,
+ * alpha), with the mask in alpha's lowest bit.
+ */
+export const GEOMETRY_GLSL = `
+uniform sampler2D uGeometry;
+uniform float uGeoNear;
+uniform float uGeoRange; // log(far / near)
+vec4 geoTexel(vec2 uv) { return floor(texture2D(uGeometry, uv) * 255.0 + 0.5); }
+float depthAt(vec2 uv) {
+  vec4 g = geoTexel(uv);
+  return uGeoNear * exp((g.b * 128.0 + floor(g.a / 2.0)) / 32766.0 * uGeoRange);
+}
+vec3 normalAt(vec2 uv) {
+  vec2 p = geoTexel(uv).rg / 127.5 - 1.0;
+  vec3 n = vec3(p, 1.0 - abs(p.x) - abs(p.y));
+  if (n.z < 0.0) n.xy = (1.0 - abs(n.yx)) * vec2(n.x >= 0.0 ? 1.0 : -1.0, n.y >= 0.0 ? 1.0 : -1.0);
+  return normalize(n);
+}
+float maskAt(vec2 uv) { return mod(geoTexel(uv).a, 2.0); }
+`;
+
+/** Whether a post effect reads the scene's depth and normals (`geometry: true`, with GLSL). */
+export function wantsGeometry(effect) {
+  return !!effect?.geometry && postPasses(effect).length > 0;
+}
+
+/**
+ * Every object an effect's `objects` list covers, children included, as a
+ * Set. Null when the effect has no list (it covers everything).
+ */
+export function maskedObjects(effect) {
+  const list = effect?.objects;
+  if (!Array.isArray(list)) return null;
+  const out = new Set();
+  const visit = (o) => {
+    if (!o || typeof o !== "object" || out.has(o)) return;
+    out.add(o);
+    if (Array.isArray(o.children)) o.children.forEach(visit);
+  };
+  list.forEach(visit);
+  return out;
+}
+
 /** A post effect's passes, as `{ glsl, scale }`. Empty when it has no GLSL (canvas only). */
 export function postPasses(effect) {
   if (Array.isArray(effect.passes)) return effect.passes.filter((p) => p?.glsl).map((p) => ({ glsl: p.glsl, scale: p.scale > 0 ? p.scale : 1 }));
@@ -90,8 +153,10 @@ export function runCanvasPost(scene, list, start) {
     time: (performance.now() - start) / 1000,
     canvas,
     rgba: (v) => (typeof v === "string" ? parseColor(ctx, v).map((x, i) => (i < 3 ? x / 255 : x)) : v),
+    near: scene.camera?.near ?? DEFAULT_NEAR,
+    far: scene.camera?.far ?? 1000,
   };
-  frame.background = frame.rgba(scene.background ?? "#000000");
+  frame.background = frame.rgba(scene.background ?? "transparent");
   for (const e of effects) {
     ctx.save();
     try {
@@ -290,6 +355,95 @@ vec4 post(vec4 color, Frame f) {
   };
 }
 
+/** Crease angle the outline uses when `creases` isn't given, in degrees. */
+export const DEFAULT_OUTLINE_CREASE = 40;
+
+/**
+ * Cartoon-style lines: around each object (where the distance jumps:
+ * silhouettes, and where one object passes in front of another) and,
+ * with `creases`, inside it where the surface turns sharply (a cube's edges).
+ * Lines are drawn on the nearer side of a jump, so they hug the objects.
+ *
+ * Smooth-shaded surfaces (`smooth: true`) only get lines where their shading
+ * keeps a hard edge; flat-shaded ones get one wherever faces meet at more
+ * than `creases` degrees.
+ *
+ * The canvas renderer draws the meshes' outer edges and creases as lines
+ * instead (sorted with the faces), so the same scene looks close on both.
+ *
+ * @param {Object} [opts]
+ * @param {string} [opts.color="#1a1a1a"] - Line color (its alpha makes lines see-through)
+ * @param {number} [opts.width=2] - Line width, in pixels (WebGL: up to 16)
+ * @param {number|false} [opts.creases=40] - Draw a line where the surface turns by more than this
+ *   many degrees. `false`: outer lines only
+ * @param {number} [opts.depth=1] - How readily a jump in distance makes a line (WebGL): higher finds
+ *   smaller steps (an object resting on another), 0 = none (creases only)
+ * @param {Object[]} [opts.objects] - Only outline these objects (and their children). Default: all
+ */
+export function outline({ color = "#1a1a1a", width = 2, creases = DEFAULT_OUTLINE_CREASE, depth = 1, objects } = {}) {
+  return {
+    name: "outline",
+    geometry: true,
+    contour: true,
+    objects,
+    uniforms: { uColor: color, uWidth: width, uCreaseAngle: creases === false ? 180 : creases, uDepth: depth },
+    passes: [
+      {
+        // Where the lines are, 1 pixel thin (red channel)
+        glsl: `
+vec4 post(vec4 color, Frame f) {
+  if (maskAt(f.uv) < 0.5) return vec4(0.0); // not an outlined object (or nothing there)
+  float zc = depthAt(f.uv);
+  vec2 d = f.texel;
+
+  // Jumps in distance. 1 / distance changes evenly across a flat face, so its
+  // second difference is 0 there and big at a jump; > 0 only on the nearer side.
+  float ic = 1.0 / zc;
+  float jx = 2.0 * ic - 1.0 / depthAt(f.uv - vec2(d.x, 0.0)) - 1.0 / depthAt(f.uv + vec2(d.x, 0.0));
+  float jy = 2.0 * ic - 1.0 / depthAt(f.uv - vec2(0.0, d.y)) - 1.0 / depthAt(f.uv + vec2(0.0, d.y));
+  float line = smoothstep(0.03, 0.08, max(jx, jy) / ic * uDepth);
+
+  // Creases: the normal turns sharply toward the next pixel, on the same surface
+  if (uCreaseAngle < 180.0) {
+    vec3 nc = normalAt(f.uv);
+    float bend = 0.0;
+    for (int k = 0; k < 2; k++) {
+      vec2 uv = f.uv + (k == 0 ? vec2(d.x, 0.0) : vec2(0.0, d.y));
+      if (abs(depthAt(uv) - zc) > zc * 0.05) continue; // another object: the jump test handles it
+      bend = max(bend, 1.0 - dot(nc, normalAt(uv)));
+    }
+    float limit = 1.0 - cos(radians(uCreaseAngle));
+    line = max(line, smoothstep(limit * 0.8, limit * 1.2 + 1e-3, bend));
+  }
+  return vec4(line, 0.0, 0.0, 1.0);
+}`,
+      },
+      // Widened to `width` pixels: across, then down (soft at the ends)
+      { glsl: widen("vec2(1.0, 0.0)", "return vec4(w, 0.0, 0.0, 1.0);") },
+      {
+        glsl: widen("vec2(0.0, 1.0)", `
+  float a = w * uColor.a;
+  return source(f.uv) * (1.0 - a) + vec4(uColor.rgb * a, a);`),
+      },
+    ],
+  };
+}
+
+/** One direction of the outline's widening: the strongest line nearby, by distance. */
+function widen(dir, finish) {
+  return `
+vec4 post(vec4 color, Frame f) {
+  float reach = max(uWidth, 1.0) * 0.5 + 0.5; // full strength up to here, fading over the next pixel
+  float w = 0.0;
+  for (int i = -8; i <= 8; i++) {
+    float o = float(i);
+    if (abs(o) > reach) continue;
+    w = max(w, frame(f.uv + ${dir} * o * f.texel).r * clamp(reach - abs(o), 0.0, 1.0));
+  }
+${finish}
+}`;
+}
+
 // --- Helpers for the canvas versions ---
 
 function supportsFilter(ctx) {