@driftengine/core 3.61.0

package/src/render/iesProfile.ts

@@ -0,0 +1,215 @@
+/** Photometric profiles packed into one texture a light can index into. */
+
+/** What a reader produces, restated structurally so core imports no package. See `readIesProfile`. */
+export interface PhotometricProfile {
+  readonly verticalAngles: Float32Array;
+  readonly horizontalAngles: Float32Array;
+  readonly candela: Float32Array;
+  readonly maxCandela: number;
+}
+
+/**
+ * Columns across the atlas: one row per profile, sampled by vertical angle.
+ *
+ * **A power of two, and 128 rather than 64 because the interesting part of a real distribution is
+ * narrow.** A spot fixture puts its whole falloff inside a few degrees of the beam edge, and at 64
+ * columns that edge is two texels wide and reads as a step. What a larger number costs is four
+ * kilobytes a profile, which is nothing against the image it replaces.
+ */
+export const IES_ATLAS_WIDTH = 128;
+
+/**
+ * `planes` rows of intensity per profile, normalised to the profile's peak, indexed by angle.
+ *
+ * **Resampled to a regular grid here rather than in the reader**, because that is a decision about
+ * a texture and not about a file: LM-63 is dense where a distribution changes and sparse where it
+ * does not, and a shader cannot sample an irregular table without carrying it.
+ *
+ * **Asymmetric fixtures keep their horizontal planes as of 2026-08-27.** This function flattened
+ * to the first plane and said in its own comment what to reach for instead — "a row per horizontal
+ * plane with the light carrying a plane count" — and that is what this is. A street light and a
+ * wall washer are the fixtures that are not axially symmetric, and they are exactly the fixtures
+ * whose whole point is that they throw more one way than another.
+ *
+ * **One plane count for the atlas rather than one per profile**, and every profile is padded to
+ * it. The shader's row is `profile * planes + plane`; a per-profile count would need a second
+ * number in a light's record to divide by, and a light's record is where space is expensive.
+ * Padding a symmetric profile repeats its single row, which costs `width` floats a plane — half a
+ * kilobyte — against the image an IES profile replaces. **A set with nothing asymmetric in it
+ * comes out at one plane and is bit-identical to what this produced before planes existed**, which
+ * is what keeps the common case free.
+ *
+ * **The planes are resampled onto a regular 0-to-360 arc**, for the reason the vertical angles are
+ * resampled onto a fixed one: the shader maps an azimuth to a plane by arithmetic and carries no
+ * per-profile angle list to search. A file measuring 0 and 180 packed into four planes has its
+ * measured values at planes 0 and 2 and the interpolation between them at 1 and 3, which is what a
+ * fixture symmetric about its own axis actually throws.
+ *
+ * **A profile occupies `planes + 1` rows, and the extra one repeats the first.** That is what lets
+ * the shader do the whole azimuth blend in **one** fetch, with the texture's own linear filter
+ * between adjacent rows: without the wrap row the plane after the last would have to blend back to
+ * the first, which a fractional row cannot express — it would reach into the *next profile's*
+ * first plane instead. The alternative was two explicit fetches and a `mix`, which was written,
+ * measured at **+18,315 gzipped bytes on `core-only`** across the sixteen fragment permutations,
+ * and replaced by this. One row a profile is 512 bytes.
+ *
+ * **Normalised to each profile's own peak** because the shader multiplies it into a light's
+ * colour, which already carries the intensity a consumer chose. A profile that also carried
+ * absolute candela would multiply the two and make every IES light either black or blinding. The
+ * peak is the *profile's*, not the plane's: normalising each plane to itself would make every
+ * plane reach 1 and throw away the asymmetry this exists to carry.
+ */
+export function packIesAtlas(
+  profiles: readonly PhotometricProfile[],
+  width: number = IES_ATLAS_WIDTH,
+): { data: Float32Array; width: number; height: number; planes: number } {
+  /*
+   * **One row of ones when there is nothing to pack, rather than a zero-height texture.**
+   *
+   * A sampler declared in the shader must have a complete texture bound whether or not any branch
+   * reads it — the argument `emptyTexture.ts` makes — and a zero-height allocation is an
+   * `INVALID_VALUE` rather than an empty one. Ones rather than zeros because this value multiplies
+   * a light's colour: an all-zero fallback would switch off every light that reached it.
+   */
+  if (profiles.length === 0) {
+    return { data: new Float32Array(width).fill(1), width, height: 1, planes: 1 };
+  }
+
+  /* The widest fixture decides the grid, so no profile is resampled *down* and loses a lobe. */
+  let planes = 1;
+  for (const profile of profiles) {
+    planes = Math.max(planes, profile?.horizontalAngles.length ?? 1);
+  }
+
+  /* The wrap row: `planes + 1` per profile, the last repeating the first. See the note above. */
+  const rows = planes + 1;
+  const height = profiles.length * rows;
+  const data = new Float32Array(width * height);
+  for (let index = 0; index < profiles.length; index++) {
+    const profile = profiles[index];
+    for (let row = 0; row < rows; row++) {
+      const at = (index * rows + row) * width;
+      if (profile === undefined) {
+        data.fill(1, at, at + width);
+        continue;
+      }
+      /* Row `planes` is plane 0 again, which is what makes the blend wrap rather than bleed. */
+      packRow(profile, row % planes, planes, data, at, width);
+    }
+  }
+  return { data, width, height, planes };
+}
+
+/**
+ * Where a plane of the regular grid falls among the angles a file measured, as a pair and a mix.
+ *
+ * **Wrapped rather than clamped at the top**, which is the difference between an azimuth and a
+ * vertical angle: a fixture measured at 0 and 180 is symmetric about its own axis and 270 degrees
+ * is the same as 90, so the plane past the last measurement interpolates back toward the first.
+ * Clamping instead would flatten one whole side of every two-plane fixture.
+ *
+ * A file that measures a full 360 — the last angle equal to the first — is handled by the same
+ * arithmetic, because the wrap lands on that duplicate.
+ */
+function planeSpan(
+  horizontal: Float32Array,
+  plane: number,
+  planes: number,
+): { lower: number; upper: number; mix: number } {
+  const count = horizontal.length;
+  if (count <= 1) return { lower: 0, upper: 0, mix: 0 };
+  const azimuth = (plane / planes) * 360;
+
+  let upper = 0;
+  while (upper < count && (horizontal[upper] ?? 0) <= azimuth) upper += 1;
+  if (upper === 0) return { lower: 0, upper: 0, mix: 0 };
+  if (upper >= count) {
+    /* Past the last measured plane: back toward the first, across whatever arc is left. */
+    const last = horizontal[count - 1] ?? 0;
+    const span = 360 - last + (horizontal[0] ?? 0);
+    return {
+      lower: count - 1,
+      upper: 0,
+      mix: span > 0 ? Math.min(1, Math.max(0, (azimuth - last) / span)) : 0,
+    };
+  }
+  const a = horizontal[upper - 1] ?? 0;
+  const b = horizontal[upper] ?? a;
+  return { lower: upper - 1, upper, mix: b > a ? (azimuth - a) / (b - a) : 0 };
+}
+
+/**
+ * One profile into one row, sampled at `width` even steps across a **fixed 0 to 180 degree arc**.
+ *
+ * **Fixed rather than the profile's own range, and that is what keeps a light's record to one
+ * slot.** A row spanning whatever a file happened to measure would need the light to carry the
+ * first angle and the span as well, so the shader could map an angle back into the row — three
+ * values where the froxel record has exactly one free. Pinning every row to the same arc makes the
+ * lookup `angle / 180`, and the row index is then all a light needs.
+ *
+ * **Outside the measured range a row holds the nearest measured value**, which is correct rather
+ * than merely safe: a downlight measured 0 to 90 emits nothing above the horizontal, and its last
+ * sample is already the near-zero that says so. **What would make it wrong** is a file measured
+ * over a partial arc that does *not* fall to zero at its end — a fixture with a documented cutoff
+ * — where clamping extends its last value across everything beyond. That is a real shape and it is
+ * rare, and the tell is a profile whose final candela is a large fraction of its peak.
+ */
+function packRow(
+  profile: PhotometricProfile,
+  plane: number,
+  planes: number,
+  out: Float32Array,
+  offset: number,
+  width: number,
+): void {
+  const angles = profile.verticalAngles;
+  const count = angles.length;
+  const peak = profile.maxCandela > 0 ? profile.maxCandela : 1;
+  /* The candela grid is horizontal-major: all vertical angles of the first plane, then the next.
+     So a plane is a run of `count` values, and blending two planes is a blend of two runs. */
+  const span = planeSpan(profile.horizontalAngles, plane, planes);
+  const lowerAt = span.lower * count;
+  const upperAt = span.upper * count;
+
+  for (let column = 0; column < width; column++) {
+    /* Texel centres over the whole arc, so column 0 is 0 degrees and the last is 180. */
+    const angle = width === 1 ? 0 : (column / (width - 1)) * 180;
+
+    /*
+     * Linear between the two measured angles either side. A nearest-neighbour lookup on a table
+     * that is sparse in the flat regions produces visible steps exactly where the distribution is
+     * smooth, which reads as banding in the light rather than as a sampling choice.
+     */
+    let upper = 1;
+    while (upper < count && (angles[upper] ?? 0) < angle) upper += 1;
+    const lower = Math.max(0, Math.min(upper - 1, count - 1));
+    const top = Math.min(upper, count - 1);
+    const a = angles[lower] ?? 0;
+    const b = angles[top] ?? a;
+    const mix = b > a ? Math.min(1, Math.max(0, (angle - a) / (b - a))) : 0;
+
+    /*
+     * Two interpolations, and the order is not arbitrary: vertical within each of the two planes
+     * either side, then horizontal between the two results. Blending the planes first and then
+     * sampling would be the same number for a linear grid and is not one for a real fixture,
+     * whose vertical lists are the same but whose lobes are not.
+     */
+    const lowPlane = interpolate(profile.candela, lowerAt, lower, top, mix);
+    const highPlane =
+      span.lower === span.upper ? lowPlane : interpolate(profile.candela, upperAt, lower, top, mix);
+    out[offset + column] = (lowPlane + (highPlane - lowPlane) * span.mix) / peak;
+  }
+}
+
+/** One plane's value between two vertical samples, at `at` in the horizontal-major grid. */
+function interpolate(
+  candela: Float32Array,
+  at: number,
+  lower: number,
+  upper: number,
+  mix: number,
+): number {
+  const low = candela[at + lower] ?? 0;
+  const high = candela[at + upper] ?? low;
+  return low + (high - low) * mix;
+}

