@driftengine/core 3.61.0

package/src/render/decalPass.ts

@@ -0,0 +1,124 @@
+import { mat4 } from 'gl-matrix';
+import type { ReadonlyMat4 } from 'gl-matrix';
+
+import { decalScissor } from './decalProjector.ts';
+import type { DecalQueue } from './decalQueue.ts';
+import { DEPTH_01_TO_CLIP } from './lightVolumeDraw.ts';
+import { compileProgram, uniformLocations } from './shader.ts';
+import { DECAL_PROJECT_FRAG } from './shaders/decalProject.ts';
+import { FULLSCREEN_VERT } from './shaders/fullscreen.ts';
+
+/**
+ * Drawn decals on WebGL2: one scissored triangle per mark, multiplied into the finished scene.
+ *
+ * **The whole pass is a blend state and a rectangle.** There is no geometry, no vertex buffer and
+ * no depth test: the mark is decided per pixel from the depth copy, so the only thing the
+ * rasteriser is asked for is coverage of the part of the screen the projector box can possibly
+ * reach. `decalScissor` computes that from the box's eight corners, which is what stands in for
+ * drawing the box as a mesh and is argued there.
+ *
+ * **`(ZERO, SRC_COLOR)` is the effect.** The result is `dst * src`, so a fragment writing white
+ * changes nothing and one writing the mark's colour tints what is under it — including the
+ * receiver's lighting, which is the reason to multiply and is stated at length in the shader.
+ */
+export class DecalPass {
+  private readonly program: WebGLProgram;
+  private readonly uniforms: Record<string, WebGLUniformLocation | null>;
+  private readonly vao: WebGLVertexArrayObject;
+
+  /** `inverse(viewProjection) * DEPTH_01_TO_CLIP`, rebuilt once a frame rather than per mark. */
+  private readonly depthToWorld = new Float32Array(16);
+  private readonly scissor = new Int32Array(4);
+
+  constructor(private readonly gl: WebGL2RenderingContext) {
+    this.program = compileProgram(gl, FULLSCREEN_VERT, DECAL_PROJECT_FRAG, 'decalProject');
+    this.uniforms = uniformLocations(gl, this.program, 'decalPass');
+    const vao = gl.createVertexArray();
+    if (vao === null) throw new Error('DecalPass: createVertexArray failed');
+    this.vao = vao;
+  }
+
+  /**
+   * Mark the bound framebuffer with everything the queue recorded.
+   *
+   * `viewProjection` is the **raw** camera matrix, not the clip-corrected one: `DEPTH_01_TO_CLIP`
+   * turns a stored depth back into the clip space that matrix was built in, and pairing it with
+   * the corrected one applies the remap twice. `lightVolumeDraw.ts` carries that derivation.
+   */
+  drawDecals(
+    queue: DecalQueue,
+    depth: WebGLTexture,
+    viewProjection: ReadonlyMat4,
+    eye: ArrayLike<number>,
+    width: number,
+    height: number,
+  ): void {
+    if (queue.length === 0) return;
+    const { gl } = this;
+    const u = this.uniforms;
+
+    mat4.invert(this.depthToWorld, viewProjection);
+    mat4.multiply(this.depthToWorld, this.depthToWorld, DEPTH_01_TO_CLIP);
+
+    gl.useProgram(this.program);
+    gl.bindVertexArray(this.vao);
+    gl.disable(gl.DEPTH_TEST);
+    gl.depthMask(false);
+    gl.disable(gl.CULL_FACE);
+    gl.enable(gl.BLEND);
+    gl.blendFunc(gl.ZERO, gl.SRC_COLOR);
+    gl.enable(gl.SCISSOR_TEST);
+
+    /* Unit 0, chosen rather than inherited: `bindTexture` binds to whichever unit is active, and
+       the renderer leaves that wherever its last pass finished. `OitPass` records what leaving it
+       there cost. */
+    gl.activeTexture(gl.TEXTURE0);
+    gl.bindTexture(gl.TEXTURE_2D, depth);
+    gl.uniform1i(u['uDecalDepth'] ?? null, 0);
+    gl.uniformMatrix4fv(u['uDecalDepthToWorld'] ?? null, false, this.depthToWorld);
+    gl.uniform3f(u['uDecalEye'] ?? null, eye[0] ?? 0, eye[1] ?? 0, eye[2] ?? 0);
+
+    queue.replay((decal) => {
+      /* False when the box is off-screen or wholly behind the eye, and then this mark costs a
+         matrix multiply and no fragments at all. */
+      if (!decalScissor(viewProjection, decal.decalToWorld, width, height, false, this.scissor)) {
+        return;
+      }
+      gl.scissor(
+        this.scissor[0] ?? 0,
+        this.scissor[1] ?? 0,
+        this.scissor[2] ?? 0,
+        this.scissor[3] ?? 0,
+      );
+      gl.uniformMatrix4fv(u['uWorldToDecal'] ?? null, false, decal.worldToDecal);
+      gl.uniform3fv(u['uDecalAxis'] ?? null, decal.axis);
+      gl.uniform3fv(u['uDecalColor'] ?? null, decal.color);
+      gl.uniform1f(u['uDecalOpacity'] ?? null, decal.opacity);
+      gl.uniform1f(u['uDecalFacingCos'] ?? null, decal.facingCos);
+      gl.uniform1f(u['uDecalSoftness'] ?? null, decal.softness);
+      gl.drawArrays(gl.TRIANGLES, 0, 3);
+    });
+
+    gl.disable(gl.SCISSOR_TEST);
+    /* And the whole viewport back, so a later `enable` inherits a rectangle that is not one mark's
+       corner of the screen. */
+    gl.scissor(0, 0, width, height);
+    gl.bindVertexArray(null);
+    /*
+     * **Released, and `OitPass` says why at length.** A binding outlives the frame it was made in,
+     * so unit 0 would keep the depth copy — which a later pass attaches as its own target while a
+     * program still declares a sampler on that unit. That is a feedback loop: reported once per
+     * draw and rasterising something undefined.
+     */
+    gl.bindTexture(gl.TEXTURE_2D, null);
+    gl.disable(gl.BLEND);
+    gl.depthMask(true);
+    gl.enable(gl.DEPTH_TEST);
+  }
+
+  dispose(): void {
+    const { gl } = this;
+    gl.deleteProgram(this.program);
+    gl.deleteVertexArray(this.vao);
+  }
+}

