@driftengine/core 4.8.7 → 4.10.0

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/glCompressed.js

@@ -10,12 +10,95 @@ const INTERNAL = {
     bc5: 0x8dbd, // COMPRESSED_RED_GREEN_RGTC2_EXT
     bc7: 0x8e8c, // COMPRESSED_RGBA_BPTC_UNORM_EXT
     'bc7-srgb': 0x8e8d, // COMPRESSED_SRGB_ALPHA_BPTC_UNORM_EXT
+    'eac-r11': 0x9270, // COMPRESSED_R11_EAC
+    'eac-rg11': 0x9272, // COMPRESSED_RG11_EAC
+    'etc2-rgb8': 0x9274, // COMPRESSED_RGB8_ETC2
+    'etc2-rgb8-srgb': 0x9275, // COMPRESSED_SRGB8_ETC2
+    'etc2-rgb8a1': 0x9276, // COMPRESSED_RGB8_PUNCHTHROUGH_ALPHA1_ETC2
+    'etc2-rgb8a1-srgb': 0x9277, // COMPRESSED_SRGB8_PUNCHTHROUGH_ALPHA1_ETC2
+    'etc2-rgba8': 0x9278, // COMPRESSED_RGBA8_ETC2_EAC
+    'etc2-rgba8-srgb': 0x9279, // COMPRESSED_SRGB8_ALPHA8_ETC2_EAC
+    'astc-4x4': 0x93b0, // COMPRESSED_RGBA_ASTC_4x4_KHR
+    'astc-4x4-srgb': 0x93d0, // COMPRESSED_SRGB8_ALPHA8_ASTC_4x4_KHR
+    'astc-5x4': 0x93b1, // COMPRESSED_RGBA_ASTC_5x4_KHR
+    'astc-5x4-srgb': 0x93d1, // COMPRESSED_SRGB8_ALPHA8_ASTC_5x4_KHR
+    'astc-5x5': 0x93b2, // COMPRESSED_RGBA_ASTC_5x5_KHR
+    'astc-5x5-srgb': 0x93d2, // COMPRESSED_SRGB8_ALPHA8_ASTC_5x5_KHR
+    'astc-6x5': 0x93b3, // COMPRESSED_RGBA_ASTC_6x5_KHR
+    'astc-6x5-srgb': 0x93d3, // COMPRESSED_SRGB8_ALPHA8_ASTC_6x5_KHR
+    'astc-6x6': 0x93b4, // COMPRESSED_RGBA_ASTC_6x6_KHR
+    'astc-6x6-srgb': 0x93d4, // COMPRESSED_SRGB8_ALPHA8_ASTC_6x6_KHR
+    'astc-8x5': 0x93b5, // COMPRESSED_RGBA_ASTC_8x5_KHR
+    'astc-8x5-srgb': 0x93d5, // COMPRESSED_SRGB8_ALPHA8_ASTC_8x5_KHR
+    'astc-8x6': 0x93b6, // COMPRESSED_RGBA_ASTC_8x6_KHR
+    'astc-8x6-srgb': 0x93d6, // COMPRESSED_SRGB8_ALPHA8_ASTC_8x6_KHR
+    'astc-8x8': 0x93b7, // COMPRESSED_RGBA_ASTC_8x8_KHR
+    'astc-8x8-srgb': 0x93d7, // COMPRESSED_SRGB8_ALPHA8_ASTC_8x8_KHR
+    'astc-10x5': 0x93b8, // COMPRESSED_RGBA_ASTC_10x5_KHR
+    'astc-10x5-srgb': 0x93d8, // COMPRESSED_SRGB8_ALPHA8_ASTC_10x5_KHR
+    'astc-10x6': 0x93b9, // COMPRESSED_RGBA_ASTC_10x6_KHR
+    'astc-10x6-srgb': 0x93d9, // COMPRESSED_SRGB8_ALPHA8_ASTC_10x6_KHR
+    'astc-10x8': 0x93ba, // COMPRESSED_RGBA_ASTC_10x8_KHR
+    'astc-10x8-srgb': 0x93da, // COMPRESSED_SRGB8_ALPHA8_ASTC_10x8_KHR
+    'astc-10x10': 0x93bb, // COMPRESSED_RGBA_ASTC_10x10_KHR
+    'astc-10x10-srgb': 0x93db, // COMPRESSED_SRGB8_ALPHA8_ASTC_10x10_KHR
+    'astc-12x10': 0x93bc, // COMPRESSED_RGBA_ASTC_12x10_KHR
+    'astc-12x10-srgb': 0x93dc, // COMPRESSED_SRGB8_ALPHA8_ASTC_12x10_KHR
+    'astc-12x12': 0x93bd, // COMPRESSED_RGBA_ASTC_12x12_KHR
+    'astc-12x12-srgb': 0x93dd, // COMPRESSED_SRGB8_ALPHA8_ASTC_12x12_KHR
 };
 const BY_EXTENSION = [
     ['WEBGL_compressed_texture_s3tc', ['bc1', 'bc2', 'bc3']],
     ['WEBGL_compressed_texture_s3tc_srgb', ['bc1-srgb', 'bc2-srgb', 'bc3-srgb']],
     ['EXT_texture_compression_rgtc', ['bc4', 'bc5']],
     ['EXT_texture_compression_bptc', ['bc7', 'bc7-srgb']],
+    /* The two families a phone has: every GLES 3 device takes ETC2, and most take ASTC beside it. */
+    [
+        'WEBGL_compressed_texture_etc',
+        [
+            'etc2-rgb8',
+            'etc2-rgb8-srgb',
+            'etc2-rgb8a1',
+            'etc2-rgb8a1-srgb',
+            'etc2-rgba8',
+            'etc2-rgba8-srgb',
+            'eac-r11',
+            'eac-rg11',
+        ],
+    ],
+    [
+        'WEBGL_compressed_texture_astc',
+        [
+            'astc-4x4',
+            'astc-4x4-srgb',
+            'astc-5x4',
+            'astc-5x4-srgb',
+            'astc-5x5',
+            'astc-5x5-srgb',
+            'astc-6x5',
+            'astc-6x5-srgb',
+            'astc-6x6',
+            'astc-6x6-srgb',
+            'astc-8x5',
+            'astc-8x5-srgb',
+            'astc-8x6',
+            'astc-8x6-srgb',
+            'astc-8x8',
+            'astc-8x8-srgb',
+            'astc-10x5',
+            'astc-10x5-srgb',
+            'astc-10x6',
+            'astc-10x6-srgb',
+            'astc-10x8',
+            'astc-10x8-srgb',
+            'astc-10x10',
+            'astc-10x10-srgb',
+            'astc-12x10',
+            'astc-12x10-srgb',
+            'astc-12x12',
+            'astc-12x12-srgb',
+        ],
+    ],
 ];
 /**
  * The BC formats this context samples, enabling each extension that offers some. Enabling is what

package/dist/render/instances.d.ts

@@ -66,6 +66,14 @@ export interface MeshInstances {
      */
     readonly uvRegions?: Float32Array;
     /** How many instances the arrays hold. Fixed at creation; the buffers are sized from it. */