package/src/render/imageTexels.ts

@@ -0,0 +1,109 @@
+/**
+ * An image's texels, exactly as they were encoded — which a canvas cannot give you.
+ *
+ * **Every ordinary way of reading an image back in a browser is lossy where alpha varies, and this
+ * was measured rather than assumed.** A 2D canvas stores colour *premultiplied*: `drawImage`
+ * multiplies each channel by the alpha and `getImageData` divides it back out, so every value
+ * round-trips through `round(round(c * a / 255) * 255 / a)`. WebCodecs is no better — Chrome
+ * decodes a WebP with alpha to a premultiplied `BGRA` frame, and `VideoFrame.copyTo` un-premultiplies
+ * it, arriving at the same arithmetic. Both were run against a lossless WebP whose values are known:
+ * worst channel off by **3 of 255**, and every deviation predicted exactly by that expression.
+ *
+ * The one route that is exact is a texture upload with the unpack flag off and a read back, and
+ * that is what this is: 0 of 255 on the same file.
+ *
+ * **For a picture none of this matters and for data it is a corruption.** The case it was found on
+ * is a `.sog` Gaussian capture, whose `sh0` image carries three *codebook indices* in RGB beside an
+ * opacity in alpha — so a premultiplying read lands the index several entries away wherever a
+ * Gaussian is transparent, and the capture's colours come back tied to its own transparency. Any
+ * image used as a lookup rather than as a picture has the same problem.
+ *
+ * **Here rather than in the package that needed it**, because `AGENTS.md` allows raw WebGL only
+ * under `packages/core/src/render/` and this is raw WebGL. `@driftengine/splats` takes a decoder as
+ * a parameter for exactly this reason and a consumer hands it this one.
+ *
+ * **What it costs, stated because the driver says it out loud**: `readPixels` synchronises the
+ * pipeline, and Chrome logs *"GPU stall due to ReadPixels"* once per image. That is the price of
+ * exactness and it is paid at load rather than per frame — five stalls for a Gaussian capture,
+ * none afterwards. Nothing here belongs in a frame, and `AGENTS.md`'s rule about the hot path is
+ * the reason this is a loader and not a per-frame utility.
+ */
+
+/** One decoded image: 8-bit RGBA, row-major from the top left, unpremultiplied. */
+export interface ImageTexels {
+  readonly width: number;
+  readonly height: number;
+  readonly rgba: Uint8Array;
+}
+
+/** What turns an encoded image's bytes into texels. */
+export type ImageTexelDecoder = (bytes: Uint8Array, type?: string) => Promise<ImageTexels>;
+
+/**
+ * A decoder that reads texels back exactly, over a context of its own.
+ *
+ * **One context for every image it decodes**, created on the first call and kept: a WebGL context
+ * is a scarce resource — browsers cap them somewhere around sixteen — and one per image is a
+ * capture that stops decoding partway through with a context-lost warning.
+ *
+ * `preserveDrawingBuffer` is not set and nothing is ever drawn: the texture is attached to a
+ * framebuffer and read, which is the whole pipeline. `antialias: false` and `depth: false` because
+ * neither is allocated for a path that rasterises nothing.
+ */
+export function createImageTexelDecoder(): ImageTexelDecoder {
+  let gl: WebGL2RenderingContext | null = null;
+  let texture: WebGLTexture | null = null;
+  let framebuffer: WebGLFramebuffer | null = null;
+
+  return async (bytes: Uint8Array, type = 'image/webp'): Promise<ImageTexels> => {
+    const bitmap = await createImageBitmap(new Blob([bytes as unknown as BlobPart], { type }), {
+      /* Both off, and both matter. Premultiplying here is the loss this module exists to avoid;
+         a colour-space conversion would rewrite values that are not colours at all. */
+      premultiplyAlpha: 'none',
+      colorSpaceConversion: 'none',
+    });
+
+    if (gl === null) {
+      const canvas =
+        typeof OffscreenCanvas === 'undefined'
+          ? (document.createElement('canvas') as HTMLCanvasElement)
+          : new OffscreenCanvas(1, 1);
+      gl = canvas.getContext('webgl2', {
+        alpha: true,
+        antialias: false,
+        depth: false,
+        stencil: false,
+      }) as WebGL2RenderingContext | null;
+      if (gl === null) {
+        bitmap.close();
+        throw new Error(
+          'createImageTexelDecoder: no WebGL2 context, and no other browser API reads an ' +
+            'image back without premultiplying it. Supply a decoder of your own.',
+        );
+      }
+      texture = gl.createTexture();
+      framebuffer = gl.createFramebuffer();
+    }
+
+    const width = bitmap.width;
+    const height = bitmap.height;
+    gl.bindTexture(gl.TEXTURE_2D, texture);
+    gl.pixelStorei(gl.UNPACK_PREMULTIPLY_ALPHA_WEBGL, false);
+    gl.pixelStorei(gl.UNPACK_COLORSPACE_CONVERSION_WEBGL, gl.NONE);
+    gl.pixelStorei(gl.UNPACK_ALIGNMENT, 1);
+    gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA8, gl.RGBA, gl.UNSIGNED_BYTE, bitmap);
+    bitmap.close();
+
+    gl.bindFramebuffer(gl.FRAMEBUFFER, framebuffer);
+    gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, gl.TEXTURE_2D, texture, 0);
+    if (gl.checkFramebufferStatus(gl.FRAMEBUFFER) !== gl.FRAMEBUFFER_COMPLETE) {
+      gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+      throw new Error('createImageTexelDecoder: this driver will not read back an RGBA8 texture.');
+    }
+    const rgba = new Uint8Array(width * height * 4);
+    gl.readPixels(0, 0, width, height, gl.RGBA, gl.UNSIGNED_BYTE, rgba);
+    gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+    gl.bindTexture(gl.TEXTURE_2D, null);
+    return { width, height, rgba };
+  };
+}

