@driftengine/splats 3.61.0

package/src/splatSorter.ts

@@ -0,0 +1,285 @@
+/** The scheduler: one sort in flight, newest view wins, and the worker is a default not a mechanism. */
+
+import { createSplatSortScratch, sortSplatsByDepth } from './splatSort.ts';
+import { createSplatSortWorker } from './splatSortWorker.ts';
+import type {
+  SplatSortFn,
+  SplatSortRequest,
+  SplatSortResult,
+  SplatSortScratch,
+} from './splatSort.ts';
+import type { SplatData } from './splatData.ts';
+import type { SplatViewLocal } from './splatView.ts';
+
+/**
+ * How far the view may turn before the order is worth recomputing.
+ *
+ * A dot product, so 0.999 is about 2.6 degrees. Below that the change in ordering is a handful of
+ * adjacent swaps among splats that overlap anyway, and re-sorting for it would mean a sort every
+ * frame at any camera speed — which is the cost this whole arrangement exists to avoid. **A still
+ * camera sorts zero times a second**, which is the property to preserve.
+ */
+const RESORT_DOT = 0.999;
+
+/**
+ * How far the camera may move, as a fraction of the capture's own radius, before a re-sort.
+ *
+ * **A fraction rather than a distance, because a distance means different things for a room and
+ * for a landscape.** Only consulted when there is a budget: see `frame`.
+ */
+const RESORT_MOVE_FRACTION = 0.1;
+
+export interface SplatSorterOptions {
+  /** The capture. Its positions, extents and bounds are all read; its packed texels are not. */
+  readonly splats: SplatData;
+  /** Defaults to a `Blob` worker, falling back to the main thread. See `createDefaultSplatSort`. */
+  readonly sort?: SplatSortFn;
+  /**
+   * The most splats to draw. Zero, or anything at or above the capture's count, draws all of them.
+   *
+   * `defaultSplatBudget` is what a consumer that has no number of its own should pass.
+   */
+  readonly budget?: number;
+  /** Overrides `RESORT_MOVE_FRACTION`. Only consulted when there is a budget. */
+  readonly moveFraction?: number;
+  /**
+   * How many of the capture's splats have actually arrived. Defaults to all of them.
+   *
+   * **A capability rather than a number, because it changes while a capture streams.** A
+   * `SplatCapture` is allocated at its final count and filled block by block, so its unarrived
+   * tail is zeroed — every phantom splat sitting at the origin with no size. Sorting those would
+   * order a cloud of them into the middle of the capture and draw them, which reads as a corrupt
+   * file rather than as a load in progress. Pass `() => capture.ready` and this follows the load.
+   */
+  readonly ready?: () => number;
+}
+
+/**
+ * The sort, on the main thread, right now.
+ *
+ * The fallback when a worker cannot be built, and the implementation a test injects. Synchronous
+ * inside a promise: there is nothing to await, and pretending otherwise would hide that this
+ * blocks.
+ *
+ * **The scratch is cached across calls and grown when it has to be.** It is 384 KB of histogram
+ * plus four bytes a splat, and allocating that per sort would make the fallback path generate more
+ * garbage than the work it is doing. Sharing one scratch between two captures is safe because this
+ * is synchronous: no second sort can start while one is running on this thread.
+ */
+let mainThreadScratch: SplatSortScratch | null = null;
+
+export function sortOnMainThread(request: SplatSortRequest): Promise<SplatSortResult> {
+  if (mainThreadScratch === null || mainThreadScratch.keys.length < request.count) {
+    mainThreadScratch = createSplatSortScratch(request.count);
+  }
+  const count = sortSplatsByDepth(request, mainThreadScratch);
+  return Promise.resolve({ order: request.out, count });
+}
+
+/**
+ * The shipped capability: a worker over the same sort this module runs on the main thread.
+ *
+ * `sortSplatsByDepth.toString()` is what goes into the worker, so there is one implementation of
+ * the decision and not two — the 2026-08-17 rule, which is about exactly this. It works because
+ * that function closes over nothing: its scratch and its two bucket counts all arrive as
+ * arguments.
+ */
+export function createDefaultSplatSort(): SplatSortFn {
+  return createSplatSortWorker(sortSplatsByDepth.toString());
+}
+
+/**
+ * Hold the newest order, ask for a new one when the view has changed enough, and never queue.
+ *
+ * **At most one sort in flight, and a request while one is running is dropped rather than
+ * queued.** The newest view is the only one worth sorting for: a queue would sort for a camera
+ * position the player has already left, and then sort again, so it converts a busy moment into a
+ * backlog that never catches up.
+ *
+ * **Two buffers, ping-ponged.** One is being filled by the sorter and the other is what the pass
+ * draws from, so a sort landing mid-frame never rewrites the order under a draw call.
+ */
+export class SplatSorter {
+  private readonly splats: SplatData;
+  private readonly sort: SplatSortFn;
+  private readonly budget: number;
+  private readonly moveFraction: number;
+  private readonly ready: () => number;
+  /** How many splats the standing order was computed over, so an arrival is a reason to re-sort. */
+  private sortedReady = 0;
+  /** Half the diagonal of the capture's own bounds. The scale the move gate is a fraction of. */
+  private readonly radius: number;
+  private readonly buffers: [Uint32Array, Uint32Array];
+  /** Which buffer the sorter owns. The other is the one a caller may read. */
+  private filling = 0;
+  private inFlight = false;
+  /** The view the standing order was computed for. Meaningless until `hasSorted`. */
+  private sortedDirX = 0;
+  private sortedDirY = 0;
+  private sortedDirZ = 0;
+  private sortedOriginX = 0;
+  private sortedOriginY = 0;
+  private sortedOriginZ = 0;
+  private hasSorted = false;
+  /** How many indices the standing order actually holds, which a budget makes smaller. */
+  private kept = 0;
+  /** Bumped by every sort that lands, so a caller can tell a new order from the one it has. */
+  private generation = 0;
+
+  constructor(options: SplatSorterOptions) {
+    this.splats = options.splats;
+    /*
+     * The worker is the default and the main thread is the fallback, and neither is the mechanism:
+     * a caller that supplies its own never reaches either. Built once per sorter rather than once
+     * per module, so two captures do not share one worker and serialise behind each other.
+     */
+    this.sort = options.sort ?? createDefaultSplatSort();
+    this.budget = options.budget ?? 0;
+    this.moveFraction = options.moveFraction ?? RESORT_MOVE_FRACTION;
+    this.ready = options.ready ?? ((): number => options.splats.count);
+    const { boundsMin, boundsMax } = options.splats;
+    this.radius =
+      0.5 *
+      Math.hypot(
+        (boundsMax[0] ?? 0) - (boundsMin[0] ?? 0),
+        (boundsMax[1] ?? 0) - (boundsMin[1] ?? 0),
+        (boundsMax[2] ?? 0) - (boundsMin[2] ?? 0),
+      );
+    const size = Math.max(1, options.splats.count);
+    this.buffers = [new Uint32Array(size), new Uint32Array(size)];
+  }
+
+  /** The standing order, or null until the first sort lands. */
+  get order(): Uint32Array | null {
+    return this.hasSorted ? (this.buffers[1 - this.filling] as Uint32Array) : null;
+  }
+
+  /** How many entries of `order` are real. Below the capture's count when a budget bit. */
+  get drawCount(): number {
+    return this.kept;
+  }
+
+  /** How many orders have landed. A caller uploads when this changes and not otherwise. */
+  get version(): number {
+    return this.generation;
+  }
+
+  /**
+   * Whether a sort is in flight.
+   *
+   * **What a measuring page waits on, and it has to wait on more than `version`.** With a budget
+   * the sort chooses *which* splats are drawn and not merely their order, so a capture
+   * photographed at the first landed sort is a capture photographed at whichever sort the worker
+   * happened to finish — and two backends that reach the held frame at different wall-clock times
+   * then draw different splats. A held camera is settled when this is false and the standing
+   * `version` has been uploaded: at a fixed direction `frame` asks for nothing further, so that
+   * state is reached and then keeps.
+   */
+  get sorting(): boolean {
+    return this.inFlight;
+  }
+
+  /**
+   * Offer the current view, in the capture's own space. Starts a sort if one is wanted.
+   *
+   * `resolveSplatView` is what turns a camera and a model matrix into this. `force` is for the
+   * first frame and for a capture whose transform moved, where the view in its own space may be
+   * unchanged and the order is stale anyway.
+   *
+   * **Turning always matters; moving only matters when there is a budget.** Depth is measured
+   * along the view axis, so translating the camera shifts every splat's depth by the same amount
+   * and leaves the ordering exactly as it was — which is why this gate did not exist until a
+   * budget did. A budget keeps the splats largest on screen, which is the extent over the
+   * *distance*, so a camera that walks across a capture without turning changes which splats are
+   * drawn. What that costs is a sort every tenth of a capture-radius while a viewer moves; what
+   * would make it wrong is a budget so generous that nothing is ever dropped, where the gate spends
+   * sorts to reach the same answer.
+   */
+  frame(local: SplatViewLocal, force = false): void {
+    const count = Math.max(0, Math.min(this.ready(), this.splats.count));
+    if (count <= 0) return;
+    if (this.inFlight) return;
+
+    /*
+     * **An arrival is a reason to sort even from a camera that has not moved.** The order this
+     * sorter holds is an order over fewer splats than the capture now has, so it is not the order
+     * it wants — and a viewer watching a capture load is exactly the viewer who is standing
+     * still. Without this a stream stops densifying the moment nobody moves.
+     */
+    let wanted = force || !this.hasSorted || count !== this.sortedReady;
+    if (!wanted) {
+      const turned =
+        local.dirX * this.sortedDirX + local.dirY * this.sortedDirY + local.dirZ * this.sortedDirZ <
+        RESORT_DOT;
+      wanted = turned;
+    }
+    if (!wanted && this.budget > 0 && this.budget < count && this.radius > 0) {
+      const moved = Math.hypot(
+        local.originX - this.sortedOriginX,
+        local.originY - this.sortedOriginY,
+        local.originZ - this.sortedOriginZ,
+      );
+      wanted = moved > this.moveFraction * this.radius;
+    }
+    if (!wanted) return;
+
+    this.inFlight = true;
+    const target = this.buffers[this.filling] as Uint32Array;
+    /*
+     * Snapshotted before the call, because `local` belongs to the caller and is rewritten in place
+     * every frame — so reading it again when the promise settles would record the view the camera
+     * has *now* as the one this order was computed for, and the re-sort gates would then compare
+     * against a lie. Six numbers on the stack rather than a copy of the object, so nothing is
+     * allocated for it.
+     */
+    const dirX = local.dirX;
+    const dirY = local.dirY;
+    const dirZ = local.dirZ;
+    const originX = local.originX;
+    const originY = local.originY;
+    const originZ = local.originZ;
+    void this.sort({
+      positions: this.splats.positions,
+      extents: this.splats.extents,
+      count,
+      dirX,
+      dirY,
+      dirZ,
+      originX,
+      originY,
+      originZ,
+      budget: this.budget,
+      out: target,
+    })
+      .then((result) => {
+        /*
+         * The buffer that comes back is the one that was handed out — a worker transfers it away
+         * and transfers it back, so the array identity may differ even though the storage is the
+         * same. Store what arrived rather than what was sent.
+         */
+        this.buffers[this.filling] = result.order;
+        this.filling = 1 - this.filling;
+        this.sortedDirX = dirX;
+        this.sortedDirY = dirY;
+        this.sortedDirZ = dirZ;
+        this.sortedOriginX = originX;
+        this.sortedOriginY = originY;
+        this.sortedOriginZ = originZ;
+        this.kept = result.count;
+        this.sortedReady = count;
+        this.hasSorted = true;
+        this.generation++;
+      })
+      .catch(() => {
+        /*
+         * **A rejected sort leaves the previous order drawing**, which is the honest degradation:
+         * a capture one camera step out of order is very slightly wrong at some silhouettes, and a
+         * capture with no order at all is not drawn. Swallowed rather than rethrown because this
+         * is reached from a frame and the loop may not throw.
+         */
+      })
+      .finally(() => {
+        this.inFlight = false;
+      });
+  }
+}

