trid3d 0.6.0 → 0.7.0

package/README.md

@@ -20,15 +20,15 @@ Trid gives you a scene, shapes you can model in code, lights, effects, model loa
 - **Modeling** — smooth curves through a few points (`spline`), shapes swept along a 3D path (`sweep`: tails, horns, pipes, rails), surfaces through cross-sections (`loft`: bodies, bottles, hulls, heads), subdivision surfaces with creases (`subdivideMesh`: box modeling), shapes that melt together (`blobMesh`: creatures, clay; or any distance field with `sdfMesh`), rounded or cut edges on any mesh (`bevelMesh`), taper, twist, bend and bulge deformers, mesh cleanup and checks (weld, clean, validate, fix winding), and rays, inside tests and distances against meshes and scenes (`meshQuery`, `raycastScene`).
 - **Mesh helpers** — clone, transform, displace, merge and measure meshes; seeded random numbers and smooth noise (`fbm2`, `fbm3`, tileable) for rocks, terrain and procedural textures.
 - **Filled faces** — give an object a `material` to fill and shade its faces, flat or smooth.
-- **Lights** — ambient, directional and point lights, with colors and intensities, as many as you need (up to 8 at once besides ambient).
+- **Lights and shadows** — ambient, directional and point lights, with colors and intensities, as many as you need (up to 8 at once besides ambient). A directional light can cast soft shadows (a shadow map with WebGL, ground shadows on the canvas).
 - **Textures** — images, canvases or videos on faces, with texture coordinates from built-in shapes and OBJ files, or made from the shape (planar, box, sphere and cylinder mapping). Repeat, offset and rotate them, or give each face its own material. Or paint one in code: wood, marble, bricks and more, all seamless.
 - **Effects** — stack shader effects like toon, rim and edge glow, gradients and fog on a material, or write your own in GLSL.
