@driftengine/core 4.8.6 → 4.9.0

package/src/render/reflectionSurfaceTargets.ts

@@ -0,0 +1,105 @@
+/**
+ * The frame's materials' reflection maps on WebGL2: two half-float textures on the scene's own
+ * framebuffer, beside its colour, written by the opaque lit draws as they are drawn. What the two
+ * hold is `shaders/flat/reflectionSurface.ts`'s to say; this is where they live on this backend.
+ *
+ * **Written in the frame's own pass, where WebGPU replays the draws in a second one.** A WebGL2
+ * program writing an output its framebuffer has no buffer enabled for loses that output and nothing
+ * else, so the maps are enabled around an opaque lit draw (`on`, `off`) and stay disabled for every
+ * other: the sky, glass, text and particles write no material, and a draw into a mirror, a probe or
+ * a capture is into another framebuffer, whose draw buffers this never touches.
+ *
+ * **Detached once the trace has read them** (`detach`), because the resolve then draws into the
+ * scene's framebuffer while sampling both, and a texture sampled while attached to the framebuffer
+ * being drawn is a feedback loop whether or not its buffer is enabled. `begin` attaches them again.
+ */
+const ZERO = new Float32Array(4);
+
+export class ReflectionSurfaceTargets {
+  private probe: WebGLTexture | null = null;
+  private tint: WebGLTexture | null = null;
+  private width = 0;
+  private height = 0;
+  private readonly all: number[];
+  private readonly colourAlone: number[];
+
+  constructor(private readonly gl: WebGL2RenderingContext) {
+    this.all = [gl.COLOR_ATTACHMENT0, gl.COLOR_ATTACHMENT1, gl.COLOR_ATTACHMENT2];
+    this.colourAlone = [gl.COLOR_ATTACHMENT0];
+  }
+
+  /** The environment as the frame shows it, and the roughness in alpha. */
+  get probeTexture(): WebGLTexture | null {
+    return this.probe;
+  }
+
+  /** What a found reflection is multiplied by. */
+  get tintTexture(): WebGLTexture | null {
+    return this.tint;
+  }
+
+  /**
+   * At the frame's start, with the scene's framebuffer bound: both at its size, attached, cleared to
+   * nothing reflected, and left disabled.
+   */
+  begin(width: number, height: number): void {
+    const { gl } = this;
+    if (this.probe === null || this.width !== width || this.height !== height) {
+      this.release();
+      this.probe = this.make(width, height);
+      this.tint = this.make(width, height);
+      this.width = width;
+      this.height = height;
+    }
+    gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT1, gl.TEXTURE_2D, this.probe, 0);
+    gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT2, gl.TEXTURE_2D, this.tint, 0);
+    gl.drawBuffers(this.all);
+    gl.clearBufferfv(gl.COLOR, 1, ZERO);
+    gl.clearBufferfv(gl.COLOR, 2, ZERO);
+    gl.drawBuffers(this.colourAlone);
+  }
+
+  /** Around an opaque lit draw into the frame: its two extra outputs land. */
+  on(): void {
+    this.gl.drawBuffers(this.all);
+  }
+
+  /** And after it: only the colour does. */
+  off(): void {
+    this.gl.drawBuffers(this.colourAlone);
+  }
+
+  /** With the scene's framebuffer bound, after the trace has read them: see the header. */
+  detach(): void {
+    const { gl } = this;
+    gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT1, gl.TEXTURE_2D, null, 0);
+    gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT2, gl.TEXTURE_2D, null, 0);
+  }
+
+  dispose(): void {
+    this.release();
+  }
+
+  private make(width: number, height: number): WebGLTexture {
+    const { gl } = this;
+    const texture = gl.createTexture();
+    if (texture === null) throw new Error('ReflectionSurfaceTargets: createTexture failed');
+    /* Unit 0, chosen rather than inherited, for the reason `SsrPass` gives. */
+    gl.activeTexture(gl.TEXTURE0);
+    gl.bindTexture(gl.TEXTURE_2D, texture);
+    gl.texStorage2D(gl.TEXTURE_2D, 1, gl.RGBA16F, width, height);
+    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);
+    gl.bindTexture(gl.TEXTURE_2D, null);
+    return texture;
+  }
+
+  private release(): void {
+    if (this.probe !== null) this.gl.deleteTexture(this.probe);
+    if (this.tint !== null) this.gl.deleteTexture(this.tint);
+    this.probe = null;
+    this.tint = null;
+  }
+}

