@driftengine/core 4.8.6 → 4.9.0

package/dist/render/lightBudget.js

@@ -1,4 +1,6 @@
-import { POINT_LIGHT_COS_INNER, POINT_LIGHT_COS_OUTER, lampSourceRadius, lampWeight, lightChannelsOf, } from './clusteredLights.js';
+/** Fixed point-light budget shared by CPU selection and the flat shader. */
+import { MAX_AREA_LIGHTS, packAreaSizesAndDoors } from './areaLights.js';
+import { POINT_LIGHT_COS_INNER, POINT_LIGHT_COS_OUTER, lampSourceRadius, lampWeight, lightChannelsOf, lightFalloffExponentOf, } from './clusteredLights.js';
 /**
  * How many point lights the shading pass shades against at once.
  *
@@ -302,6 +304,8 @@ export const SDF_TEXT_TEXTURE_UNIT = SURFACE_TEXTURE_UNIT;
 export const POINT_SHADOW_POOL = MAX_POINT_LIGHTS + 4;
 /** Weights are optional per consumer; a short array means every light is fully present. */
 const FULLY_PRESENT = new Float32Array(MAX_POINT_LIGHTS).fill(1);
+/** The fixed arm's rectangles as `uAreaLightSize` holds them; refilled per bind, allocated once. */
+const AREA_SIZES_AND_DOORS = new Float32Array(MAX_AREA_LIGHTS * 4);
 /** No size at all, which is the behaviour every scene had before a light could have one. */
 const POINT_SOURCES = new Float32Array(MAX_POINT_LIGHTS);
 /**
@@ -394,7 +398,8 @@ export function bindPointLights(gl, uniforms, lights, falloff) {
      * every lamp switched off.
      */
     gl.uniform3fv(uniforms['uLightDir[0]'] ?? null, r.directions);
-    gl.uniform2fv(uniforms['uLightCone[0]'] ?? null, r.coneCos);
+    /* The cone and, in z, the light's own falloff exponent. See `conesAndFalloffs`. */
+    gl.uniform4fv(uniforms['uLightCone[0]'] ?? null, r.conesAndFalloffs);
     gl.uniform1fv(uniforms['uLightIesProfile[0]'] ?? null, r.iesProfiles);
     /* The azimuth and, in w, the channels. See `axesAndChannels`. */
     gl.uniform4fv(uniforms['uLightIesAxis[0]'] ?? null, r.axesAndChannels);