+    /**
+     * Two floats each, the instance's clock for a batch that plays a bone animation
+     * (`InstancedOptions.animation`): its phase in seconds, added to the scene's time once the rate has
+     * scaled it, and its rate, 1 for the clip's own speed. **Absent, or an instance past its end, is
+     * `(0, 1)`** — every instance at the clip's speed and in step. Read by `uploadInstanced`, as the
+     * matrices are; a batch with no animation ignores it.
+     */
+    readonly clocks?: Float32Array;
     readonly capacity: number;
     /** How many are live. The rest of the buffer is neither uploaded nor drawn. */
     count: number;
@@ -103,6 +111,7 @@ export declare const INSTANCE_STRIDE: number;
  * Writes nothing beyond `count`, and allocates nothing: `out` is the caller's staging array.
  */
 export declare function packInstances(instances: MeshInstances, out: Float32Array): void;
+import type { BoneAnimationHandle } from './boneAnimation.ts';
 /** How a batch made by `createInstanced` behaves. */
 export interface InstancedOptions {
     /**
@@ -117,4 +126,21 @@ export interface InstancedOptions {
      * place gains only the whole-batch test, which it could as well do itself.
      */
     readonly cull?: boolean;
+    /**
+     * A bone animation every instance plays (`createBoneAnimation`): each vertex follows the bone its
+     * mesh's second coordinates name, at the instance's own moment of the clip (`MeshInstances.clocks`
+     * and the clock `setAnimationTime` sets), in the colour pass and in every shadow. The mesh must
+     * carry second coordinates. See `boneAnimation.ts`.
+     *
+     * **An animated batch is culled whole, never instance by instance**: its instances read their
+     * clocks by index, which a cull that compacts the survivors would reorder. And its bounds are the
+     * rest pose's, so a clip that carries vertices far from it wants a mesh whose bounds hold them.
+     *
+     * **What it gives up**: under reconstruction or the temporal resolve, a crowd's own movement is not
+     * in the frame's motion — the motion pass places a batch by its matrices, not by its clip — so its
+     * moving parts are reprojected as though still, which softens a fast clip a little; and a glass
+     * batch's coloured shadow is cast from rest. What would make the first wrong is a clip fast enough
+     * at the size it is seen to smear, which is then the motion pass's to learn.
+     */
+    readonly animation?: BoneAnimationHandle;
 }

