@driftengine/core 4.6.1 → 4.7.1

package/dist/render/pass.d.ts

@@ -34,7 +34,8 @@ import type { FrameResource } from './frame/index.ts';
  */
 export type PassDevice = {
     /**
-     * Pre-multiply a projection by this **if your WGSL was generated from GLSL**. Identity on WebGL2.
+     * Pre-multiply a projection by this **if your WGSL was generated from GLSL**. On WebGL2 it is
+     * the depth remap while that context draws reversed depth, and the identity where it cannot.
      *
      * A contributed pass takes its camera from its caller, so it never sees the corrected matrix the
      * renderer built for its own verbs. Without this it would have to copy four numbers — and a
@@ -55,7 +56,8 @@ export type PassDevice = {
      */
     readonly clipCorrection: Float32Array;
     /**
-     * Pre-multiply a projection by this **if you wrote your WGSL by hand**. Identity on WebGL2.
+     * Pre-multiply a projection by this **if you wrote your WGSL by hand**. On WebGL2 it is the same
+     * matrix as `clipCorrection`.
      *
      * The same matrix without the Y negation, because there is no generated negation to cancel.
      * Taking `clipCorrection` in a hand-written shader mirrors the picture vertically — and mirrors

package/dist/render/renderQuality.d.ts

@@ -88,6 +88,37 @@ export interface RenderQuality {
      * halved frame rate rather than a slightly slower one.
      */
     readonly maxDrawingBufferPixels: number;
+    /**
+     * How many times a frame may change material, on a backend that keeps a slot for each.
+     *
+     * **WebGPU spends a slot of a uniform ring per material change and skips every draw past it**,
+     * because a buffer rewritten between two draws would hand both of them its last contents. So
+     * this is a ceiling on what a frame can show, not a performance hint: a scene that needs more
+     * loses whatever it asks for last — measured on a bought city of 1,139 materials, whose street
+     * spends some nine hundred and whose river's planar mirror spends the rest twice over.
+     *
+     * **What it costs is memory, paid at construction**: a slot is the fragment block twice over,
+     * staging and buffer, so 7 to 13 KB depending on the permutation built — 1,024 is 7 to 13 MB
+     * and 2,048 twice that. Hence a default that suits most scenes and an option for the one that
+     * measures past it, rather than a number every consumer pays for. WebGL2 writes each uniform
+     * into the command stream and keeps no ring, so there it is read and does nothing, and its
+     * budget line reports no ceiling. What would make it wrong is a scene that switches material
+     * every draw, which no ring answers: many copies of one mesh want one instanced draw.
+     */
+    readonly materialChangesPerFrame: number;
+    /**
+     * How many draws a frame may make, on a backend that keeps a uniform slot for each — the main
+     * pass and the shadow passes each hold this many.
+     *
+     * **The same shape as `materialChangesPerFrame` and the same failure**: WebGPU skips every draw
+     * past the ring. A frame that draws two hundred pays for two hundred whatever this says, so
+     * raising it costs no bandwidth; it costs memory at construction, 1,540 bytes a slot — 6 MB at
+     * the default 4,096. A city whose street spends three and a half thousand and whose river
+     * mirrors that street spends more than the default, and a scene in the ordinary band of two to
+     * ten thousand draws can meet it. WebGL2 keeps no ring and reads this without effect. What would
+     * make it wrong is a frame that approaches it on the CPU first, which four thousand draws can.
+     */
+    readonly drawsPerFrame: number;
     readonly directionalShadows: boolean;
     readonly pointShadows: boolean;
     /**
@@ -564,10 +595,10 @@ export interface RenderQuality {
      * the output size with no upscaling, which is a temporal antialiaser with a better neighbourhood
      * rule than `temporalAa`'s. A sentinel that collided with it would make that unaskable.
      *
-     * The range is 1.3 to 2 and a value inside it is clamped to the end it is nearest. Below 1.3 the
-     * render saves less than a third of the fragment work and the resolve's own cost eats it; above 2
-     * the render is a quarter of the output and no reconstruction holds an edge through that. A
-     * negative number is off, not a clamp to the bottom: it cannot mean "a little".
+     * The range is 1.3 to 2 and a positive value outside it is clamped to the end it is nearest.
+     * Below 1.3 the render saves less than a third of the fragment work and the resolve's own cost
+     * eats it; above 2 the render is a quarter of the output and no reconstruction holds an edge
+     * through that. A negative number is off, not a clamp to the bottom: it cannot mean "a little".
      *
      * **What it needs from you.** A `createMover()` per moving object, passed with that object's
      * draws where `drawMesh` takes last frame's matrix — the renderer keeps last frame's model and,
@@ -810,6 +841,10 @@ export interface RenderQuality {
 /** Callers override only the levers selected by a future settings profile. */
 export type RenderQualityOptions = Partial<RenderQuality>;
 export declare const MAX_SHADOW_FILTER_TAPS = 12;
+/** The most material changes a frame may be built to hold. See `materialChangesPerFrame`. */
+export declare const MAX_MATERIAL_CHANGES_PER_FRAME = 8192;
+/** The most draws a frame may be built to hold. See `drawsPerFrame`. */
+export declare const MAX_DRAWS_PER_FRAME = 65536;
 export declare const MAX_WATER_REFLECTION_FILTER_TAPS = 9;
 export declare const POINT_SHADOW_FADE_START = 0.35;
 export declare const DIRECTIONAL_SHADOW_FADE_START = 0.65;

package/dist/render/renderQuality.js

@@ -4,6 +4,10 @@ import { MAX_GLOBAL_MEDIUM_STEPS } from './globalMedium.js';
 import { MAX_POINT_LIGHTS } from './lightBudget.js';
 import { PREFILTER_SAMPLE_COUNTS } from './prefilterEnvMap.js';
 export const MAX_SHADOW_FILTER_TAPS = 12;
+/** The most material changes a frame may be built to hold. See `materialChangesPerFrame`. */
+export const MAX_MATERIAL_CHANGES_PER_FRAME = 8192;
+/** The most draws a frame may be built to hold. See `drawsPerFrame`. */
+export const MAX_DRAWS_PER_FRAME = 65536;
 export const MAX_WATER_REFLECTION_FILTER_TAPS = 9;
 export const POINT_SHADOW_FADE_START = 0.35;
 export const DIRECTIONAL_SHADOW_FADE_START = 0.65;
@@ -46,6 +50,8 @@ export const DEFAULT_RENDER_QUALITY = Object.freeze({
      * if it is above where people actually are. Consumers wanting the pixels set it to 0.
      */
     maxDrawingBufferPixels: 12_000_000,
+    materialChangesPerFrame: 1024,
+    drawsPerFrame: 4096,
     directionalShadows: true,
     pointShadows: true,
     /* The engine's own budgets, which the renderer lowers per device when it has to. */
@@ -194,6 +200,8 @@ export function resolveRenderQuality(options = {}) {
         pointLightFalloff: options.pointLightFalloff ?? DEFAULT_RENDER_QUALITY.pointLightFalloff,
         maxDevicePixelRatio: options.maxDevicePixelRatio ?? DEFAULT_RENDER_QUALITY.maxDevicePixelRatio,
         maxDrawingBufferPixels: options.maxDrawingBufferPixels ?? DEFAULT_RENDER_QUALITY.maxDrawingBufferPixels,
+        materialChangesPerFrame: options.materialChangesPerFrame ?? DEFAULT_RENDER_QUALITY.materialChangesPerFrame,
+        drawsPerFrame: options.drawsPerFrame ?? DEFAULT_RENDER_QUALITY.drawsPerFrame,
         directionalShadows: options.directionalShadows ?? DEFAULT_RENDER_QUALITY.directionalShadows,
         pointShadows: options.pointShadows ?? DEFAULT_RENDER_QUALITY.pointShadows,
         /* Whole slots, at least one, never above what the shader is written for: these two are
@@ -260,6 +268,17 @@ export function resolveRenderQuality(options = {}) {
     // Zero is legal and means uncapped, so this is the non-negative check rather than
     // the positive one.
     nonNegative('maxDrawingBufferPixels', quality.maxDrawingBufferPixels);
+    positiveInteger('materialChangesPerFrame', quality.materialChangesPerFrame);
+    if (quality.materialChangesPerFrame > MAX_MATERIAL_CHANGES_PER_FRAME) {
+        throw new Error(`materialChangesPerFrame is ${quality.materialChangesPerFrame}, and at most ` +
+            `${MAX_MATERIAL_CHANGES_PER_FRAME} are kept: past that the ring is a hundred megabytes, ` +
+            'and a frame changing material that often wants its draws batched instead.');
+    }
+    positiveInteger('drawsPerFrame', quality.drawsPerFrame);
+    if (quality.drawsPerFrame > MAX_DRAWS_PER_FRAME) {
+        throw new Error(`drawsPerFrame is ${quality.drawsPerFrame}, and at most ${MAX_DRAWS_PER_FRAME} are kept: ` +
+            'past that the rings are a hundred megabytes, and a frame drawing that often wants instancing.');
+    }
     positiveInteger('directionalShadowMapSize', quality.directionalShadowMapSize);
     positiveInteger('pointShadowFaceSize', quality.pointShadowFaceSize);
     positiveInteger('shadowFilterTaps', quality.shadowFilterTaps);

package/dist/render/rendererHarness.js

@@ -123,7 +123,15 @@ export function recordingGl(options = {}) {
                and a small answer is read as a device that cannot do the thing. */
             return 4096;
         },
-        getExtension: (name) => (extensions.has(String(name)) ? {} : null),
+        getExtension: (name) => {
+            if (!extensions.has(String(name)))
+                return null;
+            /* Clip control is called as well as asked for, so its object has to carry the call. */
+            if (name === 'EXT_clip_control') {
+                return { LOWER_LEFT_EXT: 0x8ca1, ZERO_TO_ONE_EXT: 0x935f, clipControlEXT: () => undefined };
+            }
+            return {};
+        },
         getShaderParameter: () => true,
         /*
          * A shader remembers its own source, and a program remembers its fragment one, so a link can

package/dist/world/freeze.d.ts

@@ -23,7 +23,7 @@
  * What freezing needs of a world.
  *
  * Taken as a parameter rather than imported, on `AGENTS.md`'s rule: core has no entity store and a
- * consumer may be holding one of several. Six methods, all of which any store can answer.
+ * consumer may be holding one of several. Five methods, all of which any store can answer.
  */
 export interface FreezableWorld {
     /** Every entity whose home is this cell, live or not. */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@driftengine/core",
-  "version": "4.6.1",
-  "description": "DriftEngine reusable browser 3D runtime",
+  "version": "4.7.1",
+  "description": "The runtime of DriftEngine, a WebGPU game engine with a WebGL2 fallback: renderer, loop, input, cameras, scene graph and physics",
   "license": "Apache-2.0",
   "type": "module",
   "main": "./dist/index.js",
@@ -29,8 +29,8 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@driftengine/drft": "4.6.1",
-    "@driftengine/physics": "4.6.1",
+    "@driftengine/drft": "4.7.1",
+    "@driftengine/physics": "4.7.1",
     "gl-matrix": "^3.4.3"
   },
   "author": "Drift Technologies",
@@ -39,7 +39,7 @@
     "url": "git+https://github.com/drftrun/driftengine.git",
     "directory": "packages/core"
   },
-  "homepage": "https://github.com/drftrun/driftengine#readme",
+  "homepage": "https://driftengine.dev/docs",
   "bugs": "https://github.com/drftrun/driftengine/issues",
   "keywords": [
     "driftengine",
@@ -51,7 +51,11 @@
     "webgl2",
     "scene-graph",
     "game-engine",
-    "game-loop"
+    "game-loop",
+    "gamedev",
+    "webgpu-game-engine",
+    "physics",
+    "rigid-body"
   ],
   "engines": {
     "node": ">=22.12.0"
@@ -63,8 +67,8 @@
     "prepack": "node ../../scripts/build.mjs @driftengine/core"
   },
   "devDependencies": {
-    "@driftengine/nav": "4.6.1",
-    "@driftengine/network": "4.6.1",
-    "@driftengine/texture": "4.6.1"
+    "@driftengine/nav": "4.7.1",
+    "@driftengine/network": "4.7.1",
+    "@driftengine/texture": "4.7.1"
   }
 }

package/scripts/png.d.mts

@@ -1,4 +1,4 @@
-/** What a decoded PNG is: row-major 8-bit samples, three or four to a pixel. */
+/** What a decoded PNG is: row-major 8-bit samples, one to four to a pixel. */
 export interface DecodedPng {
   readonly width: number;
   readonly height: number;

package/scripts/png.mjs

@@ -2,10 +2,11 @@
  * Enough of a PNG reader to compare two frames, with no dependency.
  *
  * A screenshot arrives as 8-bit RGBA, filter method 0, not interlaced, which is what every
- * browser produces. A bought model's maps also arrive as 8-bit grey, grey with alpha and RGB, and
- * the baker and the native host read those through here too. Anything else — a palette, sixteen
- * bits, interlacing — is refused by name rather than guessed at, because a reader that quietly
- * mis-decodes produces pixel differences that look like a rendering change.
+ * browser produces, and is read on a path that copies nothing. A bought model's maps arrive as
+ * every other non-interlaced kind — grey, grey with alpha, RGB and RGBA at eight or sixteen bits,
+ * palettes and greys at one to eight — and the baker and the native host read those through here
+ * too, widened to 8-bit samples. Interlacing is refused by name rather than guessed at, because a
+ * reader that quietly mis-decodes produces pixel differences that look like a rendering change.
  *
  * `zlib` is Node's own, so this costs nothing to have.
  */
@@ -14,14 +15,28 @@ import { readFileSync } from 'node:fs';
 
 const SIGNATURE = 0x89504e47;
 
-/** `{ width, height, channels, pixels }`, pixels being row-major 8-bit samples. */
+/** Samples a pixel, by colour type. */
+const SAMPLES = { 0: 1, 2: 3, 3: 1, 4: 2, 6: 4 };
+/** The bit depths the specification allows for each colour type. */
+const DEPTHS = { 0: [1, 2, 4, 8, 16], 2: [8, 16], 3: [1, 2, 4, 8], 4: [8, 16], 6: [8, 16] };
+
+/**
+ * `{ width, height, channels, pixels }`, pixels being row-major 8-bit samples.
+ *
+ * A palette widens to RGB, or to RGBA where it carries `tRNS`; a grey or RGB image with a `tRNS`
+ * key gains an alpha channel, nought at that one value; sixteen bits keep the high byte; a grey
+ * below eight bits is scaled to the full byte, so one bit is 0 or 255.
+ */
 export function decodePng(bytes) {
   if (bytes.length < 8 || bytes.readUInt32BE(0) !== SIGNATURE) throw new Error('not a PNG');
 
   let at = 8;
   let width = 0;
   let height = 0;
-  let channels = 0;
+  let depth = 0;
+  let colorType = 0;
+  let palette = null;
+  let transparency = null;
   const parts = [];
 
   while (at + 8 <= bytes.length) {
@@ -31,20 +46,22 @@ export function decodePng(bytes) {
     if (type === 'IHDR') {
       width = body.readUInt32BE(0);
       height = body.readUInt32BE(4);
-      const depth = body[8];
-      const colorType = body[9];
+      depth = body[8];
+      colorType = body[9];
       const interlace = body[12];
-      if (depth !== 8) throw new Error(`bit depth ${depth}, only 8 is handled`);
       if (interlace !== 0) throw new Error('interlaced PNG, not handled');
-      /*
-       * Grey, grey with alpha, RGB and RGBA — every 8-bit type but a palette. A bought model's
-       * single-channel maps are greyscale, and refusing them left a baker's texture cap unable to
-       * shrink a third of one scene's maps. A palette needs `PLTE` read, and nothing has asked.
-       */
-      channels = { 0: 1, 4: 2, 2: 3, 6: 4 }[colorType] ?? 0;
-      if (channels === 0) {
-        throw new Error(`colour type ${colorType}, only 0, 2, 4 and 6 are handled`);
+      if (SAMPLES[colorType] === undefined) {
+        throw new Error(`colour type ${colorType}, which is not a PNG colour type`);
       }
+      if (!DEPTHS[colorType].includes(depth)) {
+        throw new Error(
+          `bit depth ${depth} for colour type ${colorType}, which PNG does not allow`,
+        );
+      }
+    } else if (type === 'PLTE') {
+      palette = body;
+    } else if (type === 'tRNS') {
+      transparency = body;
     } else if (type === 'IDAT') {
       parts.push(body);
     } else if (type === 'IEND') {
@@ -54,15 +71,21 @@ export function decodePng(bytes) {
     at += 12 + length;
   }
   if (width === 0 || height === 0) throw new Error('no IHDR');
+  if (colorType === 3 && palette === null) throw new Error('a palette PNG with no PLTE');
 
+  const samples = SAMPLES[colorType];
+  const bits = samples * depth;
+  /* What a filter steps back by: a whole pixel, or one byte where a pixel is smaller than one. */
+  const step = Math.max(1, bits >> 3);
+  const stride = (width * bits + 7) >> 3;
   const raw = inflateSync(Buffer.concat(parts));
-  const stride = width * channels;
-  const pixels = Buffer.alloc(stride * height);
+  const scan = Buffer.alloc(stride * height);
 
   /*
    * Un-filtering, which is the whole of the format that is not zlib. Each row states one of five
-   * predictors and the residual against it; `a` is the sample one pixel left, `b` the one above,
-   * `c` the one above and left, and all three are zero outside the image rather than wrapped.
+   * predictors and the residual against it; `a` is the byte one pixel left, `b` the one above,
+   * `c` the one above and left, and all three are zero outside the image rather than wrapped. It
+   * runs on the packed bytes, before a sub-byte pixel is unpacked, which is what the format says.
    */
   for (let y = 0; y < height; y++) {
     const filter = raw[y * (stride + 1)];
@@ -70,9 +93,9 @@ export function decodePng(bytes) {
     const to = y * stride;
     for (let i = 0; i < stride; i++) {
       const value = raw[from + i];
-      const a = i >= channels ? pixels[to + i - channels] : 0;
-      const b = y > 0 ? pixels[to - stride + i] : 0;
-      const c = i >= channels && y > 0 ? pixels[to - stride + i - channels] : 0;
+      const a = i >= step ? scan[to + i - step] : 0;
+      const b = y > 0 ? scan[to - stride + i] : 0;
+      const c = i >= step && y > 0 ? scan[to - stride + i - step] : 0;
       let restored;
       if (filter === 0) restored = value;
       else if (filter === 1) restored = value + a;
@@ -80,10 +103,61 @@ export function decodePng(bytes) {
       else if (filter === 3) restored = value + ((a + b) >> 1);
       else if (filter === 4) restored = value + paeth(a, b, c);
       else throw new Error(`row ${y} states filter ${filter}, which is not a PNG filter`);
-      pixels[to + i] = restored & 0xff;
+      scan[to + i] = restored & 0xff;
     }
   }
 
+  /* Eight bits of grey, grey and alpha, RGB or RGBA with no key: the scan is the pixels. */
+  if (depth === 8 && colorType !== 3 && transparency === null) {
+    return { width, height, channels: samples, pixels: scan };
+  }
+  return widen(scan, width, height, depth, colorType, stride, palette, transparency);
+}
+
+/** A sample at its own precision: pixel `x`, sample `s` of row `y`. */
+function sampleAt(scan, stride, depth, samples, y, x, s) {
+  const index = x * samples + s;
+  if (depth === 16) return scan.readUInt16BE(y * stride + index * 2);
+  if (depth === 8) return scan[y * stride + index];
+  const bit = index * depth;
+  return (scan[y * stride + (bit >> 3)] >> (8 - depth - (bit & 7))) & ((1 << depth) - 1);
+}
+
+/** Everything the 8-bit path does not take, widened to 8-bit samples. */
+function widen(scan, width, height, depth, colorType, stride, palette, transparency) {
+  const samples = SAMPLES[colorType];
+  const paletted = colorType === 3;
+  /* A key in tRNS is one sample value a channel, at the image's own depth. */
+  const keyed = !paletted && transparency !== null && (colorType === 0 || colorType === 2);
+  const channels = paletted ? (transparency === null ? 3 : 4) : samples + (keyed ? 1 : 0);
+  const key = keyed
+    ? [0, 1, 2].slice(0, samples).map((s) => transparency.readUInt16BE(s * 2))
+    : null;
+  const to8 =
+    depth === 16 ? (v) => v >> 8 : depth === 8 ? (v) => v : (v) => (v * 255) / ((1 << depth) - 1);
+  const entries = paletted ? palette.length / 3 : 0;
+  const pixels = Buffer.alloc(width * height * channels);
+  let out = 0;
+  for (let y = 0; y < height; y++) {
+    for (let x = 0; x < width; x++) {
+      if (paletted) {
+        const index = sampleAt(scan, stride, depth, 1, y, x, 0);
+        if (index >= entries) throw new Error(`palette index ${index} past a PLTE of ${entries}`);
+        pixels[out++] = palette[index * 3];
+        pixels[out++] = palette[index * 3 + 1];
+        pixels[out++] = palette[index * 3 + 2];
+        if (channels === 4) pixels[out++] = index < transparency.length ? transparency[index] : 255;
+        continue;
+      }
+      let matches = key !== null;
+      for (let s = 0; s < samples; s++) {
+        const value = sampleAt(scan, stride, depth, samples, y, x, s);
+        if (key !== null && value !== key[s]) matches = false;
+        pixels[out++] = to8(value);
+      }
+      if (keyed) pixels[out++] = matches ? 0 : 255;
+    }
+  }
   return { width, height, channels, pixels };
 }
 

package/src/render/backend/budget.ts

@@ -49,6 +49,12 @@ export interface BudgetCounter extends BudgetLine {
   ask(): void;
   /** One of them was refused, and the frame is marked. */
   drop(): void;
+  /**
+   * The ceiling, where it is a construction-time option and not known when the line is declared.
+   * Called at construction, once; a line keeps the place it was declared in, which is the order a
+   * report reads in.
+   */
+  limit(ceiling: number): void;
 }
 
 class Line implements BudgetCounter {
@@ -57,10 +63,14 @@ class Line implements BudgetCounter {
 
   constructor(
     readonly name: string,
-    readonly ceiling: number | null,
+    public ceiling: number | null,
     private readonly budget: FrameBudget,
   ) {}
 
+  limit(ceiling: number): void {
+    this.ceiling = ceiling;
+  }
+
   /** One more of this thing was asked for, whether or not it will fit. */
   ask(): void {
     this.used += 1;

package/src/render/backend/webgl2/renderer.ts

@@ -2093,14 +2093,20 @@ export class WebGL2Renderer implements RendererApi {
    */
   registerPass(definition: PassDefinition): PassHandle {
     const handle = registerIn(this.passes, definition);
-    /* Identity: this backend's clip space is the one the projections are built for. */
-    /* Both are identity here: this backend runs the GLSL natively, so there is nothing to
-       correct and nothing a generator has flipped. */
+    /*
+     * Both the same here: this backend runs the GLSL natively, so no generator has flipped
+     * anything. **What they carry is the depth remap whenever this context draws reversed**, and
+     * they were the identity until a splat capture was drawn among meshes on this backend: the
+     * renderer's own draws go through `GL_DEPTH_REMAP` (`sceneMatrix`), a pass's projection did
+     * not, so a pass wrote conventional depth into a reversed buffer and a splat behind a post was
+     * drawn over it. Identity where clip control is missing and depth stays conventional.
+     */
+    const correction = this.reversedDepth ? GL_DEPTH_REMAP : IDENTITY_CLIP;
     this.passDevice ??= {
       backend: 'webgl2',
       gl: this.gl,
-      clipCorrection: IDENTITY_CLIP,
-      depthCorrection: IDENTITY_CLIP,
+      clipCorrection: correction,
+      depthCorrection: correction,
     };
     if (definition.prepare !== undefined) this.preparingPasses++;
     definition.init?.(this.passDevice);
@@ -4746,17 +4752,14 @@ export class WebGL2Renderer implements RendererApi {
    * `endPlanarReflection`; the next water draw samples the completed target.
    */
   /**
-   * **This is a water feature, not a renderer one, and the name hides that.**
-   *
-   * The target is allocated only when `water` *and* `waterReflections` are both on, and the
-   * only thing that samples it is `WaterRenderer`. So a scenario whose ground is a mesh slab
-   * with `drawFilm` patches over it, which is what a wet street is, cannot mirror the scene
-   * into it however it calls this. Reported from outside after being attempted, which is the
-   * cost of a name that promises more than the wiring does.
+   * **Two things sample the target: water, and a wet film.** It is allocated when `water` and
+   * `waterReflections` are both on, or when `RenderQuality.planarReflections` asks for it in a
+   * scene with no water, and `drawFilm` reads it through `FilmOptions.reflectionStrength` for a
+   * film on the plane it was rendered for. This said the pass was water-only after both of those
+   * had landed, which is how a stale limitation outlives its cause: it read as a decision.
    *
-   * What is available to a surface that is not water: `bakeReflectionProbe`, which is a room
-   * rather than a mirror, and `drawFilm`'s sheen, which is iridescence rather than reflection.
-   * Neither is a substitute for a mirrored pass and this comment is not pretending otherwise.
+   * A surface on any other plane, or that is not a film, reflects a probe
+   * (`bakeReflectionProbe`), which is a room rather than a mirror.
    */
   /* Like `bakeReflectionProbe`, this re-enters the **mesh pass only**: anything a scene draws
      after the world, particles, light volumes, the sky, is missing from the mirror unless it is
@@ -8447,9 +8450,9 @@ export class WebGL2Renderer implements RendererApi {
    * tarmac at night by bisection twice, at 0.7 and again at 0.24, and landed on **0.15 to
    * 0.18**. Start there rather than repeating the search.
    *
-   * There is no mirror term here to raise instead. A surface that should reflect the scene
-   * rather than shimmer needs a planar pass, and `beginPlanarReflection` is water-only; see the
-   * comment on it. Splitting the two is an open request from outside and is not built.
+   * The mirror is a separate dial: `FilmOptions.reflectionStrength` shows the planar reflection
+   * a frame rendered for the film's plane, weighted by the viewing angle. See
+   * `beginPlanarReflection` for when that target exists.
    */
   drawFilm(
     mesh: Mesh,