@driftengine/core 4.8.7 → 4.9.0

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/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);
+}
+`;

package/src/render/fog.ts

@@ -40,7 +40,10 @@ export interface FogOptions {
   readonly underwaterFactor: number;
   /** `MEDIUM_FOG` integrates a medium; `LINEAR_FOG` ramps between near and far. */
   readonly mode: number;
-  /** Linear mode only: where haze begins, and where it is total. */
+  /**
+   * Where haze begins: the ramp's start in linear mode, and in the medium the distance along the
+   * ray it is integrated from (`Atmosphere.fogStart`), 0 at the camera.
+   */
   readonly near: number;
   readonly far: number;
 }
@@ -88,13 +91,26 @@ export function mediumFog(fog: FogOptions, dist: number, pointY: number): number
     return mix(ramp, 1 - Math.pow(2, -wetLinear * wetLinear * 1.442695), fog.underwaterFactor);
   }
 
+  /*
+   * **Where the medium begins along the ray**, `near` — the linear mode's slot, which this mode
+   * never read before `Atmosphere.fogStart`. The ray is integrated from that point on: the density
+   * there, carried over what is left of the ray. At a start of 0 every term below is the one it
+   * always was, so a world that sets none draws the same bits.
+   */
+  const start = Math.min(fog.near, dist);
+  const before = dist > 0 ? start / dist : 0;
   const t = (pointY - fog.eyeY) * fog.heightFalloff;
+  const rest = t * (1 - before);
   /*
    * `(1 - e^-t)/t`, which tends to 1 as the ray levels out. **Guarded rather than branched**: at
    * `t = 0` the quotient is 0/0, and 1e-4 of a scale height is 8 mm.
    */
-  const denom = Math.abs(t) < 1e-4 ? 1e-4 : t;
-  const air = 1 - Math.exp((-fog.density * dist * (1 - Math.exp(-denom))) / denom);
+  const denom = Math.abs(rest) < 1e-4 ? 1e-4 : rest;
+  const air =
+    1 -
+    Math.exp(
+      (-fog.density * Math.exp(-t * before) * (dist - start) * (1 - Math.exp(-denom))) / denom,
+    );
   if (fog.underwaterFactor <= 0) return air;
   /* Water is its own medium and keeps its own curve, so crossing the surface changes nothing
      about how the water column reads. */

package/src/render/frame/resources.ts

@@ -30,6 +30,12 @@ export const FRAME_RESOURCES = [
   'aoTarget',
   'depthSnapshot',
   'inset',
+  /*
+   * The frame's colour as a registered pass reads it: a copy taken at that pass's draw, so reading
+   * it constrains no attachment's store, as `depthSnapshot` does not. Last, so no bit before it
+   * moved when it arrived.
+   */
+  'colorSnapshot',
 ] as const;
 
 export type FrameResource = (typeof FRAME_RESOURCES)[number];

package/src/render/frameReflections.ts

@@ -0,0 +1,72 @@
+/**
+ * Reflections traced through the frame's own materials: `RenderQuality.screenSpaceReflections`.
+ *
+ * **Every opaque lit surface reflects the frame by its own material**, where `ReflectiveSurface`
+ * reflects it by a box's: the lit stage leaves, per pixel, how much of the environment it showed and
+ * at what roughness (`shaders/flat/reflectionSurface.ts`), and a ray marched against the frame's
+ * depth swaps that share for what it finds — so a glossy panel mirrors the figures on it and the
+ * matte panel beside it barely does, in one mesh with one material map. Past `maxRoughness` a
+ * surface keeps the probes' reflection alone, which is what a march cannot do better than: a rough
+ * lobe wants many rays, and one ray blurred is only a fair stand-in for a narrow one.
+ *
+ * **What a surface reflects is what the lit stage already reflected**: a metal by its metalness, a
+ * dielectric where `setSurfaceReflectivity` or its material asks for one. A surface that reflects
+ * no environment reflects no frame either, which is what keeps the two from disagreeing.
+ */
+
+/** How the frame's materials reflect it. Every field optional; see `DEFAULT_FRAME_REFLECTIONS`. */
+export interface FrameReflections {
+  /** The roughness past which a surface reflects the probes alone, faded over the last quarter. */
+  readonly maxRoughness?: number;
+  /** How far a ray travels before it gives up, in metres. */
+  readonly reachM?: number;
+  /** How deep a depth sample is believed to be, in metres. See `ScreenSpaceMarch.thicknessM`. */
+  readonly thicknessM?: number;
+  /** Samples along a ray, at most 32. */
+  readonly steps?: number;
+  /** How far a fully rough reflection is smeared, as a share of the frame's height. */
+  readonly blur?: number;
+}
+
+export type ResolvedFrameReflections = Required<FrameReflections>;
+
+/** The march `ReflectiveSurface` defaults to, a ceiling at satin, and a smear of 3% of the frame. */
+export const DEFAULT_FRAME_REFLECTIONS: ResolvedFrameReflections = Object.freeze({
+  maxRoughness: 0.6,
+  reachM: 8,
+  thicknessM: 0.25,
+  steps: 24,
+  blur: 0.03,
+});
+
+const finite = (value: number | undefined, fallback: number): number =>
+  value !== undefined && Number.isFinite(value) ? value : fallback;
+
+/**
+ * The option as the renderers read it: null where it is off, and every number held where the
+ * shader can use it — a ceiling above zero, a reach and a thickness above zero, a whole number of
+ * steps from 1 to 32, and a blur from none to a fifth of the frame. Clamped rather than refused,
+ * since a quality option is read at construction and a renderer that threw there would draw nothing.
+ */
+export function resolveFrameReflections(
+  asked: boolean | FrameReflections | undefined,
+): ResolvedFrameReflections | null {
+  if (asked === undefined || asked === false) return null;
+  const given = asked === true ? {} : asked;
+  const d = DEFAULT_FRAME_REFLECTIONS;
+  return {
+    maxRoughness: Math.min(Math.max(finite(given.maxRoughness, d.maxRoughness), 0.01), 1),
+    reachM: Math.max(finite(given.reachM, d.reachM), 0.01),
+    thicknessM: Math.max(finite(given.thicknessM, d.thicknessM), 0.001),
+    steps: Math.min(Math.max(Math.round(finite(given.steps, d.steps)), 1), 32),
+    blur: Math.min(Math.max(finite(given.blur, d.blur), 0), 0.2),
+  };
+}
+
+/** What a renderer says once where the frame cannot carry these reflections, and why. */
+export function frameReflectionsRefused(reason: string): string {
+  return (
+    `screenSpaceReflections is not drawn: ${reason}. Surfaces keep the probes' reflection; ` +
+    'the trace needs `screenEffects` and `hdrScene`, and a frame of one sample.'
+  );
+}

package/src/render/pass.ts

@@ -119,7 +119,23 @@ export type PassContext = {
   /** The exposure that goes with it. 1 where the composite will apply the real one. */
   readonly outputExposure: number;
 } & (
-  | { readonly backend: 'webgl2'; readonly gl: WebGL2RenderingContext }
+  | {
+      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;
@@ -217,6 +233,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;
     };
 
 /**

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;
+  }
+}