@tinypoly/gpu-renderer 0.0.0 → 0.0.2

package/src/bvh.ts

@@ -35,47 +35,6 @@ export interface PackedBvh {
   maxDepth: number;
 }
 
-interface Range {
-  start: number;
-  count: number;
-  node: number;
-  depth: number;
-}
-
-/** Axis aligned bounds under construction, in doubles so the sweep does not accumulate rounding. */
-class Bounds {
-  min = [Infinity, Infinity, Infinity];
-  max = [-Infinity, -Infinity, -Infinity];
-
-  reset() {
-    this.min = [Infinity, Infinity, Infinity];
-    this.max = [-Infinity, -Infinity, -Infinity];
-  }
-
-  addPoint(x: number, y: number, z: number) {
-    const point = [x, y, z];
-
-    for (let axis = 0; axis < 3; axis++) {
-      if (point[axis] < this.min[axis]) this.min[axis] = point[axis];
-      if (point[axis] > this.max[axis]) this.max[axis] = point[axis];
-    }
-  }
-
-  addBounds(other: Bounds) {
-    for (let axis = 0; axis < 3; axis++) {
-      if (other.min[axis] < this.min[axis]) this.min[axis] = other.min[axis];
-      if (other.max[axis] > this.max[axis]) this.max[axis] = other.max[axis];
-    }
-  }
-
-  /** Surface area, the cost the split heuristic weighs each side by. Empty bounds cost nothing. */
-  area(): number {
-    const x = this.max[0] - this.min[0], y = this.max[1] - this.min[1], z = this.max[2] - this.min[2];
-
-    return x < 0 || y < 0 || z < 0 ? 0 : 2 * (x * y + y * z + z * x);
-  }
-}
-
 /** Per-triangle bounds and centroids, the only inputs the split needs. */
 function triangleBounds(positions: Float32Array, triangleCount: number) {
   const min = new Float32Array(triangleCount * 3);
@@ -123,41 +82,81 @@ export function buildBvh(positions: Float32Array, triangleCount: number): Packed
     ints = new Int32Array(nodes);
   };
 
-  const stack: Range[] = [{ start: 0, count: triangleCount, node: 0, depth: 0 }];
-  const bounds = new Bounds();
+  // The pending ranges, four integers each: start, count, node and depth. Typed, so the loop allocates nothing.
+  let stack = new Int32Array(4 * 2 * MAX_BVH_DEPTH + 8);
+  let top = 1;
+  const bins = new Bins();
   let nodeCount = 1;
   let maxDepth = 0;
 
