@driftengine/core 4.8.7 → 4.9.0

package/dist/render/displayRange.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 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 declare function browserHighDynamicRange(): boolean;
+/** The range a profile gets on a display, before the backend has tried to configure it. */
+export declare function chooseDisplayRange(asked: boolean, composite: boolean, displayIsHigh: boolean): DisplayRangeChoice;
+/**
+ * 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 declare function displayHeadroom(range: DisplayRange, paperWhite: number, peak: number): number;

package/dist/render/displayRange.js

@@ -0,0 +1,47 @@
+/**
+ * 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.
+ */
+/** The display's own answer, as the browser gives it. A host without a DOM supplies its own. */
+export function browserHighDynamicRange() {
+    // 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, composite, displayIsHigh) {
+    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, paperWhite, peak) {
+    if (range !== 'high')
+        return 1;
+    const ratio = peak / paperWhite;
+    return Number.isFinite(ratio) ? Math.min(Math.max(ratio, 1), 64) : 1;
+}

package/dist/render/filmicCurve.d.ts

@@ -0,0 +1,74 @@
+/**
+ * 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 declare const DEFAULT_FILMIC_CURVE: FilmicCurve;
+/** How many floats `resolveFilmicCurve` fills: two vectors of the resolve's uniforms. */
+export declare const FILMIC_CONSTANTS = 8;
+/**
+ * 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 declare 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?: number): boolean;
+/** Said once a renderer, the first time `setFilmicCurve` was handed a number out of range. */
+export declare const FILMIC_CLAMPED: string;
+/**
+ * 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 declare const FILMIC_WITHOUT_COMPOSITE: string;
+/**
+ * `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 declare const FILMIC_GLSL = "\n/* sRGB to ACEScg (through D60), ACEScg back, and ACEScg to and from ACES2065-1. Columns. */\nconst mat3 FILM_SRGB_TO_AP1 = mat3(\n  0.61319, 0.07021, 0.02062,\n  0.33951, 0.91634, 0.10957,\n  0.04737, 0.01345, 0.86961\n);\n/* The inverse of the one above, computed rather than copied, so a round trip is the identity. */\nconst mat3 FILM_AP1_TO_SRGB = mat3(\n   1.70480, -0.13027, -0.02401,\n  -0.62168,  1.14082, -0.12900,\n  -0.08325, -0.01055,  1.15324\n);\nconst mat3 FILM_AP1_TO_AP0 = mat3(\n   0.6954522414, 0.0447945634, -0.0055258826,\n   0.1406786965, 0.8596711185,  0.0040252103,\n   0.1638690622, 0.0955343182,  1.0015006723\n);\nconst mat3 FILM_AP0_TO_AP1 = mat3(\n   1.4514393161, -0.0765537734,  0.0083161484,\n  -0.2365107469,  1.1762296998, -0.0060324498,\n  -0.2149285693, -0.0996759264,  0.9977163014\n);\nconst vec3 FILM_AP1_LUMA = vec3(0.2722287168, 0.6740817658, 0.0536895174);\n\nfloat filmSaturation(vec3 c) {\n  float hi = max(c.r, max(c.g, c.b));\n  float lo = min(c.r, min(c.g, c.b));\n  return (max(hi, 1e-10) - max(lo, 1e-10)) / max(hi, 1e-2);\n}\n\nfloat filmYc(vec3 c) {\n  float chroma = sqrt(max(c.b * (c.b - c.g) + c.g * (c.g - c.r) + c.r * (c.r - c.b), 0.0));\n  return (c.b + c.g + c.r + 1.75 * chroma) / 3.0;\n}\n\nfloat filmSigmoid(float x) {\n  float t = max(1.0 - abs(x / 2.0), 0.0);\n  return (1.0 + sign(x) * (1.0 - t * t)) / 2.0;\n}\n\nfloat filmGlow(float yc, float gain, float mid) {\n  if (yc <= 2.0 / 3.0 * mid) return gain;\n  if (yc >= 2.0 * mid) return 0.0;\n  return gain * (mid / yc - 0.5);\n}\n\n/* Hue in degrees, -180 to 180 about red; 0 for a grey, which then takes no red modifier. */\nfloat filmCentredHue(vec3 c) {\n  float y = sqrt(3.0) * (c.g - c.b);\n  float x = 2.0 * c.r - c.g - c.b;\n  if (abs(x) < 1e-10 && abs(y) < 1e-10) return 0.0;\n  return degrees(atan(y, x));\n}\n\nvec3 filmicCurve(vec3 linear) {\n  vec3 ap0 = FILM_AP1_TO_AP0 * (FILM_SRGB_TO_AP1 * linear);\n  /* The reference's glow, lifting dark saturated colours a little. */\n  float saturation = filmSaturation(ap0);\n  ap0 *= 1.0 + filmGlow(filmYc(ap0), 0.05 * filmSigmoid((saturation - 0.4) / 0.2), 0.08);\n  /* And its red modifier, pulling saturated reds toward a pivot so they do not run to orange. */\n  float weight = smoothstep(0.0, 1.0, 1.0 - abs(2.0 * filmCentredHue(ap0) / 135.0));\n  ap0.r += weight * weight * saturation * (0.03 - ap0.r) * (1.0 - 0.82);\n  vec3 work = max(FILM_AP0_TO_AP1 * ap0, vec3(0.0));\n  work = mix(vec3(dot(work, FILM_AP1_LUMA)), work, 0.96);\n\n  float slope = uFilmA.x;\n  float black = uFilmA.y;\n  float white = uFilmA.z;\n  float toeScale = uFilmA.w;\n  float shoulderScale = uFilmB.x;\n  float toeMatch = uFilmB.y;\n  float straightMatch = uFilmB.z;\n  float shoulderMatch = uFilmB.w;\n  /* log10, through log2: GLSL ES has no log10. */\n  vec3 logc = log2(max(work, vec3(1e-10))) * 0.30102999566;\n  vec3 straight = slope * (logc + straightMatch);\n  vec3 toeC = -black + (2.0 * toeScale) / (1.0 + exp((-2.0 * slope / toeScale) * (logc - toeMatch)));\n  vec3 shoulderC =\n    (1.0 + white) - (2.0 * shoulderScale) / (1.0 + exp((2.0 * slope / shoulderScale) * (logc - shoulderMatch)));\n  toeC = mix(straight, toeC, vec3(lessThan(logc, vec3(toeMatch))));\n  shoulderC = mix(straight, shoulderC, vec3(greaterThan(logc, vec3(shoulderMatch))));\n  vec3 t = clamp((logc - toeMatch) / (shoulderMatch - toeMatch), 0.0, 1.0);\n  if (shoulderMatch < toeMatch) t = 1.0 - t;\n  t = (3.0 - 2.0 * t) * t * t;\n  vec3 tone = mix(toeC, shoulderC, t);\n  tone = mix(vec3(dot(tone, FILM_AP1_LUMA)), tone, 0.93);\n  /* White is the ceiling on a standard display; on a high range one the shoulder's asymptote is. */\n  float ceiling = uDisplayHeadroom > 1.0 ? 1.0 + white : 1.0;\n  return clamp(FILM_AP1_TO_SRGB * max(tone, vec3(0.0)), 0.0, ceiling);\n}\n";

