@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/post/taa.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Temporal anti-aliasing (ws/post-3, on camera jitter since ws/post-4). The stack keeps two
+ * scene-size `rgba16float` history textures and ping-pongs between them. While TAA runs the
+ * stack declares `wantsJitter` and hands `Taa.jitter` (Halton 2, 3) to the renderer's
+ * `setJitter` hook (ws/post-6), which offsets the projection of every camera it draws; the
+ * frame arrives jittered by `PostInputs.view.jitter`. The resolve un-jitters it (samples the colour and the
+ * depth `P.taa2.xy` uv along the jitter, bilinear), reprojects the history through `P.reproj`
+ * (`view.previousViewProj × view.invViewProj`: this frame's jittered clip → last frame's
+ * unjittered clip), clamps it to the 3×3 neighbourhood of the current colour (min/max box, or
+ * mean ± σ) and blends it in by `P.taa.y` (feedback). `P.taa2.z` (reset) copies the current
+ * frame instead: the first frame, and the one after a resize.
+ *
+ * Since ws/post-5 a frame with a velocity target reprojects each pixel by its own motion
+ * (`uv - velocity`) instead, so moving and skinned objects keep their history, and drops the
+ * history where last frame's depth or velocity there disagree (`TAA_WGSL`, `taaRejects`).
+ *
+ * Since ws/post-6 the history is read with a 5-tap Catmull-Rom filter by default
+ * (`taa.historyFilter`, `P.taa3.z`; `taaCatmullRomWeights` is the CPU twin of its weights), so
+ * a surface moving a fraction of a pixel a frame is not re-blurred by a bilinear tap each frame.
+ */
+import { type Mat4 } from '../core/math.js';
+/** Van der Corput radical inverse in `base` of `index` (1-based). */
+export declare function halton(index: number, base: number): number;
+/** Highest history weight: above it the image smears and never settles. */
+export declare const TAA_MAX_FEEDBACK = 0.98;
+/** The history weight the resolve uses for `feedback`: clamped to 0..`TAA_MAX_FEEDBACK`. */
+export declare function taaBlendWeight(feedback: number): number;
+/**
+ * The matrix TAA and motion blur reproject by: this frame's clip space to the previous
+ * frame's, `out = prevViewProj × invViewProj`. Identity when the camera has not moved.
+ */
+export declare function taaReprojection(out: Mat4, prevViewProj: ArrayLike<number>, invViewProj: ArrayLike<number>): Mat4;
+/** The jitter sequence. `PostStack.taa` is one; the stack feeds it to `Renderer.setJitter`. */
+export declare class Taa {
+    /** Points in the cycle (8 or 16). */
+    readonly samples: 8 | 16;
+    private readonly out;
+    constructor(samples?: 8 | 16);
+    /**
+     * The sub-pixel offset for `frame` in pixel units (each in -0.5..0.5): Halton (2, 3) over
+     * the cycle, centred. The returned pair is reused; copy it to keep it.
+     */
+    jitter(frame: number): [number, number];
+}
+/**
+ * The Catmull-Rom weights of the four texels around a sample at fraction `f` (0..1) past the
+ * second one: `out[0..3]` for the texels at -1, 0, 1, 2. They sum to 1; at `f = 0` they are
+ * (0, 1, 0, 0), so a sample on a texel centre reads that texel exactly. The resolve folds the
+ * middle two into one bilinear tap per axis and drops the four corner taps (5 taps for 16).
+ */
+export declare function taaCatmullRomWeights(f: number, out?: [number, number, number, number]): [number, number, number, number];
+/** Format of the TAA history aux pair (ws/post-5): velocity (uv) in xy, linear depth in z, 1 in w. */
+export declare const TAA_AUX_FORMAT: GPUTextureFormat;
+/**
+ * The CPU twin of the resolve's history rejection (ws/post-5): true when the history sample
+ * (velocity `hv` in uv, linear depth `hz`) belongs to a different surface than the pixel
+ * (velocity `v`, linear depth `z`) on a `width × height` target: the depths differ by more
+ * than `depthReject` of the nearer one, or the velocities by more than `velocityReject` px.
+ */
+export declare function taaRejects(v: readonly [number, number], z: number, hv: readonly [number, number], hz: number, width: number, height: number, depthReject: number, velocityReject: number): boolean;
+/**
+ * The resolve pass (`DepthPass`, two targets: the HDR resolve and its `TAA_AUX_FORMAT` aux;
+ * four textures: `@binding(4)` the current scene colour, `@binding(5)` the previous resolve,
+ * `@binding(6)` the velocity target (the scene colour stands in without one; unread),
+ * `@binding(7)` the previous aux).
+ *
+ * Velocity reprojection (ws/post-5, `P.taa2.w`): the pixel takes the velocity of the nearest
+ * depth in its 3×3 (so an edge moves with the object in front) and finds its history at
+ * `uv - velocity`; where the target holds no motion it falls back to `P.reproj`. The history
+ * is dropped when its aux (last frame's velocity and linear depth there) disagrees with the
+ * pixel's by more than `P.taa3.x` (relative depth) or `P.taa3.y` (px). Without it the resolve
+ * is the ws/post-4 one; the aux is written either way so a switch finds a valid one.
+ */
+export declare const TAA_WGSL = "\n\nstruct PostUniforms {\n  frame: vec4f,      // time, aspect, 1/width, 1/height\n  enables: vec4f,    // bloom, fog, rays, vignette\n  enables2: vec4f,   // grade, tonemap (0 none, 1 aces, 2 reinhard), dither, exposure\n  bloom: vec4f,      // intensity, threshold, knee, emissiveWeight\n  bloom2: vec4f,     // scatter, -, -, -\n  fogColor: vec4f,   // rgb, density\n  fog: vec4f,        // top, bottom, noiseScale, speed\n  fog2: vec4f,       // lightScatter, falloff, -, -\n  rays: vec4f,       // light uv x, y, intensity, decay\n  rays2: vec4f,      // density, weight, source radius (uv-y units), source intensity\n  raysColor: vec4f,  // rgb, bloomSource\n  vignette: vec4f,   // intensity, radius, softness, -\n  vignetteColor: vec4f,\n  lift: vec4f,\n  gamma: vec4f,\n  gain: vec4f,\n  grade: vec4f,      // saturation, contrast, -, -\n  quality: vec4f,    // ray samples, fog octaves, ortho projection (1, ws/post-4), -\n  ao: vec4f,         // enabled (0 without depth), radius, intensity, bias\n  ao2: vec4f,        // power, samples, proj x scale, proj y scale\n  dof: vec4f,        // enabled (0 without depth), focus distance, focus range, max blur (uv of width)\n  dof2: vec4f,       // near blur, taps, near plane, far plane\n  invProj: mat4x4f,  // clip -> view\n  fxaa: vec4f,       // enabled, subpixel, edgeThreshold, -\n  lut: vec4f,        // enabled, (size-1)/size, intensity, 0.5/size\n  grain: vec4f,      // intensity, cell size (px), luminanceResponse, seed\n  aberration: vec4f, // intensity (px), radialOnly, -, -\n  sharpen: vec4f,    // amount, -, -, -\n  outline: vec4f,    // enabled (0 without depth), thickness (scene px), depthThreshold, normalThreshold\n  outlineColor: vec4f, // rgb, intensity\n  // Post 3 (ws/post-3).\n  taa: vec4f,        // enabled (0 without depth), feedback, sharpen, clampMode (0 aabb, 1 variance)\n  taa2: vec4f,       // view jitter x (uv), view jitter y (uv), reset (1 = copy the current frame), velocity reprojection (1, ws/post-5)\n  ssr: vec4f,        // enabled (0 without depth), maxSteps, thickness, maxDistance\n  ssr2: vec4f,       // roughnessCutoff, intensity, fadeEdges (uv), rough-metal target (1)\n  exposure: vec4f,   // auto (1), histogramLow, histogramHigh, keyValue\n  wb0: vec4f,        // white-balance matrix row 0 (rgb weights), enabled\n  wb1: vec4f,        // row 1\n  wb2: vec4f,        // row 2\n  motionBlur: vec4f, // enabled (0 without depth), intensity, samples, velocity target (1 = object)\n  dirt: vec4f,       // enabled, intensity, -, -\n  reproj: mat4x4f,   // current clip -> previous frame's clip (identity on a reset)\n  // Post 5 (ws/post-5).\n  taa3: vec4f,       // depthReject (fraction), velocityReject (px), history filter (1 = Catmull-Rom, ws/post-6), -\n};\n@group(0) @binding(0) var<uniform> P: PostUniforms;\n\n@group(0) @binding(1) var nearest: sampler;\n@group(0) @binding(2) var linSamp: sampler;\n@group(0) @binding(3) var depthTex: texture_depth_2d;\n@group(0) @binding(4) var colorTex: texture_2d<f32>;\n@group(0) @binding(5) var historyTex: texture_2d<f32>;\n@group(0) @binding(6) var velocityTex: texture_2d<f32>;\n@group(0) @binding(7) var auxTex: texture_2d<f32>;\n\nfn view_pos(uv: vec2f, depth: f32) -> vec3f {\n  let ndc = vec3f(uv.x * 2.0 - 1.0, 1.0 - uv.y * 2.0, depth);\n  let p = P.invProj * vec4f(ndc, 1.0);\n  return p.xyz / p.w;\n}\nfn linear_depth(uv: vec2f, depth: f32) -> f32 {\n  return -view_pos(uv, depth).z;\n}\n/** The centre of the depth texel under `uv`: positions must be rebuilt where the depth was read. */\nfn texel_uv(uv: vec2f, dim: vec2f) -> vec2f {\n  return (floor(clamp(uv, vec2f(0.0), vec2f(0.9999)) * dim) + 0.5) / dim;\n}\n\n\nstruct TaaOut {\n  @location(0) color: vec4f,\n  @location(1) aux: vec4f,\n};\n\nfn cur(uv: vec2f) -> vec3f { return textureSampleLevel(colorTex, nearest, uv, 0.0).rgb; }\n\nfn hist(uv: vec2f) -> vec3f { return textureSampleLevel(historyTex, linSamp, uv, 0.0).rgb; }\n\n// The history at uv through a Catmull-Rom filter (ws/post-6): the 4\u00D74 texels around it, the\n// middle two of each axis folded into one bilinear tap and the four corners dropped, 5 taps.\n// Normalised by the taps' weight, since the corners are gone.\nfn hist_catmull_rom(uv: vec2f) -> vec3f {\n  let dim = vec2f(textureDimensions(historyTex));\n  let p = uv * dim;\n  let t1 = floor(p - 0.5) + 0.5;\n  let f = p - t1;\n  let w0 = f * (-0.5 + f * (1.0 - 0.5 * f));\n  let w1 = 1.0 + f * f * (-2.5 + 1.5 * f);\n  let w2 = f * (0.5 + f * (2.0 - 1.5 * f));\n  let w3 = f * f * (-0.5 + 0.5 * f);\n  let w12 = w1 + w2;\n  let t0 = (t1 - 1.0) / dim;\n  let t3 = (t1 + 2.0) / dim;\n  let t12 = (t1 + w2 / w12) / dim;\n  let a = w12.x * w0.y;\n  let b = w0.x * w12.y;\n  let c = w12.x * w12.y;\n  let d = w3.x * w12.y;\n  let e = w12.x * w3.y;\n  let sum = hist(vec2f(t12.x, t0.y)) * a + hist(vec2f(t0.x, t12.y)) * b + hist(t12) * c +\n    hist(vec2f(t3.x, t12.y)) * d + hist(vec2f(t12.x, t3.y)) * e;\n  return sum / (a + b + c + d + e);\n}\n\n@fragment fn fs_main(in: FullscreenIn) -> TaaOut {\n  let dim = vec2f(textureDimensions(colorTex));\n  let t = 1.0 / dim;\n  // The camera drew this frame shifted by the jitter (+x right, +y down): what belongs at this\n  // pixel sits that far along in the colour and the depth. Un-jitter by sampling there.\n  let uv = in.uv + P.taa2.xy;\n  let c = textureSampleLevel(colorTex, linSamp, uv, 0.0).rgb;\n  let d = textureSampleLevel(depthTex, nearest, uv, 0u);\n  let velocityMode = P.taa2.w > 0.5;\n  // 3\u00D73 neighbourhood bounds of the current colour around the un-jittered point, and (velocity\n  // mode) the nearest depth's texel.\n  var mn = vec3f(1e9);\n  var mx = vec3f(-1e9);\n  var m1 = vec3f(0.0);\n  var m2 = vec3f(0.0);\n  var nearD = d;\n  var nearUv = uv;\n  for (var y = -1; y <= 1; y++) {\n    for (var x = -1; x <= 1; x++) {\n      let o = uv + vec2f(f32(x), f32(y)) * t;\n      let s = cur(o);\n      mn = min(mn, s);\n      mx = max(mx, s);\n      m1 += s;\n      m2 += s * s;\n      if (velocityMode) {\n        let sd = textureSampleLevel(depthTex, nearest, o, 0u);\n        if (sd < nearD) {\n          nearD = sd;\n          nearUv = o;\n        }\n      }\n    }\n  }\n  let mean = m1 / 9.0;\n  if (P.taa.w > 0.5) {\n    let sigma = sqrt(max(m2 / 9.0 - mean * mean, vec3f(0.0)));\n    mn = max(mn, mean - sigma);\n    mx = min(mx, mean + sigma);\n  }\n  // The target holds where the point is minus where it was (uv).\n  var vel = vec2f(0.0);\n  if (velocityMode) {\n    vel = textureSampleLevel(velocityTex, nearest, nearUv, 0.0).xy;\n  }\n  let z = linear_depth(uv, d);\n  var out = c;\n  if (P.taa2.z < 0.5) {\n    var puv = in.uv - vel;\n    var ahead = true;\n    if (dot(vel, vel) < 1e-12) {\n      // The jittered frame's clip position of that depth sample: P.reproj starts from it.\n      let ndc = vec4f(uv.x * 2.0 - 1.0, 1.0 - uv.y * 2.0, d, 1.0);\n      let prev = P.reproj * ndc;\n      let pn = prev.xy / max(prev.w, 1e-6);\n      puv = vec2f(pn.x * 0.5 + 0.5, 0.5 - pn.y * 0.5);\n      ahead = prev.w > 0.0;\n    }\n    var keep = ahead && all(puv >= vec2f(0.0)) && all(puv <= vec2f(1.0));\n    if (keep && velocityMode) {\n      let a = textureSampleLevel(auxTex, nearest, puv, 0.0);\n      let dz = abs(a.z - z) / max(min(a.z, z), 1e-4);\n      let dv = length((vel - a.xy) * dim);\n      keep = a.w > 0.5 && dz <= P.taa3.x && dv <= P.taa3.y;\n    }\n    if (keep) {\n      var hs: vec3f;\n      if (P.taa3.z > 0.5) {\n        hs = hist_catmull_rom(puv);\n      } else {\n        hs = hist(puv);\n      }\n      let h = clamp(hs, mn, mx);\n      out = mix(c, h, P.taa.y);\n    }\n  }\n  // Unsharp against the neighbourhood mean, so the blend's softness comes back as detail.\n  out = max(out + (out - mean) * P.taa.z, vec3f(0.0));\n  return TaaOut(vec4f(out, 1.0), vec4f(vel, z, 1.0));\n}\n";