-  while (stack.length) {
-    const range = stack.pop() as Range;
+  stack[0] = 0;
+  stack[1] = triangleCount;
+  stack[2] = 0;
+  stack[3] = 0;
 
-    maxDepth = Math.max(maxDepth, range.depth);
-    bounds.reset();
+  while (top) {
+    top--;
 
-    for (let i = range.start; i < range.start + range.count; i++) {
-      const triangle = order[i] * 3;
+    const start = stack[top * 4], count = stack[top * 4 + 1], node = stack[top * 4 + 2], depth = stack[top * 4 + 3];
+    const end = start + count;
 
-      bounds.addPoint(min[triangle], min[triangle + 1], min[triangle + 2]);
-      bounds.addPoint(max[triangle], max[triangle + 1], max[triangle + 2]);
-    }
+    if (depth > maxDepth) maxDepth = depth;
 
-    const word = range.node * NODE_WORDS;
+    // The node's bounds and its centroids' bounds, in one pass. Doubles, so the corners are exactly the floats read.
+    let minX = Infinity, minY = Infinity, minZ = Infinity, maxX = -Infinity, maxY = -Infinity, maxZ = -Infinity;
+    let cMinX = Infinity, cMinY = Infinity, cMinZ = Infinity, cMaxX = -Infinity, cMaxY = -Infinity, cMaxZ = -Infinity;
 
-    floats[word] = bounds.min[0];
-    floats[word + 1] = bounds.min[1];
-    floats[word + 2] = bounds.min[2];
-    floats[word + 4] = bounds.max[0];
-    floats[word + 5] = bounds.max[1];
-    floats[word + 6] = bounds.max[2];
+    for (let i = start; i < end; i++) {
+      const triangle = order[i] * 3;
+      let value = min[triangle];
+
+      if (value < minX) minX = value;
+      value = min[triangle + 1];
+      if (value < minY) minY = value;
+      value = min[triangle + 2];
+      if (value < minZ) minZ = value;
+      value = max[triangle];
+      if (value > maxX) maxX = value;
+      value = max[triangle + 1];
+      if (value > maxY) maxY = value;
+      value = max[triangle + 2];
+      if (value > maxZ) maxZ = value;
+      value = centroid[triangle];
+      if (value < cMinX) cMinX = value;
+      if (value > cMaxX) cMaxX = value;
+      value = centroid[triangle + 1];
+      if (value < cMinY) cMinY = value;
+      if (value > cMaxY) cMaxY = value;
+      value = centroid[triangle + 2];
+      if (value < cMinZ) cMinZ = value;
+      if (value > cMaxZ) cMaxZ = value;
+    }
 
-    const split = range.count > MAX_LEAF_SIZE && range.depth + 1 < MAX_BVH_DEPTH
-      ? partition(order, centroid, min, max, range, bounds.area())
-      : -1;
+    const word = node * NODE_WORDS;
+
+    floats[word] = minX;
+    floats[word + 1] = minY;
+    floats[word + 2] = minZ;
+    floats[word + 4] = maxX;
+    floats[word + 5] = maxY;
+    floats[word + 6] = maxZ;
+
+    let split = -1;
+
+    if (count > MAX_LEAF_SIZE && depth + 1 < MAX_BVH_DEPTH) {
+      bins.centroidMin[0] = cMinX;
+      bins.centroidMin[1] = cMinY;
+      bins.centroidMin[2] = cMinZ;
+      bins.centroidMax[0] = cMaxX;
+      bins.centroidMax[1] = cMaxY;
+      bins.centroidMax[2] = cMaxZ;
+      split = partition(order, centroid, min, max, start, end, area(minX, minY, minZ, maxX, maxY, maxZ), bins);
+    }
 
     if (split < 0) {
       // A leaf points into `order` instead of into the node array, which the sign of the first link tells apart.
-      ints[word + 3] = -1 - range.start;
-      ints[word + 7] = range.count;
+      ints[word + 3] = -1 - start;
+      ints[word + 7] = count;
       continue;
     }
 
@@ -168,92 +167,157 @@ export function buildBvh(positions: Float32Array, triangleCount: number): Packed
 
     ints[word + 3] = left;
     ints[word + 7] = right;
-    stack.push({ start: range.start, count: split - range.start, node: left, depth: range.depth + 1 });
-    stack.push({ start: split, count: range.start + range.count - split, node: right, depth: range.depth + 1 });
+
+    if ((top + 2) * 4 > stack.length) {
+      const grown = new Int32Array(stack.length * 2);
+
+      grown.set(stack);
+      stack = grown;
+    }
+
+    // Left first, then right, so the right side is built first, as the order the tree was always built in.
+    stack.set([start, split - start, left, depth + 1, split, end - split, right, depth + 1], top * 4);
+    top += 2;
   }
 
   return { nodes: nodes.slice(0, nodeCount * NODE_WORDS * 4), nodeCount, order, maxDepth };
 }
 