package/src/render/renderQuality.ts

@@ -1,5 +1,6 @@
 /** Construction-time GPU quality controls shared by every renderer resource. */
 
+import type { FrameReflections } from './frameReflections.ts';
 import { MAX_AREA_LIGHTS } from './areaLights.ts';
 import { MAX_GLOBAL_MEDIUM_STEPS } from './globalMedium.ts';
 import { MAX_POINT_LIGHTS } from './lightBudget.ts';
@@ -26,8 +27,14 @@ import { PREFILTER_SAMPLE_COUNTS } from './prefilterEnvMap.ts';
  * red where `srgb` clips each channel and turns its core pink and wide. It is the curve a ported
  * game's own resolve applied — for a port that has to match one — and it has none of ACES's toe or
  * desaturation. See `HIGHLIGHT_SHOULDER_GLSL` for the arithmetic.
+ *
+ * `filmic` is a film curve shaped by five numbers — a slope, a toe, a shoulder and how far black
+ * and white clip — that holds a mid grey of 0.18 at 0.18 where `aces` gives about 0.11, so a look
+ * graded against such a curve is matched by its numbers (`setFilmicCurve`) rather than by a lookup
+ * table. Applied by the composite alone, so it needs `screenEffects` and `hdrScene`; without them
+ * every pass grades with `aces` and the renderer says so once. See `filmicCurve.ts`.
  */
-export type OutputTransform = 'none' | 'srgb' | 'aces' | 'shoulder';
+export type OutputTransform = 'none' | 'srgb' | 'aces' | 'shoulder' | 'filmic';
 
 /**
  * The three settings whose accepted values are a closed set, written as one.
@@ -219,13 +226,14 @@ export interface RenderQuality {
    * **`'pre-integrated'`, the default**: the lit stage's fit alone — a terminator softened and
    * reddened by the surface's curvature, light through thin parts, a penumbra each channel crosses
    * as far as it travels — at no cost beyond the skin pipeline itself. **`'screen-space'`** adds
-   * Burley's blur in the picture as well: a skin draw writes its diffuse to a target of its own (it
-   * is drawn twice to do so), which is spread across the pixels its scatter distance covers and
-   * added back before anything blended is drawn, so light crosses a shadow's edge and a nostril's
-   * rim in the picture rather than in a fit. See `skinBlur.ts`.
-   *
-   * Construction-time: two half-float targets the size of the frame, and a multisampled one under
-   * multisampling, made at the first skin draw. It needs the composite (`screenEffects`), which is
+   * Burley's blur in the picture as well: a skin draw writes the light its diffuse is made of to a
+   * target of its own and its colour to another (it is drawn three times to do so), and the light is
+   * spread across the pixels its scatter distance covers, multiplied by the colour and added back
+   * before anything blended is drawn, so light crosses a shadow's edge and a nostril's rim in the
+   * picture rather than in a fit. See `skinBlur.ts`.
+   *
+   * Construction-time: three half-float targets the size of the frame, and two multisampled ones
+   * under multisampling, made at the first skin draw. It needs the composite (`screenEffects`), which is
    * where the frame is still linear light to add to; without one, skin is pre-integrated and the
    * renderer says so once. What would make the default wrong is a close-up face that reads as wax
    * at a shadow's edge — that is what the blur is for.
@@ -354,6 +362,18 @@ export interface RenderQuality {
    * eight-bit and this buys only the consistent grading.
    */
   readonly hdrScene: boolean;
+  /**
+   * Ask for a high dynamic range display: a canvas whose highlights run past paper white to as
+   * far as the display allows, where it reports one. Off by default.
+   *
+   * **Asked for, not assumed.** It needs WebGPU, a display reporting a high dynamic range, and a
+   * composite that holds the light to give it (`screenEffects` and `hdrScene`); where any of those
+   * is missing the frame goes out as it always did and the renderer says which in
+   * `displayRangeReason`. `displayRange` is the answer a game reads to choose a look graded for the
+   * output it got. `setDisplayLuminance` sets how far above paper white the highlights may reach.
+   * WebGL2 has no extended-range canvas to draw into, so there it is always the standard range.
+   */
+  readonly highDynamicRange: boolean;
   /** Camera-depth water tint and scattering across every visible pass. */
   readonly underwaterAtmosphere: boolean;
   /** Procedural noise octaves evaluated by plume shaders. */
