trid3d 0.6.0 → 0.7.0

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,6 +153,8 @@ 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 ?? "transparent");
   for (const e of effects) {
@@ -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) {

package/trid/render/shadows.js

@@ -0,0 +1,184 @@
+/**
+ * Shadows from a directional light.
+ *
+ *   scene.lights = [
+ *     { type: "ambient", intensity: 0.3 },
+ *     { type: "directional", direction: { x: -0.5, y: 1, z: -0.8 }, intensity: 0.7, shadows: true },
+ *   ];
+ *
+ * - The first directional light with `shadows` casts them (point lights
+ *   don't, yet). `shadows` is `true` or options, see `shadowOptions`
+ * - Objects cast and receive shadows unless they (or a group they're in)
+ *   have `castShadow: false` / `receiveShadow: false`. Only faces cast
+ *   shadows, not lines or see-through faces
+ *
+ * WebGL renderer: a shadow map. The scene is drawn from the light into a
+ * picture of distances, fitted around the casting objects every frame;
+ * each pixel then checks whether something is nearer the light than it.
+ *
+ * Canvas renderer: ground shadows. The casting objects are flattened onto
+ * the floor (the level where most of the area of flat, upward faces is, or
+ * `ground`) and drawn as one darker shape on the floor's faces. Objects
+ * don't shadow each other there.
+ */
+
+import { transformPoint } from "../math/matrix.js";
+import { newell } from "./normals.js";
+
+/** Settings used for `shadows: true`. */
+export const DEFAULT_SHADOWS = Object.freeze({ size: 2048, softness: 1.5, bias: 1, ground: null });
+
+/**
+ * A light's shadow settings, defaults filled in.
+ *
+ * @param {boolean|Object} value - The light's `shadows`
+ * @returns {{ size:number, softness:number, bias:number, ground:number|null }}
+ *   - `size`: width of the shadow map in pixels (WebGL). Bigger: sharper, slower
+ *   - `softness`: blur of the shadows' edges, in shadow map pixels (0: sharp)
+ *   - `bias`: pushes the test away from surfaces, against speckles ("shadow acne")
+ *     on surfaces facing the light. Raise it if they appear; too high and shadows
+ *     come loose from their objects
+ *   - `ground`: the floor's height for the canvas renderer (default: found)
+ */
+export function shadowOptions(value) {
+  const o = value && typeof value === "object" ? value : {};
+  return {
+    size: Math.max(64, Math.min(8192, Math.round(o.size ?? DEFAULT_SHADOWS.size))),
+    softness: Math.max(0, o.softness ?? DEFAULT_SHADOWS.softness),
+    bias: Math.max(0, o.bias ?? DEFAULT_SHADOWS.bias),
+    ground: typeof o.ground === "number" ? o.ground : null,
+  };
+}
+
+/** False when the object or one of its groups sets `key` to false. */
+export function shadowFlag(obj, key) {
+  for (let o = obj; o; o = o.parent) if (o[key] === false) return false;
+  return true;
+}
+
+const spheres = new WeakMap();
+
+/** A sphere around a mesh's vertices, in its own space (cached per vertex array). */
+function meshSphere(mesh) {
+  const v = mesh.vertices;
+  const hit = spheres.get(v);
+  if (hit && hit.n === v.length && !mesh.dirty) return hit;
+  let min = { x: Infinity, y: Infinity, z: Infinity }, max = { x: -Infinity, y: -Infinity, z: -Infinity };
+  for (const p of v) {
+    min = { x: Math.min(min.x, p.x), y: Math.min(min.y, p.y), z: Math.min(min.z, p.z) };
+    max = { x: Math.max(max.x, p.x), y: Math.max(max.y, p.y), z: Math.max(max.z, p.z) };
+  }
+  const c = { x: (min.x + max.x) / 2, y: (min.y + max.y) / 2, z: (min.z + max.z) / 2 };
+  let r = 0;
+  for (const p of v) r = Math.max(r, Math.hypot(p.x - c.x, p.y - c.y, p.z - c.z));
+  const s = { c, r, n: v.length };
+  spheres.set(v, s);
+  return s;
+}
+
+/**
+ * Where the shadow map looks: a box facing along the light, around every
+ * casting object (each object's mesh sphere, placed and scaled).
+ *
+ * @param {Object[]} casters - Objects with `mesh` and `world`
+ * @param {{x:number,y:number,z:number}} dir - Unit direction the light comes from
+ * @returns {{ matrix: Float32Array, radius: number } | null} `matrix` takes world points to
+ *   the shadow map's -1..1 cube (column-major, for WebGL)
+ */
+export function shadowFrame(casters, dir) {
+  let min = { x: Infinity, y: Infinity, z: Infinity }, max = { x: -Infinity, y: -Infinity, z: -Infinity };
+  let any = false;
+  for (const obj of casters) {
+    if (!obj.mesh?.vertices?.length) continue;
+    const s = meshSphere(obj.mesh);
+    const w = obj.world;
+    const c = transformPoint(w, s.c);
+    const k = Math.max(Math.hypot(w[0], w[1], w[2]), Math.hypot(w[4], w[5], w[6]), Math.hypot(w[8], w[9], w[10]));
+    const r = s.r * k;
+    min = { x: Math.min(min.x, c.x - r), y: Math.min(min.y, c.y - r), z: Math.min(min.z, c.z - r) };
+    max = { x: Math.max(max.x, c.x + r), y: Math.max(max.y, c.y + r), z: Math.max(max.z, c.z + r) };
+    any = true;
+  }
+  if (!any) return null;
+  const c = { x: (min.x + max.x) / 2, y: (min.y + max.y) / 2, z: (min.z + max.z) / 2 };
+  const R = Math.max(1e-6, Math.hypot(max.x - min.x, max.y - min.y, max.z - min.z) / 2);
+
+  // The light looks along -dir; right and up across it
+  const f = { x: -dir.x, y: -dir.y, z: -dir.z };
+  const up = Math.abs(f.y) > 0.99 ? { x: 0, y: 0, z: 1 } : { x: 0, y: 1, z: 0 };
+  const r = unit(cross(up, f));
+  const u = cross(f, r);
+  const dot = (a, b) => a.x * b.x + a.y * b.y + a.z * b.z;
+  const m = new Float32Array([
+    r.x / R, u.x / R, f.x / R, 0,
+    r.y / R, u.y / R, f.y / R, 0,
+    r.z / R, u.z / R, f.z / R, 0,
+    -dot(r, c) / R, -dot(u, c) / R, -dot(f, c) / R, 1,
+  ]);
+  return { matrix: m, radius: R };
+}
+
+/**
+ * The floor for ground shadows: the height where receiving objects have the
+ * most area of flat faces turned up. Null when there's none.
+ *
+ * @param {Object[]} receivers - Objects with `mesh` and `world`
+ */
+export function findGround(receivers) {
+  const area = new Map();
+  for (const obj of receivers) {
+    const v = obj.mesh.vertices;
+    for (const face of obj.mesh.faces ?? []) {
+      if (face.length < 3) continue;
+      const p = face.map((i) => transformPoint(obj.world, v[i]));
+      const n = newell(p);
+      const len = Math.hypot(n.x, n.y, n.z);
+      if (!(len > 0) || n.y / len < 0.99) continue;
+      const y = Math.round(p[0].y * 1e4) / 1e4;
+      area.set(y, (area.get(y) ?? 0) + len / 2);
+    }
+  }
+  let best = null, most = 0;
+  for (const [y, a] of area) if (a > most) [best, most] = [y, a];
+  return best;
+}
+
+/**
+ * A world polygon's part above `ground`, flattened onto it along the light.
+ * Empty when it's all at or below the ground.
+ *
+ * @param {{x:number,y:number,z:number}[]} pts - World points
+ * @param {{x:number,y:number,z:number}} dir - Unit direction the light comes from (dir.y > 0)
+ * @param {number} ground
+ */
+export function flattenOnGround(pts, dir, ground) {
+  const eps = 1e-5;
+  if (pts.every((p) => p.y <= ground + eps)) return [];
+  // Cut off what's below the ground
+  let poly = pts;
+  if (pts.some((p) => p.y < ground)) {
+    poly = [];
+    for (let i = 0; i < pts.length; i++) {
+      const a = pts[i], b = pts[(i + 1) % pts.length];
+      const aIn = a.y >= ground, bIn = b.y >= ground;
+      if (aIn) poly.push(a);
+      if (aIn !== bIn) {
+        const t = (ground - a.y) / (b.y - a.y);
+        poly.push({ x: a.x + (b.x - a.x) * t, y: ground, z: a.z + (b.z - a.z) * t });
+      }
+    }
+  }
+  return poly.map((p) => {
+    const t = (p.y - ground) / dir.y;
+    return { x: p.x - dir.x * t, y: ground, z: p.z - dir.z * t };
+  });
+}
+
+function cross(a, b) {
+  return { x: a.y * b.z - a.z * b.y, y: a.z * b.x - a.x * b.z, z: a.x * b.y - a.y * b.x };
+}
+
+function unit(v) {
+  const len = Math.hypot(v.x, v.y, v.z) || 1;
+  return { x: v.x / len, y: v.y / len, z: v.z / len };
+}