+/** Surface area, the cost the split heuristic weighs each side by. Empty bounds cost nothing. */
+function area(minX: number, minY: number, minZ: number, maxX: number, maxY: number, maxZ: number): number {
+  const x = maxX - minX, y = maxY - minY, z = maxZ - minZ;
+
+  return x < 0 || y < 0 || z < 0 ? 0 : 2 * (x * y + y * z + z * x);
+}
+
+/** Scratch space for one split, kept across every node so binning allocates nothing. */
+class Bins {
+  readonly centroidMin = new Float64Array(3);
+  readonly centroidMax = new Float64Array(3);
+  /** Six doubles per bin and axis: the minimum corner, then the maximum. */
+  readonly bounds = new Float64Array(3 * BIN_COUNT * 6);
+  readonly counts = new Int32Array(3 * BIN_COUNT);
+  readonly rightArea = new Float64Array(BIN_COUNT);
+  readonly rightCount = new Int32Array(BIN_COUNT);
+  readonly scale = new Float64Array(3);
+
+  reset() {
+    const bounds = this.bounds;
+
+    for (let i = 0; i < bounds.length; i += 6) {
+      bounds[i] = bounds[i + 1] = bounds[i + 2] = Infinity;
+      bounds[i + 3] = bounds[i + 4] = bounds[i + 5] = -Infinity;
+    }
+
+    this.counts.fill(0);
+  }
+}
+
 /**
  * Reorders `order` in place so the range splits in two, and returns where the right side starts, or -1 when no split
- * beats keeping the range as a leaf. Bins the centroids on all three axes and sweeps the surface area heuristic.
+ * beats keeping the range as a leaf. Bins the centroids on all three axes in one pass and sweeps the surface area
+ * heuristic on each.
  */
 function partition(order: Uint32Array, centroid: Float64Array, min: Float32Array, max: Float32Array,
-  range: Range, parentArea: number): number {
+  start: number, end: number, parentArea: number, bins: Bins): number {
   if (parentArea <= 0) return -1;
 
-  const end = range.start + range.count;
-  const centroidBounds = new Bounds();
+  const { centroidMin, centroidMax, bounds, counts, rightArea, rightCount, scale } = bins;
+  let binned = false;
 
-  for (let i = range.start; i < end; i++) {
-    const triangle = order[i] * 3;
+  for (let axis = 0; axis < 3; axis++) {
+    const extent = centroidMax[axis] - centroidMin[axis];
 
-    centroidBounds.addPoint(centroid[triangle], centroid[triangle + 1], centroid[triangle + 2]);
+    // Every centroid sits at the same place on this axis: no split here separates anything.
+    scale[axis] = extent > 0 ? BIN_COUNT / extent : 0;
+    binned ||= extent > 0;
   }
 
-  // Splitting costs a traversal step, so a split only wins when it beats shading the whole range as one leaf.
-  let bestCost = range.count, bestAxis = -1, bestBin = -1, bestScale = 0;
+  if (!binned) return -1;
 
-  for (let axis = 0; axis < 3; axis++) {
-    const extent = centroidBounds.max[axis] - centroidBounds.min[axis];
+  bins.reset();
 
-    // Every centroid sits at the same place on this axis: no split here separates anything.
-    if (extent <= 0) continue;
+  for (let i = start; i < end; i++) {
+    const triangle = order[i] * 3;
+    const x0 = min[triangle], y0 = min[triangle + 1], z0 = min[triangle + 2];
+    const x1 = max[triangle], y1 = max[triangle + 1], z1 = max[triangle + 2];
 
-    const scale = BIN_COUNT / extent;
-    const binBounds = Array.from({ length: BIN_COUNT }, () => new Bounds());
-    const binCounts = new Int32Array(BIN_COUNT);
+    for (let axis = 0; axis < 3; axis++) {
+      if (scale[axis] === 0) continue;
 
-    for (let i = range.start; i < end; i++) {
-      const triangle = order[i] * 3;
-      const bin = binOf(centroid[triangle + axis], centroidBounds.min[axis], scale);
+      const bin = axis * BIN_COUNT + binOf(centroid[triangle + axis], centroidMin[axis], scale[axis]);
+      const at = bin * 6;
+
+      counts[bin]++;
 
-      binCounts[bin]++;
-      binBounds[bin].addPoint(min[triangle], min[triangle + 1], min[triangle + 2]);
-      binBounds[bin].addPoint(max[triangle], max[triangle + 1], max[triangle + 2]);
+      if (x0 < bounds[at]) bounds[at] = x0;
+      if (y0 < bounds[at + 1]) bounds[at + 1] = y0;
+      if (z0 < bounds[at + 2]) bounds[at + 2] = z0;
+      if (x1 > bounds[at + 3]) bounds[at + 3] = x1;
+      if (y1 > bounds[at + 4]) bounds[at + 4] = y1;
+      if (z1 > bounds[at + 5]) bounds[at + 5] = z1;
     }
+  }
+
+  // Splitting costs a traversal step, so a split only wins when it beats shading the whole range as one leaf.
+  let bestCost = end - start, bestAxis = -1, bestBin = -1;
+
+  for (let axis = 0; axis < 3; axis++) {
+    if (scale[axis] === 0) continue;
 
     // Sweeping once from each side turns the heuristic into two passes instead of one per candidate split.
-    const rightArea = new Float64Array(BIN_COUNT);
-    const rightCount = new Int32Array(BIN_COUNT);
-    const accumulated = new Bounds();
+    let minX = Infinity, minY = Infinity, minZ = Infinity, maxX = -Infinity, maxY = -Infinity, maxZ = -Infinity;
     let running = 0;
 
     for (let bin = BIN_COUNT - 1; bin > 0; bin--) {
-      accumulated.addBounds(binBounds[bin]);
-      running += binCounts[bin];
-      rightArea[bin] = accumulated.area();
+      const at = (axis * BIN_COUNT + bin) * 6;
+
+      if (bounds[at] < minX) minX = bounds[at];
+      if (bounds[at + 1] < minY) minY = bounds[at + 1];
+      if (bounds[at + 2] < minZ) minZ = bounds[at + 2];
+      if (bounds[at + 3] > maxX) maxX = bounds[at + 3];
+      if (bounds[at + 4] > maxY) maxY = bounds[at + 4];
+      if (bounds[at + 5] > maxZ) maxZ = bounds[at + 5];
+      running += counts[axis * BIN_COUNT + bin];
+      rightArea[bin] = area(minX, minY, minZ, maxX, maxY, maxZ);
       rightCount[bin] = running;
     }
 
-    accumulated.reset();
+    minX = minY = minZ = Infinity;
+    maxX = maxY = maxZ = -Infinity;
     running = 0;
 
     for (let bin = 0; bin < BIN_COUNT - 1; bin++) {
-      accumulated.addBounds(binBounds[bin]);
-      running += binCounts[bin];
+      const at = (axis * BIN_COUNT + bin) * 6;
+
+      if (bounds[at] < minX) minX = bounds[at];
+      if (bounds[at + 1] < minY) minY = bounds[at + 1];
+      if (bounds[at + 2] < minZ) minZ = bounds[at + 2];
+      if (bounds[at + 3] > maxX) maxX = bounds[at + 3];
+      if (bounds[at + 4] > maxY) maxY = bounds[at + 4];
+      if (bounds[at + 5] > maxZ) maxZ = bounds[at + 5];
+      running += counts[axis * BIN_COUNT + bin];
 
       if (!running || !rightCount[bin + 1]) continue;
 
       const cost = TRAVERSAL_COST
-        + (accumulated.area() * running + rightArea[bin + 1] * rightCount[bin + 1]) / parentArea;
+        + (area(minX, minY, minZ, maxX, maxY, maxZ) * running + rightArea[bin + 1] * rightCount[bin + 1]) / parentArea;
 
       if (cost < bestCost) {
         bestCost = cost;
         bestAxis = axis;
         bestBin = bin;
-        bestScale = scale;
       }
     }
   }
 
   if (bestAxis < 0) return -1;
 
-  const pivot = centroidBounds.min[bestAxis];
-  let left = range.start;
+  const pivot = centroidMin[bestAxis];
+  const bestScale = scale[bestAxis];
+  let left = start;
 
-  for (let i = range.start; i < end; i++) {
+  for (let i = start; i < end; i++) {
     if (binOf(centroid[order[i] * 3 + bestAxis], pivot, bestScale) <= bestBin) {
       const swap = order[i];
 
@@ -264,7 +328,7 @@ function partition(order: Uint32Array, centroid: Float64Array, min: Float32Array
   }
 
   // The sweep only proposes splits both sides occupy, so this is a guard against rounding, not an expected outcome.
-  return left === range.start || left === end ? -1 : left;
+  return left === start || left === end ? -1 : left;
 }
 
 function binOf(value: number, origin: number, scale: number): number {

package/src/bvhBuilder.ts

@@ -0,0 +1,178 @@
+import { buildBvh, type PackedBvh } from "./bvh.js";
+
+/** What the page sends the worker: its own copy of the positions, transferred. */
+export interface BvhRequest {
+  id: number;
+  positions: Float32Array;
+  triangleCount: number;
+}
+
+/** The hierarchy back, its buffers transferred, or why it could not be built. */
+export type BvhResponse =
+  | { id: number; nodes: ArrayBuffer; nodeCount: number; order: Uint32Array; maxDepth: number }
+  | { id: number; error: string };
+
+/**
+ * What the renderer needs from a worker: the shape of a Web `Worker`. Any transport that carries structured clones and
+ * transfer lists fits, such as a `worker_threads` thread behind an adapter.
+ */
+export interface BvhWorker {
+  postMessage(message: BvhRequest, transfer?: Transferable[]): void;
+  terminate(): void;
+  onmessage: ((event: { data: BvhResponse }) => void) | null;
+  onerror: ((event: { message?: string; preventDefault?(): void }) => void) | null;
+}
+
+export type BvhWorkerFactory = () => BvhWorker;
+
+/**
+ * Below this many triangles the hierarchy is built on the page: it takes a few milliseconds, less than copying the
+ * positions to a worker and the hierarchy back.
+ */
+export const BVH_WORKER_MIN_TRIANGLES = 50_000;
+
+/** The worker this package ships, next to this module. Replace it when the bundler cannot follow the URL. */
+export function createDefaultBvhWorker(): BvhWorker {
+  if (typeof Worker === "undefined")
+    throw new Error("Web Workers are unavailable here: pass `createBvhWorker`, or `bvhWorker: false`.");
+
+  return new Worker(new URL("./bvhWorker.js", import.meta.url), { type: "module" }) as unknown as BvhWorker;
+}
+
+/** The worker's side of the exchange, apart from the worker itself so it can be run anywhere. */
+export function respondToBvhRequest(request: BvhRequest): { response: BvhResponse; transfer: Transferable[] } {
+  try {
+    const bvh = buildBvh(request.positions, request.triangleCount);
+
+    return {
+      response: { id: request.id, ...bvh },
+      transfer: [bvh.nodes, bvh.order.buffer],
+    };
+  } catch(error) {
+    const message = error instanceof Error ? error.message : String(error);
+
+    return { response: { id: request.id, error: message }, transfer: [] };
+  }
+}
+
+interface Pending {
+  positions: Float32Array;
+  triangleCount: number;
+  resolve: (bvh: PackedBvh) => void;
+  reject: (error: Error) => void;
+}
+
+/**
+ * Builds hierarchies in a worker, so a large scene does not hold the page while it is split. The worker is started on
+ * the first build that needs it and kept for the next ones. If it cannot be started or fails to load, every build from
+ * then on happens on the page, with the same result: the worker only moves the work, it never changes it.
+ */
+export class BvhBuilder {
+  private worker: BvhWorker | null = null;
+  private failed = false;
+  private disposed = false;
+  private next = 0;
+  private readonly pending = new Map<number, Pending>();
+
+  constructor(
+    private readonly enabled: boolean,
+    private readonly createWorker: BvhWorkerFactory = createDefaultBvhWorker,
+    private readonly minTriangles = BVH_WORKER_MIN_TRIANGLES) {}
+
+  /** Whether builds go to the worker: it is enabled and has not failed. */
+  get usesWorker(): boolean {
+    return this.enabled && !this.failed && !this.disposed;
+  }
+
+  build(positions: Float32Array, triangleCount: number): Promise<PackedBvh> {
+    if (this.disposed) return Promise.reject(abortError());
+
+    const worker = this.usesWorker && triangleCount >= this.minTriangles ? this.connect() : null;
+
+    if (!worker) return Promise.resolve(buildBvh(positions, triangleCount));
+
+    const id = this.next++;
+    // The page still uploads the positions, so the worker gets a copy it can own.
+    const copy = positions.slice(0, triangleCount * 9);
+
+    return new Promise<PackedBvh>((resolve, reject) => {
+      this.pending.set(id, { positions, triangleCount, resolve, reject });
+      worker.postMessage({ id, positions: copy, triangleCount }, [copy.buffer]);
+    });
+  }
+
+  /** Stops the worker. Builds still waiting for it reject with an `AbortError`. */
+  dispose() {
+    this.disposed = true;
+    this.worker?.terminate();
+    this.worker = null;
+
+    for (const pending of this.pending.values()) pending.reject(abortError());
+
+    this.pending.clear();
+  }
+
+  private connect(): BvhWorker | null {
+    if (this.worker) return this.worker;
+
+    let worker: BvhWorker;
+
+    try {
+      worker = this.createWorker();
+    } catch(error) {
+      this.fail(error instanceof Error ? error.message : String(error));
+
+      return null;
+    }
+
+    worker.onmessage = event => this.receive(event.data);
+
+    worker.onerror = event => {
+      event.preventDefault?.();
+      this.fail(event.message || "the worker failed to load");
+    };
+
+    this.worker = worker;
+
+    return worker;
+  }
+
+  private receive(response: BvhResponse) {
+    const pending = this.pending.get(response.id);
+
+    if (!pending) return;
+
+    this.pending.delete(response.id);
+
+    if ("error" in response) pending.reject(new Error(`GPU renderer: building the BVH failed: ${response.error}`));
+    else pending.resolve({
+      nodes: response.nodes, nodeCount: response.nodeCount, order: response.order, maxDepth: response.maxDepth,
+    });
+  }
+
+  /** The worker is gone for good: what it was building, and everything after, is built on the page instead. */
+  private fail(reason: string) {
+    if (!this.failed)
+      console.warn(`GPU renderer: the BVH worker is unavailable (${reason}); building on the main thread instead.`);
+
+    this.failed = true;
+    this.worker?.terminate();
+    this.worker = null;
+
+    const waiting = [...this.pending.values()];
+
+    this.pending.clear();
+
+    for (const pending of waiting) {
+      try {
+        pending.resolve(buildBvh(pending.positions, pending.triangleCount));
+      } catch(error) {
+        pending.reject(error instanceof Error ? error : new Error(String(error)));
+      }
+    }
+  }
+}
+
+function abortError(): Error {
+  return Object.assign(new Error("The renderer was disposed."), { name: "AbortError" });
+}

package/src/bvhWorker.ts

@@ -0,0 +1,13 @@
+// The worker `createDefaultBvhWorker` starts: it builds one hierarchy per message, off the page's thread.
+import { respondToBvhRequest, type BvhRequest, type BvhResponse } from "./bvhBuilder.js";
+
+const scope = self as unknown as {
+  onmessage: ((event: MessageEvent<BvhRequest>) => void) | null;
+  postMessage(message: BvhResponse, transfer: Transferable[]): void;
+};
+
+scope.onmessage = event => {
+  const { response, transfer } = respondToBvhRequest(event.data);
+
+  scope.postMessage(response, transfer);
+};