@driftengine/core 3.61.0

package/src/render/passTarget.ts

@@ -0,0 +1,225 @@
+import { glSceneDepthFormat } from './depthConvention.ts';
+import type { PassDevice } from './pass.ts';
+
+/**
+ * A render target a contributed pass owns: it renders into this and samples it later.
+ *
+ * **The asymmetry with `PassDefinition.reads` is the whole design and is worth reading first.**
+ * What a pass *writes into the frame* is not negotiable and is refused: every built-in verb writes
+ * the current target, the executor replays a flush's nodes into one open pass, and a node
+ * declaring some other write-set would schedule as a pass nothing opens — so letting a package
+ * name its writes hands it the one declaration nothing can enforce. A target the pass *owns* is
+ * outside that set by construction, which is exactly what makes it declarable when a write to the
+ * frame is not.
+ *
+ * What it is for: a package's own shadow map, blur pyramid, picking buffer or intermediate. A
+ * `@driftengine/splats` pass wanting a depth prepass of its own, a UI package wanting a cached
+ * layer, an XR package wanting a per-eye scratch.
+ *
+ * **Two implementations behind one call**, the same split `PassDevice` itself takes, and for the
+ * same reason: a neutral device abstraction would be a second renderer API and would buy nothing,
+ * because a package's shader, buffer layout and pipeline differ per backend anyway. The union
+ * makes the branch explicit and typed.
+ *
+ * **Single-sampled, and that is a decision rather than an omission.** A multisampled pass-owned
+ * target needs a resolve target beside it and a decision about who allocates it, and no
+ * contributed pass has asked. *What that costs* is that a pass wanting antialiased geometry of its
+ * own supersamples instead. *What would reverse it* is a contributed pass that needs it, at which
+ * point `samples` joins the options and the resolve target is created with the colour one.
+ *
+ * **`dispose` is the pass's to call**, from its own `dispose`, and nothing calls it for you: the
+ * renderer knows what it created and this is not that. A target left undisposed is a texture the
+ * driver holds until the context goes.
+ */
+export interface PassAttachmentOptions {
+  /** For the label a backend gives the texture, and for diagnostics. */
+  readonly label?: string;
+  readonly width: number;
+  readonly height: number;
+  /**
+   * Eight bits a channel, or half floats.
+   *
+   * Two rather than the format zoo either API offers, because these are the two a pass drawing
+   * into its own target wants: a picking buffer or a cached layer is `rgba8`, and anything
+   * carrying light before a tone curve is `rgba16float`. A third would need a reason.
+   */
+  readonly format?: 'rgba8' | 'rgba16float';
+  /** Whether to attach a depth buffer. Default true, because a pass with geometry wants one. */
+  readonly depth?: boolean;
+}
+
+export type PassTarget = {
+  readonly width: number;
+  readonly height: number;
+  /**
+   * Free the GPU objects. Call it from the pass's own `dispose`, and call it before creating a
+   * replacement — **resizing is dispose-and-recreate** rather than a method, because a resize is
+   * not a per-frame path and a mutable target would be one more thing to keep consistent.
+   */
+  dispose(): void;
+} & (
+  | {
+      readonly backend: 'webgl2';
+      /** Bind this, draw, and bind `null` again. See `PassDefinition.prepare`. */
+      readonly framebuffer: WebGLFramebuffer;
+      readonly colour: WebGLTexture;
+      readonly depth: WebGLTexture | null;
+    }
+  | {
+      readonly backend: 'webgpu';
+      readonly colour: GPUTexture;
+      readonly colourView: GPUTextureView;
+      readonly depth: GPUTexture | null;
+      readonly depthView: GPUTextureView | null;
+      /** What a pipeline drawing into this must declare. */
+      readonly format: GPUTextureFormat;
+      readonly depthFormat: GPUTextureFormat | null;
+    }
+);
+
+/**
+ * Build one. Called from a pass's `init`, or from its `prepare` when the size has changed.
+ *
+ * **Restores the default framebuffer on WebGL2**, rather than whatever was bound before. Both
+ * points where a pass may call this — `init`, outside a frame, and `prepare`, whose contract is
+ * that the default framebuffer is bound on entry and on exit — have the default bound, so
+ * restoring to it is restoring what was there. Reading the binding back to restore it exactly
+ * would be a synchronous driver query in return for covering a case the contract forbids.
+ *
+ * Fails fast on a size that cannot work, which is the init-time rule: a zero-sized attachment is a
+ * framebuffer that is never complete, and a driver reports that as a black draw rather than an
+ * error.
+ */
+export function createPassAttachment(
+  device: PassDevice,
+  options: PassAttachmentOptions,
+): PassTarget {
+  const { width, height } = options;
+  if (!Number.isInteger(width) || !Number.isInteger(height) || width < 1 || height < 1) {
+    throw new Error(
+      `createPassAttachment: ${width}x${height} is not a size — width and height must be positive integers`,
+    );
+  }
+  const wantDepth = options.depth ?? true;
+  const label = options.label ?? 'pass target';
+  const format = options.format ?? 'rgba8';
+
+  if (device.backend === 'webgpu') {
+    const { device: gpu } = device;
+    /*
+     * The two usage bits by value, which is what this renderer already does at every other
+     * `createTexture`: `GPUTextureUsage` is a global the type definitions declare and Node does
+     * not provide, so naming it here would make this module unimportable in a test that never
+     * touches a GPU.
+     */
+    const RENDER_ATTACHMENT = 0x10;
+    const TEXTURE_BINDING = 0x04;
+    const colour = gpu.createTexture({
+      label: `${label} colour`,
+      size: { width, height },
+      format: format === 'rgba8' ? 'rgba8unorm' : 'rgba16float',
+      usage: RENDER_ATTACHMENT | TEXTURE_BINDING,
+    });
+    /* The frame's own depth format, so a pass may build one pipeline for its target and the
+       frame rather than two that differ in a field it did not choose. */
+    const depth = wantDepth
+      ? gpu.createTexture({
+          label: `${label} depth`,
+          size: { width, height },
+          format: device.depthFormat,
+          usage: RENDER_ATTACHMENT,
+        })
+      : null;
+    return {
+      backend: 'webgpu',
+      width,
+      height,
+      colour,
+      colourView: colour.createView(),
+      depth,
+      depthView: depth === null ? null : depth.createView(),
+      format: colour.format,
+      depthFormat: depth === null ? null : device.depthFormat,
+      dispose(): void {
+        colour.destroy();
+        depth?.destroy();
+      },
+    };
+  }
+
+  const { gl } = device;
+  const colour = gl.createTexture();
+  if (colour === null) throw new Error('createPassAttachment: the context refused a texture');
+  gl.bindTexture(gl.TEXTURE_2D, colour);
+  gl.texImage2D(
+    gl.TEXTURE_2D,
+    0,
+    format === 'rgba8' ? gl.RGBA8 : gl.RGBA16F,
+    width,
+    height,
+    0,
+    gl.RGBA,
+    format === 'rgba8' ? gl.UNSIGNED_BYTE : gl.HALF_FLOAT,
+    null,
+  );
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+
+  let depth: WebGLTexture | null = null;
+  if (wantDepth) {
+    const sceneDepth = glSceneDepthFormat(gl);
+    depth = gl.createTexture();
+    if (depth === null) throw new Error('createPassAttachment: the context refused a texture');
+    gl.bindTexture(gl.TEXTURE_2D, depth);
+    gl.texImage2D(
+      gl.TEXTURE_2D,
+      0,
+      sceneDepth.internalFormat,
+      width,
+      height,
+      0,
+      gl.DEPTH_COMPONENT,
+      sceneDepth.type,
+      null,
+    );
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+  }
+
+  const framebuffer = gl.createFramebuffer();
+  if (framebuffer === null) {
+    throw new Error('createPassAttachment: the context refused a framebuffer');
+  }
+  gl.bindFramebuffer(gl.FRAMEBUFFER, framebuffer);
+  gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, gl.TEXTURE_2D, colour, 0);
+  if (depth !== null) {
+    gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.DEPTH_ATTACHMENT, gl.TEXTURE_2D, depth, 0);
+  }
+  const status = gl.checkFramebufferStatus(gl.FRAMEBUFFER);
+  gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+  gl.bindTexture(gl.TEXTURE_2D, null);
+  if (status !== gl.FRAMEBUFFER_COMPLETE) {
+    gl.deleteFramebuffer(framebuffer);
+    gl.deleteTexture(colour);
+    if (depth !== null) gl.deleteTexture(depth);
+    throw new Error(`createPassAttachment: framebuffer incomplete (0x${status.toString(16)})`);
+  }
+
+  return {
+    backend: 'webgl2',
+    width,
+    height,
+    framebuffer,
+    colour,
+    depth,
+    dispose(): void {
+      gl.deleteFramebuffer(framebuffer);
+      gl.deleteTexture(colour);
+      if (depth !== null) gl.deleteTexture(depth);
+    },
+  };
+}