@@ -521,14 +541,14 @@ export interface RenderQuality {
    */
   readonly sceneSamples: number;
   /**
-   * Camera motion blur, 0 to 1. Off by default.
+   * Motion blur, 0 to 1. Off by default.
    *
-   * Camera rather than per-object, and that is a decision rather than a stage. Per-object
-   * blur needs a velocity buffer: every mesh writing its own screen-space motion into a
-   * second render target, so a second set of matrices per draw and a wider G-buffer, which
-   * is a structural change to a forward renderer that writes one colour target. Camera blur
-   * needs only the previous view-projection, which is one matrix, and it covers the case
-   * that actually matters — a camera whipping round a turntable or through a world.
+   * By the camera's motion everywhere, and **by each drawn object's own motion where a
+   * reconstruction draws one** (DriftTR, WebGPU): a mover's pixels smear along its path while a
+   * still stage stays sharp. Elsewhere a velocity buffer would be every mesh writing its motion into
+   * a second target — a structural change to a forward renderer — so those frames blur by the
+   * camera alone, which needs only the previous view-projection, and say so once when a draw names
+   * where it was. `setCameraMotionBlur` is the per-frame dial and the longest smear.
    *
    * Runs inside the composite pass, so it costs a depth sample and eight taps on the pixels
    * that are moving and nothing on a still frame. Needs `screenEffects`, since without the
@@ -579,6 +599,18 @@ export interface RenderQuality {
    * Needs `screenEffects`, since the resolve composites over the finished scene.
    */
   readonly orderIndependent: boolean;
+  /**
+   * Every opaque lit surface reflects the frame by its own material: a ray marched against the
+   * frame's depth swaps the probes' share of each pixel for what it finds, at the pixel's own
+   * roughness and reflectance, and a surface past `maxRoughness` keeps the probes alone. Off by
+   * default; `true` for the defaults, or the numbers. See `frameReflections.ts`.
+   *
+   * Needs `screenEffects` and `hdrScene`, since the swap is made in scene light, and a frame of one
+   * sample; it says once where it cannot be drawn. What it costs on WebGPU is every opaque lit draw
+   * a second time without its lamps, into two half-float targets, and a march per reflective pixel;
+   * on WebGL2 the same two targets, written beside the colour by the opaque lit draws themselves.
+   */
+  readonly screenSpaceReflections: boolean | FrameReflections;
   /**
    * Depth of field: how wide the blur may reach, as a fraction of the frame's height. Off by
    * default.
@@ -963,9 +995,11 @@ export const DEFAULT_RENDER_QUALITY: Readonly<RenderQuality> = Object.freeze({
   sceneSamples: 1,
   planarReflections: false,
   hdrScene: false,
+  highDynamicRange: false,
   cameraMotionBlur: 0,
   temporalAa: false,
   orderIndependent: false,
+  screenSpaceReflections: false,
   depthOfField: 0,
   reconstruction: 0,
   indirectLight: false,
@@ -1125,12 +1159,15 @@ export function resolveRenderQuality(options: RenderQualityOptions = {}): Readon
     ),
     planarReflections: options.planarReflections ?? DEFAULT_RENDER_QUALITY.planarReflections,
     hdrScene: options.hdrScene ?? DEFAULT_RENDER_QUALITY.hdrScene,
+    highDynamicRange: options.highDynamicRange ?? DEFAULT_RENDER_QUALITY.highDynamicRange,
     cameraMotionBlur: Math.min(
       1,
       Math.max(0, options.cameraMotionBlur ?? DEFAULT_RENDER_QUALITY.cameraMotionBlur),
     ),
     temporalAa: options.temporalAa ?? DEFAULT_RENDER_QUALITY.temporalAa,
     orderIndependent: options.orderIndependent ?? DEFAULT_RENDER_QUALITY.orderIndependent,
+    screenSpaceReflections:
+      options.screenSpaceReflections ?? DEFAULT_RENDER_QUALITY.screenSpaceReflections,
     /* Off, or a ratio at least 1.3 and at most 2 — never a number between zero and the range. */
     reconstruction: resolveReconstruction(options.reconstruction),
     indirectLight: options.indirectLight ?? DEFAULT_RENDER_QUALITY.indirectLight,

package/src/render/rendererHarness.ts

@@ -119,6 +119,9 @@ export function recordingGl(
     ONE: 1,
     ONE_MINUS_SRC_ALPHA: 0x0303,
     TRIANGLES: 0x0004,
+    /* The winding a pass names, so a test can tell which one it chose. */
+    CW: 0x0900,
+    CCW: 0x0901,
     TEXTURE0: 0x84c0,
     DEPTH_BUFFER_BIT: 0x00000100,
     DEPTH_TEST: 0x0b71,

package/src/render/rgb9e5.ts

@@ -0,0 +1,52 @@
+/**
+ * rgb9e5: three 9-bit mantissas over one shared 5-bit exponent, an unsigned float colour in four
+ * bytes. `EXT_texture_shared_exponent`'s encoding, the one a GPU's `rgb9e5ufloat` reads, written
+ * out so a lightmap page can hold its irradiance in four bytes a texel against a half float's eight.
+ *
+ * **What it gives up**: precision in the smaller channels, which share the largest one's exponent —
+ * a channel a thousandth of its neighbour keeps about one bit — and anything negative or past
+ * 65,408, which it clamps. Light is neither, and a bake's colours rarely span more than a few
+ * octaves within one texel, so a lightmap loses nothing visible; a value that needs each channel
+ * exact wants a format of its own.
+ *
+ * The bits, low to high: red in 0–8, green in 9–17, blue in 18–26, the exponent in 27–31, biased by
+ * 15, and a value is `mantissa * 2^(exponent - 15 - 9)`.
+ */
+
+const BIAS = 15;
+const MANTISSA_BITS = 9;
+const MANTISSA_VALUES = 1 << MANTISSA_BITS;
+const MAX_EXPONENT = 31;
+
+/** The largest value the format holds: 511/512 of 2^16. */
+export const RGB9E5_MAX = ((MANTISSA_VALUES - 1) / MANTISSA_VALUES) * 2 ** (MAX_EXPONENT - BIAS);
+
+const clampChannel = (v: number): number => (v > 0 ? Math.min(v, RGB9E5_MAX) : 0);
+
+/** One colour packed into its 32 bits, rounding to nearest; NaN and negatives are zero. */
+export function packRgb9e5(red: number, green: number, blue: number): number {
+  const r = clampChannel(red);
+  const g = clampChannel(green);
+  const b = clampChannel(blue);
+  const largest = Math.max(r, g, b);
+  let exponent = Math.max(-BIAS - 1, Math.floor(Math.log2(largest))) + 1 + BIAS;
+  let scale = 2 ** (exponent - BIAS - MANTISSA_BITS);
+  /* Rounding the largest channel up to 512 needs one more exponent, which the spec allows for. */
+  if (Math.floor(largest / scale + 0.5) === MANTISSA_VALUES) {
+    exponent += 1;
+    scale *= 2;
+  }
+  /* Inline rather than a helper: a page packs millions of texels, and a closure a call is one each. */
+  const mr = Math.min(MANTISSA_VALUES - 1, Math.floor(r / scale + 0.5));
+  const mg = Math.min(MANTISSA_VALUES - 1, Math.floor(g / scale + 0.5));
+  const mb = Math.min(MANTISSA_VALUES - 1, Math.floor(b / scale + 0.5));
+  return (mr | (mg << 9) | (mb << 18) | (exponent << 27)) >>> 0;
+}
+
+/** A packed colour's three channels, into `out[at…at+2]`. */
+export function unpackRgb9e5(bits: number, out: { [index: number]: number }, at = 0): void {
+  const scale = 2 ** ((bits >>> 27) - BIAS - MANTISSA_BITS);
+  out[at] = (bits & 511) * scale;
+  out[at + 1] = ((bits >>> 9) & 511) * scale;
+  out[at + 2] = ((bits >>> 18) & 511) * scale;
+}

package/src/render/sceneCapture.ts

@@ -0,0 +1,56 @@
+/**
+ * A scene capture: a texture the world is drawn into from a camera of the caller's, which a material
+ * then shows like any image — a screen in the world showing what a camera elsewhere sees, a monitor,
+ * a security feed. The planar reflection's pass, for a caller's camera rather than a mirrored one.
+ *
+ * **It holds radiance, not display pixels**, as a probe does: drawn with the output transform held
+ * off, at the colour format a probe takes — half floats under `hdrScene`, bytes otherwise — and
+ * sampled linear, so a material showing it as its `emissive` emits the light the capture saw and the
+ * frame's grade then applies once, to the screen as to everything around it.
+ *
+ * **What it gives up**: it is the mesh pass alone, as a probe bake is — the sky, water, particles and
+ * anything else a scene draws after its world are in the capture only if the callback draws them;
+ * no temporal resolve, bloom or other effect after the world runs on it; and it has no mip chain, so
+ * a screen seen small and far shimmers where a mipmapped image would not.
+ */
+
+/** What a capture's texture is made from, in place of an image: its size and colour format. */
+export interface SceneCaptureTexels {
+  readonly kind: 'scene-capture';
+  readonly width: number;
+  readonly height: number;
+  /** Half floats, which hold light past one; bytes otherwise. */
+  readonly float: boolean;
+}
+
+/** The largest side a capture may have, the size every WebGL2 device must take. */
+export const MAX_SCENE_CAPTURE_SIZE = 4096;
+
+/** A capture's description, refused by name where a side is not a whole number of pixels it can be. */
+export function sceneCaptureTexels(
+  width: number,
+  height: number,
+  float: boolean,
+): SceneCaptureTexels {
+  for (const [name, side] of [
+    ['width', width],
+    ['height', height],
+  ] as const) {
+    if (!Number.isInteger(side) || side < 1 || side > MAX_SCENE_CAPTURE_SIZE) {
+      throw new Error(
+        `createSceneCapture: ${name} must be a whole number from 1 to ${MAX_SCENE_CAPTURE_SIZE}, ` +
+          `not ${String(side)}`,
+      );
+    }
+  }
+  return { kind: 'scene-capture', width, height, float };
+}
+
+/** Whether a texture source is a capture's description rather than an image. */
+export function isSceneCaptureTexels(source: unknown): source is SceneCaptureTexels {
+  return (
+    typeof source === 'object' &&
+    source !== null &&
+    (source as { kind?: unknown }).kind === 'scene-capture'
+  );
+}

package/src/render/sceneTarget.ts

@@ -1,5 +1,6 @@
 import { glSceneDepthFormat } from './depthConvention.ts';
 import { clampGrain, clampVignette, grainSeed } from './shaders/filmLook.ts';
+import { FRINGE_FLOATS, resolveFringe } from './shaders/fringe.ts';
 import { AmbientOcclusionPass } from './ambientOcclusionPass.ts';
 import { ExposurePass } from './exposurePass.ts';
 import { clampAutoExposure } from './shaders/exposure.ts';
@@ -99,6 +100,8 @@ export class SceneTarget {
   private gradeStrength = 0;
   /** The lens and the print, held like the grade. See `filmLook.ts`. */
   private vignette = 0;
+  /** The lens's colour fringe: red's and green's pull and where it begins. See `fringe.ts`. */
+  private readonly fringe = new Float32Array(FRINGE_FLOATS);
   private grain = 0;
   private grainSeed = 0;
   /** Eye adaptation: how far, and this frame's time step. See `Renderer.setAutoExposure`. */
@@ -702,6 +705,11 @@ export class SceneTarget {
     this.vignette = clampVignette(strength);
   }
 
+  /** The lens's colour fringe, held until changed. See `Renderer.setChromaticAberration`. */
+  setChromaticAberration(intensity: number, start: number): void {
+    resolveFringe(intensity, start, this.fringe);
+  }
+
   /** The print's grain and this frame's seed, held until changed. See `Renderer.setFilmGrain`. */
   setFilmGrain(strength: number, seed: number): void {
     this.grain = clampGrain(strength);
@@ -769,8 +777,15 @@ export class SceneTarget {
   resolve(
     strength: number,
     reachUv: number,
-    /* The grade, applied here because this is the last pass. See RUSH_FRAG's own note. */
-    grade: { readonly transform: number; readonly exposure: number } = {
+    /*
+     * The grade, applied here because this is the last pass. See RUSH_FRAG's own note. `film` is
+     * the `filmic` curve's eight constants (`resolveFilmicCurve`), read only under transform 4.
+     */
+    grade: {
+      readonly transform: number;
+      readonly exposure: number;
+      readonly film?: Float32Array;
+    } = {
       transform: 0,
       exposure: 1,
     },
@@ -1012,6 +1027,12 @@ export class SceneTarget {
     gl.uniform1f(this.uniforms['uReach'] ?? null, reachUv);
     gl.uniform1i(this.uniforms['uOutputTransform'] ?? null, grade.transform);
     gl.uniform1f(this.uniforms['uOutputExposure'] ?? null, grade.exposure);
+    if (grade.film !== undefined) {
+      gl.uniform4fv(this.uniforms['uFilmA'] ?? null, grade.film, 0, 4);
+      gl.uniform4fv(this.uniforms['uFilmB'] ?? null, grade.film, 4, 4);
+    }
+    /* A standard range always here: see `Renderer.displayRange`. */
+    gl.uniform1f(this.uniforms['uDisplayHeadroom'] ?? null, 1);
 
     /*
      * Depth on its own unit, and the reprojection with it. Bound every frame rather than
@@ -1113,6 +1134,12 @@ export class SceneTarget {
       this.uniforms['uLocalExposure'] ?? null,
       localGrid === null ? 0 : this.localExposure,
     );
+    /* Each object's own motion is WebGPU's under a reconstruction; here the scene stands in on
+       unit 7 and the flag says not to read it, so the camera's motion alone blurs. */
+    gl.activeTexture(gl.TEXTURE7);
+    gl.bindTexture(gl.TEXTURE_2D, scene);
+    gl.uniform1i(this.uniforms['uMotion'] ?? null, 7);
+    gl.uniform1f(this.uniforms['uObjectMotion'] ?? null, 0);
     gl.activeTexture(gl.TEXTURE0);
 
     /* No unit and no texture: a flat colour, not a sample. Uploaded unconditionally — two
@@ -1122,6 +1149,7 @@ export class SceneTarget {
     gl.uniform3fv(this.uniforms['uVeilColor'] ?? null, veilColor);
     gl.uniform1f(this.uniforms['uVeilAlpha'] ?? null, veilAlpha);
     gl.uniform1f(this.uniforms['uVignette'] ?? null, this.vignette);
+    gl.uniform3fv(this.uniforms['uFringe'] ?? null, this.fringe);
     gl.uniform2f(this.uniforms['uGrain'] ?? null, this.grain, this.grainSeed);
 
     gl.bindVertexArray(this.vao);

package/src/render/screenSpaceReflection.ts

@@ -27,6 +27,11 @@ import type { DecalBox } from './decalProjector.ts';
  * which is the same price the temporal row declined for a velocity buffer. A caller declares a
  * `ReflectiveSurface` instead: a box, and a facing rule for which surfaces inside it reflect. It is
  * the shape `DecalProjector` already has, for the same reason.
+ *
+ * **Or every surface by its own material**, where the renderer was built with
+ * `screenSpaceReflections`: the lit stage leaves two maps of what it reflected — not a G-buffer, the
+ * environment's share and its tint, which is all a swap needs — and the same trace runs in a
+ * material mode over every pixel. See `frameReflections.ts`.
  */
 
 /**
@@ -350,9 +355,30 @@ export function towardCameraFade(direction: ReadonlyVec3, viewDirection: Readonl
   return Math.min(1, Math.max(0, (along + 1) / 2));
 }
 
+/**
+ * What a `ReflectiveSurface` is made with: its box, which way the surfaces inside it face, and how
+ * much and how far they reflect. Every number but the box has a default; see each field.
+ */
 export interface ReflectiveSurfaceOptions extends DecalBox {
-  /** How much of what the ray finds lands on the surface, 0 to 1. */
+  /**
+   * How much of what the ray finds lands on the surface, 0 to 1: one share over the box, or with
+   * `fresnel` the surface's reflectance head-on.
+   */
   readonly strength?: number;
+  /**
+   * Whether `strength` is the surface's reflectance head-on, F0, rather than one share over the
+   * box. Each pixel then returns `F0 · A + B` of what its ray finds, the split-sum environment BRDF
+   * at its own view and `roughness` — Karis's fit, the one the lit stage reflects its environment
+   * by — so a floor returns more toward the horizon than underfoot, and the share follows the
+   * camera as Unreal weighs its reflections. **False by default**, the one share as before.
+   *
+   * **What it gives up**: the pass has no material buffer, so the roughness and F0 are the box's,
+   * not each pixel's, and nothing occludes the reflection where the lit stage's ambient occlusion
+   * would. A floor of one material is what it is for.
+   */
+  readonly fresnel?: boolean;
+  /** The surface's roughness, 0 to 1, that `fresnel` weighs by. 0, a polished surface, if absent. */
+  readonly roughness?: number;
   /** How far a ray may travel, world metres. */
   readonly reachM?: number;
   /** How deep a depth sample is treated as being. See `ScreenSpaceMarch.thicknessM`. */
@@ -382,6 +408,9 @@ export class ReflectiveSurface {
   readonly tint = new Float32Array(3);
 
   strength: number;
+  /** See `ReflectiveSurfaceOptions.fresnel`. */
+  fresnel: boolean;
+  roughness: number;
   reachM: number;
   thicknessM: number;
   steps: number;
@@ -405,6 +434,8 @@ export class ReflectiveSurface {
     /* Half, because a mirror is the rare case: a wet floor, polished stone and a car bonnet all
        return a fraction of what lands on them, and a consumer who wants a mirror asks for one. */
     this.strength = options.strength ?? 0.5;
+    this.fresnel = options.fresnel ?? false;
+    this.roughness = options.roughness ?? 0;
     /* Eight metres covers a room and a street corner. Further costs steps rather than accuracy,
        since the step is the reach divided by them. */
     this.reachM = options.reachM ?? 8;
@@ -469,6 +500,8 @@ export interface RecordedReflection {
   readonly axis: Float32Array;
   readonly tint: Float32Array;
   strength: number;
+  fresnel: boolean;
+  roughness: number;
   reachM: number;
   thicknessM: number;
   steps: number;
@@ -482,6 +515,8 @@ function newRecord(): RecordedReflection {
     axis: new Float32Array(3),
     tint: new Float32Array(3),
     strength: 0.5,
+    fresnel: false,
+    roughness: 0,
     reachM: 8,
     thicknessM: 0.25,
     steps: 24,
@@ -537,6 +572,8 @@ export class ReflectionQueue {
     record.axis.set(surface.axis);
     record.tint.set(surface.tint);
     record.strength = Math.min(1, Math.max(0, surface.strength));
+    record.fresnel = surface.fresnel;
+    record.roughness = Math.min(1, Math.max(0, surface.roughness));
     record.reachM = Math.max(0, surface.reachM);
     record.thicknessM = Math.max(0, surface.thicknessM);
     record.steps = Math.min(32, Math.max(1, Math.round(surface.steps)));

package/src/render/shaders/bolt.ts

@@ -107,7 +107,13 @@ void main() {
    * the glow. A single falloff gives either a hard line with no atmosphere or a
    * soft smudge with no filament.
    */
-  float across = 1.0 - abs(vSide);
+  /*
+   * Clamped, because a multisampled target shades a pixel on the quad's edge at its centre, which
+   * may lie outside the quad: there 'vSide' runs past one, 'across' goes negative, and 'pow' of a
+   * negative number is NaN. One NaN pixel is a dark speck; bloom then spreads it into a white disc
+   * the size of the blur. Found by a fight drawing short arcs at 4 samples.
+   */
+  float across = clamp(1.0 - abs(vSide), 0.0, 1.0);
   float core = pow(across, 10.0);
   /*
    * A *wide* halo, deliberately. This exponent is the single biggest control over

package/src/render/shaders/depth.ts

@@ -101,6 +101,12 @@ void main() {
 #endif
 #if INSTANCED
   mat4 model = mat4(aInstanceModel0, aInstanceModel1, aInstanceModel2, aInstanceModel3);
+  /* The bottom row is the instance's texture cell, rebuilt as the row it stands for: see flat. */
+  vec4 instanceCell = vec4(model[0].w, model[1].w, model[2].w, model[3].w);
+  model[0].w = 0.0;
+  model[1].w = 0.0;
+  model[2].w = 0.0;
+  model[3].w = 1.0;
 #else
   mat4 model = uModel;
 #endif
@@ -125,7 +131,12 @@ void main() {
   vLightPosition = uLightViewProj * vec4(bent, world.w);
   gl_Position = vLightPosition;
 #if CUTOUT
+#if INSTANCED
+  /* A cutout instance's shadow is cut by its own cell, as its picture is. */
+  vUv = vec3((aUv.xy * instanceCell.xy + instanceCell.zw) * uUvScale + uUvOffset, aUv.z);
+#else
   vUv = vec3(aUv.xy * uUvScale + uUvOffset, aUv.z);
+#endif
   vAlphaCutout = uAlphaCutout;
 #endif
 #if GLASS

package/src/render/shaders/filmLook.ts

@@ -88,7 +88,8 @@ export function grainWeight(luma: number): number {
 
 /** Both backends' words when there is no composite to apply the look in. */
 export const FILM_LOOK_WITHOUT_COMPOSITE =
-  '[driftengine] setVignette and setFilmGrain need `screenEffects`: without a composite every ' +
+  '[driftengine] setVignette, setFilmGrain and setChromaticAberration need `screenEffects`: ' +
+  'without a composite every ' +
   'pass is the last thing to touch the frame, so there is no one place to apply a lens or a ' +
   'print. The look was not applied.';
 

package/src/render/shaders/flat/anisotropic.ts

@@ -30,7 +30,16 @@ void anisotropicSurface() {
     direction.x * uModelParams[0].y - direction.y * uModelParams[0].z,
     direction.x * uModelParams[0].z + direction.y * uModelParams[0].y
   );
-  aAlong = normalize(mTangent * turned.x + mBitangent * turned.y);
+  vec3 along = mTangent * turned.x + mBitangent * turned.y;
+  /*
+   * A mesh with neither tangents nor texture coordinates has no frame to take a direction from,
+   * and normalising the zero it gives was a NaN that drew the whole surface black. Any direction in
+   * the surface stands in, the one across the world's up, so the highlight is stretched somewhere.
+   */
+  if (dot(along, along) < 1e-12) {
+    along = cross(abs(mNormal.y) < 0.999 ? vec3(0.0, 1.0, 0.0) : vec3(1.0, 0.0, 0.0), mNormal);
+  }
+  aAlong = normalize(along);
   aAcross = cross(mNormal, aAlong);
   aStrength = strength;
 }
@@ -50,12 +59,37 @@ float anisotropicLobe(vec3 h, float sourceRadius, float dist) {
   return energy / max(d * d, 1e-8);
 }
 
+/**
+ * The same stretch as GGX's own BRDF, \`π · D · Vis · N·L\`, for a surface whose highlight is
+ * physical: the distribution normalised, and Smith's height-correlated masking stretched with it
+ * (Heitz 2014, as Filament writes it). \`anisotropicPhysicalLobe\` in anisotropicLobe.ts.
+ */
+float anisotropicPhysical(vec3 l, vec3 h, float ndl, float sourceRadius, float dist) {
+  float alpha = max(mRoughness * mRoughness, MIN_LOBE_ALPHA);
+  float alongWidth = alpha + (1.0 - alpha) * aStrength * aStrength;
+  float grow = sourceRadius / max(2.0 * dist, 1e-3);
+  float along = clamp(alongWidth + grow, alongWidth, 1.0);
+  float across = clamp(alpha + grow, alpha, 1.0);
+  float x = dot(aAlong, h) / along;
+  float y = dot(aAcross, h) / across;
+  float z = dot(mNormal, h);
+  float d = x * x + y * y + z * z;
+  float distribution = 1.0 / max(3.14159265 * along * across * d * d, 1e-8);
+  float ndv = max(dot(mNormal, mToEye), 1e-4);
+  float viewed = ndl * length(vec3(along * dot(aAlong, mToEye), across * dot(aAcross, mToEye), ndv));
+  float lit = ndv * length(vec3(along * dot(aAlong, l), across * dot(aAcross, l), ndl));
+  return 3.14159265 * distribution * (0.5 / max(viewed + lit, 1e-5)) * ndl;
+}
+
 void anisotropicLight(vec3 l, float sourceRadius, float dist) {
   float ndl = max(dot(mNormal, l), 0.0);
   vec3 h = normalize(l + mToEye);
-  vec3 tint = mix(mSpecColor, vec3(1.0), pow(1.0 - max(dot(mToEye, h), 0.0), 5.0) * mMetal);
+  vec3 tint = highlightTint(mSpecColor, max(dot(mToEye, h), 0.0), mMetal);
   mDiffuse = mAlbedo * ndl * (1.0 - mMetal);
-  mSpecular = ndl > 0.0 ? tint * anisotropicLobe(h, sourceRadius, dist) : vec3(0.0);
+  float lobe = physicalSpecular()
+    ? anisotropicPhysical(l, h, ndl, sourceRadius, dist)
+    : anisotropicLobe(h, sourceRadius, dist);
+  mSpecular = ndl > 0.0 ? tint * lobe : vec3(0.0);
 }
 
 /* The environment's normal, bent toward the stretch by its strength and the surface's roughness. */