package/src/splatView.ts

@@ -0,0 +1,147 @@
+/** Where the camera is, and which way it faces, expressed in one capture's own space. */
+
+/**
+ * The camera as the sorter needs it: in the capture's coordinates rather than the world's.
+ *
+ * Mutable and filled in place, because this is resolved once a frame per batch and the engine's
+ * rule about per-frame allocation binds a package exactly as it binds the renderer.
+ */
+export interface SplatViewLocal {
+  /** The camera's forward in the capture's own space, unit length. */
+  dirX: number;
+  dirY: number;
+  dirZ: number;
+  /** The camera's position in the capture's own space. */
+  originX: number;
+  originY: number;
+  originZ: number;
+}
+
+export function createSplatViewLocal(): SplatViewLocal {
+  return { dirX: 0, dirY: 0, dirZ: -1, originX: 0, originY: 0, originZ: 0 };
+}
+
+/**
+ * Fill `out` with the camera, in the space the capture's own positions are written in.
+ *
+ * **One sorter serves one batch, and this is what makes that affordable.** A batch has a model
+ * matrix so that two captures can compose in one scene; its splat positions are in its own frame
+ * and the sort reads them there, so asking the sort for a *world* direction would mean
+ * transforming a million positions every time the view turned. Transforming the camera instead is
+ * six numbers.
+ *
+ * **The direction is the model's transpose and not its inverse, and the two disagree exactly where
+ * it matters.** What the sort needs is an ordering that matches the depth those splats really have
+ * once the model has moved them, and the world depth of a capture-space point `p` is
+ * `dot(M p + t - c, d)`, which rearranges to `dot(p, Mᵀd)` plus a constant. So `Mᵀd` is the
+ * direction that orders correctly for *any* invertible model, including one with a non-uniform
+ * scale; `M⁻¹d` is the direction that would be right if the transform were a rotation, and a
+ * plausible-looking answer everywhere else. `splatView.test.ts` asserts the ordering rather than
+ * the arithmetic, which is why the model it uses is stretched.
+ *
+ * The origin is the inverse, because that genuinely is a point: `M⁻¹(c − t)` is where the camera
+ * sits in the capture's frame, and it is what the budget's distances are measured from. It also
+ * happens to be exactly the point whose projection along `Mᵀd` cancels the constant above, so the
+ * two halves agree by construction rather than by arrangement.
+ *
+ * **What this gives up**: the ordering is along the view *axis* rather than by distance to the
+ * camera point, so two splats at equal depth and far apart across the frame are ordered by a plane
+ * rather than by a sphere. That is the ordering every splat renderer uses and it costs nothing
+ * until a capture wraps around the viewer. What would make it wrong is exactly that case —
+ * standing inside a capture at a wide field of view, where the error shows at the frame's corners.
+ *
+ * **A singular model falls back to the world rather than to `NaN`.** This is reached from a frame
+ * and the loop may not throw; a `NaN` direction is a sort in which every comparison is false,
+ * which is silently input order rather than a visible fault.
+ */
+export function resolveSplatView(
+  view: ArrayLike<number>,
+  model: ArrayLike<number>,
+  out: SplatViewLocal,
+): void {
+  /*
+   * The camera's forward in the world is the third row of the view rotation, negated: the view
+   * matrix takes world to camera and a camera looks down its own -z.
+   */
+  const forwardX = -(view[2] ?? 0);
+  const forwardY = -(view[6] ?? 0);
+  const forwardZ = -(view[10] ?? 0);
+
+  /* The camera's position is -Rᵀt, which for a rigid view matrix is an exact inverse and costs
+     nine multiplies rather than a general inversion. */
+  const tx = view[12] ?? 0;
+  const ty = view[13] ?? 0;
+  const tz = view[14] ?? 0;
+  const cameraX = -((view[0] ?? 0) * tx + (view[1] ?? 0) * ty + (view[2] ?? 0) * tz);
+  const cameraY = -((view[4] ?? 0) * tx + (view[5] ?? 0) * ty + (view[6] ?? 0) * tz);
+  const cameraZ = -((view[8] ?? 0) * tx + (view[9] ?? 0) * ty + (view[10] ?? 0) * tz);
+
+  /*
+   * **Named by row then column, because binding these the other way is a transposed inverse and a
+   * plausible picture.** `model` is column-major, so the element at row `r` and column `c` is
+   * `model[c * 4 + r]` — while the cofactor formulas below are written the way every reference
+   * writes them, in rows. Reading three consecutive array entries as a row looks like a matching
+   * pattern and quietly inverts the transpose; it did here, and the ordering test caught it by a
+   * sign.
+   */
+  const a00 = model[0] ?? 0;
+  const a10 = model[1] ?? 0;
+  const a20 = model[2] ?? 0;
+  const a01 = model[4] ?? 0;
+  const a11 = model[5] ?? 0;
+  const a21 = model[6] ?? 0;
+  const a02 = model[8] ?? 0;
+  const a12 = model[9] ?? 0;
+  const a22 = model[10] ?? 0;
+
+  /*
+   * Mᵀd. Transposing turns the matrix's columns into rows, and a column of a column-major array is
+   * three adjacent entries — so this reads as three plain dot products against the array as
+   * stored, which is the one place the layout helps rather than hinders.
+   */
+  const rawX = a00 * forwardX + a10 * forwardY + a20 * forwardZ;
+  const rawY = a01 * forwardX + a11 * forwardY + a21 * forwardZ;
+  const rawZ = a02 * forwardX + a12 * forwardY + a22 * forwardZ;
+  const length = Math.hypot(rawX, rawY, rawZ);
+
+  /* Cofactors of the first row, which give the determinant and a third of the inverse at once. */
+  const c00 = a11 * a22 - a12 * a21;
+  const c01 = a12 * a20 - a10 * a22;
+  const c02 = a10 * a21 - a11 * a20;
+  const determinant = a00 * c00 + a01 * c01 + a02 * c02;
+
+  if (
+    length === 0 ||
+    determinant === 0 ||
+    !Number.isFinite(length) ||
+    !Number.isFinite(determinant)
+  ) {
+    out.dirX = forwardX;
+    out.dirY = forwardY;
+    out.dirZ = forwardZ;
+    out.originX = cameraX;
+    out.originY = cameraY;
+    out.originZ = cameraZ;
+    return;
+  }
+
+  out.dirX = rawX / length;
+  out.dirY = rawY / length;
+  out.dirZ = rawZ / length;
+
+  const relativeX = cameraX - (model[12] ?? 0);
+  const relativeY = cameraY - (model[13] ?? 0);
+  const relativeZ = cameraZ - (model[14] ?? 0);
+  const inverse = 1 / determinant;
+  /* M⁻¹ = adj(M)/det, and the adjugate is the *transpose* of the cofactor matrix — which is why
+     c01 and c02 open the second and third rows here rather than the first. */
+  out.originX =
+    (c00 * relativeX + (a02 * a21 - a01 * a22) * relativeY + (a01 * a12 - a02 * a11) * relativeZ) *
+    inverse;
+  out.originY =
+    (c01 * relativeX + (a00 * a22 - a02 * a20) * relativeY + (a02 * a10 - a00 * a12) * relativeZ) *
+    inverse;
+  out.originZ =
+    (c02 * relativeX + (a01 * a20 - a00 * a21) * relativeY + (a00 * a11 - a01 * a10) * relativeZ) *
+    inverse;
+}