package/dist/post/taa.js

@@ -0,0 +1,235 @@
+/**
+ * Temporal anti-aliasing (ws/post-3, on camera jitter since ws/post-4). The stack keeps two
+ * scene-size `rgba16float` history textures and ping-pongs between them. While TAA runs the
+ * stack declares `wantsJitter` and hands `Taa.jitter` (Halton 2, 3) to the renderer's
+ * `setJitter` hook (ws/post-6), which offsets the projection of every camera it draws; the
+ * frame arrives jittered by `PostInputs.view.jitter`. The resolve un-jitters it (samples the colour and the
+ * depth `P.taa2.xy` uv along the jitter, bilinear), reprojects the history through `P.reproj`
+ * (`view.previousViewProj × view.invViewProj`: this frame's jittered clip → last frame's
+ * unjittered clip), clamps it to the 3×3 neighbourhood of the current colour (min/max box, or
+ * mean ± σ) and blends it in by `P.taa.y` (feedback). `P.taa2.z` (reset) copies the current
+ * frame instead: the first frame, and the one after a resize.
+ *
+ * Since ws/post-5 a frame with a velocity target reprojects each pixel by its own motion
+ * (`uv - velocity`) instead, so moving and skinned objects keep their history, and drops the
+ * history where last frame's depth or velocity there disagree (`TAA_WGSL`, `taaRejects`).
+ *
+ * Since ws/post-6 the history is read with a 5-tap Catmull-Rom filter by default
+ * (`taa.historyFilter`, `P.taa3.z`; `taaCatmullRomWeights` is the CPU twin of its weights), so
+ * a surface moving a fraction of a pixel a frame is not re-blurred by a bilinear tap each frame.
+ */
+import { mat4 } from '../core/math.js';
+import { WGSL_DEPTH_VIEW } from './ao.js';
+import { WGSL_POST_UNIFORMS } from './settings.js';
+/** Van der Corput radical inverse in `base` of `index` (1-based). */
+export function halton(index, base) {
+    let f = 1;
+    let r = 0;
+    let i = index;
+    while (i > 0) {
+        f /= base;
+        r += f * (i % base);
+        i = Math.floor(i / base);
+    }
+    return r;
+}
+/** Highest history weight: above it the image smears and never settles. */
+export const TAA_MAX_FEEDBACK = 0.98;
+/** The history weight the resolve uses for `feedback`: clamped to 0..`TAA_MAX_FEEDBACK`. */
+export function taaBlendWeight(feedback) {
+    if (!Number.isFinite(feedback))
+        return 0;
+    return Math.min(TAA_MAX_FEEDBACK, Math.max(0, feedback));
+}
+/**
+ * The matrix TAA and motion blur reproject by: this frame's clip space to the previous
+ * frame's, `out = prevViewProj × invViewProj`. Identity when the camera has not moved.
+ */
+export function taaReprojection(out, prevViewProj, invViewProj) {
+    return mat4.multiply(out, prevViewProj, invViewProj);
+}
+/** The jitter sequence. `PostStack.taa` is one; the stack feeds it to `Renderer.setJitter`. */
+export class Taa {
+    /** Points in the cycle (8 or 16). */
+    samples;
+    out = [0, 0];
+    constructor(samples = 8) {
+        this.samples = samples;
+    }
+    /**
+     * The sub-pixel offset for `frame` in pixel units (each in -0.5..0.5): Halton (2, 3) over
+     * the cycle, centred. The returned pair is reused; copy it to keep it.
+     */
+    jitter(frame) {
+        const i = (Math.max(0, Math.floor(frame)) % this.samples) + 1;
+        this.out[0] = halton(i, 2) - 0.5;
+        this.out[1] = halton(i, 3) - 0.5;
+        return this.out;
+    }
+}
+/**
+ * The Catmull-Rom weights of the four texels around a sample at fraction `f` (0..1) past the
+ * second one: `out[0..3]` for the texels at -1, 0, 1, 2. They sum to 1; at `f = 0` they are
+ * (0, 1, 0, 0), so a sample on a texel centre reads that texel exactly. The resolve folds the
+ * middle two into one bilinear tap per axis and drops the four corner taps (5 taps for 16).
+ */
+export function taaCatmullRomWeights(f, out = [0, 0, 0, 0]) {
+    out[0] = f * (-0.5 + f * (1 - 0.5 * f));
+    out[1] = 1 + f * f * (-2.5 + 1.5 * f);
+    out[2] = f * (0.5 + f * (2 - 1.5 * f));
+    out[3] = f * f * (-0.5 + 0.5 * f);
+    return out;
+}
+/** Format of the TAA history aux pair (ws/post-5): velocity (uv) in xy, linear depth in z, 1 in w. */
+export const TAA_AUX_FORMAT = 'rgba16float';
+/**
+ * The CPU twin of the resolve's history rejection (ws/post-5): true when the history sample
+ * (velocity `hv` in uv, linear depth `hz`) belongs to a different surface than the pixel
+ * (velocity `v`, linear depth `z`) on a `width × height` target: the depths differ by more
+ * than `depthReject` of the nearer one, or the velocities by more than `velocityReject` px.
+ */
+export function taaRejects(v, z, hv, hz, width, height, depthReject, velocityReject) {
+    const dz = Math.abs(hz - z) / Math.max(Math.min(hz, z), 1e-4);
+    const dv = Math.hypot((v[0] - hv[0]) * width, (v[1] - hv[1]) * height);
+    return dz > depthReject || dv > velocityReject;
+}
+/**
+ * The resolve pass (`DepthPass`, two targets: the HDR resolve and its `TAA_AUX_FORMAT` aux;
+ * four textures: `@binding(4)` the current scene colour, `@binding(5)` the previous resolve,
+ * `@binding(6)` the velocity target (the scene colour stands in without one; unread),
+ * `@binding(7)` the previous aux).
+ *
+ * Velocity reprojection (ws/post-5, `P.taa2.w`): the pixel takes the velocity of the nearest
+ * depth in its 3×3 (so an edge moves with the object in front) and finds its history at
+ * `uv - velocity`; where the target holds no motion it falls back to `P.reproj`. The history
+ * is dropped when its aux (last frame's velocity and linear depth there) disagrees with the
+ * pixel's by more than `P.taa3.x` (relative depth) or `P.taa3.y` (px). Without it the resolve
+ * is the ws/post-4 one; the aux is written either way so a switch finds a valid one.
+ */
+export const TAA_WGSL = /* wgsl */ `
+${WGSL_POST_UNIFORMS}
+@group(0) @binding(1) var nearest: sampler;
+@group(0) @binding(2) var linSamp: sampler;
+@group(0) @binding(3) var depthTex: texture_depth_2d;
+@group(0) @binding(4) var colorTex: texture_2d<f32>;
+@group(0) @binding(5) var historyTex: texture_2d<f32>;
+@group(0) @binding(6) var velocityTex: texture_2d<f32>;
+@group(0) @binding(7) var auxTex: texture_2d<f32>;
+${WGSL_DEPTH_VIEW}
+
+struct TaaOut {
+  @location(0) color: vec4f,
+  @location(1) aux: vec4f,
+};
+
+fn cur(uv: vec2f) -> vec3f { return textureSampleLevel(colorTex, nearest, uv, 0.0).rgb; }
+
+fn hist(uv: vec2f) -> vec3f { return textureSampleLevel(historyTex, linSamp, uv, 0.0).rgb; }
+
+// The history at uv through a Catmull-Rom filter (ws/post-6): the 4×4 texels around it, the
+// middle two of each axis folded into one bilinear tap and the four corners dropped, 5 taps.
+// Normalised by the taps' weight, since the corners are gone.
+fn hist_catmull_rom(uv: vec2f) -> vec3f {
+  let dim = vec2f(textureDimensions(historyTex));
+  let p = uv * dim;
+  let t1 = floor(p - 0.5) + 0.5;
+  let f = p - t1;
+  let w0 = f * (-0.5 + f * (1.0 - 0.5 * f));
+  let w1 = 1.0 + f * f * (-2.5 + 1.5 * f);
+  let w2 = f * (0.5 + f * (2.0 - 1.5 * f));
+  let w3 = f * f * (-0.5 + 0.5 * f);
+  let w12 = w1 + w2;
+  let t0 = (t1 - 1.0) / dim;
+  let t3 = (t1 + 2.0) / dim;
+  let t12 = (t1 + w2 / w12) / dim;
+  let a = w12.x * w0.y;
+  let b = w0.x * w12.y;
+  let c = w12.x * w12.y;
+  let d = w3.x * w12.y;
+  let e = w12.x * w3.y;
+  let sum = hist(vec2f(t12.x, t0.y)) * a + hist(vec2f(t0.x, t12.y)) * b + hist(t12) * c +
+    hist(vec2f(t3.x, t12.y)) * d + hist(vec2f(t12.x, t3.y)) * e;
+  return sum / (a + b + c + d + e);
+}
+
+@fragment fn fs_main(in: FullscreenIn) -> TaaOut {
+  let dim = vec2f(textureDimensions(colorTex));
+  let t = 1.0 / dim;
+  // The camera drew this frame shifted by the jitter (+x right, +y down): what belongs at this
+  // pixel sits that far along in the colour and the depth. Un-jitter by sampling there.
+  let uv = in.uv + P.taa2.xy;
+  let c = textureSampleLevel(colorTex, linSamp, uv, 0.0).rgb;
+  let d = textureSampleLevel(depthTex, nearest, uv, 0u);
+  let velocityMode = P.taa2.w > 0.5;
+  // 3×3 neighbourhood bounds of the current colour around the un-jittered point, and (velocity
+  // mode) the nearest depth's texel.
+  var mn = vec3f(1e9);
+  var mx = vec3f(-1e9);
+  var m1 = vec3f(0.0);
+  var m2 = vec3f(0.0);
+  var nearD = d;
+  var nearUv = uv;
+  for (var y = -1; y <= 1; y++) {
+    for (var x = -1; x <= 1; x++) {
+      let o = uv + vec2f(f32(x), f32(y)) * t;
+      let s = cur(o);
+      mn = min(mn, s);
+      mx = max(mx, s);
+      m1 += s;
+      m2 += s * s;
+      if (velocityMode) {
+        let sd = textureSampleLevel(depthTex, nearest, o, 0u);
+        if (sd < nearD) {
+          nearD = sd;
+          nearUv = o;
+        }
+      }
+    }
+  }
+  let mean = m1 / 9.0;
+  if (P.taa.w > 0.5) {
+    let sigma = sqrt(max(m2 / 9.0 - mean * mean, vec3f(0.0)));
+    mn = max(mn, mean - sigma);
+    mx = min(mx, mean + sigma);
+  }
+  // The target holds where the point is minus where it was (uv).
+  var vel = vec2f(0.0);
+  if (velocityMode) {
+    vel = textureSampleLevel(velocityTex, nearest, nearUv, 0.0).xy;
+  }
+  let z = linear_depth(uv, d);
+  var out = c;
+  if (P.taa2.z < 0.5) {
+    var puv = in.uv - vel;
+    var ahead = true;
+    if (dot(vel, vel) < 1e-12) {
+      // The jittered frame's clip position of that depth sample: P.reproj starts from it.
+      let ndc = vec4f(uv.x * 2.0 - 1.0, 1.0 - uv.y * 2.0, d, 1.0);
+      let prev = P.reproj * ndc;
+      let pn = prev.xy / max(prev.w, 1e-6);
+      puv = vec2f(pn.x * 0.5 + 0.5, 0.5 - pn.y * 0.5);
+      ahead = prev.w > 0.0;
+    }
+    var keep = ahead && all(puv >= vec2f(0.0)) && all(puv <= vec2f(1.0));
+    if (keep && velocityMode) {
+      let a = textureSampleLevel(auxTex, nearest, puv, 0.0);
+      let dz = abs(a.z - z) / max(min(a.z, z), 1e-4);
+      let dv = length((vel - a.xy) * dim);
+      keep = a.w > 0.5 && dz <= P.taa3.x && dv <= P.taa3.y;
+    }
+    if (keep) {
+      var hs: vec3f;
+      if (P.taa3.z > 0.5) {
+        hs = hist_catmull_rom(puv);
+      } else {
+        hs = hist(puv);
+      }
+      let h = clamp(hs, mn, mx);
+      out = mix(c, h, P.taa.y);
+    }
+  }
+  // Unsharp against the neighbourhood mean, so the blend's softness comes back as detail.
+  out = max(out + (out - mean) * P.taa.z, vec3f(0.0));
+  return TaaOut(vec4f(out, 1.0), vec4f(vel, z, 1.0));
+}
+`;