@@ -421,7 +426,9 @@ export function bindAreaLights(gl, uniforms, lights) {
     gl.uniform3fv(uniforms['uAreaLightColor[0]'] ?? null, lights.colors);
     gl.uniform3fv(uniforms['uAreaLightRight[0]'] ?? null, lights.right);
     gl.uniform3fv(uniforms['uAreaLightUp[0]'] ?? null, lights.up);
-    gl.uniform2fv(uniforms['uAreaLightSize[0]'] ?? null, lights.sizes);
+    /* The half extents and, in zw, the barn doors. See `packAreaSizesAndDoors`. */
+    packAreaSizesAndDoors(lights, AREA_SIZES_AND_DOORS);
+    gl.uniform4fv(uniforms['uAreaLightSize[0]'] ?? null, AREA_SIZES_AND_DOORS);
     gl.uniform1fv(uniforms['uAreaLightTwoSided[0]'] ?? null, lights.twoSided);
 }
 /**
@@ -463,6 +470,7 @@ const glLights = {
     iesAxes: NO_IES_AXES,
     cookies: NO_COOKIES,
     axesAndChannels: new Float32Array(MAX_POINT_LIGHTS * 4),
+    conesAndFalloffs: new Float32Array(MAX_POINT_LIGHTS * 4),
     heldSourceRadii: new Float32Array(MAX_POINT_LIGHTS),
     heldWeights: new Float32Array(MAX_POINT_LIGHTS),
 };
@@ -493,6 +501,7 @@ export function resolvePointLights(lights, falloff, out) {
         out.iesAxes = NO_IES_AXES;
         out.cookies = NO_COOKIES;
         packAxesAndChannels(NO_IES_AXES, undefined, out.axesAndChannels);
+        packConesAndFalloffs(OPEN_CONES, undefined, out.conesAndFalloffs);
         return out;
     }
     /*
@@ -574,8 +583,19 @@ export function resolvePointLights(lights, falloff, out) {
     out.iesAxes = iesAxes;
     out.cookies = cookies;
     packAxesAndChannels(iesAxes, lights.lightChannels, out.axesAndChannels);
+    packConesAndFalloffs(coneCos, lights.lightFalloffExponents, out.conesAndFalloffs);
     return out;
 }
+/** The cone and the falloff exponent, four a light, as `uLightCone` holds them. */
+function packConesAndFalloffs(cones, exponents, out) {
+    const named = (exponents?.length ?? 0) >= MAX_POINT_LIGHTS ? exponents : undefined;
+    for (let light = 0; light < MAX_POINT_LIGHTS; light++) {
+        out[light * 4] = cones[light * 2] ?? POINT_LIGHT_COS_INNER;
+        out[light * 4 + 1] = cones[light * 2 + 1] ?? POINT_LIGHT_COS_OUTER;
+        out[light * 4 + 2] = lightFalloffExponentOf(named?.[light]);
+        out[light * 4 + 3] = 0;
+    }
+}
 /** The azimuth and the channels, four a light, as `uLightIesAxis` holds them. */
 function packAxesAndChannels(axes, channels, out) {
     const named = (channels?.length ?? 0) >= MAX_POINT_LIGHTS ? channels : undefined;

package/dist/render/lightmap.d.ts

@@ -35,10 +35,12 @@ export interface LightmapPage {
     readonly width: number;
     readonly height: number;
     /**
-     * Linear irradiance, three floats a texel, row-major from the top, in the same units every other
-     * light here is in — a bake from another engine scaled by that engine's exposure, as its lights are.
+     * Linear irradiance, row-major from the top, in the same units every other light here is in — a
+     * bake from another engine scaled by that engine's exposure, as its lights are. Either three
+     * floats a texel, or one word a texel already packed as rgb9e5 (`rgb9e5.ts`), which is how such a
+     * bake usually arrives and which uploads with no conversion at all.
      */
-    readonly irradiance: Float32Array;
+    readonly irradiance: Float32Array | Uint32Array;
     /**
      * The direction the light arrives from, four bytes a texel: a first-order spherical harmonic in
      * this engine's world axes, each value stored as `v * 0.5 + 0.5` — xyz the axis, w the constant.
@@ -54,20 +56,32 @@ export declare const LIGHTMAP_LAYERS = 2;
 export type LightmapRegion = readonly [number, number, number, number];
 /** The whole page. */
 export declare const WHOLE_PAGE: LightmapRegion;
-/** A page as both backends upload it: `layers` images of half-float RGBA, row-major from the top. */
+/**
+ * A page as both backends upload it: two layers of four bytes a texel, row-major from the top. The
+ * first is the irradiance's rgb9e5 word, byte by byte from its lowest; the second is the direction.
+ *
+ * **Eight bytes a texel, and the shader filters it.** Half floats were sixteen: a stage of 49 pages
+ * and 21.8 million texels held 348 MB, where this holds 174. The price is that the irradiance cannot
+ * be filtered as it is stored — a bilinear blend of two words with different exponents is not the
+ * blend of the colours they hold — so the lit stage fetches a texel's four neighbours, decodes each
+ * and blends the colours (`modelBaked` in `shaders/flat/models.ts`): four fetches a layer where one
+ * filtered sample was, on lightmapped surfaces alone. **What would make it wrong** is every device
+ * a page reaches sampling `rgb9e5ufloat`, which WebGL2 does as `RGB9_E5` too; it would then be a
+ * texture of its own, filtered by the device, and a binding the lit stage has no room for.
+ */
 export interface LightmapTexels {
     readonly kind: 'lightmap-texels';
     readonly width: number;
     readonly height: number;
-    readonly layers: number;
-    readonly texels: Uint16Array;
+    /** Each layer's bytes, in layer order: the irradiance, then the direction. */
+    readonly layers: readonly Uint8Array[];
 }
 /** Whether a surface texture's source is a page's texels rather than an image or blocks. */
 export declare function isLightmapTexels(source: unknown): source is LightmapTexels;
 /**
- * A page as both backends upload it: two layers of half-float RGBA, the irradiance with an alpha of
- * one and the direction as the fractions its bytes are. Refuses a page whose arrays are not its
- * size, naming the one that is short.
+ * A page as both backends upload it (see `LightmapTexels`). Refuses a page whose arrays are not its
+ * size, naming the one that is short. Packed irradiance is read where it lies, with no copy; float
+ * irradiance is packed once, here.
  */
 export declare function lightmapTexels(page: LightmapPage): LightmapTexels;
 /**

package/dist/render/lightmap.js

@@ -1,4 +1,4 @@
-import { toHalfFloats } from './halfFloat.js';
+import { packRgb9e5 } from './rgb9e5.js';
 /** Layers a page is uploaded as: the irradiance, then the direction. */
 export const LIGHTMAP_LAYERS = 2;
 /** The whole page. */
@@ -10,9 +10,9 @@ export function isLightmapTexels(source) {
         source.kind === 'lightmap-texels');
 }
 /**
- * A page as both backends upload it: two layers of half-float RGBA, the irradiance with an alpha of
- * one and the direction as the fractions its bytes are. Refuses a page whose arrays are not its
- * size, naming the one that is short.
+ * A page as both backends upload it (see `LightmapTexels`). Refuses a page whose arrays are not its
+ * size, naming the one that is short. Packed irradiance is read where it lies, with no copy; float
+ * irradiance is packed once, here.
  */
 export function lightmapTexels(page) {
     const { width, height } = page;
@@ -20,32 +20,54 @@ export function lightmapTexels(page) {
         throw new Error(`createLightmap: a ${width} by ${height} page has nothing in it`);
     }
     const texels = width * height;
-    if (page.irradiance.length !== texels * 3) {
-        throw new Error(`createLightmap: ${page.irradiance.length} irradiance floats for a ${width} by ${height} ` +
-            `page, which wants ${texels * 3}: three a texel`);
+    const irradiance = page.irradiance;
+    const packed = irradiance instanceof Uint32Array;
+    const wanted = packed ? texels : texels * 3;
+    if (irradiance.length !== wanted) {
+        throw new Error(`createLightmap: ${irradiance.length} irradiance ${packed ? 'words' : 'floats'} for a ` +
+            `${width} by ${height} page, which wants ${wanted}: ` +
+            (packed ? 'one rgb9e5 word a texel' : 'three a texel'));
     }
     if (page.direction.length !== texels * 4) {
         throw new Error(`createLightmap: ${page.direction.length} direction bytes for a ${width} by ${height} ` +
             `page, which wants ${texels * 4}: four a texel`);
     }
-    const floats = new Float32Array(texels * 4 * LIGHTMAP_LAYERS);
-    for (let t = 0; t < texels; t++) {
-        floats[t * 4] = page.irradiance[t * 3];
-        floats[t * 4 + 1] = page.irradiance[t * 3 + 1];
-        floats[t * 4 + 2] = page.irradiance[t * 3 + 2];
-        floats[t * 4 + 3] = 1;
-        const at = (texels + t) * 4;
-        for (let c = 0; c < 4; c++)
-            floats[at + c] = page.direction[t * 4 + c] / 255;
+    let words;
+    if (packed) {
+        words = irradiance;
+    }
+    else {
+        words = new Uint32Array(texels);
+        for (let t = 0; t < texels; t++) {
+            words[t] = packRgb9e5(irradiance[t * 3], irradiance[t * 3 + 1], irradiance[t * 3 + 2]);
+        }
     }
     return {
         kind: 'lightmap-texels',
         width,
         height,
-        layers: LIGHTMAP_LAYERS,
-        texels: toHalfFloats(floats),
+        layers: [littleEndianBytes(words), page.direction],
     };
 }
+/** Whether this platform lays a word out lowest byte first, which the shader's decode assumes. */
+const LITTLE_ENDIAN = new Uint8Array(new Uint32Array([1]).buffer)[0] === 1;
+/**
+ * A page's words as bytes, lowest first: a view of the same memory on every little-endian platform,
+ * which is every one a browser runs on, and a reordered copy anywhere else.
+ */
+function littleEndianBytes(words) {
+    const bytes = new Uint8Array(words.buffer, words.byteOffset, words.length * 4);
+    if (LITTLE_ENDIAN)
+        return bytes;
+    const swapped = new Uint8Array(bytes.length);
+    for (let i = 0; i < bytes.length; i += 4) {
+        swapped[i] = bytes[i + 3];
+        swapped[i + 1] = bytes[i + 2];
+        swapped[i + 2] = bytes[i + 1];
+        swapped[i + 3] = bytes[i];
+    }
+    return swapped;
+}
 /**
  * A mesh with its second coordinates moved onto the grain and relief streams they ride, or the
  * mesh itself where it has none. Called by both backends' `createMesh`, before anything records

package/dist/render/particlePool.d.ts

@@ -50,6 +50,27 @@ export interface ParticleInstances {
     count: number;
     capacity: number;
 }
+/**
+ * Floats one particle takes in a buffer a caller's own compute writes (`DeviceParticles`), in this
+ * order: position 3, half-width 1, roll 1, colour 3, opacity 1, age 1, seed 1, velocity 3, a
+ * sprite's frame 1 and its half-height 1 — `ParticleInstances`' streams, interleaved as the pool's
+ * own upload interleaves them. 64 bytes a particle.
+ */
+export declare const DEVICE_PARTICLE_FLOATS = 16;
+/**
+ * Particles a caller's own compute shader wrote into a buffer of its own (`registerCompute`), drawn
+ * where they lie by `drawDeviceParticles` rather than read back and uploaded again. WebGPU only.
+ *
+ * **Not sorted**, as a pool's are where its batch asks: the device holds them, so an alpha-blended
+ * set that must be drawn far to near sorts itself. A slot with a half-width of 0 draws nothing, which
+ * is how a fixed-size buffer holds fewer live particles than it has room for.
+ */
+export interface DeviceParticles {
+    /** A buffer with `VERTEX` usage, `DEVICE_PARTICLE_FLOATS` floats a particle. */
+    readonly buffer: GPUBuffer;
+    /** How many particles from its start to draw; no more than the buffer holds. */
+    readonly count: number;
+}
 /**
  * A pool of short-lived particles, simulated on the CPU and drawn as instances.
  *

package/dist/render/particlePool.js

@@ -1,4 +1,11 @@
 import { createInstanceData, writeInstance } from './instancedMesh.js';
+/**
+ * Floats one particle takes in a buffer a caller's own compute writes (`DeviceParticles`), in this
+ * order: position 3, half-width 1, roll 1, colour 3, opacity 1, age 1, seed 1, velocity 3, a
+ * sprite's frame 1 and its half-height 1 — `ParticleInstances`' streams, interleaved as the pool's
+ * own upload interleaves them. 64 bytes a particle.
+ */
+export const DEVICE_PARTICLE_FLOATS = 16;
 function createParticleInstances(capacity) {
     return {
         positions: new Float32Array(capacity * 3),

package/dist/render/pass.d.ts

@@ -117,6 +117,19 @@ export type PassContext = {
 } & ({
     readonly backend: 'webgl2';
     readonly gl: WebGL2RenderingContext;
+    /**
+     * The frame's colour with everything drawn before this pass, for a pass declaring
+     * `reads: ['colorSnapshot']`, and null for one that does not or where the frame keeps no
+     * scene target (`screenEffects` off). A copy, never the attachment being drawn into, which
+     * WebGL2 cannot sample; taken afresh at each such pass's draw. WebGPU hands the same copy
+     * over in `PrepareContext.sceneColor`, where a bind group has to be built before the pass.
+     */
+    readonly sceneColor: WebGLTexture | null;
+    /**
+     * The frame's depth as it stands, for a pass declaring `reads: ['depthSnapshot']`: a copy, at
+     * the buffer's own values and reversed as it is (1 near, 0 far). Null as `sceneColor` is.
+     */
+    readonly sceneDepth: WebGLTexture | null;
 } | {
     readonly backend: 'webgpu';
     readonly pass: GPURenderPassEncoder;
@@ -213,6 +226,42 @@ export type PrepareContext = {
      * should not apply it either; the renderer's own verbs do not jitter a mirror.
      */
     readonly jitter: Float32Array;
+    /**
+     * The frame's single-sample copy of its depth, or null where the frame keeps none (no
+     * composite: `screenEffects` off).
+     *
+     * One `r32float` texel a pixel holding the depth buffer's own value, reversed as the
+     * buffer is (`REVERSED_DEPTH`: 1 at the near plane, 0 at the far one). Unfilterable, so a
+     * pass binds it as `'unfilterable-float'` and reads it with a non-filtering sampler or
+     * `textureLoad`.
+     *
+     * **Handed over here, filled at the draw.** The view is the one this frame's copy will be
+     * written into, so a pass builds its bind groups with it before the frame's pass opens; the
+     * copy itself is taken when a pass that declares `reads: ['depthSnapshot']` is drawn, with
+     * everything drawn before it, which is what the soft edge of a translucent particle
+     * needs. A pass that does not declare that read finds whatever the frame last wrote there.
+     */
+    readonly sceneDepth: GPUTextureView | null;
+    /**
+     * The frame's colour, for a pass that declares `reads: ['colorSnapshot']`, or null where no
+     * registered pass does or the frame keeps no composite (`screenEffects` off).
+     *
+     * At the scene's own size and format — under a reconstruction, the render's rather than the
+     * output's, since that is the picture a registered pass draws into — and filterable.
+     * **Handed over here, refilled at the draw**: the view is the texture each reading pass's
+     * draw copies the frame into, with everything drawn before it, so a distortion samples the
+     * scene behind it and a full-screen effect drawn last reads the whole frame and writes over
+     * it, in scene light, before the tone curve. A copy a reading pass, where `sceneDepth` is one
+     * a frame.
+     *
+     * **Under a reconstruction a pass that reads it is drawn after the upscale**, over the
+     * reconstructed picture and after every blended draw, whatever order it was asked in — at the
+     * output's size and the reconstruction's format, which `PassContext.format` names at that
+     * draw, so a pass drawn there keeps a pipeline for it. The view is then the output-size copy.
+     * `sceneDepth` stays the render's opaque depth: at a ratio above 1 its texels are coarser by
+     * the ratio, and a blended draw is in neither depth, as it never is.
+     */
+    readonly sceneColor: GPUTextureView | null;
 };
 /**
  * The world's distance field on the device, as the two buffers and four numbers that address it.

package/dist/render/pointLightSelection.d.ts

@@ -69,6 +69,14 @@ export interface PointLightSource {
      * whose uniform budget has none to spare.
      */
     inLightField?: boolean;
+    /**
+     * How the light fades with distance when it names its own way: `(1 - (d/R)^2)^n` with no distance
+     * term, `R` its radius and `n` this. Unreal's falloff for a light without inverse-square falloff,
+     * so a rig authored there — a fill of brightness 160 across 164 m, a key at exponent 8 — lights
+     * the space it was authored for rather than one that ends a few metres out. Absent or 0, the
+     * frame's own falloff (`pointLightFalloff`), which is every light before 4.8.7.
+     */
+    falloffExponent?: number;
 }
 export interface PointLightBuffer {
     readonly positions: Float32Array;
@@ -126,6 +134,11 @@ export interface PointLightBuffer {
     readonly directions: Float32Array;
     /** Two per slot: the cosine of the inner cone angle, then of the outer. */
     readonly coneCos: Float32Array;
+    /**
+     * One per slot: the light's own falloff exponent, or 0 for the frame's falloff. See
+     * `PointLightSource.falloffExponent`.
+     */
+    readonly falloffExponents: Float32Array;
     /** One per slot: a row of the photometric atlas, or −1 for a light with no profile. */
     readonly iesProfiles: Float32Array;
     /** Internal insertion-sort storage; exposed only to keep one flat object. */

package/dist/render/pointLightSelection.js

@@ -1,5 +1,5 @@
 /** Allocation-free selection and packing of point lights for a fixed shader budget. */
-import { POINT_LIGHT_COS_INNER, POINT_LIGHT_COS_OUTER } from './clusteredLights.js';
+import { POINT_LIGHT_COS_INNER, POINT_LIGHT_COS_OUTER, lightFalloffExponentOf, } from './clusteredLights.js';
 import { MAX_POINT_LIGHTS, POINT_SHADOW_POOL } from './lightBudget.js';
 import { gatherLights } from './lightGrid.js';
 export const DEFAULT_POINT_LIGHT_VIEW_RANGE = 180;
@@ -150,6 +150,7 @@ export function createPointLightBuffer(capacity = MAX_POINT_LIGHTS) {
         weights: new Float32Array(shaded),
         directions: new Float32Array(shaded * 3),
         coneCos: new Float32Array(shaded * 2),
+        falloffExponents: new Float32Array(shaded),
         /* −1 rather than 0, because row 0 is a real fixture and a light that asked for none must not
            be shaped by whichever profile happened to load first. */
         iesProfiles: new Float32Array(shaded).fill(-1),
@@ -382,6 +383,7 @@ function choose(sources, visit, visitCount, x, y, z, out, timeSeconds, viewRange
          * Restricting it to spots would be a smaller feature for no saving.
          */
         out.iesProfiles[slot] = light.iesProfile ?? -1;
+        out.falloffExponents[slot] = lightFalloffExponentOf(light.falloffExponent);
     }
     out.count = chosen;
     /*

package/dist/render/reflectionSurfaceTargets.d.ts

@@ -0,0 +1,28 @@
+export declare class ReflectionSurfaceTargets {
+    private readonly gl;
+    private probe;
+    private tint;
+    private width;
+    private height;
+    private readonly all;
+    private readonly colourAlone;
+    constructor(gl: WebGL2RenderingContext);
+    /** The environment as the frame shows it, and the roughness in alpha. */
+    get probeTexture(): WebGLTexture | null;
+    /** What a found reflection is multiplied by. */
+    get tintTexture(): WebGLTexture | null;
+    /**
+     * 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;
+    /** Around an opaque lit draw into the frame: its two extra outputs land. */
+    on(): void;
+    /** And after it: only the colour does. */
+    off(): void;
+    /** With the scene's framebuffer bound, after the trace has read them: see the header. */
+    detach(): void;
+    dispose(): void;
+    private make;
+    private release;
+}

package/dist/render/reflectionSurfaceTargets.js

@@ -0,0 +1,99 @@
+/**
+ * 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 {
+    gl;
+    probe = null;
+    tint = null;
+    width = 0;
+    height = 0;
+    all;
+    colourAlone;
+    constructor(gl) {
+        this.gl = gl;
+        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() {
+        return this.probe;
+    }
+    /** What a found reflection is multiplied by. */
+    get tintTexture() {
+        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, height) {
+        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() {
+        this.gl.drawBuffers(this.all);
+    }
+    /** And after it: only the colour does. */
+    off() {
+        this.gl.drawBuffers(this.colourAlone);
+    }
+    /** With the scene's framebuffer bound, after the trace has read them: see the header. */
+    detach() {
+        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() {
+        this.release();
+    }
+    make(width, height) {
+        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;
+    }
+    release() {
+        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/dist/render/renderQuality.d.ts

@@ -1,4 +1,5 @@
 /** Construction-time GPU quality controls shared by every renderer resource. */
+import type { FrameReflections } from './frameReflections.ts';
 /**
  * What happens to a shaded colour on its way to the framebuffer.
  *
@@ -20,8 +21,14 @@
  * 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.
  *
@@ -209,13 +216,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.
@@ -344,6 +352,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. */
@@ -511,14 +531,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
@@ -569,6 +589,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.

package/dist/render/renderQuality.js

@@ -85,9 +85,11 @@ export const DEFAULT_RENDER_QUALITY = Object.freeze({
     sceneSamples: 1,
     planarReflections: false,
     hdrScene: false,
+    highDynamicRange: false,
     cameraMotionBlur: 0,
     temporalAa: false,
     orderIndependent: false,
+    screenSpaceReflections: false,
     depthOfField: 0,
     reconstruction: 0,
     indirectLight: false,
@@ -227,9 +229,11 @@ export function resolveRenderQuality(options = {}) {
         sceneSamples: Math.max(1, Math.round(options.sceneSamples ?? DEFAULT_RENDER_QUALITY.sceneSamples)),
         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/dist/render/rendererHarness.js

@@ -76,6 +76,9 @@ export function recordingGl(options = {}) {
         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,