@driftengine/core 4.8.6 → 4.9.0

package/src/render/backend/webgpu/sceneCaptureTarget.ts

@@ -0,0 +1,63 @@
+import { DEPTH_FORMAT } from '../../depthConvention.ts';
+
+/**
+ * A scene capture's attachments on WebGPU: the depth and, above one sample, the multisampled colour
+ * its pass draws into and resolves from — the capture's own texture being the resolve, since **a
+ * texture cannot be both multisampled and sampled**. At the world's sample count and format, because
+ * a capture draws the world with the world's pipelines: a pipeline whose count or format disagrees
+ * with its attachment is rejected at `finish` and takes the whole capture with it. Remade only if
+ * either has changed since. See `sceneCapture.ts` for what a capture is.
+ */
+export class GpuSceneCaptureTarget {
+  private depth: GPUTexture | null = null;
+  private depthView: GPUTextureView | null = null;
+  private colorMsaa: GPUTexture | null = null;
+  private colorMsaaView: GPUTextureView | null = null;
+  private key = '';
+
+  constructor(
+    private readonly device: GPUDevice,
+    readonly width: number,
+    readonly height: number,
+  ) {}
+
+  attachments(
+    samples: number,
+    format: GPUTextureFormat,
+  ): { depth: GPUTextureView; colorMsaa: GPUTextureView | null } {
+    const key = `${samples}:${format}`;
+    if (this.depthView === null || key !== this.key) {
+      this.dispose();
+      this.key = key;
+      this.depth = this.device.createTexture({
+        label: 'capture.depth',
+        size: [this.width, this.height],
+        format: DEPTH_FORMAT,
+        sampleCount: samples,
+        usage: 0x10, // RENDER_ATTACHMENT
+      });
+      this.depthView = this.depth.createView();
+      this.colorMsaa =
+        samples > 1
+          ? this.device.createTexture({
+              label: 'capture.colorMsaa',
+              size: [this.width, this.height],
+              format,
+              sampleCount: samples,
+              usage: 0x10, // RENDER_ATTACHMENT
+            })
+          : null;
+      this.colorMsaaView = this.colorMsaa?.createView() ?? null;
+    }
+    return { depth: this.depthView as GPUTextureView, colorMsaa: this.colorMsaaView };
+  }
+
+  dispose(): void {
+    this.depth?.destroy();
+    this.colorMsaa?.destroy();
+    this.depth = null;
+    this.depthView = null;
+    this.colorMsaa = null;
+    this.colorMsaaView = null;
+  }
+}

package/src/render/backend/webgpu/surfaceTexturePass.ts

@@ -3,6 +3,8 @@ import { SURFACE_EFFECT_TEXELS, packSurfaceEffects } from '../../surfaceEffects.
 import { toHalfFloats } from '../../halfFloat.ts';
 import { isLightmapTexels } from '../../lightmap.ts';
 import type { LightmapTexels } from '../../lightmap.ts';