package/dist/post/white-balance.d.ts

@@ -0,0 +1,25 @@
+/**
+ * White balance (ws/post-3): the 3×3 linear-sRGB matrix that tints an image toward the colour
+ * of a black body at a temperature, shifted green–magenta by a tint.
+ *
+ * Method: the target white's CIE 1931 chromaticity comes from the Kim et al. (2002) cubic
+ * approximation of the Planckian locus (valid 1667..25000 K); `tint` moves its `y` by 0.05 per
+ * unit (negative `y` shift = magenta). The matrix is the Bradford chromatic adaptation
+ * transform (Lam 1985, as used by ICC) from the 6500 K white to that target, wrapped in the
+ * sRGB (D65) ↔ XYZ matrices. At 6500 K / tint 0 source and target coincide and the matrix is
+ * the identity, so the default setting leaves every pixel as it was.
+ */
+/**
+ * CIE 1931 `xy` of a black body at `kelvin` (clamped to 1667..25000), written to `out[0..1]`
+ * (Kim et al. 2002).
+ */
+export declare function planckianXy(out: {
+    [i: number]: number;
+}, kelvin: number): void;
+/**
+ * Write the 3×3 row-major linear-sRGB white-balance matrix for `kelvin` and `tint` into `out`
+ * (9 numbers): `rgb' = M × rgb`. 6500 / 0 gives the identity. No allocation.
+ */
+export declare function whiteBalanceMatrix(out: {
+    [i: number]: number;
+}, kelvin: number, tint: number): typeof out;