package/src/render/decalProjector.ts

@@ -0,0 +1,390 @@
+import type { ReadonlyMat4, ReadonlyVec3 } from 'gl-matrix';
+
+/**
+ * A decal evaluated at render time: a box, the depth buffer, and whatever surface is inside it.
+ *
+ * **`projectDecal` is the other half of this and neither replaces the other.** That one clips the
+ * receiving surface's own triangles to a projector box and lifts them off along their normals, so
+ * the mark *is* the surface: it follows every curve and bump exactly, it is lit as the surface is
+ * lit, and it costs nothing per frame. What it cannot do is change afterwards. The clip happens
+ * once, against the mesh as it stood, so a mark on something that later deforms rides the old
+ * shape, and a mark on something that streams in later cannot be made at all because there was
+ * nothing to clip.
+ *
+ * **This is the projector kept alive instead.** Nothing is clipped and no mesh is built: the pass
+ * reads the depth the frame has already drawn, turns each pixel back into the world point it
+ * stands for, and asks whether that point is inside the box. A surface that deforms, streams in,
+ * or is drawn by something with no CPU-side geometry at all — a heightfield, a skinned mesh, an
+ * instanced crowd — is marked on the frame it is drawn, because the mark is decided from the
+ * picture rather than from the mesh.
+ *
+ * **What it costs, and it is the honest half of the trade.** The mark is applied to the finished
+ * pixel rather than to the surface's albedo, so it multiplies what is already there: it can
+ * darken, stain and tint, and it cannot brighten or add a highlight. It has no geometry of its
+ * own, so it takes the receiver's lighting exactly — which is the *reason* to multiply rather
+ * than an accident of it — and a purely diffuse receiver is shaded as though the albedo had been
+ * marked before the light was applied. And it knows only what the depth buffer knows: anything
+ * that drew without writing depth, a beam or a particle, is in front of the mark and is darkened
+ * with it.
+ *
+ * The shape is procedural — an ellipse across the box's face with a soft edge, faded where the
+ * surface turns away from the projector. A textured mark is what it does not do yet, and
+ * `docs/CAPABILITIES.md` says so where it says the rest.
+ */
+
+/** The box a projector occupies. Every field is world space. */
+export interface DecalBox {
+  /** Middle of the projector box. */
+  readonly center: ReadonlyVec3;
+  /** Half-size across, up, and along the projection. The third is how deep the box reaches. */
+  readonly halfExtents: ReadonlyVec3;
+  /**
+   * The direction the decal is projected *along* — for a mark on the ground, straight down.
+   *
+   * A surface is marked when it faces back along this. Need not be normalised.
+   */
+  readonly forward: ReadonlyVec3;
+  /** Which way is up in the decal's own image, so a mark can be turned. Need not be normalised. */
+  readonly up: ReadonlyVec3;
+}
+
+export interface DecalProjectorOptions extends DecalBox {
+  /** What the mark multiplies the surface by. White marks nothing; black is a hole. */
+  readonly color?: ReadonlyVec3;
+  /** How much of that colour lands, 0 to 1. */
+  readonly opacity?: number;
+  /**
+   * How far from facing the projector a surface may be turned and still be marked, as a cosine.
+   *
+   * **The stretch this prevents is the classic failure of a projected decal.** A wall standing
+   * edge-on to the projector occupies one pixel of depth per metre of wall, so a mark aimed at the
+   * floor smears the full depth of the box up it in a long streak. `projectDecal` has the same
+   * number for the same reason, and this one is read from the depth buffer's own derivatives
+   * rather than from a vertex normal.
+   */
+  readonly facingCos?: number;
+  /** How much of the mark's radius is edge, 0 for a hard ellipse and 1 for all falloff. */
+  readonly softness?: number;
+}
+
+/** Scratch for the orthonormal frame, so building a matrix allocates nothing. */
+const RIGHT = new Float64Array(3);
+const UP = new Float64Array(3);
+const FORWARD = new Float64Array(3);
+/** The eight corners of the box, projected, for the scissor bound. */
+const CORNER = new Float64Array(4);
+
+function frame(box: DecalBox): void {
+  const f = box.forward;
+  const length = Math.hypot(f[0] ?? 0, f[1] ?? 0, f[2] ?? 0);
+  if (length === 0) throw new Error('DecalProjector: forward has no direction');
+  FORWARD[0] = (f[0] ?? 0) / length;
+  FORWARD[1] = (f[1] ?? 0) / length;
+  FORWARD[2] = (f[2] ?? 0) / length;
+
+  const u = box.up;
+  /* right = up x forward, which is the frame `projectDecal` builds and the one a caller's `up`
+     therefore already means. */
+  RIGHT[0] = (u[1] ?? 0) * FORWARD[2] - (u[2] ?? 0) * FORWARD[1];
+  RIGHT[1] = (u[2] ?? 0) * FORWARD[0] - (u[0] ?? 0) * FORWARD[2];
+  RIGHT[2] = (u[0] ?? 0) * FORWARD[1] - (u[1] ?? 0) * FORWARD[0];
+  const across = Math.hypot(RIGHT[0], RIGHT[1], RIGHT[2]);
+  if (across === 0) {
+    throw new Error('DecalProjector: up is parallel to forward, so the box has no orientation');
+  }
+  RIGHT[0] /= across;
+  RIGHT[1] /= across;
+  RIGHT[2] /= across;
+
+  /* Re-derived so the frame is orthonormal even where the caller's up was not perpendicular —
+     which is what a caller aiming a projector by hand hands in, and what shears the mark if it is
+     taken as given. */
+  UP[0] = FORWARD[1] * RIGHT[2] - FORWARD[2] * RIGHT[1];
+  UP[1] = FORWARD[2] * RIGHT[0] - FORWARD[0] * RIGHT[2];
+  UP[2] = FORWARD[0] * RIGHT[1] - FORWARD[1] * RIGHT[0];
+}
+
+/** `-0` back to `0`, and anything else through untouched — including a NaN, which `|| 0` would eat. */
+function zeroed(value: number): number {
+  return value === 0 ? 0 : value;
+}
+
+function extents(box: DecalBox): [number, number, number] {
+  const hx = box.halfExtents[0] ?? 0;
+  const hy = box.halfExtents[1] ?? 0;
+  const hz = box.halfExtents[2] ?? 0;
+  if (!(hx > 0 && hy > 0 && hz > 0)) {
+    throw new Error(`DecalProjector: halfExtents must be positive, got ${hx}, ${hy}, ${hz}`);
+  }
+  return [hx, hy, hz];
+}
+
+/**
+ * World space into the projector's unit box, column major.
+ *
+ * The box is `[-1, 1]` on every axis: x across the mark, y up it, z along the projection. A
+ * fragment is inside the projector exactly when all three come back within one, which is the whole
+ * of the test the shader runs.
+ */
+export function worldToDecalMatrix(out: Float32Array, box: DecalBox): Float32Array {
+  frame(box);
+  const [hx, hy, hz] = extents(box);
+  const c = box.center;
+  const cx = c[0] ?? 0;
+  const cy = c[1] ?? 0;
+  const cz = c[2] ?? 0;
+
+  /* The rows are the axes divided by their half-extent, and the translation is the centre run
+     through them and negated: an orthonormal frame's inverse is its transpose, so this is the
+     inverse of `decalToWorldMatrix` written out rather than computed.
+
+     The translations go through `zeroed` because negating a centre on an axis produces `-0`, which
+     is equal to zero in every arithmetic use and not under `Object.is` — so two projectors alike in
+     every way a GPU can see would compare unequal. `depthOffsetForLayer` records the same trap. */
+  out[0] = RIGHT[0] / hx;
+  out[4] = RIGHT[1] / hx;
+  out[8] = RIGHT[2] / hx;
+  out[12] = zeroed(-(RIGHT[0] * cx + RIGHT[1] * cy + RIGHT[2] * cz) / hx);
+
+  out[1] = UP[0] / hy;
+  out[5] = UP[1] / hy;
+  out[9] = UP[2] / hy;
+  out[13] = zeroed(-(UP[0] * cx + UP[1] * cy + UP[2] * cz) / hy);
+
+  out[2] = FORWARD[0] / hz;
+  out[6] = FORWARD[1] / hz;
+  out[10] = FORWARD[2] / hz;
+  out[14] = zeroed(-(FORWARD[0] * cx + FORWARD[1] * cy + FORWARD[2] * cz) / hz);
+
+  out[3] = 0;
+  out[7] = 0;
+  out[11] = 0;
+  out[15] = 1;
+  return out;
+}
+
+/**
+ * The unit box back out into the world, column major.
+ *
+ * Only the scissor needs this — it projects the eight corners to find what part of the screen the
+ * box can possibly cover — but it is written here beside its inverse so the two cannot drift, and
+ * a test asserts they round-trip.
+ */
+export function decalToWorldMatrix(out: Float32Array, box: DecalBox): Float32Array {
+  frame(box);
+  const [hx, hy, hz] = extents(box);
+  const c = box.center;
+
+  out[0] = RIGHT[0] * hx;
+  out[1] = RIGHT[1] * hx;
+  out[2] = RIGHT[2] * hx;
+  out[3] = 0;
+
+  out[4] = UP[0] * hy;
+  out[5] = UP[1] * hy;
+  out[6] = UP[2] * hy;
+  out[7] = 0;
+
+  out[8] = FORWARD[0] * hz;
+  out[9] = FORWARD[1] * hz;
+  out[10] = FORWARD[2] * hz;
+  out[11] = 0;
+
+  out[12] = c[0] ?? 0;
+  out[13] = c[1] ?? 0;
+  out[14] = c[2] ?? 0;
+  out[15] = 1;
+  return out;
+}
+
+/** One pixel of slack, because the frame may be jittered and a bound is rounded. */
+const SCISSOR_PAD = 1;
+
+/**
+ * The part of the screen a projector can possibly mark, as a scissor rectangle.
+ *
+ * **This is what stands in for drawing the box as geometry**, and the trade is deliberate. A box
+ * submitted as a mesh covers its own silhouette exactly, and costs a vertex buffer, an index
+ * buffer, a choice between front and back faces depending on whether the camera is inside it, and
+ * a near-plane case where the front faces are clipped away. A rectangle around the same eight
+ * corners costs none of those and over-covers by the difference between a silhouette and its
+ * bounding box — at worst about twice the fragments, each of them one depth fetch and one matrix
+ * multiply before it decides it is outside the box. For a pass that is otherwise two textures and
+ * a blend state, that is the cheaper half.
+ *
+ * **A corner behind the camera is the trap, and it does not look like one.** Dividing clip space
+ * by a negative `w` mirrors the point through the origin, so a box the camera stands inside
+ * produces eight perfectly ordinary screen positions describing a rectangle that is nowhere near
+ * the truth — the mark then appears in a patch of the frame it has nothing to do with, and the
+ * rest of it silently does not draw. So a box with any corner at or behind the eye is scissored to
+ * the whole viewport, which is always correct and merely costs more, and one with *every* corner
+ * behind is skipped entirely.
+ *
+ * `yDown` is which way the caller's framebuffer counts rows: false for WebGL2's `gl.scissor`,
+ * whose origin is the bottom left, and true for WebGPU's `setScissorRect`, whose origin is the top
+ * left. Both describe the same pixels, and the pair is here rather than in either backend for the
+ * reason `DEPTH_01_TO_CLIP_Y_DOWN` gives at length: a convention held in two places is a pass that
+ * marks the mirror image of what it should on one backend and nothing raises.
+ *
+ * Returns false when there is nothing to draw, and fills `out` with `[x, y, width, height]` when
+ * there is.
+ */
+export function decalScissor(
+  viewProjection: ReadonlyMat4,
+  decalToWorld: ReadonlyMat4,
+  width: number,
+  height: number,
+  yDown: boolean,
+  out: Int32Array,
+): boolean {
+  let minX = Infinity;
+  let maxX = -Infinity;
+  let minY = Infinity;
+  let maxY = -Infinity;
+  let behind = 0;
+
+  for (let corner = 0; corner < 8; corner++) {
+    const bx = (corner & 1) === 0 ? -1 : 1;
+    const by = (corner & 2) === 0 ? -1 : 1;
+    const bz = (corner & 4) === 0 ? -1 : 1;
+
+    /* Box space to world, then world to clip, without a scratch matrix: two transforms of one
+       point is less work than the 4x4 multiply that would fuse them, and this runs per decal. */
+    for (let row = 0; row < 4; row++) {
+      CORNER[row] =
+        (decalToWorld[row] ?? 0) * bx +
+        (decalToWorld[4 + row] ?? 0) * by +
+        (decalToWorld[8 + row] ?? 0) * bz +
+        (decalToWorld[12 + row] ?? 0);
+    }
+    const wx = CORNER[0] ?? 0;
+    const wy = CORNER[1] ?? 0;
+    const wz = CORNER[2] ?? 0;
+    const clipX =
+      (viewProjection[0] ?? 0) * wx +
+      (viewProjection[4] ?? 0) * wy +
+      (viewProjection[8] ?? 0) * wz +
+      (viewProjection[12] ?? 0);
+    const clipY =
+      (viewProjection[1] ?? 0) * wx +
+      (viewProjection[5] ?? 0) * wy +
+      (viewProjection[9] ?? 0) * wz +
+      (viewProjection[13] ?? 0);
+    const clipW =
+      (viewProjection[3] ?? 0) * wx +
+      (viewProjection[7] ?? 0) * wy +
+      (viewProjection[11] ?? 0) * wz +
+      (viewProjection[15] ?? 0);
+
+    if (clipW <= 1e-6) {
+      behind++;
+      continue;
+    }
+    const ndcX = clipX / clipW;
+    const ndcY = clipY / clipW;
+    if (ndcX < minX) minX = ndcX;
+    if (ndcX > maxX) maxX = ndcX;
+    if (ndcY < minY) minY = ndcY;
+    if (ndcY > maxY) maxY = ndcY;
+  }
+
+  if (behind === 8) return false;
+  if (behind > 0) {
+    out[0] = 0;
+    out[1] = 0;
+    out[2] = width;
+    out[3] = height;
+    return true;
+  }
+
+  const left = Math.max(0, Math.floor(((minX + 1) / 2) * width) - SCISSOR_PAD);
+  const right = Math.min(width, Math.ceil(((maxX + 1) / 2) * width) + SCISSOR_PAD);
+  const bottom = Math.max(0, Math.floor(((minY + 1) / 2) * height) - SCISSOR_PAD);
+  const top = Math.min(height, Math.ceil(((maxY + 1) / 2) * height) + SCISSOR_PAD);
+  if (right <= left || top <= bottom) return false;
+
+  out[0] = left;
+  out[1] = yDown ? height - top : bottom;
+  out[2] = right - left;
+  out[3] = top - bottom;
+  return true;
+}
+
+/**
+ * A projector a consumer holds and moves.
+ *
+ * **Held rather than passed per call**, because that is what the row is for: a mark that follows
+ * something is a pose written every frame, and rebuilding two matrices from four vectors is the
+ * whole of that. Both matrices live in the object and are rewritten in place, so a scene with a
+ * hundred marks allocates on the frame it creates them and never again.
+ */
+export class DecalProjector {
+  /** World space into the unit box. Rewritten in place by `setPose` and `setSize`. */
+  readonly worldToDecal = new Float32Array(16);
+  /** The unit box back into the world, for the scissor bound. */
+  readonly decalToWorld = new Float32Array(16);
+  /** The projection axis, normalised, which the facing test compares a surface normal against. */
+  readonly axis = new Float32Array(3);
+  /** What the mark multiplies the surface by. */
+  readonly color = new Float32Array(3);
+
+  opacity: number;
+  facingCos: number;
+  softness: number;
+
+  private readonly box: {
+    center: Float32Array;
+    halfExtents: Float32Array;
+    forward: Float32Array;
+    up: Float32Array;
+  };
+
+  constructor(options: DecalProjectorOptions) {
+    this.box = {
+      center: Float32Array.from(options.center as ArrayLike<number>),
+      halfExtents: Float32Array.from(options.halfExtents as ArrayLike<number>),
+      forward: Float32Array.from(options.forward as ArrayLike<number>),
+      up: Float32Array.from(options.up as ArrayLike<number>),
+    };
+    this.color.set(options.color === undefined ? [1, 1, 1] : (options.color as ArrayLike<number>));
+    this.opacity = options.opacity ?? 1;
+    /* The same 0.1 `projectDecal` defaults to, which keeps everything within about 84 degrees of
+       facing — and for the same reason, stated there. */
+    this.facingCos = options.facingCos ?? 0.1;
+    /* A quarter of the radius as edge. A hard ellipse reads as a decal that was cut out with
+       scissors, and a mark with no texture has nothing else to soften it. */
+    this.softness = options.softness ?? 0.25;
+    this.rebuild();
+  }
+
+  /** Move the projector. Allocation-free, so a mark may follow something every frame. */
+  setPose(center: ReadonlyVec3, forward: ReadonlyVec3, up: ReadonlyVec3): void {
+    this.box.center.set(center as ArrayLike<number>);
+    this.box.forward.set(forward as ArrayLike<number>);
+    this.box.up.set(up as ArrayLike<number>);
+    this.rebuild();
+  }
+
+  /** Resize the box, on the same terms. */
+  setSize(halfExtents: ReadonlyVec3): void {
+    this.box.halfExtents.set(halfExtents as ArrayLike<number>);
+    this.rebuild();
+  }
+
+  setColor(color: ReadonlyVec3): void {
+    this.color.set(color as ArrayLike<number>);
+  }
+
+  private rebuild(): void {
+    worldToDecalMatrix(this.worldToDecal, this.box);
+    decalToWorldMatrix(this.decalToWorld, this.box);
+    /* `frame` left the normalised axis in its scratch, and reading it back here would couple this
+       to the order those two ran in. Normalised again instead: it is three multiplies once per
+       pose, against a coupling that would break silently. */
+    const f = this.box.forward;
+    const length = Math.hypot(f[0] ?? 0, f[1] ?? 0, f[2] ?? 0);
+    this.axis[0] = (f[0] ?? 0) / length;
+    this.axis[1] = (f[1] ?? 0) / length;
+    this.axis[2] = (f[2] ?? 0) / length;
+  }
+}

