@driftengine/core 4.4.2 → 4.6.0

package/dist/world/hlod.js

@@ -0,0 +1,214 @@
+import { batchBoxVisible } from '../render/instanceCull.js';
+/** The level of a region drawn at none of its own: past `farDistance`, or not arrived yet. */
+export const HLOD_NONE = 255;
+/** Room for every region of a set of this capacity, each crossfading at once. */
+export function createHlodDraws(capacity) {
+    return {
+        count: 0,
+        region: new Uint32Array(capacity * 2),
+        level: new Uint8Array(capacity * 2),
+        dither: new Float32Array(capacity * 2),
+    };
+}
+/** Pixels a metre spans at one metre's distance: the screen's half of the switch distance. */
+export function projectionScaleOf(fovYDeg, heightPx) {
+    return heightPx / (2 * Math.tan((fovYDeg * Math.PI) / 360));
+}
+export class HlodSet {
+    capacity;
+    maxLevels;
+    tolerance;
+    band;
+    fadeSec;
+    far;
+    slots = new Map();
+    ids;
+    boxes;
+    errors;
+    levels;
+    /** The level each region is at, or arriving at. */
+    level;
+    /** The level a crossfade is leaving. */
+    from;
+    /** How far through its crossfade each region is; 1 is settled. */
+    fade;
+    box = new Float32Array(6);
+    count = 0;
+    constructor(options) {
+        this.capacity = options.capacity;
+        this.maxLevels = options.maxLevels ?? 4;
+        if (this.maxLevels < 1 || this.maxLevels >= HLOD_NONE) {
+            throw new Error(`HlodSet: maxLevels must be 1 to ${HLOD_NONE - 1}, not ${this.maxLevels}`);
+        }
+        this.tolerance = options.pixelTolerance ?? 1.5;
+        this.band = options.hysteresis ?? 0.15;
+        this.fadeSec = options.fadeSec ?? 0.4;
+        this.far = options.farDistance ?? Number.POSITIVE_INFINITY;
+        this.ids = new Uint32Array(this.capacity);
+        this.boxes = new Float32Array(this.capacity * 6);
+        this.errors = new Float32Array(this.capacity * this.maxLevels);
+        this.levels = new Uint8Array(this.capacity);
+        this.level = new Uint8Array(this.capacity);
+        this.from = new Uint8Array(this.capacity);
+        this.fade = new Float32Array(this.capacity);
+    }
+    get size() {
+        return this.count;
+    }
+    has(id) {
+        return this.slots.has(id);
+    }
+    /** The level a region is at or arriving at, or `HLOD_NONE`. -1 for a region not in the set. */
+    levelOf(id) {
+        const slot = this.slots.get(id);
+        return slot === undefined ? -1 : this.level[slot];
+    }
+    /**
+     * Add a region: its box as min then max, and one geometric error per level, finest first and
+     * never shrinking. It arrives at no level and fades into the one the next `select` picks.
+     */
+    add(id, box, errors) {
+        if (this.slots.has(id))
+            throw new Error(`HlodSet: region ${id} is already in the set`);
+        if (this.count >= this.capacity) {
+            throw new Error(`HlodSet: the set holds ${this.capacity} regions and is full`);
+        }
+        if (errors.length < 1 || errors.length > this.maxLevels) {
+            throw new Error(`HlodSet: region ${id} has ${errors.length} levels; 1 to ${this.maxLevels} are allowed`);
+        }
+        for (let i = 1; i < errors.length; i++) {
+            if (errors[i] < errors[i - 1]) {
+                throw new Error(`HlodSet: region ${id}'s level ${i} is finer than level ${i - 1}`);
+            }
+        }
+        const slot = this.count++;
+        this.slots.set(id, slot);
+        this.ids[slot] = id;
+        for (let i = 0; i < 6; i++)
+            this.boxes[slot * 6 + i] = box[i];
+        for (let i = 0; i < errors.length; i++) {
+            this.errors[slot * this.maxLevels + i] = errors[i];
+        }
+        this.levels[slot] = errors.length;
+        this.level[slot] = HLOD_NONE;
+        this.from[slot] = HLOD_NONE;
+        this.fade[slot] = 1;
+    }
+    /** Remove a region; nothing if it is not there. The last region takes its slot. */
+    remove(id) {
+        const slot = this.slots.get(id);
+        if (slot === undefined)
+            return;
+        this.slots.delete(id);
+        const last = --this.count;
+        if (slot === last)
+            return;
+        const moved = this.ids[last];
+        this.slots.set(moved, slot);
+        this.ids[slot] = moved;
+        this.boxes.copyWithin(slot * 6, last * 6, last * 6 + 6);
+        this.errors.copyWithin(slot * this.maxLevels, last * this.maxLevels, (last + 1) * this.maxLevels);
+        this.levels[slot] = this.levels[last];
+        this.level[slot] = this.level[last];
+        this.from[slot] = this.from[last];
+        this.fade[slot] = this.fade[last];
+    }
+    /**
+     * Decide every region's level for this view and write what to draw into `out`, returning how
+     * many draws that is. `projectionScale` is `projectionScaleOf(fov, height)`; `occluder` may be
+     * the renderer, asked after this frame's occluders are declared.
+     */
+    select(eye, projectionScale, frustum, occluder, dtSec, out) {
+        const ex = eye[0];
+        const ey = eye[1];
+        const ez = eye[2];
+        const perError = projectionScale / this.tolerance;
+        const step = this.fadeSec > 0 ? dtSec / this.fadeSec : 1;
+        let n = 0;
+        for (let slot = 0; slot < this.count; slot++) {
+            const b = slot * 6;
+            const dx = Math.max(this.boxes[b] - ex, 0, ex - this.boxes[b + 3]);
+            const dy = Math.max(this.boxes[b + 1] - ey, 0, ey - this.boxes[b + 4]);
+            const dz = Math.max(this.boxes[b + 2] - ez, 0, ez - this.boxes[b + 5]);
+            const d = Math.sqrt(dx * dx + dy * dy + dz * dz);
+            const target = this.levelFor(slot, d, perError);
+            this.move(slot, target);
+            for (let i = 0; i < 6; i++)
+                this.box[i] = this.boxes[b + i];
+            if (!batchBoxVisible(this.box, frustum, occluder)) {
+                this.fade[slot] = 1;
+                continue;
+            }
+            let t = this.fade[slot];
+            if (t < 1) {
+                t = Math.min(1, t + step);
+                this.fade[slot] = t;
+            }
+            const level = this.level[slot];
+            const id = this.ids[slot];
+            if (t >= 1) {
+                if (level !== HLOD_NONE)
+                    n = this.emit(out, n, id, level, 0);
+                continue;
+            }
+            /* Nothing of the arriving level at t = 0, and a dither of 0 would draw it whole. */
+            if (level !== HLOD_NONE && t > 0)
+                n = this.emit(out, n, id, level, t);
+            const from = this.from[slot];
+            if (from !== HLOD_NONE)
+                n = this.emit(out, n, id, from, -t);
+        }
+        out.count = n;
+        return n;
+    }
+    /** The level a region at distance `d` should be at, from where it is, through the bands. */
+    levelFor(slot, d, perError) {
+        const count = this.levels[slot];
+        const current = this.level[slot];
+        /* NONE counts as the level past the coarsest, whose distance is the far limit. */
+        let at = current === HLOD_NONE ? count : current;
+        while (at < count && d > this.switchAt(slot, at + 1, count, perError) * (1 + this.band))
+            at++;
+        while (at > 0 && d < this.switchAt(slot, at, count, perError) * (1 - this.band))
+            at--;
+        return at === count ? HLOD_NONE : at;
+    }
+    /** The distance level `index` takes over at; the level past the coarsest is the far limit. */
+    switchAt(slot, index, count, perError) {
+        if (index >= count)
+            return this.far;
+        return this.errors[slot * this.maxLevels + index] * perError;
+    }
+    /** Begin, reverse or redirect a crossfade toward `target`. */
+    move(slot, target) {
+        const level = this.level[slot];
+        if (target === level)
+            return;
+        const fade = this.fade[slot];
+        if (fade >= 1) {
+            this.from[slot] = level;
+            this.fade[slot] = 0;
+        }
+        else if (target === this.from[slot]) {
+            /* Back the way it came, at the share each level already covers rather than from the start.
+               The cells swap — the arriving level always takes the low ones — so a reversal changes the
+               grain for a frame and never the balance. */
+            this.from[slot] = level;
+            this.fade[slot] = 1 - fade;
+        }
+        else {
+            /* A third level: leave from whichever of the two covers more of the region. */
+            this.from[slot] = fade < 0.5 ? this.from[slot] : level;
+            this.fade[slot] = 0;
+        }
+        this.level[slot] = target;
+        if (this.fadeSec <= 0)
+            this.fade[slot] = 1;
+    }
+    emit(out, n, id, level, dither) {
+        out.region[n] = id;
+        out.level[n] = level;
+        out.dither[n] = dither;
+        return n + 1;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@driftengine/core",
-  "version": "4.4.2",
+  "version": "4.6.0",
   "description": "DriftEngine reusable browser 3D runtime",
   "license": "Apache-2.0",
   "type": "module",
@@ -29,8 +29,8 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@driftengine/drft": "4.4.2",
-    "@driftengine/physics": "4.4.2",
+    "@driftengine/drft": "4.6.0",
+    "@driftengine/physics": "4.6.0",
     "gl-matrix": "^3.4.3"
   },
   "author": "Drift Technologies",
@@ -63,8 +63,8 @@
     "prepack": "node ../../scripts/build.mjs @driftengine/core"
   },
   "devDependencies": {
-    "@driftengine/nav": "4.4.2",
-    "@driftengine/network": "4.4.2",
-    "@driftengine/texture": "4.4.2"
+    "@driftengine/nav": "4.6.0",
+    "@driftengine/network": "4.6.0",
+    "@driftengine/texture": "4.6.0"
   }
 }

