@driftengine/core 4.4.2 → 4.6.0

package/src/render/instanceCull.ts

@@ -0,0 +1,205 @@
+/**
+ * Which instances of a batch can be seen: the decision both backends make, and the reference the
+ * WebGPU compute cull is held to.
+ *
+ * **An instance's bounds are the mesh's, placed by its matrix** — the mesh's bounding sphere with its
+ * centre through the model matrix and its radius scaled by the largest axis, exactly as
+ * `boundsVisible` treats one mesh — so a batch needs no bounds of its own and a caller supplies none.
+ * The test is `sphereInFrustum`'s: kept unless wholly beyond one plane.
+ *
+ * WebGL2 runs `cullInstances` on the CPU; WebGPU runs `CULL_INSTANCES_WGSL`, the same arithmetic, on
+ * the device. Both keep what this keeps: `gpu-parity.mjs` compares them on a device. What this gives
+ * up is shape: a long thin mesh is culled by the sphere around it, which keeps it in more views than
+ * its box would. What would make that wrong is a batch of long thin things seen end on, where a box
+ * test pays; nothing in the engine draws those instanced today.
+ *
+ * Per frame and allocation-free: everything writes into arrays the caller owns.
+ */
+import type { MeshInstances } from './instances.ts';
+import type { Bounds } from '../math/bounds.ts';
+import { boxInFrustum } from '../math/frustum.ts';
+import type { FrustumPlanes } from '../math/frustum.ts';
+
+/** How many planes a frustum holds, four floats each. */
+const PLANES = 6;
+
+/**
+ * Indices a culling batch must draw, all its instances together, before culling it instance by
+ * instance pays; below it the batch is drawn whole once its box is seen (`batchBoxVisible`).
+ *
+ * **What a per-instance cull costs is fixed a batch, and what it saves grows with the batch.** On
+ * WebGPU it is a dispatch and an indirect draw, and Chrome validates every indirect draw in its GPU
+ * process — measured at 8 µs apiece in a city frame whose six hundred small prop batches took one
+ * each, 52 fps against 70 with those draws gone. On WebGL2 it is a loop over the instances and an
+ * upload of the survivors. A few thousand indices cost a device less than either.
+ *
+ * What it gives up is the instances of a small batch that stand out of view once its box is in it,
+ * which the device transforms and clips for nothing. What would make it wrong is a device whose
+ * vertex stage limits the frame while the CPU idles — where this wants to come down.
+ */
+export const INSTANCE_CULL_MIN_INDICES = 1 << 14;
+
+/**
+ * Whether a culling batch of `count` instances of a mesh of `indexCount` indices is culled instance
+ * by instance, or drawn whole once its box is seen. See `INSTANCE_CULL_MIN_INDICES`.
+ */
+export function cullsInstances(count: number, indexCount: number): boolean {
+  return count * indexCount >= INSTANCE_CULL_MIN_INDICES;
+}
+
+/**
+ * Keep the instances of `data` whose spheres meet `frustum`, compacted in order into `out`, and
+ * return how many. `out` must hold as many as `data` does; its count is set.
+ */
+export function cullInstances(
+  data: MeshInstances,
+  local: Bounds,
+  frustum: FrustumPlanes,
+  out: MeshInstances,
+): number {
+  const count = Math.min(data.count, data.capacity, out.capacity);
+  const models = data.models;
+  const tints = data.tints;
+  let kept = 0;
+  for (let i = 0; i < count; i++) {
+    sphereOf(models, i, local, scratch);
+    if (!sphereMeets(frustum, scratch)) continue;
+    /* Copied float by float: a subarray would be a view allocated per instance, per frame. */
+    const from = i * 16;
+    const to = kept * 16;
+    for (let k = 0; k < 16; k++) out.models[to + k] = models[from + k] as number;
+    out.tints[kept * 3] = tints[i * 3] as number;
+    out.tints[kept * 3 + 1] = tints[i * 3 + 1] as number;
+    out.tints[kept * 3 + 2] = tints[i * 3 + 2] as number;
+    kept++;
+  }
+  out.count = kept;
+  return kept;
+}
+
+/** `sphereInFrustum` over a packed (x, y, z, radius): kept unless wholly beyond one plane. */
+function sphereMeets(frustum: FrustumPlanes, sphere: Float32Array): boolean {
+  const x = sphere[0] as number;
+  const y = sphere[1] as number;
+  const z = sphere[2] as number;
+  const radius = sphere[3] as number;
+  for (let plane = 0; plane < PLANES; plane++) {
+    const at = plane * 4;
+    const distance =
+      (frustum[at] as number) * x +
+      (frustum[at + 1] as number) * y +
+      (frustum[at + 2] as number) * z +
+      (frustum[at + 3] as number);
+    if (distance < -radius) return false;
+  }
+  return true;
+}
+
+/**
+ * The world box around every instance's sphere, for testing a whole batch at once: (minX, minY,
+ * minZ, maxX, maxY, maxZ) into `out`. A batch holding nothing writes a min above its max.
+ *
+ * **A box, not a sphere, and the difference is the whole point for a flat batch.** A region of props
+ * a hundred metres square has a sphere seventy metres deep underground, where nothing occludes it,
+ * so a sphere test never finds a region hidden. The box stays as flat as the props are.
+ */
+export function instancesBox(data: MeshInstances, local: Bounds, out: Float32Array): void {
+  const count = Math.min(data.count, data.capacity);
+  if (count === 0) {
+    out[0] = 1;
+    out[1] = 1;
+    out[2] = 1;
+    out[3] = -1;
+    out[4] = -1;
+    out[5] = -1;
+    return;
+  }
+  let minX = Infinity;
+  let minY = Infinity;
+  let minZ = Infinity;
+  let maxX = -Infinity;
+  let maxY = -Infinity;
+  let maxZ = -Infinity;
+  for (let i = 0; i < count; i++) {
+    sphereOf(data.models, i, local, scratch);
+    const r = scratch[3] as number;
+    minX = Math.min(minX, (scratch[0] as number) - r);
+    minY = Math.min(minY, (scratch[1] as number) - r);
+    minZ = Math.min(minZ, (scratch[2] as number) - r);
+    maxX = Math.max(maxX, (scratch[0] as number) + r);
+    maxY = Math.max(maxY, (scratch[1] as number) + r);
+    maxZ = Math.max(maxZ, (scratch[2] as number) + r);
+  }
+  out[0] = minX;
+  out[1] = minY;
+  out[2] = minZ;
+  out[3] = maxX;
+  out[4] = maxY;
+  out[5] = maxZ;
+}
+
+const scratch = new Float32Array(4);
+
+/** Instance `i`'s world sphere into `out` as (x, y, z, radius). */
+function sphereOf(models: Float32Array, i: number, local: Bounds, out: Float32Array): void {
+  const m = i * 16;
+  const cx = local.centre[0] ?? 0;
+  const cy = local.centre[1] ?? 0;
+  const cz = local.centre[2] ?? 0;
+  const m0 = models[m] as number;
+  const m1 = models[m + 1] as number;
+  const m2 = models[m + 2] as number;
+  const m4 = models[m + 4] as number;
+  const m5 = models[m + 5] as number;
+  const m6 = models[m + 6] as number;
+  const m8 = models[m + 8] as number;
+  const m9 = models[m + 9] as number;
+  const m10 = models[m + 10] as number;
+  out[0] = m0 * cx + m4 * cy + m8 * cz + (models[m + 12] as number);
+  out[1] = m1 * cx + m5 * cy + m9 * cz + (models[m + 13] as number);
+  out[2] = m2 * cx + m6 * cy + m10 * cz + (models[m + 14] as number);
+  out[3] =
+    local.radius *
+    Math.sqrt(
+      Math.max(
+        m0 * m0 + m1 * m1 + m2 * m2,
+        m4 * m4 + m5 * m5 + m6 * m6,
+        m8 * m8 + m9 * m9 + m10 * m10,
+      ),
+    );
+}
+
+/** What the batch test asks of an occlusion buffer. `OcclusionBuffer` and both renderers answer it. */
+export interface BoxOccluder {
+  occludedBox(min: ArrayLike<number>, max: ArrayLike<number>): boolean;
+}
+
+/**
+ * Whether a batch's box (`instancesBox`) can be seen at all: inside the frustum, and not behind the
+ * declared occluders. One test for a whole region's props, run before any instance is looked at.
+ */
+export function batchBoxVisible(
+  box: Float32Array,
+  frustum: FrustumPlanes,
+  occluder: BoxOccluder | null,
+): boolean {
+  const minX = box[0] as number;
+  const minY = box[1] as number;
+  const minZ = box[2] as number;
+  const maxX = box[3] as number;
+  const maxY = box[4] as number;
+  const maxZ = box[5] as number;
+  if (minX > maxX) return false;
+  if (!boxInFrustum(frustum, minX, minY, minZ, maxX, maxY, maxZ)) return false;
+  if (occluder === null) return true;
+  boxMin[0] = minX;
+  boxMin[1] = minY;
+  boxMin[2] = minZ;
+  boxMax[0] = maxX;
+  boxMax[1] = maxY;
+  boxMax[2] = maxZ;
+  return !occluder.occludedBox(boxMin, boxMax);
+}
+
+const boxMin = new Float32Array(3);
+const boxMax = new Float32Array(3);