-- **Post effects** — bloom, vignette, color grading and film grain over the whole picture, or your own full-screen shaders (several passes if needed).
+- **Post effects** — bloom, vignette, color grading, film grain and cartoon outlines over the whole picture, or your own full-screen shaders (several passes if needed, reading the scene's depth and normals if wanted).
 - **Two renderers** — the canvas 2D context by default, or `WebGLRenderer` for exact depth and big models, with the same scene code.
 - **OBJ files** — load models from a URL (with their `.mtl` colors and textures), or let users drop their own `.obj` files on the canvas.
 - **Export** — `scene.screenshot()` and `scene.record()` save images and videos of the canvas; `exportOBJ` / `exportModel` write meshes, objects or whole scenes as OBJ files with their MTL materials and textures.
 - **Camera** — position, yaw, pitch and field of view (50° by default), with near-plane clipping.
-- **Tools** — orbit and fly cameras, object dragging, hover highlight, a move / rotate / scale gizmo (with a pivot of your choice), a view axes gizmo, a floor grid, an FPS meter and an OBJ uploader, one line each. Exact picking by triangles, with the hit point and texture coordinates under the mouse. Writing your own is a plain object with a few methods.
+- **Tools** — orbit and fly cameras, object dragging, hover highlight, a selection outline, a move / rotate / scale gizmo (with a pivot of your choice), a view axes gizmo, a floor grid, an FPS meter and an OBJ uploader, one line each. Exact picking by triangles, with the hit point and texture coordinates under the mouse. Writing your own is a plain object with a few methods.
 - **Pure math** — every transform and projection step is exported, plus 4×4 matrices and rotations, so you can use the pipeline piece by piece.
 
 ## Install
@@ -41,7 +41,7 @@ No bundler? Use the CDN with an import map, or copy the `trid/` folder next to y
 
 ```html
 <script type="importmap">
-  { "imports": { "trid3d": "https://cdn.jsdelivr.net/npm/trid3d@0.6/trid/index.js" } }
+  { "imports": { "trid3d": "https://cdn.jsdelivr.net/npm/trid3d@0.7/trid/index.js" } }
 </script>
 ```
 
@@ -122,10 +122,17 @@ See [`docs/README.md`](https://github.com/ZachR622/Trid/blob/master/docs/README.
 npm test
 ```
 
-Uses Node's built-in test runner (Node 21+), so there's nothing to install. The tests cover shapes (lathe poles included), mesh helpers, curves, sweeps, lofts, subdivision, blobs, bevels, deformers, mesh cleanup, mesh and scene queries, noise, textures, OBJ / MTL, picking, tools, groups and matrices, lights, post effects, grids, the field of view, see-through backgrounds, and the WebGL renderer's GPU memory on a fake WebGL context.
+Uses Node's built-in test runner (Node 21+), so there's nothing to install. The tests cover shapes (lathe poles included), mesh helpers, curves, sweeps, lofts, subdivision, blobs, bevels, deformers, mesh cleanup, mesh and scene queries, noise, textures, OBJ / MTL, picking, tools, groups and matrices, lights, shadows, post effects, grids, the field of view, see-through backgrounds, and the WebGL renderer's GPU memory on a fake WebGL context.
 
 ## Upgrading
 
+### From 0.6 to 0.7
+
+Nothing changes for existing scenes: shadows, outlines and the selection outline are all off until asked for. Only names Trid now uses itself could clash with yours:
+
+- In **post effect GLSL**, `Frame` has two more fields (`f.near`, `f.far`), and the uniforms `uNear`, `uFar`, `uGeometry`, `uGeoNear` and `uGeoRange` are taken. A post effect declaring its own uniform with one of those names needs to rename it.
+- In **material effect GLSL**, the functions `tridShadow` and `tridShadowDepth` and the uniforms starting with `uShadow` (plus `uReceive`) are taken. Effect uniforms are renamed by Trid, so only helper functions with those names would clash.
+
 ### From 0.5 to 0.6
 
 - **The cone's tip is a single point** (a pole), so the cone is closed: `isClosed` and `validateMesh` no longer report a hole there. It has fewer vertices than before (its tip ring of 32 is now 1), and its side faces are triangles. Any `lathe` profile point with `r: 0` works the same way.
@@ -150,7 +157,8 @@ Uses Node's built-in test runner (Node 21+), so there's nothing to install. The
 
 Roughly in order:
 
-- **More import and export formats** — STL; basic glTF later
-- **More tools** — a selection outline
-- **More post effects** — outlines (from depth), antialiasing (FXAA)
+- **More shadows** — point lights casting shadows, and several lights at once
+- **Combining shapes** — union, subtract and intersect meshes (CSG)
 - **More tests** — the canvas renderer's drawing and the remaining math functions
+- **More import and export formats** — STL; basic glTF later
+- **More post effects** — antialiasing (FXAA)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trid3d",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "A small 3D library for the HTML canvas: wireframes, filled and smooth faces, textures and shader effects, drawn with Canvas 2D or WebGL. No dependencies.",
   "keywords": [
     "3d",

package/trid/index.d.ts

@@ -164,6 +164,10 @@ export interface SceneObjectInput {
   hoverable?: boolean;
   /** Set to false so `pick` / `pickHit` never find this object or its children (helpers like a grid) */
   pickable?: boolean;
+  /** Set to false so this object (and its children) casts no shadow */
+  castShadow?: boolean;
+  /** Set to false so no shadow falls on this object (and its children) */
+  receiveShadow?: boolean;
 }
 
 /**
@@ -459,8 +463,35 @@ export interface DirectionalLight {
   color?: string;
   intensity?: number;
   enabled?: boolean;
+  /** Cast shadows (the first directional light with it does): true, or settings */
+  shadows?: boolean | ShadowOptions;
 }
 
+/** Shadow settings of a directional light. */
+export interface ShadowOptions {
+  /** Shadow map width in pixels (WebGL, default 2048). Bigger: sharper, slower */
+  size?: number;
+  /** Edge blur, in shadow map pixels (default 1.5; 0 = sharp) */
+  softness?: number;
+  /** Raise if lit surfaces get speckles; too high and shadows come loose (default 1) */
+  bias?: number;
+  /** Floor height for the canvas renderer's ground shadows (default: found) */
+  ground?: number;
+}
+
+/** Settings used for `shadows: true`. */
+export const DEFAULT_SHADOWS: Readonly<Required<Omit<ShadowOptions, "ground">> & { ground: null }>;
+/** A light's shadow settings, defaults filled in. */
+export function shadowOptions(value: boolean | ShadowOptions): Required<Omit<ShadowOptions, "ground">> & { ground: number | null };
+/** False when the object or one of its groups sets `key` to false. */
+export function shadowFlag(obj: SceneObject, key: "castShadow" | "receiveShadow"): boolean;
+/** The shadow map's box around casting objects (`matrix`: world → -1..1, column-major). */
+export function shadowFrame(casters: SceneObject[], dir: Vec3): { matrix: Float32Array; radius: number } | null;
+/** The floor height for ground shadows: where receivers have the most area of upward flat faces. */
+export function findGround(receivers: SceneObject[]): number | null;
+/** A world polygon's part above `ground`, flattened onto it along the light (`dir`: where it comes from). */
+export function flattenOnGround(pts: Vec3[], dir: Vec3, ground: number): Vec3[];
+
 /** Light from a point, like a bulb. */
 export interface PointLight {
   type: "point";
@@ -490,6 +521,8 @@ export interface SceneLights {
   lights: { point: boolean; dir: Vec3 | null; pos: Vec3 | null; color: [number, number, number]; range: number }[];
   /** Unit direction of the first directional light */
   mainDir: Vec3;
+  /** The light casting shadows (`index` in `lights`) and its settings, or null */
+  shadow: ({ index: number; dir: Vec3 } & Required<Omit<ShadowOptions, "ground">> & { ground: number | null }) | null;
 }
 
 /** A scene's lights, colors parsed and multiplied by intensity, directions unit length. */
@@ -704,6 +737,10 @@ export interface PostFrame {
   canvas: HTMLCanvasElement;
   /** Turns a uniform value (CSS color, array) into RGBA 0..1 */
   rgba(value: UniformValue): RGBA;
+  /** The camera's near distance */
+  near: number;
+  /** The camera's far distance */
+  far: number;
 }
 
 /** One pass of a post effect. */
@@ -727,8 +764,46 @@ export interface PostEffect<U extends Record<string, UniformValue> = Record<stri
   uniforms?: U;
   /** Set to false to turn it off without removing it */
   enabled?: boolean;
+  /** Also read the scene's depth and normals (WebGL): GLSL gets `depthAt(uv)`, `normalAt(uv)` and `maskAt(uv)` */
+  geometry?: boolean;
+  /** With `geometry`: the objects `maskAt` is 1 on (children included). Default: all */
+  objects?: SceneObject[];
+  /** Canvas renderer: draw the meshes' silhouettes and creases as lines, using `uColor`, `uWidth` and `uCreaseAngle` */
+  contour?: boolean;
 }
 
+/** Cartoon-style lines around objects and along their sharp creases. */
+export function outline(opts?: {
+  color?: string;
+  width?: number;
+  /** Degrees the surface must turn for an inner line (default 40); false = outer lines only */
+  creases?: number | false;
+  /** How readily a jump in distance makes a line (default 1; 0 = none) */
+  depth?: number;
+  /** Only outline these objects (and their children) */
+  objects?: SceneObject[];
+}): PostEffect<{
+  uColor: string;
+  uWidth: number;
+  uCreaseAngle: number;
+  uDepth: number;
+}>;
+
+/** Crease angle `outline()` uses by default, in degrees (40). */
+export const DEFAULT_OUTLINE_CREASE: number;
+
+/** Whether a post effect reads the scene's depth and normals (`geometry: true`, with GLSL). */
+export function wantsGeometry(effect: PostEffect): boolean;
+
+/** The objects an effect's `objects` list covers, children included (null: all). */
+export function maskedObjects(effect: PostEffect): Set<SceneObject> | null;
+
+/** GLSL helpers `depthAt`, `normalAt` and `maskAt`, for effects with `geometry: true`. */
+export const GEOMETRY_GLSL: string;
+
+/** Each edge of a mesh's faces once, with the faces on its sides (`f2` = -1 on an open border). */
+export function meshEdges(mesh: Mesh): { a: number; b: number; f1: number; f2: number }[];
+
 /** Darkens the corners of the picture. */
 export function vignette(opts?: { strength?: number; radius?: number; softness?: number; color?: string }): PostEffect<{
   uStrength: number;
@@ -1323,6 +1398,36 @@ export interface TransformGizmoOptions {
   onChange?: (op: TransformOp, targets: SceneObject[]) => void;
   /** On release: the whole operation */
   onDrop?: (op: TransformOp, targets: SceneObject[]) => void;
+  /** Outline the targets, under the handles (default false). Options: see `SelectionOutline` */
+  outline?: boolean | Omit<SelectionOutlineOptions, "targets">;
+}
+
+export interface SelectionOutlineOptions {
+  /** Objects to outline, or a function asked every frame (default none) */
+  targets?: SceneObject[] | (() => SceneObject[]);
+  /** Line color (default "#ffa64d") */
+  color?: string;
+  /** Line width in CSS pixels (default 2) */
+  width?: number;
+  /** Opacity of the outline where the objects are hidden behind others (default 0.35; 0 = not shown) */
+  hidden?: number;
+}
+
+/**
+ * A colored line around selected objects, like a 3D editor's selection. Parts hidden
+ * behind other objects get a faint outline. Add it before tools that draw handles.
+ */
+export class SelectionOutline implements Tool {
+  constructor(opts?: SelectionOutlineOptions);
+  targets: SceneObject[] | (() => SceneObject[]);
+  color: string;
+  width: number;
+  hidden: number;
+  /** Hide the outline without removing the tool. */
+  visible: boolean;
+  /** The objects outlined this frame. */
+  current(): SceneObject[];
+  draw(ctx: CanvasRenderingContext2D, scene: Scene): void;
 }
 
 /**
@@ -1352,6 +1457,8 @@ export class TransformGizmo implements Tool {
   visible: boolean;
   /** True while a handle is being dragged. */
   readonly dragging: boolean;
+  /** The outline around the targets (`outline` option), or null. */
+  outline: SelectionOutline | null;
   /** The pivot in world space, or null when there are no targets. */
   center(): Vec3 | null;
   draw(ctx: CanvasRenderingContext2D, scene: Scene): void;

package/trid/index.js

@@ -19,11 +19,12 @@ export { gridMesh, gridHelper } from "./render/grid.js";
 export { cloneMesh, transformMesh, displaceMesh, mergeMeshes, meshBounds } from "./render/meshUtils.js";
 
 // Renderers
-export { CanvasRenderer, DEFAULT_LIGHT, DEFAULT_AMBIENT, materialsOf } from "./render/canvasRenderer.js";
+export { CanvasRenderer, DEFAULT_LIGHT, DEFAULT_AMBIENT, materialsOf, meshEdges } from "./render/canvasRenderer.js";
 export { WebGLRenderer, DEFAULT_FAR } from "./render/webglRenderer.js";
 
 // Lights
 export { defaultLights, sceneLights, lightAt, lightLevels, rangeFade, MAX_LIGHTS } from "./render/lights.js";
+export { shadowOptions, shadowFlag, shadowFrame, findGround, flattenOnGround, DEFAULT_SHADOWS } from "./render/shadows.js";
 
 // Effects
 export {
@@ -32,7 +33,10 @@ export {
 } from "./render/effects.js";
 
 // Post effects
-export { vignette, bloom, grade, grain, postPasses, activePost, runCanvasPost, FRAME_GLSL } from "./render/post.js";
+export {
+  vignette, bloom, grade, grain, outline, postPasses, activePost, runCanvasPost, wantsGeometry, maskedObjects,
+  FRAME_GLSL, GEOMETRY_GLSL, DEFAULT_OUTLINE_CREASE,
+} from "./render/post.js";
 
 // Procedural textures
 export { makeTexture, texturePixels, colorBytes, TEXTURE_STYLES } from "./render/proceduralTextures.js";
@@ -56,7 +60,7 @@ export { screenshot, record, download } from "./export/capture.js";
 // Tools
 export {
   OrbitCamera, FlyCamera, DragObject, HoverHighlight, FpsMeter, ObjUploader,
-  ViewGizmo, TransformGizmo,
+  ViewGizmo, TransformGizmo, SelectionOutline,
   ToolManager, pick, pickHit, isPickable, screenBounds, worldPerPixel,
 } from "./tools/index.js";
 

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 };
 
@@ -126,6 +127,14 @@ export class CanvasRenderer {
     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 ?? "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/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,
   };
 }