package/dist/render/lightBudget.d.ts

@@ -243,6 +243,16 @@ export declare const SKIN_BLUR_ALBEDO_UNIT: number;
  */
 export declare const PARTICLE_SPRITE_UNIT: number;
 export declare const PARTICLE_DEPTH_UNIT: number;
+/**
+ * A bone animation's places and turns and its batch's clocks (`shaders/boneAnimation.ts`): vertex
+ * samplers of the animated instanced program, so they count against the vertex stage's sixteen, not
+ * the lit stage's. Numbered past every unit before them rather than sharing the cloth's, which no
+ * animated program declares: a unit two programs both write is a binding one draw can leave for the
+ * other to read. Twenty-six to twenty-eight, inside the combined pool of thirty-two.
+ */
+export declare const BONE_PLACES_TEXTURE_UNIT: number;
+export declare const BONE_TURNS_TEXTURE_UNIT: number;
+export declare const INSTANCE_CLOCKS_TEXTURE_UNIT: number;
 /**
  * A cookie's tile, in texels a side.
  *

package/dist/render/lightBudget.js

@@ -244,6 +244,16 @@ export const SKIN_BLUR_ALBEDO_UNIT = SKIN_BLUR_DEPTH_UNIT + 1;
  */
 export const PARTICLE_SPRITE_UNIT = SKIN_BLUR_ALBEDO_UNIT + 1;
 export const PARTICLE_DEPTH_UNIT = PARTICLE_SPRITE_UNIT + 1;
+/**
+ * A bone animation's places and turns and its batch's clocks (`shaders/boneAnimation.ts`): vertex
+ * samplers of the animated instanced program, so they count against the vertex stage's sixteen, not
+ * the lit stage's. Numbered past every unit before them rather than sharing the cloth's, which no
+ * animated program declares: a unit two programs both write is a binding one draw can leave for the
+ * other to read. Twenty-six to twenty-eight, inside the combined pool of thirty-two.
+ */
+export const BONE_PLACES_TEXTURE_UNIT = PARTICLE_DEPTH_UNIT + 1;
+export const BONE_TURNS_TEXTURE_UNIT = BONE_PLACES_TEXTURE_UNIT + 1;
+export const INSTANCE_CLOCKS_TEXTURE_UNIT = BONE_TURNS_TEXTURE_UNIT + 1;
 /**
  * A cookie's tile, in texels a side.
  *

package/dist/render/lightmap.d.ts

@@ -15,7 +15,7 @@
  *     light = irradiance(uv) * max(0, dot(d.xyz, n) + d.w)
  *     diffuse += albedo * (1 - metal) * light
  *
- * Unreal's high-quality lightmap read, `GetLightMapColorHQ`, once its own vectors have decoded the
+ * A directional lightmap read, once its own vectors have decoded the
  * page — the first-order spherical harmonic its direction carries, in this engine's axes. **Added
  * to what the dynamic lights give**, and to the ambient: a consumer whose bake already holds the
  * sky's light zeroes the ambient for those draws itself, with `setAmbientSH` and nine zeros.

package/dist/render/mesh.d.ts

@@ -63,6 +63,11 @@ export declare class Mesh {
     readonly isSkinnedEight: boolean;
     /** Whether it has texture coordinates, without which a material's maps read one texel. */
     readonly hasUvs: boolean;
+    /**
+     * Whether it carries a grain lane, which is where second coordinates ride (`lightmap.ts`): what
+     * a bone animation reads each vertex's bone from.
+     */
+    readonly hasGrain: boolean;
     /** How many vertices it has, which a cloth binding is checked against. */
     readonly vertexCount: number;
     /**

package/dist/render/mesh.js

@@ -136,6 +136,11 @@ export class Mesh {
     isSkinnedEight;
     /** Whether it has texture coordinates, without which a material's maps read one texel. */
     hasUvs;
+    /**
+     * Whether it carries a grain lane, which is where second coordinates ride (`lightmap.ts`): what
+     * a bone animation reads each vertex's bone from.
+     */
+    hasGrain;
     /** How many vertices it has, which a cloth binding is checked against. */
     vertexCount;
     /**
@@ -304,6 +309,7 @@ export class Mesh {
         else {
             this.attachAttribute(gl, ATTR_TANGENT, data.tangents, 4);
         }
+        this.hasGrain = data.grain !== undefined;
         if (data.grain === undefined) {
             gl.disableVertexAttribArray(ATTR_GRAIN);
             this.constants.push({ location: ATTR_GRAIN, value: ABSENT_ATTRIBUTE['grain'] });

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.