@tinypoly/gpu-renderer 0.0.0-stage → 0.0.1

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);
+};

package/src/camera.ts

@@ -0,0 +1,77 @@
+import { Matrix4, OrthographicCamera, PerspectiveCamera } from "three";
+import type { CameraState } from "./upstream.js";
+
+/**
+ * Everything the renderer derives from a camera snapshot. Rays are cast through the inverse of the camera's own
+ * projection, so zoom, film offsets, `setViewOffset` and any custom projection come out exactly as Three draws them,
+ * and so do the near and far planes, which clip a camera ray the way they clip a rasterized fragment.
+ */
+export interface CameraMatrices {
+  /** Column-major, as Three stores them. */
+  cameraWorld: number[];
+  view: number[];
+  projection: number[];
+  inverseProjection: number[];
+  orthographic: boolean;
+  near: number;
+  far: number;
+  /** Vertical field of view in degrees, for the lens; 50 when the snapshot has none. */
+  fov: number;
+  position: number[];
+}
+
+/** The camera's projection: the snapshot's own when it has one, otherwise rebuilt from its parameters. */
+export function cameraProjection(camera: CameraState, aspect: number): Matrix4 {
+  if (camera.projectionMatrix) return new Matrix4().fromArray(camera.projectionMatrix);
+
+  const projection = camera.type === "orthographic"
+    ? new OrthographicCamera(camera.left, camera.right, camera.top, camera.bottom, camera.near, camera.far)
+    : new PerspectiveCamera(camera.fov ?? 50, camera.aspect ?? aspect, camera.near, camera.far);
+
+  projection.zoom = camera.zoom ?? 1;
+  projection.updateProjectionMatrix();
+
+  return projection.projectionMatrix;
+}
+
+export function cameraMatrices(camera: CameraState, width: number, height: number): CameraMatrices {
+  const world = new Matrix4().fromArray(camera.matrixWorld);
+  const projection = cameraProjection(camera, width / height);
+  const orthographic = camera.type === "orthographic" || (projection.elements[11] === 0 && projection.elements[15] === 1);
+
+  return {
+    cameraWorld: world.toArray(),
+    view: world.clone().invert().toArray(),
+    projection: projection.toArray(),
+    inverseProjection: projection.clone().invert().toArray(),
+    orthographic,
+    near: camera.near,
+    far: camera.far,
+    fov: camera.fov ?? 50,
+    position: [camera.matrixWorld[12], camera.matrixWorld[13], camera.matrixWorld[14]],
+  };
+}
+
+/** A column-major 4x4 matrix times a point, with the w it produced. */
+export function transform4(matrix: ArrayLike<number>, x: number, y: number, z: number, w = 1): number[] {
+  return [
+    matrix[0] * x + matrix[4] * y + matrix[8] * z + matrix[12] * w,
+    matrix[1] * x + matrix[5] * y + matrix[9] * z + matrix[13] * w,
+    matrix[2] * x + matrix[6] * y + matrix[10] * z + matrix[14] * w,
+    matrix[3] * x + matrix[7] * y + matrix[11] * z + matrix[15] * w,
+  ];
+}
+
+/** A point in clip space back to world space, through the camera that produced it. */
+export function clipToWorld(camera: CameraMatrices, clip: readonly number[]): number[] {
+  const view = transform4(camera.inverseProjection, clip[0], clip[1], clip[2], clip[3]);
+  const w = view[3] || 1e-30;
+
+  return transform4(camera.cameraWorld, view[0] / w, view[1] / w, view[2] / w).slice(0, 3);
+}
+
+export function worldToClip(camera: CameraMatrices, point: readonly number[]): number[] {
+  const view = transform4(camera.view, point[0], point[1], point[2]);
+
+  return transform4(camera.projection, view[0], view[1], view[2], view[3]);
+}

package/src/canvas.ts

@@ -0,0 +1,13 @@
+import type { GpuRenderer } from "./renderer.js";
+
+/**
+ * Sends the renderer's output to a canvas. It configures the WebGPU context, sizes the canvas to the render
+ * resolution and presents after every submit, so the image refines in place while it converges.
+ *
+ * Returns the function that detaches it.
+ */
+export function attachCanvas(renderer: GpuRenderer, canvas: HTMLCanvasElement): () => void {
+  renderer.setOutputCanvas(canvas);
+
+  return () => renderer.setOutputCanvas(null);
+}