package/src/render/instances.ts

@@ -90,3 +90,19 @@ export function packInstances(instances: MeshInstances, out: Float32Array): void
     out[at + 18] = tints[t + 2] as number;
   }
 }
+
+/** How a batch made by `createInstanced` behaves. */
+export interface InstancedOptions {
+  /**
+   * Cull the camera draw: the whole batch skipped when its instances' sphere is out of view or behind
+   * the declared occluders, and otherwise each instance kept only where its sphere meets the view —
+   * on the CPU on WebGL2, as compute into an indirect draw on WebGPU — once the batch is large enough
+   * to repay that (`cullsInstances`); a smaller one is drawn whole. Shadow, mirror-free motion and
+   * blended draws still see every instance. Off by default, because a batch small enough to draw whole
+   * pays for nothing it would save.
+   *
+   * **For a batch spread over space** — a prop across a region, a crowd, traffic. A batch in one
+   * place gains only the whole-batch test, which it could as well do itself.
+   */
+  readonly cull?: boolean;
+}

package/src/render/lightBudget.ts

@@ -38,13 +38,14 @@ export const MAX_POINT_LIGHTS = 16;
 export const LIVE_POINT_SHADOW_MAPS = 2;
 
 /**
- * Texture units the directional cascade binds: static, its depth peel, and dynamic.
+ * Texture units the sun's shadow binds: one, for its static, moving and peeled layers.
  *
- * Named because the shading pass's total unit count has to be compared against what a
- * device offers, and a budget assembled from three literals scattered across two files
- * is a budget nobody can check. See the guard in `Renderer`'s constructor.
+ * **It was three**, a `sampler2D` per map, until 4.5.0 folded them into one `sampler2DArray`
+ * (`shadowMap.ts`) the way the lamps' twelve cubemaps became one — which is where the two tints
+ * glass casts with found their units. Named because the shading pass's total has to be compared
+ * against what a device offers; see the guard in `Renderer`'s constructor.
  */