package/src/render/instancedMesh.ts

@@ -0,0 +1,187 @@
+import type { MeshData } from './mesh.ts';
+
+/**
+ * One base mesh drawn many times in a single call.
+ *
+ * A field of grass is tens of thousands of copies of the same few triangles.
+ * Submitted individually that is tens of thousands of draw calls, which is the
+ * one thing a browser renderer cannot absorb; as instances it is one call and
+ * the GPU does the rest. This is what makes "dress the world" affordable at all.
+ *
+ * Per-instance attributes advance once per instance rather than once per vertex
+ * (`vertexAttribDivisor`), so the base mesh is uploaded once and never again.
+ */
+export interface InstanceData {
+  /** 3 floats each: world position. */
+  readonly positions: Float32Array;
+  /** 2 floats each: uniform scale, then yaw in radians. */
+  readonly scaleAndYaw: Float32Array;
+  /** 3 floats each: multiplied into the base mesh's colour. */
+  readonly tints: Float32Array;
+  /**
+   * 3 floats each: how far this instance bends, how much the gust moves it,
+   * and a phase offset.
+   *
+   * Per instance rather than global so a field does not sway in lockstep —
+   * uniform motion is the single clearest sign that foliage is a texture with
+   * an animation on it rather than many separate plants.
+   */
+  readonly windResponse: Float32Array;
+  readonly capacity: number;
+  /** How many instances are live; the rest of the buffer is ignored. */
+  count: number;
+}
+
+export function createInstanceData(capacity: number): InstanceData {
+  return {
+    positions: new Float32Array(capacity * 3),
+    scaleAndYaw: new Float32Array(capacity * 2),
+    tints: new Float32Array(capacity * 3),
+    windResponse: new Float32Array(capacity * 3),
+    capacity,
+    count: 0,
+  };
+}
+
+export function writeInstance(
+  data: InstanceData,
+  index: number,
+  x: number,
+  y: number,
+  z: number,
+  scale: number,
+  yaw: number,
+  tintR: number,
+  tintG: number,
+  tintB: number,
+  bend: number,
+  flutter: number,
+  phase: number,
+): void {
+  if (index < 0 || index >= data.capacity) {
+    throw new Error(`Instance ${index} is outside capacity ${data.capacity}`);
+  }
+  const p = index * 3;
+  data.positions[p] = x;
+  data.positions[p + 1] = y;
+  data.positions[p + 2] = z;
+
+  const s = index * 2;
+  data.scaleAndYaw[s] = scale;
+  data.scaleAndYaw[s + 1] = yaw;
+
+  data.tints[p] = tintR;
+  data.tints[p + 1] = tintG;
+  data.tints[p + 2] = tintB;
+
+  data.windResponse[p] = bend;
+  data.windResponse[p + 1] = flutter;
+  data.windResponse[p + 2] = phase;
+}
+
+export class InstancedMesh {
+  private readonly vao: WebGLVertexArrayObject;
+  private readonly buffers: WebGLBuffer[] = [];
+  private readonly indexCount: number;
+  private readonly positionBuffer: WebGLBuffer;
+  private readonly scaleBuffer: WebGLBuffer;
+  private readonly tintBuffer: WebGLBuffer;
+  private readonly windBuffer: WebGLBuffer;
+
+  constructor(gl: WebGL2RenderingContext, base: MeshData, capacity: number) {
+    /*
+     * **Refused rather than dropped.** The per-vertex channel sits at location 13, which this path
+     * spends on `aInstanceModel2` — eleven base attributes plus five per-instance is exactly the
+     * sixteen WebGL2 guarantees, so there is nothing left to put it in. Drawing the mesh anyway
+     * would read the absent-attribute constant and produce a plausible picture: leaves that never
+     * move, a cave face at full sun, a pane at full opacity, with nothing anywhere saying why.
+     * That is the silent no-op `AGENTS.md` forbids, so it throws at construction instead.
+     *
+     * **The escape hatch is written down and untaken**: the instance tint could ride in the `w`
+     * lanes of the four model columns, which an affine matrix leaves unused, freeing location 15
+     * — at the cost of narrowing instance transforms to affine and making a projective one
+     * silently wrong. Not paid for yet, because the obvious instanced case for sway is a field of
+     * vegetation and `ScatterBatch` already draws that with wind of its own. A consumer filing
+     * instanced geometry that needs a lane is what reverses it.
+     */
+    if (base.channel !== undefined) {
+      throw new Error(
+        'InstancedMesh: this mesh carries a per-vertex channel, which needs attribute location ' +
+          '13, and an instanced draw already spends 11 through 15 on its transform and tint. ' +
+          'Draw it as an ordinary mesh, or drop the channel — the sway, sky and alpha lanes ' +
+          'cannot reach an instanced pipeline.',
+      );
+    }
+    const vao = gl.createVertexArray();
+    if (vao === null) throw new Error('InstancedMesh: createVertexArray failed');
+    this.vao = vao;
+    gl.bindVertexArray(vao);
+
+    const make = (): WebGLBuffer => {
+      const buffer = gl.createBuffer();
+      if (buffer === null) throw new Error('InstancedMesh: createBuffer failed');
+      this.buffers.push(buffer);
+      return buffer;
+    };
+
+    // Base mesh: divisor 0, so these advance per vertex as usual.
+    const attach = (data: Float32Array, location: number, size: number): void => {
+      gl.bindBuffer(gl.ARRAY_BUFFER, make());
+      gl.bufferData(gl.ARRAY_BUFFER, data, gl.STATIC_DRAW);
+      gl.enableVertexAttribArray(location);
+      gl.vertexAttribPointer(location, size, gl.FLOAT, false, 0, 0);
+    };
+    attach(base.positions, 0, 3);
+    attach(base.normals, 1, 3);
+    attach(base.colors, 2, 3);
+
+    const indexBuffer = make();
+    gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, indexBuffer);
+    gl.bufferData(gl.ELEMENT_ARRAY_BUFFER, base.indices, gl.STATIC_DRAW);
+    this.indexCount = base.indices.length;
+
+    // Per-instance: divisor 1, so each advances once per copy rather than once
+    // per vertex. Sized to capacity now and rewritten later, because resizing a
+    // buffer mid-frame is a stall.
+    const instanced = (location: number, size: number): WebGLBuffer => {
+      const buffer = make();
+      gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
+      gl.bufferData(gl.ARRAY_BUFFER, capacity * size * 4, gl.DYNAMIC_DRAW);
+      gl.enableVertexAttribArray(location);
+      gl.vertexAttribPointer(location, size, gl.FLOAT, false, 0, 0);
+      gl.vertexAttribDivisor(location, 1);
+      return buffer;
+    };
+    this.positionBuffer = instanced(3, 3);
+    this.scaleBuffer = instanced(4, 2);
+    this.tintBuffer = instanced(5, 3);
+    this.windBuffer = instanced(6, 3);
+
+    gl.bindVertexArray(null);
+  }
+
+  /** Upload placement. Called at load; scatter does not move once placed. */
+  upload(gl: WebGL2RenderingContext, data: InstanceData): void {
+    const put = (buffer: WebGLBuffer, values: Float32Array, perInstance: number): void => {
+      gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
+      gl.bufferSubData(gl.ARRAY_BUFFER, 0, values.subarray(0, data.count * perInstance));
+    };
+    put(this.positionBuffer, data.positions, 3);
+    put(this.scaleBuffer, data.scaleAndYaw, 2);
+    put(this.tintBuffer, data.tints, 3);
+    put(this.windBuffer, data.windResponse, 3);
+    gl.bindBuffer(gl.ARRAY_BUFFER, null);
+  }
+
+  draw(gl: WebGL2RenderingContext, count: number): void {
+    if (count <= 0) return;
+    gl.bindVertexArray(this.vao);
+    gl.drawElementsInstanced(gl.TRIANGLES, this.indexCount, gl.UNSIGNED_INT, 0, count);
+    gl.bindVertexArray(null);
+  }
+
+  dispose(gl: WebGL2RenderingContext): void {
+    for (const buffer of this.buffers) gl.deleteBuffer(buffer);
+    gl.deleteVertexArray(this.vao);
+  }
+}

