@es3d/es3d 1.0.2 → 1.1.0

package/src/render/stage.js

@@ -20,11 +20,16 @@
 //   the page is idle, and read back instead of tessellated on the next visit.
 //
 // Reduced motion (prefers-reduced-motion) stops clock animations and the
-// automatic orbit; scroll-driven cameras jump between stops.
+// automatic orbit; scroll-driven cameras jump between stops. stage.reducedMotion
+// reads that preference on each access, and the clock checks it every frame.
+//
+// clock: 'always' advances time even when the document has no <animate>.
+// background: true selects that clock and leaves the camera still, for a
+// page that moves shapes itself with stage.setTransform(id, matrix).
 
 import { compile } from '../pipeline.js';
 import { formatDiagnostics } from '../format/parse.js';
-import { updateDynamic } from '../scene/flatten.js';
+import { applyLocalMatrices, updateDynamic } from '../scene/flatten.js';
 import { pick } from '../scene/picking.js';
 import { createRenderer, PROGRESSIVE_BUDGET_MS } from './renderer.js';
 import { openGeometryStore, persistGeometry } from '../cache/geometry-store.js';
@@ -32,9 +37,36 @@ import { Camera } from './camera.js';
 import { OrbitControls } from './orbit-controls.js';
 import { ScrollTimeline } from './scroll-timeline.js';
 
-const reducedMotion = () => typeof matchMedia === 'function' && matchMedia('(prefers-reduced-motion: reduce)').matches;
+const prefersReducedMotion = () => typeof matchMedia === 'function' && matchMedia('(prefers-reduced-motion: reduce)').matches;
 const idle = (fn) => (typeof requestIdleCallback === 'function' ? requestIdleCallback(fn, { timeout: 500 }) : setTimeout(fn, 16));
 