-export const DIRECTIONAL_SHADOW_UNITS = 3;
+export const DIRECTIONAL_SHADOW_UNITS = 1;
 
 /**
  * Texture units every point light's shadow binds: one, for all of them.
@@ -142,22 +143,20 @@ export const ENVIRONMENT_TEXTURE_UNIT = EMISSIVE_TEXTURE_UNIT + 1;
 export const CLUSTER_TABLE_TEXTURE_UNIT = ENVIRONMENT_TEXTURE_UNIT + 1;
 
 /**
- * Where the photometric atlas binds: one row per IES profile, any number of them.
- *
- * **One unit for every profile a world holds, which is the whole reason it is an atlas.** A
- * fixture's distribution is a curve rather than an image, so a row of 128 floats holds one and a
- * texture holds as many as a consumer loads. Per-profile textures would have spent the remaining
- * units on the third fixture.
- *
- * **Spent unconditionally, for the same reason the froxel table is**, and the argument is at that
- * declaration: the lookup is a branch on a value rather than a permutation, so the sampler is
- * declared in every profile and a declared sampler needs a complete texture bound whether or not
- * the branch reads it. With no profile loaded that texture is a single row of ones, which is the
- * multiplicative identity — a row of zeros would switch off every light that reached it.
- *
- * The tenth of sixteen. `CAPABILITIES.md` §3 keeps the running count.
+ * Where the fixture atlas binds: a fixture's spot cookies and its photometric profiles, one texture.
+ *
+ * **Two tables in one binding since 2026-09-30**, which is the fold `textureUnitBudget.test.ts` asks
+ * the next sampler for: the widest lit shader bound fifteen of the sixteen fragment samplers WebGL2
+ * guarantees, and the cookie atlas and the photometric atlas were two small float tables read with
+ * `textureLod`, both 128 texels across. See `fixtureAtlas.ts` for the layout and why cookies sit on
+ * top.
+ *
+ * **Spent unconditionally, for the reason the froxel table is**: both lookups are branches on values
+ * rather than permutations, so the sampler is declared in every profile and a declared sampler needs
+ * a complete texture. With nothing loaded that is a single row of ones — the multiplicative
+ * identity, since a row of zeros would switch off every light that reached it.
  */