package/dist/post/white-balance.js

@@ -0,0 +1,98 @@
+/**
+ * White balance (ws/post-3): the 3×3 linear-sRGB matrix that tints an image toward the colour
+ * of a black body at a temperature, shifted green–magenta by a tint.
+ *
+ * Method: the target white's CIE 1931 chromaticity comes from the Kim et al. (2002) cubic
+ * approximation of the Planckian locus (valid 1667..25000 K); `tint` moves its `y` by 0.05 per
+ * unit (negative `y` shift = magenta). The matrix is the Bradford chromatic adaptation
+ * transform (Lam 1985, as used by ICC) from the 6500 K white to that target, wrapped in the
+ * sRGB (D65) ↔ XYZ matrices. At 6500 K / tint 0 source and target coincide and the matrix is
+ * the identity, so the default setting leaves every pixel as it was.
+ */
+/** Bradford cone response matrix (row-major 3×3) and its inverse. */
+const BRADFORD = [0.8951, 0.2664, -0.1614, -0.7502, 1.7135, 0.0367, 0.0389, -0.0685, 1.0296];
+const BRADFORD_INV = [
+    0.9869929, -0.1470543, 0.1599627, 0.4323053, 0.5183603, 0.0492912, -0.0085287, 0.0400428,
+    0.9684867,
+];
+/** Linear sRGB → XYZ (D65) and back, row-major. */
+const XYZ_FROM_SRGB = [
+    0.4124564, 0.3575761, 0.1804375, 0.2126729, 0.7151522, 0.072175, 0.0193339, 0.119192, 0.9503041,
+];
+const SRGB_FROM_XYZ = [
+    3.2404542, -1.5371385, -0.4985314, -0.969266, 1.8760108, 0.041556, 0.0556434, -0.2040259,
+    1.0572252,
+];
+const scratchA = new Float64Array(9);
+const scratchB = new Float64Array(9);
+const srcLms = new Float64Array(3);
+const dstLms = new Float64Array(3);
+const srcWhite = new Float64Array(3);
+const dstWhite = new Float64Array(3);
+/**
+ * CIE 1931 `xy` of a black body at `kelvin` (clamped to 1667..25000), written to `out[0..1]`
+ * (Kim et al. 2002).
+ */
+export function planckianXy(out, kelvin) {
+    const t = Math.min(25000, Math.max(1667, kelvin));
+    const t2 = t * t;
+    const t3 = t2 * t;
+    const x = t <= 4000
+        ? -0.2661239e9 / t3 - 0.2343589e6 / t2 + 0.8776956e3 / t + 0.17991
+        : -3.0258469e9 / t3 + 2.1070379e6 / t2 + 0.2226347e3 / t + 0.24039;
+    const x2 = x * x;
+    const x3 = x2 * x;
+    let y;
+    if (t <= 2222)
+        y = -1.1063814 * x3 - 1.3481102 * x2 + 2.18555832 * x - 0.20219683;
+    else if (t <= 4000)
+        y = -0.9549476 * x3 - 1.37418593 * x2 + 2.09137015 * x - 0.16748867;
+    else
+        y = 3.081758 * x3 - 5.8733867 * x2 + 3.75112997 * x - 0.37001483;
+    out[0] = x;
+    out[1] = y;
+}
+function xyToXyz(out, x, y) {
+    const yy = Math.max(y, 1e-4);
+    out[0] = x / yy;
+    out[1] = 1;
+    out[2] = (1 - x - yy) / yy;
+}
+function mul3(out, a, b) {
+    for (let r = 0; r < 3; r++) {
+        for (let c = 0; c < 3; c++) {
+            out[r * 3 + c] = a[r * 3] * b[c] + a[r * 3 + 1] * b[3 + c] + a[r * 3 + 2] * b[6 + c];
+        }
+    }
+    return out;
+}
+function apply3(out, m, v) {
+    out[0] = m[0] * v[0] + m[1] * v[1] + m[2] * v[2];
+    out[1] = m[3] * v[0] + m[4] * v[1] + m[5] * v[2];
+    out[2] = m[6] * v[0] + m[7] * v[1] + m[8] * v[2];
+}
+/**
+ * Write the 3×3 row-major linear-sRGB white-balance matrix for `kelvin` and `tint` into `out`
+ * (9 numbers): `rgb' = M × rgb`. 6500 / 0 gives the identity. No allocation.
+ */
+export function whiteBalanceMatrix(out, kelvin, tint) {
+    planckianXy(srcWhite, 6500);
+    xyToXyz(srcWhite, srcWhite[0], srcWhite[1]);
+    planckianXy(dstWhite, kelvin);
+    xyToXyz(dstWhite, dstWhite[0], dstWhite[1] - 0.05 * Math.min(1, Math.max(-1, tint)));
+    apply3(srcLms, BRADFORD, srcWhite);
+    apply3(dstLms, BRADFORD, dstWhite);
+    // A = Bradford⁻¹ × diag(dst / src) × Bradford.
+    for (let r = 0; r < 3; r++) {
+        const k = dstLms[r] / srcLms[r];
+        scratchA[r * 3] = BRADFORD[r * 3] * k;
+        scratchA[r * 3 + 1] = BRADFORD[r * 3 + 1] * k;
+        scratchA[r * 3 + 2] = BRADFORD[r * 3 + 2] * k;
+    }
+    mul3(scratchB, BRADFORD_INV, scratchA); // A in XYZ
+    mul3(scratchA, scratchB, XYZ_FROM_SRGB); // A × XYZ_from_sRGB
+    mul3(scratchB, SRGB_FROM_XYZ, scratchA); // sRGB_from_XYZ × ...
+    for (let i = 0; i < 9; i++)
+        out[i] = scratchB[i];
+    return out;
+}

