@es3d/es3d 1.1.1 → 1.2.0

package/src/render/compile-worker.js

@@ -0,0 +1,143 @@
+// The stage's compiler thread.
+//
+// The stage is one file. A page that calls stage.prepare() starts a worker
+// from that same file; there it finds itself in a worker and serves compile
+// requests instead of drawing (render/stage.js calls serveCompiler). The
+// worker runs preparePayload (scene/prepared.js): parsing, validation,
+// building, flattening and mesh generation, and sends the result back as
+// transferred buffers.
+//
+// A worker script must come from the page's origin. A stage loaded from a CDN
+// is started through a small module made in the page (a blob URL) that
+// imports the stage by its URL, which the CDN's CORS headers allow. Where
+// neither works (a content security policy without worker-src blob:, an old
+// browser, Node), every request is compiled on the main thread instead, and
+// the page does not need to know.
+
+import { preparePayload } from '../scene/prepared.js';
+import { early, inWorker } from './worker-boot.js';
+
+/** True inside a dedicated worker. */
+export function isWorkerScope() {
+  return inWorker;
+}
+
+// a worker that has not answered its first request by then is given up on
+const FIRST_ANSWER_MS = 10000;
+
+// keys whose meshes this worker sent; capped, so a long session does not grow it forever
+const SENT_LIMIT = 200000;
+
+/**
+ * Answer compile requests posted to this worker.
+ * @param {object} scope the worker's global scope
+ */
+export function serveCompiler(scope) {
+  const sent = new Set();
+  const answer = (e) => {
+    const { id, input, time, progress, quality } = e.data || {};
+    if (sent.size > SENT_LIMIT) sent.clear();
+    let reply;
+    try {
+      reply = preparePayload(input, { time, progress, quality, sent });
+    } catch (err) {
+      scope.postMessage({ id, error: String(err && err.message ? err.message : err) });
+      return;
+    }
+    try {
+      scope.postMessage({ id, ...reply.message }, reply.transfer);
+    } catch (err) {
+      // something in the scene could not be cloned: the main thread compiles it
+      scope.postMessage({ id, ok: reply.message.ok, diagnostics: reply.message.diagnostics, hostOnly: reply.message.hostOnly, timings: reply.message.timings, lineText: reply.message.lineText, lineIndex: reply.message.lineIndex, main: true });
+    }
+  };
+  scope.onmessage = answer;
+  // requests that came while the module was still loading (worker-boot.js)
+  for (const e of early.splice(0)) answer(e);
+}
+
+/** Start a module worker running this file, or null where none can start. */
+function startWorker(url) {
+  if (typeof Worker !== 'function' || !url) return null;
+  const sameOrigin = typeof location === 'undefined' || new URL(url).origin === location.origin;
+  try {
+    if (sameOrigin) return new Worker(url, { type: 'module' });
+  } catch {
+    // fall through to the blob module
+  }
+  try {
+    const blob = new Blob([`import ${JSON.stringify(url)};`], { type: 'text/javascript' });
+    return new Worker(URL.createObjectURL(blob), { type: 'module' });
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The page's side: posts documents to the worker and resolves each request
+ * with its payload. A failed worker (it did not load, or it crashed) answers
+ * every waiting and later request with null, which means: compile here.
+ */
+export class CompilerClient {
+  /** @param {string} url this module's file (the stage bundle's import.meta.url) */
+  constructor(url) {
+    this.worker = startWorker(url);
+    this.failed = !this.worker;
+    this.pending = new Map();
+    this.next = 1;
+    if (!this.worker) return;
+    this.answered = false;
+    this.watchdog = 0;
+    this.worker.onmessage = (e) => {
+      const msg = e.data;
+      this.answered = true;
+      clearTimeout(this.watchdog);
+      const done = this.pending.get(msg.id);
+      if (!done) return;
+      this.pending.delete(msg.id);
+      done(msg.error ? null : msg);
+    };
+    const fail = () => {
+      clearTimeout(this.watchdog);
+      this.failed = true;
+      for (const done of this.pending.values()) done(null);
+      this.pending.clear();
+      try { this.worker.terminate(); } catch {}
+    };
+    this.worker.onerror = (e) => {
+      if (e && e.preventDefault) e.preventDefault();
+      fail();
+    };
+    this.worker.onmessageerror = fail;
+    this.fail = fail;
+  }
+
+  /**
+   * @param {string|ArrayBuffer|Uint8Array} input copied to the worker, not transferred
+   * @param {{time?: number, progress?: number, quality?: number}} opts
+   * @returns {Promise<object|null>} the payload, or null: compile on this thread
+   */
+  compile(input, opts) {
+    if (this.failed) return Promise.resolve(null);
+    const id = this.next++;
+    return new Promise((resolve) => {
+      this.pending.set(id, resolve);
+      // a worker that never starts (blocked, or its module failed silently)
+      // must not hold the page's documents: compile them here instead
+      if (!this.answered && !this.watchdog) this.watchdog = setTimeout(() => this.fail(), FIRST_ANSWER_MS);
+      try {
+        this.worker.postMessage({ id, input, time: opts.time, progress: opts.progress, quality: opts.quality });
+      } catch {
+        this.pending.delete(id);
+        resolve(null);
+      }
+    });
+  }
+
+  dispose() {
+    if (this.worker) this.worker.terminate();
+    for (const done of this.pending.values()) done(null);
+    this.pending.clear();
+    this.failed = true;
+  }
+}

package/src/render/frame-builder.js

@@ -21,6 +21,41 @@ function length3(x, y, z) {
   return Math.sqrt(x * x + y * y + z * z);
 }
 
+/**
+ * Per-frame constants for `instancePixelsPerUnit`.
+ * `ppuFactor` is F = viewportHeight / (2 tan(verticalFov / 2)) for a perspective
+ * camera, or the constant scale for an orthographic one. `cornerStretch` is
+ * 1/cos^2 of the angle to the frustum's corner.
+ */
+export function lodFrameConstants(camera, viewportHeight) {
+  const aspect = camera.aspect || 1;
+  const tanV = Math.tan(camera.verticalFov(aspect) / 2);
+  return {
+    orthographic: camera.type === 'orthographic',
+    ppuFactor: camera.pixelsPerUnit(1, viewportHeight),
+    view: camera.view,
+    cornerStretch: 1 + tanV * tanV * (1 + aspect * aspect),
+  };
+}
+
+/**
+ * Largest projected size, in CSS pixels, of a unit length at the centre
+ * (cx, cy, cz) of an instance's bounding sphere; `d` is the distance from the
+ * eye to that centre. A flat image plane stretches a displacement at angle a
+ * from the view axis by up to 1/cos^2(a) = d^2/z^2 (z = depth along the axis)
+ * radially. Inside the view that never exceeds its value at the frustum's
+ * corners, which is also used when the centre is at or behind the eye plane
+ * while the sphere is still visible. Orthographic views do not stretch.
+ * Allocation-free: it runs once per instance.
+ */
+export function instancePixelsPerUnit(k, cx, cy, cz, d) {
+  if (k.orthographic) return k.ppuFactor;
+  const V = k.view;
+  const z = -(V[2] * cx + V[6] * cy + V[10] * cz + V[14]);
+  const stretch = z > 0 ? Math.min((d * d) / (z * z), k.cornerStretch) : k.cornerStretch;
+  return (k.ppuFactor * stretch) / Math.max(d, 1e-6);
+}
+
 /**
  * The level to draw while `lod` is not generated yet: the nearest coarser
  * level that exists, else the nearest finer one, else the coarsest level
@@ -136,78 +171,98 @@ export class FrameBuilder {
    */
   build(p) {
     const { scene, camera, pool, meshOf, options } = p;
-    const n = scene.count;
+    // A SceneSet draws several instance tables (the host and the fragments,
+    // scene-set.js); a RenderScene is one part whose indices need no map.
+    const parts = scene.parts ? scene.drawnParts() : [{ scene, geomMap: null, matMap: null, selectable: true }];
+    let n = 0;
+    for (const part of parts) n += part.scene.count;
     // reserve instance rows for: batches (<= n), bounding boxes (<= n), selection boxes
     let selCount = 0;
     if (options.selection && options.selection.size) {
-      for (let i = 0; i < n; i++) if (options.selection.has(scene.uid[i])) selCount++;
+      for (const part of parts) {
+        if (!part.selectable) continue;
+        const P = part.scene;
+        for (let i = 0; i < P.count; i++) if (options.selection.has(P.uid[i])) selCount++;
+      }
     }
     this.ensure(n + (options.bbox ? n : 0) + selCount + 64);
     const camPos = camera.position;
     const dist = (c) => Math.hypot(c[0] - camPos[0], c[1] - camPos[1], c[2] - camPos[2]);
-    const sw = this.lodStates(scene, camPos, dist);
     const planes = options.culling === false ? null : planesFrom(camera.viewProj);
-    const S = scene.spheres;
     const keys = this.keys;
     const lods = this.lods;
     const batchMap = new Map();
     const batches = [];
-    const nMat = Math.max(1, scene.materials.length);
+    const geometries = scene.geometries;
+    const materials = scene.materials;
+    const nMat = Math.max(1, materials.length);
     const lodHist = [0, 0, 0, 0];
     let visibleCount = 0;
     let culled = 0;
     const vh = p.viewportHeight;
     const bias = options.lodBias || 1;
     const fixedLod = options.autoLod === false ? options.fixedLod || 0 : -1;
-    // pixels per world unit at distance 1 (perspective) or everywhere (orthographic)
-    const ppuFactor = camera.pixelsPerUnit(1, vh);
+    // pixels per world unit: depth based for perspective, constant for orthographic
+    const lodK = lodFrameConstants(camera, vh);
 
-    for (let i = 0; i < n; i++) {
-      keys[i] = -1;
-      const ln = scene.lodNode[i];
-      if (ln >= 0 && !(sw.visible[ln] && sw.active[ln] === scene.lodChild[i])) continue;
-      const cx = S[i * 4], cy = S[i * 4 + 1], cz = S[i * 4 + 2], r = S[i * 4 + 3];
-      if (planes) {
-        let out = false;
-        for (let k = 0; k < 5; k++) {
-          const pl = planes[k];
-          if (pl[0] * cx + pl[1] * cy + pl[2] * cz + pl[3] < -r) {
-            out = true;
-            break;
+    // rows are numbered across the parts: part k's row r is base(k) + r
+    let base = 0;
+    for (const part of parts) {
+      const P = part.scene;
+      const gm = part.geomMap;
+      const mm = part.matMap;
+      const pn = P.count;
+      const sw = this.lodStates(P, camPos, dist);
+      const S = P.spheres;
+      for (let r = 0; r < pn; r++) {
+        const i = base + r;
+        keys[i] = -1;
+        const ln = P.lodNode[r];
+        if (ln >= 0 && !(sw.visible[ln] && sw.active[ln] === P.lodChild[r])) continue;
+        const cx = S[r * 4], cy = S[r * 4 + 1], cz = S[r * 4 + 2], rad = S[r * 4 + 3];
+        if (planes) {
+          let out = false;
+          for (let k = 0; k < 5; k++) {
+            const pl = planes[k];
+            if (pl[0] * cx + pl[1] * cy + pl[2] * cz + pl[3] < -rad) {
+              out = true;
+              break;
+            }
+          }
+          if (out) {
+            culled++;
+            continue;
           }
         }
-        if (out) {
-          culled++;
-          continue;
+        const gi = gm ? gm[P.geom[r]] : P.geom[r];
+        const entry = geometries[gi];
+        let lod = 0;
+        if (entry.lods > 1) {
+          if (fixedLod >= 0) lod = Math.min(fixedLod, entry.lods - 1);
+          else {
+            const dx = cx - camPos[0], dy = cy - camPos[1], dz = cz - camPos[2];
+            const d = length3(dx, dy, dz);
+            const ppu = instancePixelsPerUnit(lodK, cx, cy, cz, d);
+            lod = selectLod(entry.lodDeviation, entry.lods, axisScale(P.matrices, r), ppu, bias);
+          }
         }
-      }
-      const gi = scene.geom[i];
-      const entry = scene.geometries[gi];
-      let lod = 0;
-      if (entry.lods > 1) {
-        if (fixedLod >= 0) lod = Math.min(fixedLod, entry.lods - 1);
-        else {
-          const dx = cx - camPos[0], dy = cy - camPos[1], dz = cz - camPos[2];
-          const d = length3(dx, dy, dz);
-          const ppu = camera.type === 'orthographic' ? ppuFactor : ppuFactor / Math.max(d, 1e-6);
-          lod = selectLod(entry.lodDeviation, entry.lods, axisScale(scene.matrices, i), ppu, bias);
+        lods[i] = lod;
+        lodHist[lod]++;
+        const mirrored = P.flags[r] & 1;
+        const mi = mm ? mm[P.mat[r]] : P.mat[r];
+        const key = ((gi * 4 + lod) * nMat + mi) * 2 + mirrored;
+        let b = batchMap.get(key);
+        if (b === undefined) {
+          b = batches.length;
+          batchMap.set(key, b);
+          const material = materials[mi];
+          batches.push({ gi, entry, lod, mi, material, mirrored: !!mirrored, count: 0, firstInstance: 0, depth: 0, instances: null });
         }
+        batches[b].count++;
+        keys[i] = b;
+        visibleCount++;
       }
-      lods[i] = lod;
-      lodHist[lod]++;
-      const mirrored = scene.flags[i] & 1;
-      const mi = scene.mat[i];
-      const key = ((gi * 4 + lod) * nMat + mi) * 2 + mirrored;
-      let b = batchMap.get(key);
-      if (b === undefined) {
-        b = batches.length;
-        batchMap.set(key, b);
-        const material = scene.materials[mi];
-        batches.push({ gi, entry, lod, mi, material, mirrored: !!mirrored, count: 0, firstInstance: 0, depth: 0, instances: null });
-      }
-      batches[b].count++;
-      keys[i] = b;
-      visibleCount++;
+      base += pn;
     }
 
     // resolve meshes / pool ranges. Once this frame has spent its tessellation
@@ -253,27 +308,32 @@ export class FrameBuilder {
       b.cursor = b.firstInstance;
     }
     const data = this.instanceData;
-    const M = scene.matrices;
-    const transparentInstances = [];
-    for (let i = 0; i < n; i++) {
-      const k = keys[i];
-      if (k < 0) continue;
-      const b = batches[k];
-      if (b.transparent) {
-        transparentInstances.push(i);
-        continue;
+    const transparent = []; // {M, r, b, depth}: drawn back to front after the opaque rows
+    base = 0;
+    for (const part of parts) {
+      const P = part.scene;
+      const M = P.matrices;
+      const S = P.spheres;
+      for (let r = 0; r < P.count; r++) {
+        const k = keys[base + r];
+        if (k < 0) continue;
+        const b = batches[k];
+        if (b.transparent) {
+          transparent.push({ M, r, b, depth: -length3(S[r * 4] - camPos[0], S[r * 4 + 1] - camPos[1], S[r * 4 + 2] - camPos[2]) });
+          continue;
+        }
+        const o = b.cursor++ * 16;
+        for (let j = 0; j < 16; j++) data[o + j] = M[r * 16 + j];
       }
-      const o = b.cursor++ * 16;
-      for (let j = 0; j < 16; j++) data[o + j] = M[i * 16 + j];
+      base += P.count;
     }
-    if (transparentInstances.length) {
-      const depthOf = (i) => -length3(S[i * 4] - camPos[0], S[i * 4 + 1] - camPos[1], S[i * 4 + 2] - camPos[2]);
-      transparentInstances.sort((a, b) => depthOf(a) - depthOf(b));
-      for (const i of transparentInstances) {
-        const b = batches[keys[i]];
+    if (transparent.length) {
+      transparent.sort((a, b) => a.depth - b.depth);
+      for (const t of transparent) {
+        const b = t.b;
         const o = b.cursor++ * 16;
-        for (let j = 0; j < 16; j++) data[o + j] = M[i * 16 + j];
-        b.depth = Math.max(b.depth, -depthOf(i));
+        for (let j = 0; j < 16; j++) data[o + j] = t.M[t.r * 16 + j];
+        b.depth = Math.max(b.depth, -t.depth);
       }
       // farthest transparent batches first
       const opaque = order.filter((b) => !b.transparent);
@@ -291,12 +351,13 @@ export class FrameBuilder {
         if (options.normals) overlays.normals.push({ range: pool.normalRange(b.mesh), firstInstance: b.firstInstance, count: b.count });
       }
     }
-    const boxMatrix = (i, o) => {
-      const e = scene.geometries[scene.geom[i]];
+    const boxMatrix = (part, r, o) => {
+      const P = part.scene;
+      const e = geometries[part.geomMap ? part.geomMap[P.geom[r]] : P.geom[r]];
       const bb = e.bounds;
       const cx = (bb.min[0] + bb.max[0]) / 2, cy = (bb.min[1] + bb.max[1]) / 2, cz = (bb.min[2] + bb.max[2]) / 2;
       const sx = Math.max(bb.max[0] - bb.min[0], 1e-4), sy = Math.max(bb.max[1] - bb.min[1], 1e-4), sz = Math.max(bb.max[2] - bb.min[2], 1e-4);
-      const m = M.subarray(i * 16, i * 16 + 16);
+      const m = P.matrices.subarray(r * 16, r * 16 + 16);
       // world * T(c) * S(s)
       for (let k = 0; k < 3; k++) {
         data[o + k] = m[k] * sx;
@@ -311,22 +372,33 @@ export class FrameBuilder {
     };
     if (options.bbox) {
       const first = offset;
-      for (let i = 0; i < n; i++) {
-        if (keys[i] < 0) continue;
-        boxMatrix(i, offset * 16);
-        offset++;
+      base = 0;
+      for (const part of parts) {
+        for (let r = 0; r < part.scene.count; r++) {
+          if (keys[base + r] < 0) continue;
+          boxMatrix(part, r, offset * 16);
+          offset++;
+        }
+        base += part.scene.count;
       }
       overlays.bbox = { firstInstance: first, count: offset - first };
     }
     if (selCount) {
       const first = offset;
       const sel = options.selection;
-      for (let i = 0; i < n; i++) {
-        if (!sel.has(scene.uid[i])) continue;
-        // hidden level-of-detail alternatives are not highlighted
-        if (keys[i] < 0 && scene.lodNode[i] >= 0) continue;
-        boxMatrix(i, offset * 16);
-        offset++;
+      base = 0;
+      for (const part of parts) {
+        const P = part.scene;
+        if (part.selectable) {
+          for (let r = 0; r < P.count; r++) {
+            if (!sel.has(P.uid[r])) continue;
+            // hidden level-of-detail alternatives are not highlighted
+            if (keys[base + r] < 0 && P.lodNode[r] >= 0) continue;
+            boxMatrix(part, r, offset * 16);
+            offset++;
+          }
+        }
+        base += P.count;
       }
       overlays.selection = { firstInstance: first, count: offset - first };
     }

package/src/render/renderer.js

@@ -5,7 +5,7 @@
 // The facade is the only renderer API used by the application and the
 // benchmark; backends never see the ES3D document, only a RenderScene.
 
-import { GeometryPool } from './geometry-pool.js';
+import { GeometryPool, VERTEX_BYTES } from './geometry-pool.js';
 import { FrameBuilder } from './frame-builder.js';
 import { TextureCache } from './texture-cache.js';
 import { FRAME_FLOATS, packFrameUniforms } from './lighting.js';
@@ -106,14 +106,40 @@ export class Renderer {
   setScene(scene, meshOf, { keepGeometry = true } = {}) {
     this.scene = scene;
     this.meshOf = meshOf;
-    if (!scene || !keepGeometry || this.pool.byteSize > POOL_REPACK_BYTES) {
+    if (!scene || !keepGeometry || (!scene.parts && this.pool.byteSize > POOL_REPACK_BYTES)) {
       this.pool.reset();
+      this.pool.unusedBytes = 0;
       this.cubeRange = this.pool.meshRange(this.cube);
     }
     this.backend.releaseMaterials(new Set(scene ? scene.materials : []));
     this.stats.totalUploadBytes = 0;
   }
 
+  /**
+   * The scene set being drawn changed (a fragment placed, hidden or removed):
+   * keep every packed mesh, free the materials no part uses, and repack the
+   * pool only once most of what it holds is geometry no part draws any more.
+   * Cheap: nothing here is proportional to the scene.
+   * @param {import('../scene/scene-set.js').SceneSet} set
+   */
+  updateScene(set) {
+    for (const entry of set.takeReleased()) {
+      if (set.geomIndex.has(entry)) continue; // taken again by another part
+      for (const mesh of entry.meshes) {
+        if (!mesh) continue;
+        const r = this.pool.ranges.get(mesh);
+        if (r) this.pool.unusedBytes = (this.pool.unusedBytes || 0) + mesh.vertexCount * VERTEX_BYTES + r.indexCount * 4;
+      }
+    }
+    if (this.pool.byteSize > POOL_REPACK_BYTES && (this.pool.unusedBytes || 0) * 2 > this.pool.byteSize) {
+      this.pool.reset();
+      this.pool.unusedBytes = 0;
+      this.cubeRange = this.pool.meshRange(this.cube);
+    }
+    if (this.materialsSeen !== set.materials.length || set.freeMaterials.length) this.backend.releaseMaterials(new Set(set.materials));
+    this.materialsSeen = set.materials.length;
+  }
+
   /**
    * Render one frame.
    * @param {import('./camera.js').Camera} camera