-export const IES_ATLAS_TEXTURE_UNIT = CLUSTER_TABLE_TEXTURE_UNIT + 1;
+export const FIXTURE_ATLAS_TEXTURE_UNIT = CLUSTER_TABLE_TEXTURE_UNIT + 1;
 
 /**
  * The joint palette, read by the **vertex** stage.
@@ -176,7 +175,7 @@ export const IES_ATLAS_TEXTURE_UNIT = CLUSTER_TABLE_TEXTURE_UNIT + 1;
  * What it costs is one of the five units left after the IES atlas. What would make it wrong is
  * the lit pass growing past sixteen, which `textureUnitBudget.test.ts` asserts against.
  */
-export const SKIN_PALETTE_TEXTURE_UNIT = IES_ATLAS_TEXTURE_UNIT + 1;
+export const SKIN_PALETTE_TEXTURE_UNIT = FIXTURE_ATLAS_TEXTURE_UNIT + 1;
 
 /**
  * A mesh's morph deltas, also read by the vertex stage, and also out of this same sixteen.
@@ -187,22 +186,6 @@ export const SKIN_PALETTE_TEXTURE_UNIT = IES_ATLAS_TEXTURE_UNIT + 1;
  */
 export const MORPH_DELTA_TEXTURE_UNIT = SKIN_PALETTE_TEXTURE_UNIT + 1;
 
-/**
- * Where the spot-light cookie atlas binds: one row of square tiles, one tile a cookie.
- *
- * **The fourteenth of sixteen, and two are left.** `CAPABILITIES.md` §3 keeps the running count —
- * and had been three units stale for as long as the IES atlas, the skin palette and the morph
- * deltas have existed, which is why the number is derived in `textureUnitBudget.test.ts` and only
- * quoted in prose.
- *
- * **Spent unconditionally, for the reason the froxel table and the IES atlas are**: a declared
- * sampler needs a complete texture bound whether or not the branch reads it, so a one-texel white
- * placeholder stands in it when no consumer has loaded a cookie. White rather than black, because
- * it multiplies a light's colour and a black stand-in would switch off every light that reached
- * it — the identity `packIesAtlas` chooses for the same reason.
- */
-export const COOKIE_ATLAS_TEXTURE_UNIT = MORPH_DELTA_TEXTURE_UNIT + 1;
-
 /**
  * The colour the frame had already drawn, for a refracting surface to sample.
  *
@@ -216,7 +199,7 @@ export const COOKIE_ATLAS_TEXTURE_UNIT = MORPH_DELTA_TEXTURE_UNIT + 1;
  * cubemaps became one array, which is what freed the units this one is spending.
  * `textureUnitBudget.test.ts` carries the phone that budget was written for.
  */