package/src/render/pickable.ts

@@ -0,0 +1,222 @@
+/**
+ * What is under a ray, from a set of registered meshes.
+ *
+ * Backend-agnostic on purpose: nothing here touches a context, so one implementation
+ * answers for WebGL2 and WebGPU alike and the tests need neither. Same argument
+ * `textLayout.ts` makes for keeping glyph arithmetic out of the two text renderers.
+ *
+ * **Broad phase then narrow phase.** A world-space box per entry rejects nearly
+ * everything for the cost of six compares, and only survivors pay for their triangles.
+ * Without it a scene of forty pickables would walk every triangle of all of them on every
+ * pointer move.
+ *
+ * **The box is recomputed when a model matrix is set, not when a ray is cast.** A scene
+ * moves a handful of things per frame and casts one ray per pointer move, so the work
+ * belongs on the write.
+ */
+import { rayAabb, rayTriangle } from '../math/intersect.ts';
+
+export interface PickableSource {
+  readonly positions: Float32Array;
+  readonly indices: Uint32Array;
+}
+
+export interface PickHit {
+  handle: number;
+  distance: number;
+  /** Where the ray met it, in world space. Reused between queries; copy to keep it. */
+  readonly point: Float32Array;
+}
+
+interface Entry {
+  handle: number;
+  source: PickableSource;
+  model: Float32Array;
+  inverse: Float32Array;
+  min: Float32Array;
+  max: Float32Array;
+}
+
+export class PickableSet {
+  private readonly entries: Entry[] = [];
+  private nextHandle = 1;
+
+  /* Reused per query: a pick runs on pointermove and must not allocate. */
+  private readonly localOrigin = new Float32Array(3);
+  private readonly localDirection = new Float32Array(3);
+  private readonly hit: PickHit = { handle: 0, distance: 0, point: new Float32Array(3) };
+
+  add(source: PickableSource, model: Float32Array): number {
+    const handle = this.nextHandle++;
+    const entry: Entry = {
+      handle,
+      source,
+      model: new Float32Array(model),
+      inverse: new Float32Array(16),
+      min: new Float32Array(3),
+      max: new Float32Array(3),
+    };
+    this.entries.push(entry);
+    this.refresh(entry, model);
+    return handle;
+  }
+
+  update(handle: number, model: Float32Array): void {
+    const entry = this.entries.find((candidate) => candidate.handle === handle);
+    if (entry === undefined) return;
+    this.refresh(entry, model);
+  }
+
+  remove(handle: number): void {
+    const at = this.entries.findIndex((candidate) => candidate.handle === handle);
+    if (at >= 0) this.entries.splice(at, 1);
+  }
+
+  clear(): void {
+    this.entries.length = 0;
+  }
+
+  /** The nearest registered mesh along the ray, or null. */
+  pick(origin: ArrayLike<number>, direction: ArrayLike<number>): PickHit | null {
+    let best = Infinity;
+    let bestEntry: Entry | null = null;
+
+    for (const entry of this.entries) {
+      const broad = rayAabb(origin, direction, entry.min, entry.max);
+      if (broad < 0 || broad > best) continue;
+
+      transformPoint(this.localOrigin, entry.inverse, origin);
+      transformDirection(this.localDirection, entry.inverse, direction);
+
+      const { positions, indices } = entry.source;
+      for (let i = 0; i + 2 < indices.length; i += 3) {
+        const distance = rayTriangle(
+          this.localOrigin,
+          this.localDirection,
+          positions,
+          indices[i] as number,
+          indices[i + 1] as number,
+          indices[i + 2] as number,
+        );
+        if (distance >= 0 && distance < best) {
+          best = distance;
+          bestEntry = entry;
+        }
+      }
+    }
+
+    if (bestEntry === null) return null;
+    this.hit.handle = bestEntry.handle;
+    this.hit.distance = best;
+    this.hit.point[0] = (origin[0] as number) + (direction[0] as number) * best;
+    this.hit.point[1] = (origin[1] as number) + (direction[1] as number) * best;
+    this.hit.point[2] = (origin[2] as number) + (direction[2] as number) * best;
+    return this.hit;
+  }
+
+  /**
+   * Re-take the model matrix, its inverse and the world-space box.
+   *
+   * The box is the transformed corners' extent rather than the transformed local box,
+   * which for a rotated mesh is looser than tight and tighter than wrong. A loose broad
+   * phase costs triangles; a wrong one loses picks.
+   */
+  private refresh(entry: Entry, model: Float32Array): void {
+    entry.model.set(model);
+    invertAffine(entry.inverse, model);
+
+    const { positions } = entry.source;
+    entry.min.fill(Infinity);
+    entry.max.fill(-Infinity);
+    for (let i = 0; i + 2 < positions.length; i += 3) {
+      for (let axis = 0; axis < 3; axis++) {
+        const value =
+          (model[axis] as number) * (positions[i] as number) +
+          (model[axis + 4] as number) * (positions[i + 1] as number) +
+          (model[axis + 8] as number) * (positions[i + 2] as number) +
+          (model[axis + 12] as number);
+        if (value < (entry.min[axis] as number)) entry.min[axis] = value;
+        if (value > (entry.max[axis] as number)) entry.max[axis] = value;
+      }
+    }
+  }
+}
+
+/** A point through a 4x4, with the translation. */
+function transformPoint(out: Float32Array, m: Float32Array, p: ArrayLike<number>): void {
+  for (let axis = 0; axis < 3; axis++) {
+    out[axis] =
+      (m[axis] as number) * (p[0] as number) +
+      (m[axis + 4] as number) * (p[1] as number) +
+      (m[axis + 8] as number) * (p[2] as number) +
+      (m[axis + 12] as number);
+  }
+}
+
+/**
+ * A direction through a 4x4, without the translation, left unnormalised on purpose.
+ *
+ * `localOrigin` and this are both built from the same inverse matrix, so the local ray
+ * `localOrigin + t * localDirection` is `inverse(model)` applied to the world ray
+ * `origin + t * direction` at every `t` — the model's linear part and its inverse cancel.
+ * That makes `t` itself invariant under the transform, scale included, uniform or not, so
+ * the `t` `rayTriangle` finds in local space is already the caller's world-space distance.
+ * Normalising this would break that: it would rescale `t` by this vector's length and
+ * `rayTriangle` would start returning a value that needs converting back, for nothing
+ * gained.
+ */
+function transformDirection(out: Float32Array, m: Float32Array, d: ArrayLike<number>): void {
+  for (let axis = 0; axis < 3; axis++) {
+    out[axis] =
+      (m[axis] as number) * (d[0] as number) +
+      (m[axis + 4] as number) * (d[1] as number) +
+      (m[axis + 8] as number) * (d[2] as number);
+  }
+}
+
+/**
+ * The inverse of a model matrix, assuming it is affine.
+ *
+ * Every model matrix this engine produces is translation, rotation and scale, so the
+ * general 4x4 inverse would be arithmetic spent on a bottom row that is always
+ * `0 0 0 1`. Written out rather than reached for from gl-matrix because this is called
+ * whenever anything moves.
+ */
+function invertAffine(out: Float32Array, m: Float32Array): void {
+  const a = m[0] as number,
+    b = m[1] as number,
+    c = m[2] as number;
+  const d = m[4] as number,
+    e = m[5] as number,
+    f = m[6] as number;
+  const g = m[8] as number,
+    h = m[9] as number,
+    i = m[10] as number;
+
+  const A = e * i - f * h;
+  const B = f * g - d * i;
+  const C = d * h - e * g;
+  const determinant = a * A + b * B + c * C;
+  const s = determinant === 0 ? 0 : 1 / determinant;
+
+  out[0] = A * s;
+  out[1] = (c * h - b * i) * s;
+  out[2] = (b * f - c * e) * s;
+  out[3] = 0;
+  out[4] = B * s;
+  out[5] = (a * i - c * g) * s;
+  out[6] = (c * d - a * f) * s;
+  out[7] = 0;
+  out[8] = C * s;
+  out[9] = (b * g - a * h) * s;
+  out[10] = (a * e - b * d) * s;
+  out[11] = 0;
+
+  const tx = m[12] as number,
+    ty = m[13] as number,
+    tz = m[14] as number;
+  out[12] = -((out[0] as number) * tx + (out[4] as number) * ty + (out[8] as number) * tz);
+  out[13] = -((out[1] as number) * tx + (out[5] as number) * ty + (out[9] as number) * tz);
+  out[14] = -((out[2] as number) * tx + (out[6] as number) * ty + (out[10] as number) * tz);
+  out[15] = 1;
+}

