@driftengine/core 4.5.0 → 4.6.1

package/src/render/driftLight/lightField.ts

@@ -34,11 +34,11 @@ import type { FieldLight } from './bake.ts';
 import type { PointLightFalloff } from './falloff.ts';
 import { BRICK_SAMPLES, layoutLightField } from './layout.ts';
 import type { LightFieldLayout } from './layout.ts';
+import { FieldPresence } from './presence.ts';
+import type { DriftLightVolumes } from './presence.ts';
 
 /** Seconds the summed light takes to fade in once the field is whole. */
 export const FIELD_FADE_SEC = 0.5;
-/** How fast the shading radius grows back, per second, when the choice reaches further again. */
-const RADIUS_GROWTH_PER_SEC = 2;
 /** Bricks along each axis of the atlas: 256 texels a side, the least 3D texture WebGL2 promises. */
 const ATLAS_BRICKS: readonly [number, number, number] = [32, 64, 64];
 /** A brick's footprint in the atlas: its light block and its direction block side by side. */
@@ -66,7 +66,7 @@ export interface LightFieldOptions {
   readonly fadeSec?: number;
 }
 
-export class LightField {
+export class LightField implements DriftLightVolumes {
   readonly layout: LightFieldLayout;
   /** Texels on each axis of the atlas. */
   readonly atlasSize: readonly [number, number, number];
@@ -82,18 +82,15 @@ export class LightField {
   readonly fadeSec: number;
   /** The summed light's brightness, for a scene that dims all its lamps at once: dawn, a switch. */
   scale = 1;
-  /** Where the frame's choice was centred, which the shader measures the radius from. */
-  readonly centre = new Float32Array(3);
 
   private readonly lights: readonly FieldLight[];
   private readonly falloff: PointLightFalloff;
   private readonly distance: ((x: number, y: number, z: number) => number) | null;
   private readonly lightBlock = new Float32Array(BRICK_TEXELS * 4);
   private readonly directionBlock = new Float32Array(BRICK_TEXELS * 4);
+  private readonly showing: FieldPresence;
   private baked = 0;
   private taken = 0;
-  private eased = 0;
-  private shown = 0;
 
   constructor(lights: readonly LightFieldSource[], options: LightFieldOptions) {
     for (const light of lights) light.inLightField = true;
@@ -110,6 +107,7 @@ export class LightField {
     this.falloff = options.falloff;
     this.band = options.band ?? 2;
     this.fadeSec = Math.max(0, options.fadeSec ?? FIELD_FADE_SEC);
+    this.showing = new FieldPresence(this.fadeSec);
     const fields = options.fields ?? [];
     this.occluded = fields.length > 0;
     this.distance = this.occluded ? distanceToInstances(fields) : null;
@@ -143,12 +141,37 @@ export class LightField {
 
   /** The radius, in metres from `centre`, inside which lights are shaded exactly. */
   get radius(): number {
-    return this.eased;
+    return this.showing.radius;
   }
 
   /** How much of the summed light is in the frame, 0 until the field is whole, then up to 1. */
   get presence(): number {
-    return this.shown;
+    return this.showing.presence;
+  }
+
+  /** Where the frame's choice was centred, which the shader measures the radius from. */
+  get centre(): Float32Array {
+    return this.showing.centre;
+  }
+
+  get empty(): boolean {
+    return this.layout.count === 0;
+  }
+
+  get indexDims(): readonly [number, number, number] {
+    return this.layout.dims;
+  }
+
+  get index(): Uint32Array {
+    return this.layout.index;
+  }
+
+  get sampleOrigin(): readonly [number, number, number] {
+    return this.layout.origin;
+  }
+
+  get signedSpacing(): number {
+    return this.layout.spacing;
   }
 
   /** The texel at which brick `brick`'s light block starts; its direction block is 4 along x. */
@@ -195,15 +218,7 @@ export class LightField {
    * which is only less exact. While nothing is summed the radius simply follows.
    */
   follow(complete: number, x: number, y: number, z: number, dtSec: number): void {
-    this.centre[0] = x;
-    this.centre[1] = y;
-    this.centre[2] = z;
-    const showing = this.shown > 0;
-    if (!showing || complete < this.eased) this.eased = complete;
-    else this.eased += (complete - this.eased) * (1 - Math.exp(-RADIUS_GROWTH_PER_SEC * dtSec));
-    if (this.ready) {
-      this.shown = this.fadeSec > 0 ? Math.min(1, this.shown + dtSec / this.fadeSec) : 1;
-    }
+    this.showing.follow(this.ready, complete, x, y, z, dtSec);
   }
 
   /** Write the brick just baked into its place in the atlas, as half floats. */

package/src/render/driftLight/presence.ts

@@ -0,0 +1,69 @@
+/**
+ * How much of a DriftLight field is in the frame, and the radius inside which the frame's exact
+ * lights take over from it — the part every kind of field shares, kept once.
+ *
+ * **The radius shrinks at once and grows back slowly.** A pixel inside it that a left-out light
+ * reaches would be shaded short, so it cannot lag a shrink; a pixel it has not reached yet takes the
+ * summed light, which is only less exact, so a grow may ease. While nothing is summed the radius
+ * simply follows. The presence fades in over `fadeSec` once the field is whole, so a field
+ * completing in view does not pop — and a held clock never finishes a fade, so a field behind a
+ * loading screen asks for none.
+ */
+
+/** How fast the shading radius grows back, per second, when the choice reaches further again. */
+const RADIUS_GROWTH_PER_SEC = 2;
+
+export class FieldPresence {
+  /** Where the frame's choice was centred, which the shader measures the radius from. */
+  readonly centre = new Float32Array(3);
+  private eased = 0;
+  private shown = 0;
+
+  constructor(readonly fadeSec: number) {}
+
+  /** The radius, in metres from `centre`, inside which lights are shaded exactly. */
+  get radius(): number {
+    return this.eased;
+  }
+
+  /** How much of the summed light is in the frame, 0 until the field is whole, then up to 1. */
+  get presence(): number {
+    return this.shown;
+  }
+
+  /** Follow the frame's choice: `complete` from the selection, centred at (x, y, z). */
+  follow(ready: boolean, complete: number, x: number, y: number, z: number, dtSec: number): void {
+    this.centre[0] = x;
+    this.centre[1] = y;
+    this.centre[2] = z;
+    if (this.shown <= 0 || complete < this.eased) this.eased = complete;
+    else this.eased += (complete - this.eased) * (1 - Math.exp(-RADIUS_GROWTH_PER_SEC * dtSec));
+    if (ready) this.shown = this.fadeSec > 0 ? Math.min(1, this.shown + dtSec / this.fadeSec) : 1;
+  }
+}
+
+/**
+ * What a backend uploads and binds for a field of either kind, and what the uniforms are made of.
+ *
+ * A sparse field's index finds its bricks; a dense one brings a 1×1×1 index of nothing, so the
+ * upload and the bind are one code path, and says it is dense by a negative spacing.
+ */
+export interface DriftLightVolumes {
+  readonly ready: boolean;
+  /** Nothing summed at all: nothing to upload. */
+  readonly empty: boolean;
+  readonly indexDims: readonly [number, number, number];
+  readonly index: Uint32Array;
+  readonly atlasSize: readonly [number, number, number];
+  /** Half floats, four channels a texel, x fastest. */
+  readonly atlas: Uint16Array;
+  readonly presence: number;
+  readonly radius: number;
+  readonly band: number;
+  readonly scale: number;
+  readonly centre: Float32Array;
+  /** The world position of the first sample. */
+  readonly sampleOrigin: readonly [number, number, number];
+  /** Metres between samples, negative for a dense volume: the shader's mode. */
+  readonly signedSpacing: number;
+}

package/src/render/driftLight/uniforms.ts

@@ -14,12 +14,12 @@
  * from the centre, gets a smaller radius and more of the volume, which is the safe direction.
  */
 
-import type { LightField } from './lightField.ts';
+import type { DriftLightVolumes } from './presence.ts';
 
 export interface DriftLightUniforms {
   /** How much of the summed light is in, the radius, the band, the scale. */
   readonly light: Float32Array;
-  /** The first brick's first sample, and the metres between samples. */
+  /** The first sample, and the metres between samples — negative for a dense volume. */
   readonly origin: Float32Array;
 }
 
@@ -35,16 +35,15 @@ export function createDriftLightUniforms(): DriftLightUniforms {
  * being drawn.
  */
 export function resolveDriftLight(
-  field: LightField | null,
+  field: DriftLightVolumes | null,
   probePass: boolean,
   eye: ArrayLike<number>,
   out: DriftLightUniforms,
 ): void {
-  if (field === null || !field.ready || field.presence <= 0 || field.layout.count === 0) {
+  if (field === null || !field.ready || field.presence <= 0 || field.empty) {
     out.light.fill(0);
     return;
   }
-  const { layout } = field;
   const offset = Math.hypot(
     (eye[0] ?? 0) - (field.centre[0] as number),
     (eye[1] ?? 0) - (field.centre[1] as number),
@@ -54,8 +53,8 @@ export function resolveDriftLight(
   out.light[1] = probePass ? 0 : Math.max(0, field.radius - offset);
   out.light[2] = field.band;
   out.light[3] = field.scale;
-  out.origin[0] = layout.origin[0];
-  out.origin[1] = layout.origin[1];
-  out.origin[2] = layout.origin[2];
-  out.origin[3] = layout.spacing;
+  out.origin[0] = field.sampleOrigin[0];
+  out.origin[1] = field.sampleOrigin[1];
+  out.origin[2] = field.sampleOrigin[2];
+  out.origin[3] = field.signedSpacing;
 }

package/src/render/driftLight/worldLightField.ts

@@ -0,0 +1,83 @@
+/**
+ * A world's DriftLight: a dense volume baked offline (`bakeDenseField`), handed to the renderer
+ * whole, standing in for every fixed light past the frame's exact choice.
+ *
+ * **Whole from the start**, because nothing is baked in the page: `ready` is true on construction
+ * and the volume fades in over `fadeSec` from the first `follow`. The lights it summed are the
+ * scene's to mark `inLightField`, so the selection knows not to count them twice — a volume carries
+ * no list of the lights it came from.
+ *
+ * **Light and direction side by side along y**, the short axis: a city is 256 samples across and a
+ * few dozen up, and a 3D texture promises 256 on every axis, so stacking the two there keeps both
+ * inside one texture and one sampler. The shader keeps each lookup inside its own half.
+ */
+
+import { halfBits } from '../halfFloat.ts';
+import type { DenseLightVolume } from './denseField.ts';
+import { FieldPresence } from './presence.ts';
+import type { DriftLightVolumes } from './presence.ts';
+
+export interface WorldLightFieldOptions {
+  /** Metres over which exact and summed light crossfade at the shading radius. Two by default. */
+  readonly band?: number;
+  /** Seconds the volume fades in over; zero behind a loading screen, whose clock may be held. */
+  readonly fadeSec?: number;
+}
+
+/** The index a dense volume binds in the sparse one's place: one cell, no brick. */
+const NO_INDEX = new Uint32Array(1);
+
+export class WorldLightField implements DriftLightVolumes {
+  readonly ready = true;
+  readonly empty = false;
+  readonly indexDims: readonly [number, number, number] = [1, 1, 1];
+  readonly index = NO_INDEX;
+  readonly atlasSize: readonly [number, number, number];
+  readonly atlas: Uint16Array;
+  readonly band: number;
+  readonly sampleOrigin: readonly [number, number, number];
+  readonly signedSpacing: number;
+  /** The summed light's brightness, for a scene that dims all its lamps at once. */
+  scale = 1;
+  private readonly showing: FieldPresence;
+
+  constructor(volume: DenseLightVolume, options: WorldLightFieldOptions = {}) {
+    const [x, y, z] = volume.dims;
+    this.atlasSize = [x, y * 2, z];
+    this.atlas = new Uint16Array(x * y * 2 * z * 4);
+    for (let k = 0; k < z; k++) {
+      for (let j = 0; j < y; j++) {
+        for (let i = 0; i < x; i++) {
+          const from = (i + x * (j + y * k)) * 4;
+          const light = (i + x * (j + 2 * y * k)) * 4;
+          const direction = (i + x * (j + y + 2 * y * k)) * 4;
+          for (let c = 0; c < 4; c++) {
+            this.atlas[light + c] = halfBits(volume.light[from + c] as number);
+            this.atlas[direction + c] = halfBits(volume.direction[from + c] as number);
+          }
+        }
+      }
+    }
+    this.band = options.band ?? 2;
+    this.sampleOrigin = volume.origin;
+    this.signedSpacing = -volume.spacing;
+    this.showing = new FieldPresence(Math.max(0, options.fadeSec ?? 0.5));
+  }
+
+  get radius(): number {
+    return this.showing.radius;
+  }
+
+  get presence(): number {
+    return this.showing.presence;
+  }
+
+  get centre(): Float32Array {
+    return this.showing.centre;
+  }
+
+  /** Follow the frame's choice, as `LightField.follow` does. */
+  follow(complete: number, x: number, y: number, z: number, dtSec: number): void {
+    this.showing.follow(true, complete, x, y, z, dtSec);
+  }
+}

package/src/render/fixtureAtlas.ts

@@ -0,0 +1,63 @@
+/**
+ * What a light fixture throws, in one texture: its spot cookies in the top band, its photometric
+ * profiles in the rows below.
+ *
+ * **One binding for two tables, because the lit stage had one sampler left.** The cookie atlas and
+ * the photometric atlas were two small float textures read with `textureLod`, and the widest lit
+ * shader bound fifteen of the sixteen fragment samplers WebGL2 guarantees — so the next sampler had
+ * to be found by folding two into one, which is what this is. Both describe a fixture's emission
+ * pattern, and both are 128 texels across, which is what lets them share a texture exactly.
+ *
+ * **Cookies on top, profiles at the bottom, and the order is load-bearing.** A profile's row blend
+ * only ever reaches forward — to the next plane, and from the last to the repeat of the first — so
+ * past its last row it meets the texture's edge and the clamp, never a cookie. A cookie's own
+ * half-texel inset keeps it inside its band on both axes. The shader finds the bands from
+ * `textureSize` and `uIesAtlasRows`, so the fold cost no uniform.
+ *
+ * **What it gives up**: every texel is four half floats where a profile needed one, a few kilobytes
+ * a scene; and setting either table rebuilds the whole texture, which a consumer does once per set.
+ */
+import { IES_ATLAS_WIDTH } from './iesProfile.ts';
+import { COOKIE_TILE } from './lightBudget.ts';
+
+export interface FixtureAtlasLayout {
+  readonly width: number;
+  readonly height: number;
+  /** Rows of cookie tiles at the top: `COOKIE_TILE`, or 0 with none loaded. */
+  readonly cookieRows: number;
+  /** The first row of the profiles, below the cookies. */
+  readonly iesTop: number;
+}
+
+/** The atlas for `iesRows` rows of profile and `cookieTiles` cookies. */
+export function fixtureAtlasLayout(iesRows: number, cookieTiles: number): FixtureAtlasLayout {
+  const cookieRows = cookieTiles > 0 ? COOKIE_TILE : 0;
+  return {
+    width: Math.max(IES_ATLAS_WIDTH, COOKIE_TILE * cookieTiles),
+    height: cookieRows + iesRows,
+    cookieRows,
+    iesTop: cookieRows,
+  };
+}
+
+/**
+ * The profiles' rows as the atlas holds them: `data` one float a texel, `width` across and `rows`
+ * down, spread into the red channel of a four-channel image the atlas's size, the rest ones. The
+ * cookie band is left zero for the backend to fill from its images.
+ */
+export function fixtureAtlasTexels(
+  layout: FixtureAtlasLayout,
+  ies: { readonly data: Float32Array; readonly width: number; readonly height: number },
+): Float32Array {
+  const out = new Float32Array(layout.width * layout.height * 4);
+  for (let row = 0; row < ies.height; row++) {
+    for (let x = 0; x < ies.width; x++) {
+      const at = ((layout.iesTop + row) * layout.width + x) * 4;
+      out[at] = ies.data[row * ies.width + x] as number;
+      out[at + 1] = 1;
+      out[at + 2] = 1;
+      out[at + 3] = 1;
+    }
+  }
+  return out;
+}

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