@driftengine/core 4.8.7 → 4.10.0

package/src/render/filmicCurve.ts

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

package/src/render/fog.ts

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

package/src/render/frame/resources.ts

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

package/src/render/frameReflections.ts

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

package/src/render/glCompressed.ts

@@ -28,6 +28,42 @@ const INTERNAL: Readonly<Record<CompressedTextureFormat, number>> = {
   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: readonly (readonly [string, readonly CompressedTextureFormat[]])[] = [
@@ -35,6 +71,53 @@ const BY_EXTENSION: readonly (readonly [string, readonly CompressedTextureFormat
   ['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',
+    ],
+  ],
 ];
 
 /**

package/src/render/instances.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;
@@ -140,6 +148,8 @@ export function packInstances(instances: MeshInstances, out: Float32Array): void
   }
 }
 
+import type { BoneAnimationHandle } from './boneAnimation.ts';
+
 /** How a batch made by `createInstanced` behaves. */
 export interface InstancedOptions {
   /**
@@ -154,4 +164,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/src/render/lightBudget.ts

@@ -276,6 +276,17 @@ 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/src/render/lightmap.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/src/render/mesh.ts

@@ -149,6 +149,11 @@ export 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;
 
@@ -319,6 +324,7 @@ export class Mesh {
       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/src/render/pass.ts

@@ -119,7 +119,23 @@ export type PassContext = {
   /** The exposure that goes with it. 1 where the composite will apply the real one. */
   readonly outputExposure: number;
 } & (
-  | { readonly backend: 'webgl2'; readonly gl: WebGL2RenderingContext }
+  | {
+      readonly backend: 'webgl2';
+      readonly gl: WebGL2RenderingContext;
+      /**
+       * The frame's colour with everything drawn before this pass, for a pass declaring
+       * `reads: ['colorSnapshot']`, and null for one that does not or where the frame keeps no
+       * scene target (`screenEffects` off). A copy, never the attachment being drawn into, which
+       * WebGL2 cannot sample; taken afresh at each such pass's draw. WebGPU hands the same copy
+       * over in `PrepareContext.sceneColor`, where a bind group has to be built before the pass.
+       */
+      readonly sceneColor: WebGLTexture | null;
+      /**
+       * The frame's depth as it stands, for a pass declaring `reads: ['depthSnapshot']`: a copy, at
+       * the buffer's own values and reversed as it is (1 near, 0 far). Null as `sceneColor` is.
+       */
+      readonly sceneDepth: WebGLTexture | null;
+    }
   | {
       readonly backend: 'webgpu';
       readonly pass: GPURenderPassEncoder;
@@ -217,6 +233,42 @@ export type PrepareContext =
        * should not apply it either; the renderer's own verbs do not jitter a mirror.
        */
       readonly jitter: Float32Array;
+      /**
+       * The frame's single-sample copy of its depth, or null where the frame keeps none (no
+       * composite: `screenEffects` off).
+       *
+       * One `r32float` texel a pixel holding the depth buffer's own value, reversed as the
+       * buffer is (`REVERSED_DEPTH`: 1 at the near plane, 0 at the far one). Unfilterable, so a
+       * pass binds it as `'unfilterable-float'` and reads it with a non-filtering sampler or
+       * `textureLoad`.
+       *
+       * **Handed over here, filled at the draw.** The view is the one this frame's copy will be
+       * written into, so a pass builds its bind groups with it before the frame's pass opens; the
+       * copy itself is taken when a pass that declares `reads: ['depthSnapshot']` is drawn, with
+       * everything drawn before it, which is what the soft edge of a translucent particle
+       * needs. A pass that does not declare that read finds whatever the frame last wrote there.
+       */
+      readonly sceneDepth: GPUTextureView | null;
+      /**
+       * The frame's colour, for a pass that declares `reads: ['colorSnapshot']`, or null where no
+       * registered pass does or the frame keeps no composite (`screenEffects` off).
+       *
+       * At the scene's own size and format — under a reconstruction, the render's rather than the
+       * output's, since that is the picture a registered pass draws into — and filterable.
+       * **Handed over here, refilled at the draw**: the view is the texture each reading pass's
+       * draw copies the frame into, with everything drawn before it, so a distortion samples the
+       * scene behind it and a full-screen effect drawn last reads the whole frame and writes over
+       * it, in scene light, before the tone curve. A copy a reading pass, where `sceneDepth` is one
+       * a frame.
+       *
+       * **Under a reconstruction a pass that reads it is drawn after the upscale**, over the
+       * reconstructed picture and after every blended draw, whatever order it was asked in — at the
+       * output's size and the reconstruction's format, which `PassContext.format` names at that
+       * draw, so a pass drawn there keeps a pipeline for it. The view is then the output-size copy.
+       * `sceneDepth` stays the render's opaque depth: at a ratio above 1 its texels are coarser by
+       * the ratio, and a blended draw is in neither depth, as it never is.
+       */
+      readonly sceneColor: GPUTextureView | null;
     };
 
 /**

package/src/render/pointLightSelection.ts

@@ -204,10 +204,10 @@ export interface PointLightSource {
   inLightField?: boolean;
   /**
    * How the light fades with distance when it names its own way: `(1 - (d/R)^2)^n` with no distance
-   * term, `R` its radius and `n` this. Unreal's falloff for a light without inverse-square falloff,
-   * so a rig authored there — a fill of brightness 160 across 164 m, a key at exponent 8 — lights
-   * the space it was authored for rather than one that ends a few metres out. Absent or 0, the
-   * frame's own falloff (`pointLightFalloff`), which is every light before 4.8.7.
+   * term, `R` its radius and `n` this. The usual falloff for a light without inverse-square
+   * falloff, so a rig authored that way — a fill of brightness 160 across 164 m, a key at exponent
+   * 8 — lights the space it was authored for rather than one that ends a few metres out. Absent or
+   * 0, the frame's own falloff (`pointLightFalloff`), which is every light before 4.8.7.
    */
   falloffExponent?: number;
 }