@driftengine/core 4.8.6 → 4.9.0

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/gi/bounceLights.d.ts

@@ -26,9 +26,10 @@ import type { PointLightSet } from '../lightBudget.ts';
 export declare const MAX_BOUNCE_LIGHTS = 32;
 /**
  * Floats a light takes: where it is and how far it reaches; its colour at its weight and the cosine
- * of its inner cone; the way it points and the cosine of its outer cone.
+ * of its inner cone; the way it points and the cosine of its outer cone; and its own falloff
+ * exponent, 0 for the frame's, in a fourth row of its own (`PointLightSource.falloffExponent`).
  */
-export declare const BOUNCE_LIGHT_FLOATS = 12;
+export declare const BOUNCE_LIGHT_FLOATS = 16;
 export declare function createBounceLights(): Float32Array;
 /** Pack the lights of `lights` the bounce reads into `out`, and answer how many. */
 export declare function resolveBounceLights(lights: PointLightSet | null, out: Float32Array): number;

package/dist/render/gi/bounceLights.js

@@ -21,14 +21,15 @@
  * What it gives up against the frame: a photometric profile and a cookie, which the bounce reads as
  * a plain cone, and a light's specular, which a diffuse bounce has no use for.
  */
-import { POINT_LIGHT_COS_INNER, POINT_LIGHT_COS_OUTER } from '../clusteredLights.js';
+import { POINT_LIGHT_COS_INNER, POINT_LIGHT_COS_OUTER, lightFalloffExponentOf, } from '../clusteredLights.js';
 /** Lights the probe bake shades a hit with. */
 export const MAX_BOUNCE_LIGHTS = 32;
 /**
  * Floats a light takes: where it is and how far it reaches; its colour at its weight and the cosine
- * of its inner cone; the way it points and the cosine of its outer cone.
+ * of its inner cone; the way it points and the cosine of its outer cone; and its own falloff
+ * exponent, 0 for the frame's, in a fourth row of its own (`PointLightSource.falloffExponent`).
  */
-export const BOUNCE_LIGHT_FLOATS = 12;
+export const BOUNCE_LIGHT_FLOATS = 16;
 export function createBounceLights() {
     return new Float32Array(MAX_BOUNCE_LIGHTS * BOUNCE_LIGHT_FLOATS);
 }
@@ -60,6 +61,10 @@ export function resolveBounceLights(lights, out) {
         out[at + 9] = lights.lightDirections?.[i * 3 + 1] ?? 0;
         out[at + 10] = lights.lightDirections?.[i * 3 + 2] ?? 0;
         out[at + 11] = lights.lightConeCos?.[i * 2 + 1] ?? POINT_LIGHT_COS_OUTER;
+        out[at + 12] = lightFalloffExponentOf(lights.lightFalloffExponents?.[i]);
+        out[at + 13] = 0;
+        out[at + 14] = 0;
+        out[at + 15] = 0;
         count++;
     }
     return count;

package/dist/render/instanceCull.js

@@ -51,6 +51,11 @@ export function cullInstances(data, local, frustum, out) {
             for (let k = 0; k < 4; k++)
                 out.lightmapRegions[kept * 4 + k] = regions[i * 4 + k];
         }
+        const cells = data.uvRegions;
+        if (cells !== undefined && out.uvRegions !== undefined) {
+            for (let k = 0; k < 4; k++)
+                out.uvRegions[kept * 4 + k] = cells[i * 4 + k];
+        }
         kept++;
     }
     out.count = kept;

package/dist/render/instances.d.ts

@@ -12,9 +12,9 @@
  *
  * **What it gives up** is a matrix per instance where a scatter spends five floats: 80 bytes
  * against 44, and no wind. **What would make it wrong** is a caller wanting per-instance