package/src/render/decalQueue.ts

@@ -0,0 +1,110 @@
+import type { DecalProjector } from './decalProjector.ts';
+
+/**
+ * The frame's drawn decals, held until the pass that reads the depth buffer can run.
+ *
+ * **The pass cannot run where the call is made.** A projected decal is decided from the depth the
+ * frame has drawn, so it has to happen once the opaque world is finished — and a consumer submits
+ * a mark wherever in its own frame the thing that made the mark lives. So `drawDecal` records and
+ * the renderer replays, exactly as `TranslucentQueue` does for the order-independent passes.
+ *
+ * **Everything is copied, and that is the whole correctness of this file.** A projector is an
+ * object a consumer keeps and moves: it is submitted, then moved to follow whatever it is stuck
+ * to, and submitted again next frame. A queue holding the reference would replay every mark
+ * wearing the last pose written — one wheel's skid under every wheel — which is a plausible
+ * picture rather than an obviously broken one, and that is the kind that gets blamed on the pass.
+ *
+ * **Records are pooled and never released**, for the reason `AGENTS.md` gives: `reset` returns the
+ * count to zero and keeps the storage, so a steady scene allocates on its first frame and never
+ * again.
+ */
+
+/**
+ * How many marks one frame may draw.
+ *
+ * **A cap rather than an open number**, because each is a scissored pass of its own with a uniform
+ * slot behind it, and the slots are one buffer written before the passes are recorded. Thirty-two
+ * is more than a scene has needed: a mark is a projector kept alive per frame, and a world with
+ * more than thirty-two of them in view at once wants `projectDecal`, which costs nothing per frame
+ * and is what the static half of this row is for.
+ */
+export const MAX_DRAWN_DECALS = 32;
+
+/** One recorded mark. Every field is a copy of what the projector held when it was submitted. */
+export interface DrawnDecal {
+  readonly worldToDecal: Float32Array;
+  readonly decalToWorld: Float32Array;
+  readonly axis: Float32Array;
+  readonly color: Float32Array;
+  opacity: number;
+  facingCos: number;
+  softness: number;
+}
+
+function newRecord(): DrawnDecal {
+  return {
+    worldToDecal: new Float32Array(16),
+    decalToWorld: new Float32Array(16),
+    axis: new Float32Array(3),
+    color: new Float32Array(3),
+    opacity: 1,
+    facingCos: 0.1,
+    softness: 0.25,
+  };
+}
+
+export class DecalQueue {
+  private readonly pool: DrawnDecal[] = [];
+  private count = 0;
+  /** Set once when the cap is first reached, so a scene over it says so and then draws. */
+  private warned = false;
+
+  /** How many marks this frame has recorded. */
+  get length(): number {
+    return this.count;
+  }
+
+  /** How many records are pooled, which a test uses to assert a steady scene stops allocating. */
+  get capacity(): number {
+    return this.pool.length;
+  }
+
+  record(projector: DecalProjector): void {
+    if (this.count >= MAX_DRAWN_DECALS) {
+      if (!this.warned) {
+        this.warned = true;
+        console.warn(
+          `driftengine: more than ${MAX_DRAWN_DECALS} drawn decals in one frame, so the rest are ` +
+            'dropped. A mark that never moves is cheaper as projectDecal, which builds it once.',
+        );
+      }
+      return;
+    }
+
+    let record = this.pool[this.count];
+    if (record === undefined) {
+      record = newRecord();
+      this.pool.push(record);
+    }
+    record.worldToDecal.set(projector.worldToDecal);
+    record.decalToWorld.set(projector.decalToWorld);
+    record.axis.set(projector.axis);
+    record.color.set(projector.color);
+    record.opacity = Math.min(1, Math.max(0, projector.opacity));
+    record.facingCos = projector.facingCos;
+    record.softness = Math.min(1, Math.max(0, projector.softness));
+    this.count++;
+  }
+
+  replay(each: (decal: DrawnDecal) => void): void {
+    for (let i = 0; i < this.count; i++) {
+      const record = this.pool[i];
+      if (record !== undefined) each(record);
+    }
+  }
+
+  /** Empty it for the next frame, keeping the storage. */
+  reset(): void {
+    this.count = 0;
+  }
+}