package/dist/render/filmicCurve.js

@@ -0,0 +1,203 @@
+/**
+ * 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.
+ */
+/** The defaults the curve ships with where a volume states nothing. */
+export const DEFAULT_FILMIC_CURVE = {
+    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, out, 
+/**
+ * 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) {
+    let clamped = false;
+    const within = (value, low, high, fallback) => {
+        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;
+    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/dist/render/fog.d.ts

@@ -36,7 +36,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;
 }

package/dist/render/fog.js

@@ -62,13 +62,23 @@ export function mediumFog(fog, dist, pointY) {
         const wetLinear = fog.underwaterDensity * dist;
         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

package/dist/render/frame/resources.d.ts

@@ -9,9 +9,9 @@
  * A mask is a `number` and not a bitset object. Thirty-one bits is more than the table needs,
  * a number compares and combines in one instruction, and the scheduler does this per node.
  */
-export declare const FRAME_RESOURCES: readonly ['sceneColor', 'sceneDepth', 'canvas', 'cascade0', 'cascade1', 'cascade2', 'pointShadows', 'probeCube', 'mirrorColor', 'mirrorDepth', 'bloomChain', 'aoTarget', 'depthSnapshot', 'inset'];
+export declare const FRAME_RESOURCES: readonly ['sceneColor', 'sceneDepth', 'canvas', 'cascade0', 'cascade1', 'cascade2', 'pointShadows', 'probeCube', 'mirrorColor', 'mirrorDepth', 'bloomChain', 'aoTarget', 'depthSnapshot', 'inset', 'colorSnapshot'];
 export type FrameResource = (typeof FRAME_RESOURCES)[number];
-export declare const RESOURCE_COUNT: 14;
+export declare const RESOURCE_COUNT: 15;
 /** The single bit that stands for one resource. */
 export declare function resourceBit(name: FrameResource): number;
 /** A mask of the named resources, for declaring what a node reads or writes. */

package/dist/render/frame/resources.js

@@ -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',
 ];
 export const RESOURCE_COUNT = FRAME_RESOURCES.length;
 const BITS = new Map(FRAME_RESOURCES.map((name, i) => [name, 1 << i]));

package/dist/render/frameReflections.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 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 declare const DEFAULT_FRAME_REFLECTIONS: ResolvedFrameReflections;
+/**
+ * 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 declare function resolveFrameReflections(asked: boolean | FrameReflections | undefined): ResolvedFrameReflections | null;
+/** What a renderer says once where the frame cannot carry these reflections, and why. */
+export declare function frameReflectionsRefused(reason: string): string;

package/dist/render/frameReflections.js

@@ -0,0 +1,48 @@
+/**
+ * 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.
+ */
+/** The march `ReflectiveSurface` defaults to, a ceiling at satin, and a smear of 3% of the frame. */
+export const DEFAULT_FRAME_REFLECTIONS = Object.freeze({
+    maxRoughness: 0.6,
+    reachM: 8,
+    thicknessM: 0.25,
+    steps: 24,
+    blur: 0.03,
+});
+const finite = (value, fallback) => 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) {
+    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) {
+    return (`screenSpaceReflections is not drawn: ${reason}. Surfaces keep the probes' reflection; ` +
+        'the trace needs `screenEffects` and `hdrScene`, and a frame of one sample.');
+}

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