package/src/geometry/boxCsg.ts

@@ -0,0 +1,186 @@
+/**
+ * Booleans on axis-aligned boxes, exactly and with as few faces as the result has.
+ *
+ * **Why beside `csg.ts` rather than in it.** A BSP boolean splits every face along every plane that
+ * crosses it, unrelated cutters included, and never re-merges: a wall of seven boxes with twenty
+ * window openings cut out of it came back as 325,187 triangles and took a minute. Boxes that share
+ * their axes need none of that. Every face of the result lies on a plane some box already has, so
+ * the space splits into the grid of all their coordinates, each cell is in or out by applying the
+ * operations to its centre in order, and the surface is the faces between cells that differ —
+ * merged greedily into the largest rectangles that fit. The same wall is a few hundred triangles,
+ * in milliseconds.
+ *
+ * **What it gives up.** Only boxes, only on the three axes: a box turned off them is the BSP's.
+ * Merged rectangles meet with T-junctions, as the BSP's pieces do, so the result is closed as a
+ * surface — its volume exact — but not edge for edge. Texture coordinates run 0..1 across the
+ * result's own extent on each face's plane, which is what `solidBox` gives a single box. The grid
+ * costs a byte a cell, so a caller with hundreds of boxes should check `boxBooleanCells` first.
+ */
+import type { Solid } from './solid.ts';
+import { emptySolid } from './solid.ts';
+import { SolidWriter } from './solidWriter.ts';
+
+export interface BoxOperation {
+  /** Minimum and maximum corners: `[x0, y0, z0, x1, y1, z1]`. */
+  readonly box: readonly [number, number, number, number, number, number];
+  readonly op: 'union' | 'subtract' | 'intersect';
+}
+
+/** Coordinates within this distance are one. */
+const SAME = 1e-6;
+
+function axis(operations: readonly BoxOperation[], a: number): number[] {
+  const values = operations
+    .flatMap((o) => [o.box[a] as number, o.box[a + 3] as number])
+    .sort((p, q) => p - q);
+  const out: number[] = [];
+  for (const v of values)
+    if (out.length === 0 || v - (out[out.length - 1] as number) > SAME) out.push(v);
+  return out;
+}
+
+/** How many grid cells `solidBoxBoolean` would allocate for `operations`. */
+export function boxBooleanCells(operations: readonly BoxOperation[]): number {
+  return (
+    (axis(operations, 0).length - 1) *
+    (axis(operations, 1).length - 1) *
+    (axis(operations, 2).length - 1)
+  );
+}
+
+/** The solid the operations make, applied left to right from nothing. */
+export function solidBoxBoolean(operations: readonly BoxOperation[]): Solid {
+  if (operations.length === 0) return emptySolid();
+  const xs = axis(operations, 0);
+  const ys = axis(operations, 1);
+  const zs = axis(operations, 2);
+  const nx = xs.length - 1;
+  const ny = ys.length - 1;
+  const nz = zs.length - 1;
+  if (nx <= 0 || ny <= 0 || nz <= 0) return emptySolid();
+  const inside = new Uint8Array(nx * ny * nz);
+  const at = (i: number, j: number, k: number): number => (k * ny + j) * nx + i;
+  for (let k = 0; k < nz; k += 1) {
+    const cz = ((zs[k] as number) + (zs[k + 1] as number)) / 2;
+    for (let j = 0; j < ny; j += 1) {
+      const cy = ((ys[j] as number) + (ys[j + 1] as number)) / 2;
+      for (let i = 0; i < nx; i += 1) {
+        const cx = ((xs[i] as number) + (xs[i + 1] as number)) / 2;
+        let state = false;
+        for (const o of operations) {
+          const b = o.box;
+          const hit = cx > b[0] && cx < b[3] && cy > b[1] && cy < b[4] && cz > b[2] && cz < b[5];
+          if (o.op === 'union') state ||= hit;
+          else if (o.op === 'subtract') state &&= !hit;
+          else state &&= hit;
+        }
+        inside[at(i, j, k)] = state ? 1 : 0;
+      }
+    }
+  }
+  const filled = (i: number, j: number, k: number): boolean =>
+    i >= 0 && j >= 0 && k >= 0 && i < nx && j < ny && k < nz && inside[at(i, j, k)] === 1;
+  const out = new SolidWriter();
+  const coords = [xs, ys, zs];
+  const counts = [nx, ny, nz];
+  const lo = [xs[0] as number, ys[0] as number, zs[0] as number];
+  const span = [
+    (xs[nx] as number) - (lo[0] as number),
+    (ys[ny] as number) - (lo[1] as number),
+    (zs[nz] as number) - (lo[2] as number),
+  ];
+  for (let d = 0; d < 3; d += 1) {
+    /* The face plane's two in-plane axes, ordered so (u × v) is +d. */
+    const u = (d + 1) % 3;
+    const v = (d + 2) % 3;
+    const nu = counts[u] as number;
+    const nv = counts[v] as number;
+    for (let s = 0; s <= (counts[d] as number); s += 1) {
+      for (const sign of [1, -1]) {
+        /* Faces on plane s facing `sign`: the cell behind is in, the one in front is out. */
+        const mask = new Uint8Array(nu * nv);
+        for (let b = 0; b < nv; b += 1) {
+          for (let a = 0; a < nu; a += 1) {
+            const cell = [0, 0, 0];
+            cell[u] = a;
+            cell[v] = b;
+            cell[d] = sign > 0 ? s - 1 : s;
+            const front = [...cell];
+            front[d] = sign > 0 ? s : s - 1;
+            const inCell = filled(cell[0] as number, cell[1] as number, cell[2] as number);
+            const inFront = filled(front[0] as number, front[1] as number, front[2] as number);
+            if (inCell && !inFront) mask[b * nu + a] = 1;
+          }
+        }
+        for (let b = 0; b < nv; b += 1) {
+          for (let a = 0; a < nu; a += 1) {
+            if (mask[b * nu + a] !== 1) continue;
+            let a1 = a + 1;
+            while (a1 < nu && mask[b * nu + a1] === 1) a1 += 1;
+            let b1 = b + 1;
+            grow: while (b1 < nv) {
+              for (let x = a; x < a1; x += 1) if (mask[b1 * nu + x] !== 1) break grow;
+              b1 += 1;
+            }
+            for (let y = b; y < b1; y += 1) for (let x = a; x < a1; x += 1) mask[y * nu + x] = 0;
+            quad(
+              out,
+              d,
+              u,
+              v,
+              sign,
+              (coords[d] as number[])[s] as number,
+              [
+                (coords[u] as number[])[a] as number,
+                (coords[u] as number[])[a1] as number,
+                (coords[v] as number[])[b] as number,
+                (coords[v] as number[])[b1] as number,
+              ],
+              lo,
+              span,
+            );
+          }
+        }
+      }
+    }
+  }
+  return out.finish();
+}
+
+function quad(
+  out: SolidWriter,
+  d: number,
+  u: number,
+  v: number,
+  sign: number,
+  plane: number,
+  [u0, u1, v0, v1]: [number, number, number, number],
+  lo: number[],
+  span: number[],
+): void {
+  const corner = (cu: number, cv: number): number => {
+    const p = [0, 0, 0];
+    p[d] = plane;
+    p[u] = cu;
+    p[v] = cv;
+    const n = [0, 0, 0];
+    n[d] = sign;
+    return out.vertex(
+      p[0] as number,
+      p[1] as number,
+      p[2] as number,
+      n[0] as number,
+      n[1] as number,
+      n[2] as number,
+      (cu - (lo[u] as number)) / ((span[u] as number) || 1),
+      (cv - (lo[v] as number)) / ((span[v] as number) || 1),
+    );
+  };
+  const a = corner(u0, v0);
+  const b = corner(u1, v0);
+  const c = corner(u1, v1);
+  const e = corner(u0, v1);
+  /* Counter-clockwise from outside: (u × v) is +d, so a facing +d winds a b c, a facing −d reverses. */
+  if (sign > 0) out.quad(a, b, c, e);
+  else out.quad(a, e, c, b);
+}