- * anything beyond an opacity — a morph weight, a texture cell — which wants another attribute,
- * and the sixteen WebGL2 guarantees are already spent. The opacity rides the float the stride was
- * padded with, which is why it costs nothing.
+ * anything beyond an opacity and a texture cell — a morph weight, say — which wants another
+ * attribute, and the sixteen WebGL2 guarantees are already spent. The opacity rides the float the
+ * stride was padded with and the cell the matrix's bottom row, which is why neither costs a byte.
  */
 export interface MeshInstances {
     /**
@@ -51,6 +51,20 @@ export interface MeshInstances {
      * either mismatch is said once on the console.
      */
     readonly lightmapRegions?: Float32Array;
+    /**
+     * Four floats each, the instance's cell of its texture: `[scaleU, scaleV, offsetU, offsetV]`,
+     * applied to the mesh's coordinates before the material's own scale and offset, in every pass
+     * that reads them — so one draw carries particles in different cells of a flipbook, or props
+     * wearing different tiles of one atlas. **Absent, or past `count`, is the whole texture**,
+     * `[1, 1, 0, 0]`, which is what every instance read before 4.8.7.
+     *
+     * **It rides the matrix's bottom row**, which an instance's placement — a turn, a scale and a
+     * move — leaves at `[0, 0, 0, 1]`, and which every stage drawing an instance rebuilds as that.
+     * So a placement must be affine, as every placement of a solid object is; a projective one is
+     * drawn as its affine part. A culled batch (`cullInstances`) carries the cells only into a
+     * target that has the array.
+     */
+    readonly uvRegions?: Float32Array;
     /** How many instances the arrays hold. Fixed at creation; the buffers are sized from it. */
     readonly capacity: number;
     /** How many are live. The rest of the buffer is neither uploaded nor drawn. */
@@ -65,8 +79,8 @@ export interface MeshInstances {
  */
 export declare function createMeshInstances(capacity: number): MeshInstances;
 /**
- * Floats one instance occupies in the interleaved vertex buffer: sixteen of matrix, three of
- * tint, and the opacity.
+ * Floats one instance occupies in the interleaved vertex buffer: sixteen of matrix, the bottom row
+ * of which carries the texture cell, three of tint, and the opacity.
  *
  * **Twenty so the stride is 80 bytes rather than 76.** A vertex buffer's stride must be a multiple
  * of four on both backends, which 76 already is — the twentieth float was padding for the

package/dist/render/instances.js

@@ -15,8 +15,8 @@ export function createMeshInstances(capacity) {
     };
 }
 /**
- * Floats one instance occupies in the interleaved vertex buffer: sixteen of matrix, three of
- * tint, and the opacity.
+ * Floats one instance occupies in the interleaved vertex buffer: sixteen of matrix, the bottom row
+ * of which carries the texture cell, three of tint, and the opacity.
  *
  * **Twenty so the stride is 80 bytes rather than 76.** A vertex buffer's stride must be a multiple
  * of four on both backends, which 76 already is — the twentieth float was padding for the
@@ -39,13 +39,19 @@ export const INSTANCE_STRIDE = INSTANCE_FLOATS * 4;
  * Writes nothing beyond `count`, and allocates nothing: `out` is the caller's staging array.
  */
 export function packInstances(instances, out) {
-    const { models, tints, alphas, lightmapRegions } = instances;
+    const { models, tints, alphas, lightmapRegions, uvRegions } = instances;
     const count = Math.min(instances.count, instances.capacity);
     for (let i = 0; i < count; i += 1) {
         const at = i * INSTANCE_FLOATS;
         const m = i * 16;
         for (let c = 0; c < 16; c += 1)
             out[at + c] = models[m + c];
+        /* The texture cell in the bottom row an affine placement leaves free. See `uvRegions`. */
+        const cell = i * 4;
+        out[at + 3] = uvRegions?.[cell] ?? 1;
+        out[at + 7] = uvRegions?.[cell + 1] ?? 1;
+        out[at + 11] = uvRegions?.[cell + 2] ?? 0;
+        out[at + 15] = uvRegions?.[cell + 3] ?? 0;
         if (lightmapRegions !== undefined) {
             /* The region in the tint's and the opacity's place. See `lightmapRegions`. */
             for (let c = 0; c < 4; c += 1)

package/dist/render/lightBudget.d.ts

@@ -1,4 +1,3 @@
-/** Fixed point-light budget shared by CPU selection and the flat shader. */
 import type { AreaLightBuffer } from './areaLights.ts';
 import type { ResolvedAreaShadows } from './areaShadowSet.ts';
 /**
@@ -368,6 +367,12 @@ export interface PointLightSet {
      * character's own key and rim lights, which the floor around the character must not take.
      */
     readonly lightChannels?: Float32Array;
+    /**
+     * One per light: its own falloff exponent, `(1 - (d/R)^2)^n` with no distance term, or 0 for the
+     * frame's falloff. **Absent, or a short array, is 0 for every light**, so a scene that names none
+     * falls off as it did. See `PointLightSource.falloffExponent`.
+     */
+    readonly lightFalloffExponents?: Float32Array;
 }
 /**
  * A cone that admits every direction, for every light.
@@ -441,6 +446,12 @@ export interface ResolvedPointLights {
      * array of their own, which would cost a row a light of a budget that has none to give.
      */
     readonly axesAndChannels: Float32Array;
+    /**
+     * Owned, four a light: the cone's two cosines, then the light's own falloff exponent, as
+     * `uLightCone` carries them — a `vec2` array costs a whole row a light on WebGL2 anyway, so the
+     * exponent rides the half it left rather than a row of its own.
+     */
+    readonly conesAndFalloffs: Float32Array;
     /**
      * Owned, `MAX_POINT_LIGHTS` long: the emitter sizes and weights as the froxel record carries
      * them, at half precision. `sourceRadii` and `weights` point here once a light set resolves, so