-export const REFRACT_SCENE_TEXTURE_UNIT = COOKIE_ATLAS_TEXTURE_UNIT + 1;
+export const REFRACT_SCENE_TEXTURE_UNIT = MORPH_DELTA_TEXTURE_UNIT + 1;
 
 /**
  * DriftLight's brick index and atlas, the lit program's fourteenth and fifteenth fragment samplers.
@@ -230,6 +213,26 @@ export const REFRACT_SCENE_TEXTURE_UNIT = COOKIE_ATLAS_TEXTURE_UNIT + 1;
 export const DRIFT_LIGHT_INDEX_TEXTURE_UNIT = REFRACT_SCENE_TEXTURE_UNIT + 1;
 export const DRIFT_LIGHT_ATLAS_TEXTURE_UNIT = DRIFT_LIGHT_INDEX_TEXTURE_UNIT + 1;
 
+/**
+ * What the sun keeps through glass (`sunGlassTint.ts`), the lit program's fourteenth fragment
+ * sampler: the unit the sun's three maps gave back when they became one array.
+ */
+export const SUN_GLASS_TINT_TEXTURE_UNIT = DRIFT_LIGHT_ATLAS_TEXTURE_UNIT + 1;
+
+/**
+ * What each lamp keeps through glass (`pointGlassTint.ts`), a fragment sampler of the lit program.
+ * A unit of the combined pool, which WebGL2 guarantees thirty-two of; what a stage may declare is
+ * sixteen, which `textureUnitBudget.test.ts` counts from the shader source.
+ */
+export const POINT_GLASS_TINT_TEXTURE_UNIT = SUN_GLASS_TINT_TEXTURE_UNIT + 1;
+
+/**
+ * Each surface layer's effects table (`surfaceEffects.ts`), bound beside the albedo array it
+ * describes. **Paid for by folding**: the cookie and photometric atlases became one fixture atlas
+ * to free the sampler this takes, so the lit stage still keeps one of its sixteen spare.
+ */
+export const SURFACE_EFFECTS_TEXTURE_UNIT = POINT_GLASS_TINT_TEXTURE_UNIT + 1;
+
 /**
  * A cookie's tile, in texels a side.
  *

package/src/render/lightGrid.ts

@@ -0,0 +1,130 @@
+/**
+ * A world's fixed lights bucketed once, so the frame's exact choice looks only at the lights near
+ * the eye rather than at every one of them.
+ *
+ * **The choice must be the full scan's, exactly, and needs no sort to be.** Both of the choice's
+ * lists break a tie in distance by source index, so the order the lights are met in cannot reach the
+ * result: what reaches it is the full scan's candidates minus only lights no query could keep —
+ * every light whose cell lies within `viewRange + maxRadius` of the eye is gathered, and the
+ * selection's own `viewRange + radius` test does the rest.
+ *
+ * **Cost stated**: built once, from where the lights stood. A light that moves or changes its reach
+ * must be re-bucketed by the caller — this is for the city's fixed thousands, and a scene's handful
+ * of movers stays with the plain scan.
+ *
+ * Nothing here allocates after construction; the gather writes into the grid's own scratch.
+ */
+import type { PointLightSource } from './pointLightSelection.ts';
+
+/** The most cells a grid may span, which keeps a stray light far away from costing a gigabyte. */
+export const LIGHT_GRID_MAX_CELLS = 1 << 22;
+
+export interface LightGrid {
+  readonly sources: readonly PointLightSource[];
+  /** Metres a cell spans on each axis. */
+  readonly cell: number;
+  /** The world position of cell (0, 0, 0)'s corner. */
+  readonly origin: readonly [number, number, number];
+  readonly dims: readonly [number, number, number];
+  /** Where cell `c`'s lights start in `lights`; `start[c + 1]` is where they end. */
+  readonly start: Uint32Array;
+  /** Source indices by cell, ascending within each. */
+  readonly lights: Uint32Array;
+  /** The largest reach of any source, which widens every query. */
+  readonly maxRadius: number;
+  /** The last gather, cell by cell: `gathered[0..count)`. */
+  readonly gathered: Int32Array;
+}
+
+/** Bucket `sources` into cells of `cell` metres. Built once; not a frame path. */
+export function createLightGrid(sources: readonly PointLightSource[], cell: number): LightGrid {
+  if (!(cell > 0)) throw new Error(`createLightGrid: a cell of ${String(cell)} metres`);
+  let minX = Infinity;
+  let minY = Infinity;
+  let minZ = Infinity;
+  let maxX = -Infinity;
+  let maxY = -Infinity;
+  let maxZ = -Infinity;
+  let maxRadius = 0;
+  for (const light of sources) {
+    minX = Math.min(minX, light.x);
+    minY = Math.min(minY, light.y);
+    minZ = Math.min(minZ, light.z);
+    maxX = Math.max(maxX, light.x);
+    maxY = Math.max(maxY, light.y);
+    maxZ = Math.max(maxZ, light.z);
+    maxRadius = Math.max(maxRadius, light.radius);
+  }
+  if (sources.length === 0) minX = minY = minZ = maxX = maxY = maxZ = 0;
+  const dims: [number, number, number] = [
+    Math.floor((maxX - minX) / cell) + 1,
+    Math.floor((maxY - minY) / cell) + 1,
+    Math.floor((maxZ - minZ) / cell) + 1,
+  ];
+  const cells = dims[0] * dims[1] * dims[2];
+  if (cells > LIGHT_GRID_MAX_CELLS) {
+    throw new Error(
+      `createLightGrid: these lights span ${dims.join(' × ')} cells of ${cell} m, past ` +
+        `${LIGHT_GRID_MAX_CELLS}; a larger cell fits them.`,
+    );
+  }
+  const cellOf = (light: PointLightSource): number =>
+    Math.floor((light.x - minX) / cell) +
+    dims[0] * (Math.floor((light.y - minY) / cell) + dims[1] * Math.floor((light.z - minZ) / cell));
+  const start = new Uint32Array(cells + 1);
+  for (const light of sources) {
+    const c = cellOf(light);
+    start[c + 1] = (start[c + 1] as number) + 1;
+  }
+  for (let c = 0; c < cells; c++) start[c + 1] = (start[c + 1] as number) + (start[c] as number);
+  const lights = new Uint32Array(sources.length);
+  const cursor = start.slice(0, cells);
+  for (let index = 0; index < sources.length; index++) {
+    const c = cellOf(sources[index] as PointLightSource);
+    lights[cursor[c] as number] = index;
+    cursor[c] = (cursor[c] as number) + 1;
+  }
+  return {
+    sources,
+    cell,
+    origin: [minX, minY, minZ],
+    dims,
+    start,
+    lights,
+    maxRadius,
+    gathered: new Int32Array(sources.length),
+  };
+}
+
+/**
+ * Gather into `grid.gathered`, cell by cell, every light whose cell lies within `reach` metres of
+ * (x, y, z) on each axis, and answer how many.
+ */
+export function gatherLights(
+  grid: LightGrid,
+  x: number,
+  y: number,
+  z: number,
+  reach: number,
+): number {
+  const { cell, origin, dims, start, lights, gathered } = grid;
+  const x0 = Math.max(0, Math.floor((x - reach - origin[0]) / cell));
+  const x1 = Math.min(dims[0] - 1, Math.floor((x + reach - origin[0]) / cell));
+  const y0 = Math.max(0, Math.floor((y - reach - origin[1]) / cell));
+  const y1 = Math.min(dims[1] - 1, Math.floor((y + reach - origin[1]) / cell));
+  const z0 = Math.max(0, Math.floor((z - reach - origin[2]) / cell));
+  const z1 = Math.min(dims[2] - 1, Math.floor((z + reach - origin[2]) / cell));
+  let count = 0;
+  for (let cz = z0; cz <= z1; cz++) {
+    for (let cy = y0; cy <= y1; cy++) {
+      const row = dims[0] * (cy + dims[1] * cz);
+      for (let cx = x0; cx <= x1; cx++) {
+        const c = row + cx;
+        for (let at = start[c] as number; at < (start[c + 1] as number); at++) {
+          gathered[count++] = lights[at] as number;
+        }
+      }
+    }
+  }
+  return count;
+}