package/dist/render/bindings.d.ts

@@ -0,0 +1,98 @@
+import { type SamplerKind, type TextureLike } from './texture.js';
+/**
+ * Shared "uniform + sampler + N textures" binding convention used by materials (group 1) and
+ * fullscreen passes (group 0):
+ *
+ * - `@binding(0)` `var<uniform>`: present when `uniformBytes > 0`
+ * - `@binding(1)` `sampler`: present when `textures > 0`
+ * - `@binding(2 + i)` `texture_2d<f32>`: one per texture slot (`texture_2d_array<f32>` for a
+ *   slot whose `viewDimension` is `'2d-array'`)
+ * - `@binding(16 + i)` (`BUFFER_BINDING_BASE`) `var<storage, read>`: one per `buffers` entry
+ */
+export interface BindingDesc {
+    uniformBytes?: number;
+    textures?: number;
+    sampler?: SamplerKind;
+    /**
+     * View dimension of the texture slots: one value for every slot, or one per slot. Default
+     * `'2d'`. Use `'2d-array'` to bind a texture array (`createTextureArray` /
+     * `loadTextureArray`) as `texture_2d_array<f32>`; an array slot left unbound reads a
+     * 1-layer white array.
+     */
+    viewDimension?: GPUTextureViewDimension | readonly GPUTextureViewDimension[];
+    /** Which stages see the bindings. Default fragment + vertex. */
+    visibility?: GPUShaderStageFlags;
+    /**
+     * Read-only storage buffers, bound whole at `@binding(BUFFER_BINDING_BASE + i)` (a
+     * `SkinPalette.buffer`, a lookup table). Swap one later with `BindingSet.setBuffer`.
+     */
+    buffers?: readonly GPUBuffer[];
+}
+/** First binding of `BindingDesc.buffers` (textures stop at 15, so up to 14 texture slots). */
+export declare const BUFFER_BINDING_BASE = 16;
+/** Extra `BindingSet` behaviour. */
+export interface BindingSetOptions {
+    /**
+     * Per-draw uniform blocks: the uniform binding uses a dynamic offset into a growable buffer.
+     * Slot 0 holds the shared block (`setUniforms`); `pushDrawUniforms` appends one block per
+     * draw for the current frame. Needs `uniformBytes > 0`.
+     */
+    perDraw?: boolean;
+}
+export declare function hasBindings(desc: BindingDesc): boolean;
+/** The view dimension of texture slot `slot` under `desc.viewDimension` (default `'2d'`). */
+export declare function slotViewDimension(desc: BindingDesc, slot: number): GPUTextureViewDimension;
+export declare function createBindingLayout(device: GPUDevice, desc: BindingDesc, label: string, dynamicUniform?: boolean): GPUBindGroupLayout;
+/**
+ * Owns the uniform buffer + bind group for one binding set; rebuilds the group lazily.
+ * Bind groups for the last few texture sets are cached, so alternating textures (ping-pong)
+ * allocates nothing after the first round. Every texture slot starts bound to a 1×1 white
+ * texture (`defaultView`, or `defaultTextures(device).white` when none is given; a 1-layer white
+ * array for `'2d-array'` slots), so a material with four slots draws with none of them set;
+ * `setTexture` later rebuilds the group.
+ */
+export declare class BindingSet {
+    private readonly device;
+    private readonly sampler;
+    private readonly label;
+    readonly layout: GPUBindGroupLayout;
+    /** Replaced when a per-draw set grows. */
+    uniformBuffer: GPUBuffer | null;
+    /** True when the uniform binding takes a dynamic offset (see `BindingSetOptions.perDraw`). */
+    readonly perDraw: boolean;
+    /** Uniform block size in bytes (rounded up to 16), 0 when there is none. */
+    readonly blockBytes: number;
+    /** Byte distance between per-draw blocks (block size rounded up to the offset alignment). */
+    readonly stride: number;
+    private readonly views;
+    private readonly buffers;
+    private group;
+    private readonly cache;
+    private staging;
+    private stagingF32;
+    private drawSlots;
+    constructor(device: GPUDevice, desc: BindingDesc, sampler: GPUSampler, defaultView: GPUTextureView | null | undefined, label: string, opts?: BindingSetOptions);
+    setUniforms(data: BufferSource, byteOffset?: number): void;
+    /** Per-draw blocks recorded since the last flush. */
+    get drawCount(): number;
+    /**
+     * Stage one per-draw uniform block (f32s; the rest of the block reads 0) and return its
+     * dynamic offset. Uploaded by `flushDrawUniforms`, normally called by the renderer.
+     */
+    pushDrawUniforms(data: ArrayLike<number>): number;
+    /** Upload this frame's per-draw blocks (growing the buffer if needed) and reset the count. */
+    flushDrawUniforms(): void;
+    /** Drop this frame's per-draw blocks without uploading. */
+    discardDrawUniforms(): void;
+    setTexture(slot: number, tex: TextureLike | GPUTextureView): void;
+    /** Rebind storage buffer slot `i` (`@binding(BUFFER_BINDING_BASE + i)`); groups rebuild lazily. */
+    setBuffer(slot: number, buffer: GPUBuffer): void;
+    /** Build a bind group for an explicit set of views (callers cache it). */
+    createGroup(views?: readonly GPUTextureView[]): GPUBindGroup;
+    get bindGroup(): GPUBindGroup;
+    destroy(): void;
+    private cachedGroup;
+    private stageShared;
+    private invalidateGroups;
+    private makeUniformBuffer;
+}