package/src/render/instances.ts

@@ -0,0 +1,92 @@
+/**
+ * One base mesh's per-instance placement and colour.
+ *
+ * **Many copies of one mesh are one draw and one material.** A street of thirty cars of five
+ * models is five draws rather than thirty, and — the half that is easy to miss — five *material*
+ * changes rather than thirty, which on the WebGPU backend is the scarcer of the two.
+ *
+ * Distinct from `InstanceData`, which `createScatter` takes, and deliberately not merged with it:
+ * a scatter instance carries a uniform scale, a yaw and a wind response, because it describes a
+ * plant. This one carries a full transform, because a vehicle pitches and rolls on its suspension
+ * and a yaw cannot say so.
+ *
+ * **What it gives up** is a matrix per instance where a scatter spends five floats: 76 bytes
+ * against 44, and no wind. **What would make it wrong** is a caller wanting per-instance
+ * anything else — an opacity, a morph weight — which wants another attribute, and the sixteen
+ * WebGL2 guarantees are already spent.
+ */
+export interface MeshInstances {
+  /**
+   * Sixteen floats each, column-major: one model matrix per instance.
+   *
+   * The same layout `drawMesh` takes, so a caller that already builds a matrix per object passes
+   * what it has rather than decomposing it.
+   */
+  readonly models: Float32Array;
+  /**
+   * Three floats each, multiplied into the base mesh's colour exactly as `drawMesh`'s tint is.
+   *
+   * White is the identity. A batch whose instances share a colour still spends three floats each
+   * — the alternative is a second batch per colour, which is the thing this exists to avoid.
+   */
+  readonly tints: Float32Array;
+  /** How many instances the arrays hold. Fixed at creation; the buffers are sized from it. */
+  readonly capacity: number;
+  /** How many are live. The rest of the buffer is neither uploaded nor drawn. */
+  count: number;
+}
+
+/**
+ * Allocate both arrays at `capacity`, empty.
+ *
+ * Allocated once and rewritten in place, never per frame — the arrays are the caller's to fill
+ * and the count is the caller's to set, which is what keeps a frame that redraws a batch
+ * allocation-free.
+ */
+export function createMeshInstances(capacity: number): MeshInstances {
+  return {
+    models: new Float32Array(capacity * 16),
+    tints: new Float32Array(capacity * 3),
+    capacity,
+    count: 0,
+  };
+}
+
+/**
+ * Floats one instance occupies in the interleaved vertex buffer: sixteen of matrix, three of
+ * tint, and one of padding.
+ *
+ * **Padded to twenty so the stride is 80 bytes rather than 76.** A vertex buffer's stride must be
+ * a multiple of four on both backends, which 76 already is — the padding is for the *attribute*
+ * offsets: the tint sits at byte 64 and a three-float attribute ending at 76 leaves the next
+ * instance's first column starting there, which is legal but puts every second instance on an
+ * offset no driver aligns well. One wasted float an instance is 4 bytes against 76.
+ */
+export const INSTANCE_FLOATS = 20;
+
+/** Bytes one instance occupies. See `INSTANCE_FLOATS`. */
+export const INSTANCE_STRIDE = INSTANCE_FLOATS * 4;
+
+/**
+ * Interleave `count` instances into `out`, matrix then tint, at `INSTANCE_FLOATS` apart.
+ *
+ * **Interleaved rather than two buffers** so a batch's upload is one `writeBuffer` and an
+ * instance's colour sits beside the matrix that places it. Shared by both backends, because
+ * which floats go where is a decision and not a binding — the rule this repository draws around
+ * `resolveAtmosphere` and `resolvePointLights`.
+ *
+ * Writes nothing beyond `count`, and allocates nothing: `out` is the caller's staging array.
+ */
+export function packInstances(instances: MeshInstances, out: Float32Array): void {
+  const { models, tints } = instances;
+  const count = Math.min(instances.count, instances.capacity);
+  for (let i = 0; i < count; i += 1) {
+    const at = i * INSTANCE_FLOATS;
+    const m = i * 16;
+    for (let c = 0; c < 16; c += 1) out[at + c] = models[m + c] as number;
+    const t = i * 3;
+    out[at + 16] = tints[t] as number;
+    out[at + 17] = tints[t + 1] as number;
+    out[at + 18] = tints[t + 2] as number;
+  }
+}