+import { isSceneCaptureTexels } from '../../sceneCapture.ts';
+import type { SceneCaptureTexels } from '../../sceneCapture.ts';
 import { layerSize, refuseArrayUpdate, sourceSize } from '../../textureSource.ts';
 import { compressedLayers, planBlocks, refuseBlockUpdate } from '../../compressedSource.ts';
 import type {
@@ -195,35 +197,54 @@ export class GpuSurfaceTexture {
   constructor(
     private readonly device: GPUDevice,
     private readonly pipelines: PipelineCache,
-    source: SurfaceSource | readonly SurfaceSource[] | LightmapTexels,
+    source: SurfaceSource | readonly SurfaceSource[] | LightmapTexels | SceneCaptureTexels,
     options: SurfaceTextureOptions = {},
     compressed: readonly CompressedTextureFormat[] = [],
   ) {
-    /* A lightmap's page: half floats, uploaded as they are. See `lightmap.ts`. */
+    /* A scene capture's target: one empty layer the world is drawn into. See `sceneCapture.ts`. */
+    const capture = isSceneCaptureTexels(source) ? source : null;
+    /* A lightmap's page: two layers of bytes, uploaded as they are. See `lightmap.ts`. */
     const baked = isLightmapTexels(source) ? source : null;
     const listed = (
-      baked !== null ? [] : Array.isArray(source) ? source : [source]
+      baked !== null || capture !== null ? [] : Array.isArray(source) ? source : [source]
     ) as readonly SurfaceSource[];
     const blocks = compressedLayers(listed);
     const srgb = (options.colorSpace ?? 'linear') === 'srgb';
     /* `SRGB8_ALPHA8`'s equivalent. Decoded in the sampler, before filtering, which is the only
-       place it is correct — `surfaceTexture.ts` makes the argument in full. */
-    this.format = baked !== null ? 'rgba16float' : srgb ? 'rgba8unorm-srgb' : 'rgba8unorm';
-    if (baked !== null) {
+       place it is correct — `surfaceTexture.ts` makes the argument in full. A capture takes the
+       world's own format, which its pass resolves into. */
+    this.format =
+      capture !== null
+        ? pipelines.format
+        : srgb && baked === null
+          ? 'rgba8unorm-srgb'
+          : 'rgba8unorm';
+    if (capture !== null) {
+      this.layers = 1;
+      this.blockFormat = null;
+      this.mipmapped = false;
+      this.width = capture.width;
+      this.height = capture.height;
+      this.levels = 1;
+      this.texture = this.allocate();
+    } else if (baked !== null) {
       /* No chain: a page is read at its own resolution, and a level of it would blend regions. */
-      this.layers = baked.layers;
+      this.layers = baked.layers.length;
       this.blockFormat = null;
       this.mipmapped = false;
       this.width = baked.width;
       this.height = baked.height;
       this.levels = 1;
       this.texture = this.allocate();
-      device.queue.writeTexture(
-        { texture: this.texture },
-        baked.texels,
-        { bytesPerRow: baked.width * 8, rowsPerImage: baked.height },
-        { width: baked.width, height: baked.height, depthOrArrayLayers: baked.layers },
-      );
+      /* A layer at a time, so a page's arrays are uploaded where they lie rather than joined. */
+      for (let layer = 0; layer < this.layers; layer++) {
+        device.queue.writeTexture(
+          { texture: this.texture, origin: [0, 0, layer] },
+          baked.layers[layer] as Uint8Array<ArrayBuffer>,
+          { bytesPerRow: baked.width * 4, rowsPerImage: baked.height },
+          { width: baked.width, height: baked.height, depthOrArrayLayers: 1 },
+        );
+      }
     } else if (blocks !== null) {
       /* Refused before anything is allocated; the stored chain, or level 0 alone where no chain
          was asked for. See `compressedUpload.ts`. */
@@ -282,7 +303,9 @@ export class GpuSurfaceTexture {
           : 1,
     });
 
-    if (blocks === null && baked === null) this.upload(listed as readonly TexImageSource[]);
+    if (blocks === null && baked === null && capture === null) {
+      this.upload(listed as readonly TexImageSource[]);
+    }
 
     /* Half floats, as `renderer.ts` uploads it: filterable, so the ordinary float layout takes it,
        and read by `textureLoad` alone, so the filter never runs. */
@@ -315,6 +338,13 @@ export class GpuSurfaceTexture {
     return this.current;
   }
 
+  /** The only layer as a plain 2D view, which a scene capture's pass resolves into. */
+  layerView(): GPUTextureView | null {
+    return (
+      this.texture?.createView({ dimension: '2d', baseArrayLayer: 0, arrayLayerCount: 1 }) ?? null
+    );
+  }
+
   /**
    * Replace the pixels, keeping the handle and its sampler.
    *

package/src/render/clusteredLights.ts

@@ -92,7 +92,7 @@ export const MAX_CLUSTERED_LIGHTS = 320;
  * it cannot. That is what lets a light index the shadow uniforms by a number read from a texture,
  * and it is the same fact the octahedral array texture was built on.
  */
-export const LIGHT_TEXELS = 5;
+export const LIGHT_TEXELS = 6;
 
 /**
  * Where each field of a light's record sits, as an offset in `uint`s from `lightBase`.
@@ -123,7 +123,11 @@ export const LIGHT_TEXELS = 5;
  * **Reordered 2026-10-02 so a plain light's fields are the first eight**, which is what lets the
  * shader stop after two texels. Nine values are needed by every light and eight fit in two
  * texels, so the emitter size and the weight share slot 7 as two halves; see `packSizeAndWeight`.
- * Slot 19 is spare.
+ *
+ * **A sixth texel arrived in 4.8.7 for a light's own falloff exponent**, the fifth's last slot
+ * having gone to the channels: 6 KB more of a table near 300, read only for a light whose record
+ * carries a fixture, which a light with an exponent does. Slots 21 and 22 are a rectangle's barn
+ * doors and spare on a lamp; slot 23 is spare.
  */
 export const LIGHT_RECORD = {
   positionX: 0,
@@ -154,6 +158,11 @@ export const LIGHT_RECORD = {
    * last texels are fetched; a plain light's are not, and the shader takes the default for it.
    */
   channels: 19,
+  /** The light's own falloff exponent, or 0 for the frame's falloff. `PointLightSource.falloffExponent`. */
+  falloffExponent: 20,
+  /** A rectangle's barn doors: the cosine of their angle from its normal, then their length in metres. */
+  barnDoorCos: 21,
+  barnDoorLength: 22,
 } as const;
 
 /** The lighting channel every light and every surface is on unless it says otherwise. */
@@ -171,11 +180,20 @@ export function lightChannelsOf(value: number | undefined): number {
   return value;
 }
 
+/**
+ * A light's own falloff exponent as the shader reads it: a positive finite number, or 0 for the
+ * frame's falloff where none was named or what was named is not one. The record and the uniform
+ * path both write this, so a light named badly falls off by the frame's rule in both.
+ */
+export function lightFalloffExponentOf(value: number | undefined): number {
+  return value !== undefined && Number.isFinite(value) && value > 0 ? value : 0;
+}
+
 /** Texels the lit pass reads for a light whose record carries no fixture. */
 export const PLAIN_LIGHT_TEXELS = 2;
 
 /**
- * The bit of `sizeAndWeight` that says the record's last three texels hold something: the sign of
+ * The bit of `sizeAndWeight` that says the record's last four texels hold something: the sign of
  * the emitter size's half, which a size never needs.
  */
 export const LIGHT_FIXTURE_FLAG = 0x8000;
@@ -426,6 +444,8 @@ export interface ClusterLightSet {
   readonly iesProfiles?: Float32Array;
   /** One per light: its lighting channels. See `PointLightSet.lightChannels`. */
   readonly channels?: Float32Array;
+  /** One per light: its own falloff exponent, or 0. See `PointLightSource.falloffExponent`. */
+  readonly falloffExponents?: Float32Array;
   /**
    * The rectangles shaded through the table, after the `count` point lights: those of `areas` from
    * `areaFrom` on, `areaCount` of them. The ones before `areaFrom` are the fixed arm's, which is
@@ -450,6 +470,7 @@ export interface ClusterLightArrays {
   readonly lightIesAxes?: Float32Array;
   readonly lightCookies?: Float32Array;
   readonly lightChannels?: Float32Array;
+  readonly lightFalloffExponents?: Float32Array;
   readonly areaLights?: AreaLightBuffer | null;
 }
 
@@ -510,6 +531,7 @@ export function fillClusterLightSet(
   out.iesAxes = env.lightIesAxes;
   out.cookies = env.lightCookies;
   out.channels = env.lightChannels;
+  out.falloffExponents = env.lightFalloffExponents;
   return out;
 }
 
@@ -559,8 +581,8 @@ function distanceSqToBounds(x: number, y: number, z: number, b: Float32Array): n
 }
 
 /**
- * Whether a light's record needs its last three texels: it holds a shadow slot, a cone, a profile
- * or a cookie. Everything else is a plain light, read in `PLAIN_LIGHT_TEXELS`.
+ * Whether a light's record needs its last four texels: it holds a shadow slot, a cone, a profile,
+ * a cookie, channels of its own or a falloff exponent of its own. Everything else is a plain light, read in `PLAIN_LIGHT_TEXELS`.
  *
  * **`shadowSlots` is zero where the lit shader has no point shadows**, and both binners are handed
  * it that way: a slot is only read under `POINT_SHADOWS`, so a light holding one in a build without
@@ -580,7 +602,8 @@ export function lightHasFixture(
     (cone?.[light * 2 + 1] ?? POINT_LIGHT_COS_OUTER) !== POINT_LIGHT_COS_OUTER ||
     (lights.iesProfiles?.[light] ?? NO_IES_PROFILE) >= 0 ||
     (lights.cookies?.[light] ?? NO_IES_PROFILE) >= 0 ||
-    lightChannelsOf(lights.channels?.[light]) !== DEFAULT_LIGHT_CHANNELS
+    lightChannelsOf(lights.channels?.[light]) !== DEFAULT_LIGHT_CHANNELS ||
+    lightFalloffExponentOf(lights.falloffExponents?.[light]) > 0
   );
 }
 
@@ -665,6 +688,12 @@ export function writeLightRecord(
   out[at + LIGHT_RECORD.iesAxisY] = floatBits(axes?.[light * 3 + 1] ?? 0);
   out[at + LIGHT_RECORD.iesAxisZ] = floatBits(axes?.[light * 3 + 2] ?? 0);
   out[at + LIGHT_RECORD.channels] = floatBits(lightChannelsOf(lights.channels?.[light]));
+  out[at + LIGHT_RECORD.falloffExponent] = floatBits(
+    lightFalloffExponentOf(lights.falloffExponents?.[light]),
+  );
+  out[at + LIGHT_RECORD.barnDoorCos] = 0;
+  out[at + LIGHT_RECORD.barnDoorLength] = 0;
+  out[at + LIGHT_RECORD.barnDoorLength + 1] = 0;
 }
 
 /**
@@ -677,9 +706,9 @@ function areaSlot(lights: ClusterLightSet, light: number): number {
 
 /**
  * A rectangle's record, which the shader tells from a lamp's by its **negative radius** — its
- * reach, negated — and reads to its fifth texel: sidedness where a lamp keeps its shadow slot,
+ * reach, negated — and reads to its sixth texel: sidedness where a lamp keeps its shadow slot,
  * the right axis where a spot keeps its direction, the half extents where its cone is, the up
- * axis where the azimuth is, and the channels last. Never shadowed: a rectangle's occlusion is
+ * axis where the azimuth is, the channels, and the barn doors in the sixth. Never shadowed: a rectangle's occlusion is
  * the fixed arm's, which is why the first `maxAreaLights` stay there.
  */
 function writeAreaRecord(
@@ -715,6 +744,10 @@ function writeAreaRecord(
   out[at + LIGHT_RECORD.iesAxisY] = floatBits(up?.[a * 3 + 1] ?? 1);
   out[at + LIGHT_RECORD.iesAxisZ] = floatBits(up?.[a * 3 + 2] ?? 0);
   out[at + LIGHT_RECORD.channels] = floatBits(DEFAULT_LIGHT_CHANNELS);
+  out[at + LIGHT_RECORD.falloffExponent] = 0;
+  out[at + LIGHT_RECORD.barnDoorCos] = floatBits(areas?.barnDoors?.[a * 2] ?? 0);
+  out[at + LIGHT_RECORD.barnDoorLength] = floatBits(areas?.barnDoors?.[a * 2 + 1] ?? 0);
+  out[at + LIGHT_RECORD.barnDoorLength + 1] = 0;
 }
 
 /** A clustered rectangle's reach, which its record carries negated. See `AreaLightSource.range`. */

package/src/render/displayRange.ts

@@ -0,0 +1,61 @@
+/**
+ * Which dynamic range the frame goes out in, and why: the one decision behind
+ * `RenderQuality.highDynamicRange`, made here so both backends answer it in the same words.
+ *
+ * **A high range is asked for, found, and held, or it is not had.** Three things must all be true:
+ * the profile asked; the frame has a composite holding light past white (`screenEffects` and
+ * `hdrScene`), since every other pass writes display values already clipped; and the display says
+ * it can show more than paper white. The backend then has to be able to configure such a canvas,
+ * which only it knows, and it may still answer standard after this says high.
+ *
+ * **What a high range gives up** is nothing a standard frame had: paper white stays where it is,
+ * and only what was above it — a lamp, a flash, a sunlit edge — goes on rising to the display's
+ * peak instead of rolling off at white. **What would make it wrong** is a display that reports a
+ * high range it cannot show, which a page cannot detect and the platform owns.
+ */
+
+export type DisplayRange = 'high' | 'standard';
+
+export interface DisplayRangeChoice {
+  readonly range: DisplayRange;
+  /** A sentence saying why, for `RendererApi.displayRangeReason`. */
+  readonly reason: string;
+}
+
+/** The display's own answer, as the browser gives it. A host without a DOM supplies its own. */
+export function browserHighDynamicRange(): boolean {
+  // platform: browser default — `CreateRendererOptions.highDynamicRangeDisplay` replaces it
+  return typeof matchMedia === 'function' && matchMedia('(dynamic-range: high)').matches;
+}
+
+/** The range a profile gets on a display, before the backend has tried to configure it. */
+export function chooseDisplayRange(
+  asked: boolean,
+  composite: boolean,
+  displayIsHigh: boolean,
+): DisplayRangeChoice {
+  if (!asked) return { range: 'standard', reason: 'highDynamicRange was not asked for' };
+  if (!composite) {
+    return {
+      range: 'standard',
+      reason:
+        'highDynamicRange needs screenEffects and hdrScene: without a composite holding light ' +
+        'past white, every pass writes values already clipped to it',
+    };
+  }
+  if (!displayIsHigh) {
+    return { range: 'standard', reason: 'the display reports a standard dynamic range' };
+  }
+  return { range: 'high', reason: 'an extended-range canvas on a high dynamic range display' };
+}
+
+/**
+ * The display's peak over the frame's paper white, as `setDisplayLuminance` is handed it: at
+ * least 1, and 1 where the range is standard or a number is not one. Capped at 64, a thousand nits
+ * over a sixteen-nit white, which no display reaches and no curve should be asked to.
+ */
+export function displayHeadroom(range: DisplayRange, paperWhite: number, peak: number): number {
+  if (range !== 'high') return 1;
+  const ratio = peak / paperWhite;
+  return Number.isFinite(ratio) ? Math.min(Math.max(ratio, 1), 64) : 1;
+}

package/src/render/driftLight/bake.ts

@@ -32,6 +32,8 @@ export interface FieldLight extends LightReach {
   readonly b: number;
   /** The emitter's physical radius, which widens its penumbra. */
   readonly sourceRadius: number;
+  /** Its own falloff exponent, overriding the frame's above zero. See `pointLightShape`. */
+  readonly falloffExponent?: number;
 }
 
 /**
@@ -115,7 +117,7 @@ export function sampleFieldLight(
     const dz = source.z - pz;
     const dist = Math.hypot(dx, dy, dz);
     if (dist >= source.radius) continue;
-    const shape = pointLightShape(dist, source.radius, falloff);
+    const shape = pointLightShape(dist, source.radius, falloff, source.falloffExponent);
     if (shape <= 0) continue;
     const seen =
       distance === null

package/src/render/driftLight/falloff.ts

@@ -9,13 +9,24 @@
  *
  * Both of the renderer's falloffs: `smooth`, the default, is a linear ramp squared, reaching zero at
  * the radius; `inverseSquare` is physical, windowed so it still reaches zero at the radius, and
- * floored at ten centimetres so a surface touching a light is not infinitely bright.
+ * floored at ten centimetres so a surface touching a light is not infinitely bright. And a light's
+ * own, which overrides both: `(1 - (d/R)^2)^n` with no distance term, for an exponent `n` above zero
+ * (`PointLightSource.falloffExponent`).
  */
 
 export type PointLightFalloff = 'smooth' | 'inverseSquare';
 
 /** The shader's `shape` for an unshaped point light: no cone, no photometric profile. */
-export function pointLightShape(dist: number, radius: number, falloff: PointLightFalloff): number {
+export function pointLightShape(
+  dist: number,
+  radius: number,
+  falloff: PointLightFalloff,
+  exponent = 0,
+): number {
+  if (exponent > 0) {
+    const reach = dist / Math.max(radius, 1e-4);
+    return Math.min(1, Math.max(0, 1 - reach * reach)) ** exponent;
+  }
   if (falloff === 'inverseSquare') {
     const ratio = dist / Math.max(radius, 1e-4);
     const window = Math.min(1, Math.max(0, 1 - ratio ** 4));

package/src/render/filmicCurve.ts

@@ -0,0 +1,229 @@
+/**
+ * The `filmic` output transform: a parametric film curve, its five numbers, and the eight
+ * constants the resolve reads, decided once here for both backends.
+ *
+ * **Why a second filmic curve beside `aces`.** `aces` is the reference RRT and ODT fit, which
+ * holds a mid grey of 0.18 at about 0.11 of display linear: graded for a dark cinema and kept dark.
+ * The curve here holds 0.18 at 0.18 by construction, and is shaped by five numbers a grading
+ * volume carries — a slope through mid grey, a toe and a shoulder, and how far black and white are
+ * clipped past the ends — so a look authored against such a curve is matched by passing its numbers
+ * rather than by baking the difference into a colour lookup table, which has the fewest steps
+ * exactly where two curves differ most: in the shadows.
+ *
+ * **What the curve is.** In the ACEScg working space, after the ACES reference's glow and red
+ * modifier and a 4% desaturation: a straight line of `slope` through mid grey in log10, joined to a
+ * logistic toe below `toeMatch` and a logistic shoulder above `shoulderMatch`, blended by a smooth
+ * step between the two, then desaturated by 7% and taken back to linear sRGB. The toe's position is
+ * solved so that 0.18 in is 0.18 out.
+ *
+ * **What it gives up.** It needs the composite to grade: `screenEffects` and `hdrScene`, since the
+ * forward passes that grade a frame without one carry two uniforms between them and not eight.
+ * Without them every pass grades with `aces` and the renderer says so once at construction.
+ * **What would make it wrong** is a profile wanting this curve without a scene target, which would
+ * then pay six floats in every forward program to have it.
+ */
+
+/** A film curve's five numbers, as a grading volume states them. */
+export interface FilmicCurve {
+  /** The straight segment's slope in log10, through mid grey. Positive. */
+  readonly slope: number;
+  /** How much of the curve below mid grey the toe takes, 0 to 1. Larger is a longer, softer toe. */
+  readonly toe: number;
+  /** How much of the curve above mid grey the shoulder takes, 0 to 1. Larger rolls off sooner. */
+  readonly shoulder: number;
+  /** How far below 0 the toe's asymptote sits: 0 holds black at black, more crushes it. */
+  readonly blackClip: number;
+  /** How far above 1 the shoulder's asymptote sits: 0 never reaches white, more lets it clip. */
+  readonly whiteClip: number;
+}
+
+/** The defaults the curve ships with where a volume states nothing. */
+export const DEFAULT_FILMIC_CURVE: FilmicCurve = {
+  slope: 0.88,
+  toe: 0.55,
+  shoulder: 0.26,
+  blackClip: 0,
+  whiteClip: 0.04,
+};
+
+/** How many floats `resolveFilmicCurve` fills: two vectors of the resolve's uniforms. */
+export const FILMIC_CONSTANTS = 8;
+
+/** Mid grey, which the curve takes to itself. */
+const MID_GREY = 0.18;
+
+/** The largest toe or shoulder kept: at 1 the toe's or the shoulder's scale is zero. */
+const MOST = 0.999;
+/** The shallowest slope kept, which is still a curve rather than a flat line. */
+const LEAST_SLOPE = 0.01;
+
+/**
+ * The eight constants the resolve reads, into `out`: `uFilmA` = (slope, black clip, white clip,
+ * toe scale) and `uFilmB` = (shoulder scale, toe match, straight match, shoulder match). Returns
+ * whether any of the five numbers had to be brought into range.
+ *
+ * Here rather than in the shader, because they are one solve a curve and would be one per pixel
+ * there. **Clamped rather than refused**, because a grading volume is set from inside a frame and
+ * the frame loop never throws: a slope below 0.01, a toe, shoulder or clip outside 0 to 1, and a
+ * toe or shoulder of exactly 1 — whose scale is then zero and divides the curve by it — are each
+ * a picture made of NaN otherwise. A number that is not finite takes the default's. The renderer
+ * says once when anything was clamped.
+ */
+export function resolveFilmicCurve(
+  curve: FilmicCurve,
+  out: Float32Array,
+  /**
+   * The display's peak over paper white (`displayHeadroom`), 1 for a standard range. Above 1 the
+   * white clip is raised by the difference, so the shoulder rolls off toward the display's peak
+   * rather than toward white, and the toe and mid grey stay exactly where they were.
+   */
+  headroom = 1,
+): boolean {
+  let clamped = false;
+  const within = (value: number, low: number, high: number, fallback: number): number => {
+    const finite = Number.isFinite(value) ? value : fallback;
+    const kept = Math.min(Math.max(finite, low), high);
+    if (kept !== value) clamped = true;
+    return kept;
+  };
+  const slope = within(curve.slope, LEAST_SLOPE, Number.MAX_VALUE, DEFAULT_FILMIC_CURVE.slope);
+  const toe = within(curve.toe, 0, MOST, DEFAULT_FILMIC_CURVE.toe);
+  const shoulder = within(curve.shoulder, 0, MOST, DEFAULT_FILMIC_CURVE.shoulder);
+  const blackClip = within(curve.blackClip, 0, 1, DEFAULT_FILMIC_CURVE.blackClip);
+  const whiteClip =
+    within(curve.whiteClip, 0, 1, DEFAULT_FILMIC_CURVE.whiteClip) + Math.max(headroom, 1) - 1;
+  const toeScale = 1 + blackClip - toe;
+  const shoulderScale = 1 + whiteClip - shoulder;
+  let toeMatch: number;
+  if (toe > 0.8) {
+    /* Mid grey falls on the straight segment. */
+    toeMatch = (1 - toe - MID_GREY) / slope + Math.log10(MID_GREY);
+  } else {
+    /* Mid grey falls on the toe: solve the toe's logistic for 0.18 in, 0.18 out. */
+    const bt = (MID_GREY + blackClip) / toeScale - 1;
+    toeMatch = Math.log10(MID_GREY) - 0.5 * Math.log((1 + bt) / (1 - bt)) * (toeScale / slope);
+  }
+  const straightMatch = (1 - toe) / slope - toeMatch;
+  const shoulderMatch = shoulder / slope - straightMatch;
+  out[0] = slope;
+  out[1] = blackClip;
+  out[2] = whiteClip;
+  out[3] = toeScale;
+  out[4] = shoulderScale;
+  out[5] = toeMatch;
+  out[6] = straightMatch;
+  out[7] = shoulderMatch;
+  return clamped;
+}
+
+/** Said once a renderer, the first time `setFilmicCurve` was handed a number out of range. */
+export const FILMIC_CLAMPED =
+  '[driftengine] setFilmicCurve was handed a number outside its range — a slope under 0.01, a ' +
+  'toe, shoulder or clip outside 0 to 1, or one that is not a number — and drew with it clamped.';
+
+/**
+ * Said once at construction where `filmic` was asked for and the frame has no composite that
+ * grades: the passes grade with `aces`, which is the nearest curve they carry.
+ */
+export const FILMIC_WITHOUT_COMPOSITE =
+  "[driftengine] outputTransform 'filmic' is applied by the composite, which grades only with " +
+  "`screenEffects` and `hdrScene` both on: without them every pass grades itself, with 'aces'.";
+
+/**
+ * `filmicCurve(c)`: linear sRGB in, display-linear sRGB out, clamped to 0 to 1 — or, on a high
+ * range display, to the shoulder's own asymptote. Reads `uFilmA`, `uFilmB` and `uDisplayHeadroom`,
+ * which the including stage declares. The ACES helpers are the reference's own:
+ * saturation, `yc`, the glow's sigmoid, and hue in degrees.
+ */
+export const FILMIC_GLSL = `
+/* sRGB to ACEScg (through D60), ACEScg back, and ACEScg to and from ACES2065-1. Columns. */
+const mat3 FILM_SRGB_TO_AP1 = mat3(
+  0.61319, 0.07021, 0.02062,
+  0.33951, 0.91634, 0.10957,
+  0.04737, 0.01345, 0.86961
+);
+/* The inverse of the one above, computed rather than copied, so a round trip is the identity. */
+const mat3 FILM_AP1_TO_SRGB = mat3(
+   1.70480, -0.13027, -0.02401,
+  -0.62168,  1.14082, -0.12900,
+  -0.08325, -0.01055,  1.15324
+);
+const mat3 FILM_AP1_TO_AP0 = mat3(
+   0.6954522414, 0.0447945634, -0.0055258826,
+   0.1406786965, 0.8596711185,  0.0040252103,
+   0.1638690622, 0.0955343182,  1.0015006723
+);
+const mat3 FILM_AP0_TO_AP1 = mat3(
+   1.4514393161, -0.0765537734,  0.0083161484,
+  -0.2365107469,  1.1762296998, -0.0060324498,
+  -0.2149285693, -0.0996759264,  0.9977163014
+);
+const vec3 FILM_AP1_LUMA = vec3(0.2722287168, 0.6740817658, 0.0536895174);
+
+float filmSaturation(vec3 c) {
+  float hi = max(c.r, max(c.g, c.b));
+  float lo = min(c.r, min(c.g, c.b));
+  return (max(hi, 1e-10) - max(lo, 1e-10)) / max(hi, 1e-2);
+}
+
+float filmYc(vec3 c) {
+  float chroma = sqrt(max(c.b * (c.b - c.g) + c.g * (c.g - c.r) + c.r * (c.r - c.b), 0.0));
+  return (c.b + c.g + c.r + 1.75 * chroma) / 3.0;
+}
+
+float filmSigmoid(float x) {
+  float t = max(1.0 - abs(x / 2.0), 0.0);
+  return (1.0 + sign(x) * (1.0 - t * t)) / 2.0;
+}
+
+float filmGlow(float yc, float gain, float mid) {
+  if (yc <= 2.0 / 3.0 * mid) return gain;
+  if (yc >= 2.0 * mid) return 0.0;
+  return gain * (mid / yc - 0.5);
+}
+
+/* Hue in degrees, -180 to 180 about red; 0 for a grey, which then takes no red modifier. */
+float filmCentredHue(vec3 c) {
+  float y = sqrt(3.0) * (c.g - c.b);
+  float x = 2.0 * c.r - c.g - c.b;
+  if (abs(x) < 1e-10 && abs(y) < 1e-10) return 0.0;
+  return degrees(atan(y, x));
+}
+
+vec3 filmicCurve(vec3 linear) {
+  vec3 ap0 = FILM_AP1_TO_AP0 * (FILM_SRGB_TO_AP1 * linear);
+  /* The reference's glow, lifting dark saturated colours a little. */
+  float saturation = filmSaturation(ap0);
+  ap0 *= 1.0 + filmGlow(filmYc(ap0), 0.05 * filmSigmoid((saturation - 0.4) / 0.2), 0.08);
+  /* And its red modifier, pulling saturated reds toward a pivot so they do not run to orange. */
+  float weight = smoothstep(0.0, 1.0, 1.0 - abs(2.0 * filmCentredHue(ap0) / 135.0));
+  ap0.r += weight * weight * saturation * (0.03 - ap0.r) * (1.0 - 0.82);
+  vec3 work = max(FILM_AP0_TO_AP1 * ap0, vec3(0.0));
+  work = mix(vec3(dot(work, FILM_AP1_LUMA)), work, 0.96);
+
+  float slope = uFilmA.x;
+  float black = uFilmA.y;
+  float white = uFilmA.z;
+  float toeScale = uFilmA.w;
+  float shoulderScale = uFilmB.x;
+  float toeMatch = uFilmB.y;
+  float straightMatch = uFilmB.z;
+  float shoulderMatch = uFilmB.w;
+  /* log10, through log2: GLSL ES has no log10. */
+  vec3 logc = log2(max(work, vec3(1e-10))) * 0.30102999566;
+  vec3 straight = slope * (logc + straightMatch);
+  vec3 toeC = -black + (2.0 * toeScale) / (1.0 + exp((-2.0 * slope / toeScale) * (logc - toeMatch)));
+  vec3 shoulderC =
+    (1.0 + white) - (2.0 * shoulderScale) / (1.0 + exp((2.0 * slope / shoulderScale) * (logc - shoulderMatch)));
+  toeC = mix(straight, toeC, vec3(lessThan(logc, vec3(toeMatch))));
+  shoulderC = mix(straight, shoulderC, vec3(greaterThan(logc, vec3(shoulderMatch))));
+  vec3 t = clamp((logc - toeMatch) / (shoulderMatch - toeMatch), 0.0, 1.0);
+  if (shoulderMatch < toeMatch) t = 1.0 - t;
+  t = (3.0 - 2.0 * t) * t * t;
+  vec3 tone = mix(toeC, shoulderC, t);
+  tone = mix(vec3(dot(tone, FILM_AP1_LUMA)), tone, 0.93);
+  /* White is the ceiling on a standard display; on a high range one the shoulder's asymptote is. */
+  float ceiling = uDisplayHeadroom > 1.0 ? 1.0 + white : 1.0;
+  return clamp(FILM_AP1_TO_SRGB * max(tone, vec3(0.0)), 0.0, ceiling);
+}
+`;