+/**
+ * Clock and orbit flags for createStage. background: true runs the clock
+ * and does not orbit, unless clock or autoOrbit is set explicitly.
+ * @param {object} [opts]
+ * @param {boolean} [reduced]
+ */
+export function stageOptions(opts = {}, reduced = false) {
+  const background = opts.background === true;
+  const always = opts.clock === 'always' || (opts.clock == null && background);
+  const autoOrbit = opts.autoOrbit !== undefined ? opts.autoOrbit !== false : !background;
+  return {
+    clock: always ? 'always' : 'document',
+    playing: opts.playing !== false && !reduced,
+    auto: autoOrbit && !reduced,
+  };
+}
+
+/** True when this frame should add dt to the stage clock. */
+export function clockAdvances(state, scene, reduced) {
+  return !!(state.playing && !reduced && (state.clock === 'always' || (scene.animation && scene.animation.time)));
+}
+
+/** True when this frame should turn the automatic orbit. */
+export function orbitAdvances(state, reduced) {
+  return !!(state.auto && !reduced);
+}
+
 /** Names (name or id) on an element and its ancestors, nearest first. */
 export function ancestorNames(doc, uid) {
   const names = [];
@@ -57,7 +89,12 @@ const RESTORE_WAIT_MS = 50;
  * @param {HTMLCanvasElement} canvas sized by its parent element
  * @param {object} [opts]
  * @param {boolean} [opts.playing=true] play clock animations
- * @param {boolean} [opts.autoOrbit=true] turn slowly around the target until someone drags
+ * @param {boolean} [opts.autoOrbit=true] turn slowly around the target until someone drags.
+ *   background: true starts this off
+ * @param {'always'|'document'} [opts.clock] 'always' advances time with no <animate>.
+ *   background: true selects 'always'
+ * @param {boolean} [opts.background=false] a still camera and a running clock, for a script
+ *   that moves shapes with setTransform. <controls mode="none"/> turns dragging off
  * @param {number} [opts.orbitSpeed=0.22] radians per second
  * @param {boolean} [opts.interactive=true] false: no dragging, whatever the document says
  * @param {HTMLElement} [opts.scroll] section whose scroll position drives timeline="scroll"
@@ -80,15 +117,16 @@ export async function createStage(canvas, opts = {}) {
   target.style.display = 'block';
   const camera = new Camera();
   const controls = new OrbitControls(target, camera);
-  const motion = !reducedMotion();
+  const motion = stageOptions(opts, prefersReducedMotion());
   const state = {
     result: null,
     time: 0,
     progress: 0,
     last: 0,
     disposed: false,
-    playing: opts.playing !== false && motion,
-    auto: opts.autoOrbit !== false && motion,
+    clock: motion.clock,
+    playing: motion.playing,
+    auto: motion.auto,
     orbitSpeed: opts.orbitSpeed ?? 0.22,
     onScreen: true,
     // A frame is drawn only when something visible changed: the camera, the
@@ -250,6 +288,43 @@ export async function createStage(canvas, opts = {}) {
     set playing(v) {
       state.playing = !!v;
     },
+    /** True while the visitor prefers reduced motion. The clock and the automatic orbit stay still. */
+    get reducedMotion() {
+      return prefersReducedMotion();
+    },
+    /**
+     * Replace the local matrix of each element. An entry is `[id, matrix]`
+     * or `{id, matrix}`. The matrix is column-major, 16 numbers, the same
+     * layout as matrix(). Every matrix is stored first, then each affected
+     * part of the scene is walked once. The returned array has false for an
+     * id that is missing or drawn in more than one place (a shared
+     * definition, or a copy made by repeat or scatter).
+     * @param {Array<[string, ArrayLike<number>]|{id: string, matrix: ArrayLike<number>}>} entries
+     */
+    setTransforms(entries) {
+      const list = Array.from(entries || []);
+      const res = state.result;
+      const graph = res && res.graph;
+      const byId = graph && graph.byId;
+      const nodes = list.map((entry) => byId && byId.get(Array.isArray(entry) ? entry[0] : entry && entry.id));
+      const matrices = list.map((entry) => Array.isArray(entry) ? entry[1] : entry && entry.matrix);
+      const applied = graph && res.scene
+        ? applyLocalMatrices(res.scene, graph, nodes, matrices, state.time, state.progress)
+        : list.map(() => false);
+      if (applied.some(Boolean)) state.dirty = true;
+      return applied;
+    },
+    /**
+     * Replace the local matrix of the element with this id. The matrix is
+     * column-major, 16 numbers, the same layout as matrix(). Returns false
+     * when the id is missing or that element is drawn in more than one place
+     * (a shared definition, or a copy made by repeat or scatter).
+     * @param {string} id
+     * @param {ArrayLike<number>} matrix
+     */
+    setTransform(id, matrix) {
+      return this.setTransforms([[id, matrix]])[0] === true;
+    },
     /** Draw the next frame even if nothing the stage tracks has changed. */
     invalidate,
     get result() {
@@ -320,11 +395,11 @@ export async function createStage(canvas, opts = {}) {
     if (!state.width || !state.height) return;
     const res = state.result;
     const scene = res.scene;
-    // a scene without clock animations looks the same at every time
-    if (state.playing && scene.animation.time) state.time += dt;
+    const reduced = prefersReducedMotion();
+    if (clockAdvances(state, scene, reduced)) state.time += dt;
     if (state.timeline && state.timeline.update(dt)) state.progress = state.timeline.value;
     if (opts.onFrame) opts.onFrame(dt, api);
-    if (state.auto) {
+    if (orbitAdvances(state, reduced)) {
       const prev = controls.snapshot();
       const dx = camera.position[0] - camera.target[0];
       const dz = camera.position[2] - camera.target[2];

package/src/scene/flatten.js

@@ -15,6 +15,13 @@
 //
 // The RenderScene is renderer-agnostic; the OBJ and glTF importers produce the
 // same structure, which lets the benchmark render all formats identically.
+//
+// A node the walker visits once remembers that placement: the parent matrix
+// and the cursors at its start. applyLocalMatrices() stores every script
+// matrix first, then rewrites each affected subtree once. A later animation
+// walk reads the script matrix, so the document's own animation does not put
+// the old matrix back. A node visited again, or written by the instance
+// kernel, is shared and left alone.
 
 import * as mat4 from '../math/mat4.js';
 import { mulberry32 } from '../math/random.js';
@@ -160,6 +167,33 @@ class Walker {
     return this.stack[depth];
   }
 
+  /**
+   * Remember the one placement of a node. A second visit drops it: scatter,
+   * repeat and a definition used twice do not have one matrix to replace.
+   */
+  notePlace(node, parent, material, color, sel, lodNode, lodChild) {
+    if (node.place === 'many') return;
+    if (node.place) {
+      node.place = 'many';
+      return;
+    }
+    const copy = new Float64Array(16);
+    copy.set(parent);
+    node.place = {
+      parent: copy,
+      material,
+      color,
+      sel,
+      lodNode,
+      lodChild,
+      noCollide: this.noCollide,
+      rowStart: this.cursor,
+      lightStart: this.lightCursor,
+      cameraStart: this.cameraCursor,
+      switchStart: this.switchCursor,
+    };
+  }
+
   /** Local matrix of a node at the current time. */
   localOf(node, out) {
     if (!node.anims.length) {
@@ -177,7 +211,7 @@ class Walker {
 
   walk(node, parent, material, color, sel, lodNode, lodChild, depth) {
     if (!node || !node.visible) return;
-    const g = this.graph;
+    if (!this.overwrite) this.notePlace(node, parent, material, color, sel, lodNode, lodChild);
     const isSegmentRoot = node.anims.length > 0 && this.segmentDepth === 0 && !this.overwrite;
     let seg = null;
     if (isSegmentRoot) {
@@ -213,13 +247,14 @@ class Walker {
     else if (node.kind === 'camera') this.emitCamera(node, parent);
     else {
       let world;
-      if (!node.local && !node.anims.length) {
+      const scripted = node.scriptLocal;
+      if (!scripted && !node.local && !node.anims.length) {
         // identity local transform: children write only to deeper stack slots, so the parent can be shared
         world = parent;
       } else {
         world = this.mat(depth);
-        // static nodes multiply by their stored matrix directly (no copy)
-        const local = node.anims.length ? this.localOf(node, this.tmp) : node.local;
+        // a script matrix replaces the element's own transform, including its <animate>
+        const local = scripted || (node.anims.length ? this.localOf(node, this.tmp) : node.local);
         mat4.multiply(world, parent, local);
       }
       switch (node.kind) {
@@ -256,6 +291,12 @@ class Walker {
       seg.switchEnd = this.switchCursor;
       this.scene.dynamic.push(seg);
     }
+    if (!this.overwrite && node.place && node.place !== 'many') {
+      node.place.rowEnd = this.cursor;
+      node.place.lightEnd = this.lightCursor;
+      node.place.cameraEnd = this.cameraCursor;
+      node.place.switchEnd = this.switchCursor;
+    }
   }
 
   emitShape(node, world, material, color, uid, lodNode, lodChild, depth) {
@@ -438,6 +479,7 @@ class Walker {
     }
     this.cursor = cursor;
     this.switchCursor = sw;
+    markPlacedMany(node);
     return true;
   }
 
@@ -728,6 +770,168 @@ export function flattenScene(graph, opts = {}) {
   return scene;
 }
 
+/**
+ * The instance kernel wrote every copy of this subtree, so none of those
+ * nodes has a single placement a script can replace.
+ */
+function markPlacedMany(node) {
+  const visit = (n) => {
+    if (!n || n.place === 'many') return;
+    n.place = 'many';
+    if (n.target) visit(n.target);
+    if (n.children) for (const c of n.children) visit(c);
+  };
+  if (node.target) visit(node.target);
+  if (node.children) for (const c of node.children) visit(c);
+}
+
+/**
+ * The animated subtree that contains this node, if its parent matrix depends
+ * on the clock. The segment's own parent is above that animation, so rewalking
+ * the segment at the current time keeps a script matrix in the right place.
+ */
+function segmentFor(scene, node) {
+  for (const seg of scene.dynamic) {
+    for (let n = node; n; n = n.parent) if (n === seg.node) return seg;
+  }
+  return null;
+}
+
+function finiteMatrix(matrix) {
+  if (!matrix || matrix.length < 16) return false;
+  for (let i = 0; i < 16; i++) if (!Number.isFinite(+matrix[i])) return false;
+  return true;
+}
+
+function writeScriptLocal(node, matrix) {
+  let local = node.scriptLocal;
+  if (!local) local = node.scriptLocal = new Float64Array(16);
+  for (let i = 0; i < 16; i++) local[i] = +matrix[i];
+}
+
+function under(node, ancestor) {
+  for (let n = node; n; n = n.parent) if (n === ancestor) return true;
+  return false;
+}
+
+/** The deepest node that contains every entry, itself included. */
+function deepestCovering(nodes) {
+  for (let p = nodes[0]; p; p = p.parent) {
+    if (nodes.every((n) => n === p || under(n, p))) return p;
+  }
+  return null;
+}
+
+/**
+ * One walk root per cluster. A shared parent of several moves is walked
+ * once. The document root is not that parent: two unrelated shapes keep
+ * two small walks.
+ */
+function clusterRoots(nodes, root) {
+  if (nodes.length <= 1) return nodes.slice();
+  const common = deepestCovering(nodes);
+  if (common && common !== root && common.place && common.place !== 'many') return [common];
+  const groups = new Map();
+  for (const node of nodes) {
+    let top = node;
+    for (let p = node.parent; p && p !== root && p.place && p.place !== 'many'; p = p.parent) top = p;
+    let list = groups.get(top);
+    if (!list) groups.set(top, list = []);
+    list.push(node);
+  }
+  const out = [];
+  for (const [top, members] of groups) {
+    if (members.length > 1 && top.place && top.place !== 'many' && top !== root) out.push(top);
+    else if (members.length === nodes.length) for (const member of members) out.push(member);
+    else out.push(...clusterRoots(members, root));
+  }
+  return out;
+}
+
+function rewalkAt(w, rowStart, lightStart, cameraStart, switchStart, noCollide, node, parent, material, color, sel, lodNode, lodChild) {
+  w.cursor = rowStart;
+  w.lightCursor = lightStart;
+  w.cameraCursor = cameraStart;
+  w.switchCursor = switchStart;
+  w.segmentDepth = 0;
+  w.noCollide = noCollide;
+  w.walk(node, parent, material, color, sel, lodNode, lodChild, 0);
+}
+
+/**
+ * Replace the local matrix of each node and rewrite the rows once per
+ * affected subtree. Each entry of the returned array is false when that
+ * node is missing, the matrix is not 16 finite numbers, or the element is
+ * shared (a definition used twice, a repeat or scatter copy, or a subtree
+ * the instance kernel expanded). Column-major, the same layout as matrix().
+ * @param {RenderScene} scene
+ * @param {object} graph
+ * @param {import('./scene-graph.js').SceneNode[]} nodes
+ * @param {ArrayLike<number>[]} matrices
+ */
+export function applyLocalMatrices(scene, graph, nodes, matrices, time = 0, progress = 0) {
+  const list = nodes || [];
+  const ok = new Array(list.length);
+  const accepted = [];
+  const seen = new Set();
+  for (let i = 0; i < list.length; i++) {
+    const node = list[i];
+    const matrix = matrices && matrices[i];
+    if (!scene || !graph || !node || !node.place || node.place === 'many' || !finiteMatrix(matrix)) {
+      ok[i] = false;
+      continue;
+    }
+    writeScriptLocal(node, matrix);
+    ok[i] = true;
+    if (!seen.has(node)) {
+      seen.add(node);
+      accepted.push(node);
+    }
+  }
+  if (!accepted.length) return ok;
+
+  const segments = [];
+  const staticNodes = [];
+  const seenSeg = new Set();
+  for (const node of accepted) {
+    const seg = segmentFor(scene, node);
+    if (seg) {
+      if (!seenSeg.has(seg)) {
+        seenSeg.add(seg);
+        segments.push(seg);
+      }
+    } else staticNodes.push(node);
+  }
+  const roots = clusterRoots(staticNodes, graph.root);
+  const w = new Walker(scene, graph, time, progress);
+  w.overwrite = true;
+  for (const node of roots) {
+    const p = node.place;
+    rewalkAt(w, p.rowStart, p.lightStart, p.cameraStart, p.switchStart, p.noCollide, node, p.parent, p.material, p.color, p.sel, p.lodNode, p.lodChild);
+  }
+  for (const seg of segments) {
+    if (roots.some((node) => under(seg.node, node))) continue;
+    rewalkAt(w, seg.start, seg.lightStart, seg.cameraStart, seg.switchStart, seg.noCollide, seg.node, seg.parent, seg.material, seg.color, seg.sel, seg.lodNode, seg.lodChild);
+  }
+  scene.version++;
+  return ok;
+}
+
+/**
+ * Replace one element's local matrix and rewrite the rows of its single
+ * placement. The matrix is column-major, the same layout as matrix().
+ * Returns false when the id is missing, the matrix is not 16 finite numbers,
+ * or the element is shared (a definition used twice, a repeat or scatter
+ * copy, or a subtree the instance kernel expanded).
+ * @param {RenderScene} scene
+ * @param {object} graph
+ * @param {import('./scene-graph.js').SceneNode} node
+ * @param {ArrayLike<number>} matrix
+ */
+export function applyLocalMatrix(scene, graph, node, matrix, time = 0, progress = 0) {
+  return applyLocalMatrices(scene, graph, [node], [matrix], time, progress)[0] === true;
+}
+
 /** Re-evaluate animated subtrees at time t and scroll progress, overwriting their rows. */
 export function updateDynamic(scene, graph, time, progress = 0) {
   if (!scene.dynamic.length) return false;

package/src/scene/scene-graph.js

@@ -37,6 +37,12 @@ export class SceneNode {
     this.step = null;
     // scatter / lod / light / camera parameters
     this.params = null;
+    /** Column-major local matrix written by a script, or null. It wins over this node's own transform. */
+    this.scriptLocal = null;
+    /** One recorded placement, or 'many' when the node is drawn in more than one place. */
+    this.place = null;
+    /** Scene-graph parent. A shared definition has none: it is not a child of the uses that draw it. */
+    this.parent = null;
   }
 
   get animated() {
@@ -65,6 +71,7 @@ export function buildSceneGraph(doc, cache, opts = {}) {
   const diagnostics = [];
   const materials = new MaterialTable();
   const memo = new Map();
+  const byId = new Map();
   let environment = { ...ENV_DEFAULTS, explicit: false };
   let envFound = false;
   let controls = null;
@@ -132,6 +139,7 @@ export function buildSceneGraph(doc, cache, opts = {}) {
     memo.set(el, node);
     stats.nodes++;
     const v = el.values || {};
+    if (v.id !== undefined) byId.set(v.id, node);
     if (kind !== 'camera' && kind !== 'light') {
       const m = localMatrix(v);
       node.local = isIdentity(m) ? null : m;
@@ -167,7 +175,10 @@ export function buildSceneGraph(doc, cache, opts = {}) {
       }
       if (c.name === 'material' || c.name === 'environment' || c.name === 'controls') continue;
       const child = nodeFor(c, depth + 1);
-      if (child) node.children.push(child);
+      if (child) {
+        child.parent = node;
+        node.children.push(child);
+      }
     }
 
     switch (kind) {
@@ -298,7 +309,7 @@ export function buildSceneGraph(doc, cache, opts = {}) {
     report(doc.root, 'error', 'E_TOO_MANY_INSTANCES', `The scene expands to ${expanded.toLocaleString('en-US')} instances, more than the limit of ${maxInstances.toLocaleString('en-US')}. Reduce repeat or scatter counts.`, 'render');
   }
 
-  return { doc, root, materials, environment, controls, animation, cache, diagnostics, stats, tooLarge: expanded > maxInstances, expanded };
+  return { doc, root, materials, environment, controls, animation, cache, diagnostics, stats, tooLarge: expanded > maxInstances, expanded, byId };
 }
 
 /** Viewer settings from a <controls> element (angles in degrees, as written). */

package/src/stage.js

@@ -0,0 +1,8 @@
+// The page entry. The published file is one minified build of this module
+// (browser/es3d-stage.min.js, `npm run build:stage`), so a page loads the
+// stage in a single request. createStage, ancestorNames and the placement
+// functions a script shares with the reader are the exports.
+
+export { createStage, ancestorNames } from './render/stage.js';
+export { mulberry32 } from './math/random.js';
+export { es3dSin, es3dCos } from './math/trig.js';