package/src/render/planarReflection.ts

@@ -0,0 +1,233 @@
+/** GPU target and mirrored camera for one horizontal planar reflection. */
+
+import type { ReadonlyMat4 } from 'gl-matrix';
+import type { Vec3 } from '../math/color.ts';
+import { Camera } from './camera.ts';
+import {
+  mirrorCamera,
+  reflectionClipPlane,
+  reflectionTargetSize,
+  type ReflectionSize,
+} from './planarReflectionDraw.ts';
+
+export class PlanarReflection {
+  readonly camera = new Camera();
+  readonly clipPlane = new Float32Array(4);
+  readonly texture: WebGLTexture;
+
+  private readonly framebuffer: WebGLFramebuffer;
+  private readonly depth: WebGLRenderbuffer;
+  private readonly scale: number;
+  private readonly maxTextureSize: number;
+  private width = 0;
+  private height = 0;
+  /** Refilled per resize rather than allocated; `ensureSize` runs from `Renderer.resize`. */
+  private readonly size: ReflectionSize = { width: 0, height: 0 };
+  private planeY = 0;
+  private ready = false;
+  /**
+   * Set once the target proves it cannot be allocated, and never cleared.
+   *
+   * A reflection is an optimisation of appearance, not a requirement: a world without
+   * one still renders, and `WaterRenderer` already has a complete path for water that
+   * has no reflection to sample. So a device that refuses the allocation should lose the
+   * reflection and keep the scene, which is what this makes possible.
+   */
+  private unusable = false;
+
+  constructor(
+    gl: WebGL2RenderingContext,
+    scale: number,
+    maxTextureSize: number,
+    /** `RenderQuality.discardResolvedAttachments`, and see `end` for what it decides. */
+    private readonly discardResolved = true,
+  ) {
+    this.scale = scale;
+    this.maxTextureSize = maxTextureSize;
+
+    const texture = gl.createTexture();
+    if (texture === null) throw new Error('PlanarReflection: createTexture failed');
+    this.texture = texture;
+    gl.bindTexture(gl.TEXTURE_2D, texture);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+
+    const depth = gl.createRenderbuffer();
+    if (depth === null) throw new Error('PlanarReflection: createRenderbuffer failed');
+    this.depth = depth;
+
+    const framebuffer = gl.createFramebuffer();
+    if (framebuffer === null) throw new Error('PlanarReflection: createFramebuffer failed');
+    this.framebuffer = framebuffer;
+    gl.bindTexture(gl.TEXTURE_2D, null);
+  }
+
+  get viewProjection(): ReadonlyMat4 {
+    return this.camera.viewProjection;
+  }
+
+  get textureWidth(): number {
+    return this.width;
+  }
+
+  get textureHeight(): number {
+    return this.height;
+  }
+
+  /** True only after this target was rendered for the supplied water plane. */
+  isReadyFor(planeY: number): boolean {
+    return this.ready && Math.abs(this.planeY - planeY) < 1e-4;
+  }
+
+  /** Whether this target can be rendered into at all. See `unusable`. */
+  get usable(): boolean {
+    return !this.unusable;
+  }
+
+  /** Bind, clear and return the persistent camera mirrored across `planeY`. */
+  begin(
+    gl: WebGL2RenderingContext,
+    canvasWidth: number,
+    canvasHeight: number,
+    source: Camera,
+    planeY: number,
+    clearColor: Vec3,
+  ): Camera {
+    this.ensureSize(gl, canvasWidth, canvasHeight);
+    this.planeY = planeY;
+
+    /* Both chosen in `planarReflectionDraw.ts`, so both backends mirror the same world. */
+    const reflected = this.camera;
+    mirrorCamera(source, planeY, this.width / this.height, reflected);
+    reflectionClipPlane(source.position[1] ?? 0, planeY, this.clipPlane);
+
+    gl.bindFramebuffer(gl.FRAMEBUFFER, this.framebuffer);
+    gl.viewport(0, 0, this.width, this.height);
+    gl.clearColor(clearColor[0], clearColor[1], clearColor[2], 1);
+    gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT);
+    return reflected;
+  }
+
+  end(gl: WebGL2RenderingContext): void {
+    /*
+     * **The mirror's depth is finished with the moment the mirror is.**
+     *
+     * It is a `DEPTH_COMPONENT24` *renderbuffer*, so no shader can sample it — the same argument
+     * `SceneTarget.resolve` makes about the multisampled pair, and the same one the WebGPU
+     * backend acts on with `depthStoreOp: 'discard'`. This asymmetry between the two backends
+     * was the thing worth finding: one threw the attachment away and the other unbound and left
+     * it, so a tile-based GPU wrote a full drawing-buffer depth attachment out to memory every
+     * frame that reflected, for a reader that cannot exist. At 824x1830 that is 6.0 MB a frame
+     * a mirror, and the consumer draws two.
+     *
+     * **Before the unbind, deliberately.** `invalidateFramebuffer` acts on whatever is bound to
+     * the target it is given, so below the next line it would name the default framebuffer,
+     * which is the frame. `SceneTarget.resolve` carries the same warning for the same reason.
+     */
+    if (this.discardResolved) {
+      gl.invalidateFramebuffer(gl.FRAMEBUFFER, [gl.DEPTH_ATTACHMENT]);
+    }
+    gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+    this.ready = true;
+  }
+
+  dispose(gl: WebGL2RenderingContext): void {
+    gl.deleteFramebuffer(this.framebuffer);
+    gl.deleteRenderbuffer(this.depth);
+    gl.deleteTexture(this.texture);
+  }
+
+  /**
+   * Allocate the target now, rather than on the first frame that shows water.
+   *
+   * The target is a full drawing-buffer RGBA8 texture and a depth renderbuffer, so on
+   * a large display it is tens of megabytes. Allocated lazily, that landed in whichever
+   * frame first put water on screen — measured as 28% of a 62 ms frame the first time a
+   * character came within sight of it, which is a stall in the middle of play rather than
+   * during a load.
+   *
+   * The renderer calls this from `resize`, so the cost is paid where every other
+   * allocation of this size is paid: once, at the size the frame is about to be, while
+   * the loading plate is still up.
+   */
+  prepare(gl: WebGL2RenderingContext, canvasWidth: number, canvasHeight: number): void {
+    this.ensureSize(gl, canvasWidth, canvasHeight);
+  }
+
+  private ensureSize(gl: WebGL2RenderingContext, canvasWidth: number, canvasHeight: number): void {
+    // One refusal is enough. Retrying every resize would spend the same memory asking
+    // the same question and would put the warning back in the frame loop.
+    if (this.unusable) return;
+    /* Clamped by one shared factor rather than per axis; see `reflectionTargetSize`. */
+    const { width, height } = reflectionTargetSize(
+      canvasWidth,
+      canvasHeight,
+      this.scale,
+      this.maxTextureSize,
+      this.size,
+    );
+    if (width === this.width && height === this.height) return;
+
+    this.width = width;
+    this.height = height;
+    this.ready = false;
+    gl.bindTexture(gl.TEXTURE_2D, this.texture);
+    gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA8, width, height, 0, gl.RGBA, gl.UNSIGNED_BYTE, null);
+    gl.bindRenderbuffer(gl.RENDERBUFFER, this.depth);
+    gl.renderbufferStorage(gl.RENDERBUFFER, gl.DEPTH_COMPONENT24, width, height);
+    gl.bindFramebuffer(gl.FRAMEBUFFER, this.framebuffer);
+    gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, gl.TEXTURE_2D, this.texture, 0);
+    gl.framebufferRenderbuffer(gl.FRAMEBUFFER, gl.DEPTH_ATTACHMENT, gl.RENDERBUFFER, this.depth);
+    const status = gl.checkFramebufferStatus(gl.FRAMEBUFFER);
+    if (status !== gl.FRAMEBUFFER_COMPLETE) {
+      /*
+       * A lost context reports every attachment as unusable, so this check fires with
+       * FRAMEBUFFER_UNSUPPORTED (0x8CDD) for a reason that is not a programming error
+       * and cannot be fixed by the caller. Throwing there breaks the engine's own rule
+       * that only init fails loudly and the running frame never throws — and it broke it
+       * from `Renderer.resize`, a window listener, so the exception escaped into the
+       * page rather than into anything that could handle it.
+       *
+       * It was reported as an uncaught throw immediately after CONTEXT_LOST_WEBGL.
+       * A genuine misconfiguration still throws; a dead context is simply nothing to do.
+       */
+      if (gl.isContextLost()) return;
+
+      /*
+       * A refused allocation disables the reflection. It does not stop the frame.
+       *
+       * This used to throw, and the throw was reached from `Renderer.resize` — which a
+       * consumer calls every frame. On a device that cannot afford this target the
+       * result was not a missing reflection, it was an exception escaping the middle of
+       * every single frame: nothing after `resize` ran, the canvas kept whatever was
+       * last drawn, and the scene appeared to render as a fragment of itself. Reported
+       * from an iOS webview as a room with only its fire in it, on the one scene in the
+       * project that uses a planar reflection.
+       *
+       * It also broke the rule the block above already states, and states correctly:
+       * only initialisation fails loudly, and a running frame never throws. A driver
+       * refusing tens of megabytes on a memory-constrained device is the same category
+       * as a lost context — not a programming error, and not something the caller can
+       * fix by being more careful.
+       *
+       * Loud in the console, because a genuine misconfiguration must still be findable,
+       * and once rather than sixty times a second.
+       */
+      this.unusable = true;
+      this.ready = false;
+      console.warn(
+        `PlanarReflection: framebuffer incomplete (0x${status.toString(16)}) at ` +
+          `${width}x${height}; reflections are off for the rest of this session.`,
+      );
+      gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+      gl.bindRenderbuffer(gl.RENDERBUFFER, null);
+      gl.bindTexture(gl.TEXTURE_2D, null);
+      return;
+    }
+    gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+    gl.bindRenderbuffer(gl.RENDERBUFFER, null);
+    gl.bindTexture(gl.TEXTURE_2D, null);
+  }
+}