@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/post/exposure.js

@@ -0,0 +1,322 @@
+import { createShaderModule } from '../render/wgsl.js';
+export const EXPOSURE_BINS = 64;
+/** log2 luminance of the first bin's lower edge (2^-10 ≈ 0.001). */
+export const EXPOSURE_LOG_MIN = -10;
+/** log2 luminance of the last bin's upper edge (2^6 = 64). */
+export const EXPOSURE_LOG_MAX = 6;
+const LUMA_R = 0.2126;
+const LUMA_G = 0.7152;
+const LUMA_B = 0.0722;
+/** The bin (0..63) a luminance falls in; black and anything under the range land in bin 0. */
+export function exposureBin(luminance) {
+    if (!(luminance > 0))
+        return 0;
+    const t = (Math.log2(luminance) - EXPOSURE_LOG_MIN) / (EXPOSURE_LOG_MAX - EXPOSURE_LOG_MIN);
+    return Math.min(EXPOSURE_BINS - 1, Math.max(0, Math.floor(t * EXPOSURE_BINS)));
+}
+/** log2 luminance at the centre of bin `i`. */
+export function exposureBinLog(i) {
+    return EXPOSURE_LOG_MIN + ((i + 0.5) / EXPOSURE_BINS) * (EXPOSURE_LOG_MAX - EXPOSURE_LOG_MIN);
+}
+/**
+ * CPU reference of the histogram kernel: `rgba` holds `count` linear RGBA texels (any
+ * `ArrayLike`); `out` (64 entries) receives the counts (cleared first).
+ */
+export function exposureHistogram(rgba, count, out = new Uint32Array(EXPOSURE_BINS)) {
+    out.fill(0);
+    for (let i = 0; i < count; i++) {
+        const l = LUMA_R * rgba[i * 4] + LUMA_G * rgba[i * 4 + 1] + LUMA_B * rgba[i * 4 + 2];
+        out[exposureBin(l)]++;
+    }
+    return out;
+}
+/**
+ * CPU reference of the average kernel: the mean log2 luminance of the texels between the
+ * `low` and `high` percentiles of `hist` (bins partially inside the range count partially).
+ * Returns `EXPOSURE_LOG_MIN` for an empty histogram.
+ */
+export function exposureAverage(hist, low, high) {
+    let total = 0;
+    for (let i = 0; i < EXPOSURE_BINS; i++)
+        total += hist[i];
+    if (total <= 0)
+        return EXPOSURE_LOG_MIN;
+    const lo = total * Math.min(1, Math.max(0, low));
+    const hi = total * Math.min(1, Math.max(0, high));
+    let seen = 0;
+    let sum = 0;
+    let weight = 0;
+    for (let i = 0; i < EXPOSURE_BINS; i++) {
+        const n = hist[i];
+        const start = seen;
+        seen += n;
+        // The part of this bin inside [lo, hi].
+        const inside = Math.max(0, Math.min(seen, hi) - Math.max(start, lo));
+        if (inside > 0) {
+            sum += inside * exposureBinLog(i);
+            weight += inside;
+        }
+    }
+    return weight > 0 ? sum / weight : EXPOSURE_LOG_MIN;
+}
+/** The EV the metered average asks for: `log2(keyValue / average)`, clamped to the range. */
+export function exposureTarget(averageLog, keyValue, minEv, maxEv) {
+    const ev = Math.log2(Math.max(keyValue, 1e-6)) - averageLog;
+    return Math.min(maxEv, Math.max(minEv, ev));
+}
+/**
+ * One step of the adaptation: `ev` eased toward `target` over `dt` seconds, at `speedUp`
+ * per second when rising and `speedDown` when falling (exponential, so it settles without
+ * overshoot and a long `dt` lands on the target).
+ */
+export function adaptExposure(ev, target, dt, speedUp, speedDown) {
+    const speed = target > ev ? speedUp : speedDown;
+    if (!(speed > 0) || !(dt > 0))
+        return ev;
+    return target + (ev - target) * Math.exp(-speed * dt);
+}
+/** Bytes of the params block the kernels read: low, high, -, - (as f32). */
+const PARAM_FLOATS = 4;
+const HISTOGRAM_WGSL = /* wgsl */ `
+struct Params { low: f32, high: f32, pad0: f32, pad1: f32 };
+@group(0) @binding(0) var colorTex: texture_2d<f32>;
+@group(0) @binding(1) var<storage, read_write> hist: array<atomic<u32>, ${EXPOSURE_BINS}>;
+@group(0) @binding(2) var<uniform> params: Params;
+var<workgroup> local: array<atomic<u32>, ${EXPOSURE_BINS}>;
+
+const LOG_MIN: f32 = ${EXPOSURE_LOG_MIN}.0;
+const LOG_RANGE: f32 = ${EXPOSURE_LOG_MAX - EXPOSURE_LOG_MIN}.0;
+
+@compute @workgroup_size(16, 16, 1)
+fn main(@builtin(global_invocation_id) gid: vec3u, @builtin(local_invocation_index) li: u32) {
+  if (li < ${EXPOSURE_BINS}u) {
+    atomicStore(&local[li], 0u);
+  }
+  workgroupBarrier();
+  let dim = textureDimensions(colorTex);
+  if (gid.x < dim.x && gid.y < dim.y) {
+    let c = textureLoad(colorTex, vec2i(gid.xy), 0).rgb;
+    let l = dot(c, vec3f(${LUMA_R}, ${LUMA_G}, ${LUMA_B}));
+    var bin = 0u;
+    if (l > 0.0) {
+      let t = (log2(l) - LOG_MIN) / LOG_RANGE;
+      bin = u32(clamp(floor(t * ${EXPOSURE_BINS}.0), 0.0, ${EXPOSURE_BINS - 1}.0));
+    }
+    atomicAdd(&local[bin], 1u);
+  }
+  workgroupBarrier();
+  if (li < ${EXPOSURE_BINS}u) {
+    let n = atomicLoad(&local[li]);
+    if (n > 0u) {
+      atomicAdd(&hist[li], n);
+    }
+  }
+}
+`;
+const AVERAGE_WGSL = /* wgsl */ `
+struct Params { low: f32, high: f32, pad0: f32, pad1: f32 };
+@group(0) @binding(0) var<storage, read> hist: array<u32, ${EXPOSURE_BINS}>;
+@group(0) @binding(1) var<storage, read_write> result: vec4f;
+@group(0) @binding(2) var<uniform> params: Params;
+
+const LOG_MIN: f32 = ${EXPOSURE_LOG_MIN}.0;
+const LOG_RANGE: f32 = ${EXPOSURE_LOG_MAX - EXPOSURE_LOG_MIN}.0;
+
+@compute @workgroup_size(1, 1, 1)
+fn main() {
+  var total = 0.0;
+  for (var i = 0u; i < ${EXPOSURE_BINS}u; i++) {
+    total += f32(hist[i]);
+  }
+  if (total <= 0.0) {
+    result = vec4f(LOG_MIN, 0.0, 0.0, 0.0);
+    return;
+  }
+  let lo = total * clamp(params.low, 0.0, 1.0);
+  let hi = total * clamp(params.high, 0.0, 1.0);
+  var seen = 0.0;
+  var sum = 0.0;
+  var weight = 0.0;
+  for (var i = 0u; i < ${EXPOSURE_BINS}u; i++) {
+    let n = f32(hist[i]);
+    let start = seen;
+    seen += n;
+    let inside = max(0.0, min(seen, hi) - max(start, lo));
+    if (inside > 0.0) {
+      sum += inside * (LOG_MIN + ((f32(i) + 0.5) / ${EXPOSURE_BINS}.0) * LOG_RANGE);
+      weight += inside;
+    }
+  }
+  var avg = LOG_MIN;
+  if (weight > 0.0) {
+    avg = sum / weight;
+  }
+  result = vec4f(avg, total, 0.0, 0.0);
+}
+`;
+/**
+ * The two compute passes and their buffers. `encode` records both (clearing the histogram
+ * first) and the copy into the readback buffer; `poll` maps it when free and stores the last
+ * average in `averageLog`. On a device without `mapAsync` (the fake one) nothing is read back.
+ */
+export class ExposurePasses {
+    device;
+    histogram;
+    average;
+    histLayout;
+    histBuffer;
+    resultBuffer;
+    readBuffer;
+    params;
+    paramData = new Float32Array(PARAM_FLOATS);
+    averageGroup;
+    histGroup = null;
+    boundColor = null;
+    histDesc = { label: 'pass:post-exposure-histogram' };
+    avgDesc = { label: 'pass:post-exposure-average' };
+    /** A copy into the readback buffer is in flight (the next `poll` may map it). */
+    pending = false;
+    mapping = false;
+    /** The last metered average log2 luminance (`EXPOSURE_LOG_MIN` until the first readback). */
+    averageLog = EXPOSURE_LOG_MIN;
+    /** How many readbacks have landed. */
+    readbacks = 0;
+    onMapped;
+    onMapFailed;
+    constructor(renderer) {
+        const device = renderer.device;
+        this.device = device;
+        const compute = GPUShaderStage.COMPUTE;
+        this.histLayout = device.createBindGroupLayout({
+            label: 'pass:post-exposure-histogram',
+            entries: [
+                { binding: 0, visibility: compute, texture: { sampleType: 'unfilterable-float' } },
+                { binding: 1, visibility: compute, buffer: { type: 'storage' } },
+                { binding: 2, visibility: compute, buffer: {} },
+            ],
+        });
+        const avgLayout = device.createBindGroupLayout({
+            label: 'pass:post-exposure-average',
+            entries: [
+                { binding: 0, visibility: compute, buffer: { type: 'read-only-storage' } },
+                { binding: 1, visibility: compute, buffer: { type: 'storage' } },
+                { binding: 2, visibility: compute, buffer: {} },
+            ],
+        });
+        this.histogram = device.createComputePipeline({
+            label: 'pass:post-exposure-histogram',
+            layout: device.createPipelineLayout({ bindGroupLayouts: [this.histLayout] }),
+            compute: {
+                module: createShaderModule(device, HISTOGRAM_WGSL, 'pass:post-exposure-histogram'),
+                entryPoint: 'main',
+            },
+        });
+        this.average = device.createComputePipeline({
+            label: 'pass:post-exposure-average',
+            layout: device.createPipelineLayout({ bindGroupLayouts: [avgLayout] }),
+            compute: {
+                module: createShaderModule(device, AVERAGE_WGSL, 'pass:post-exposure-average'),
+                entryPoint: 'main',
+            },
+        });
+        this.histBuffer = device.createBuffer({
+            label: 'post-exposure-histogram',
+            size: EXPOSURE_BINS * 4,
+            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+        });
+        this.resultBuffer = device.createBuffer({
+            label: 'post-exposure-average',
+            size: 16,
+            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC,
+        });
+        this.readBuffer = device.createBuffer({
+            label: 'post-exposure-readback',
+            size: 16,
+            usage: GPUBufferUsage.MAP_READ | GPUBufferUsage.COPY_DST,
+        });
+        this.params = device.createBuffer({
+            label: 'post-exposure-params',
+            size: PARAM_FLOATS * 4,
+            usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+        });
+        this.averageGroup = device.createBindGroup({
+            label: 'pass:post-exposure-average',
+            layout: avgLayout,
+            entries: [
+                { binding: 0, resource: { buffer: this.histBuffer } },
+                { binding: 1, resource: { buffer: this.resultBuffer } },
+                { binding: 2, resource: { buffer: this.params } },
+            ],
+        });
+        this.onMapped = () => {
+            const data = new Float32Array(this.readBuffer.getMappedRange());
+            this.averageLog = data[0];
+            this.readBuffer.unmap();
+            this.mapping = false;
+            this.pending = false;
+            this.readbacks++;
+        };
+        this.onMapFailed = () => {
+            this.mapping = false;
+            this.pending = false;
+        };
+    }
+    /**
+     * Map the last copy if one is waiting and the buffer is free (call before `encode`, once the
+     * previous frame's work has been submitted).
+     */
+    poll() {
+        if (!this.pending || this.mapping)
+            return;
+        if (typeof this.readBuffer.mapAsync !== 'function')
+            return;
+        if (this.readBuffer.mapState !== 'unmapped')
+            return;
+        this.mapping = true;
+        this.readBuffer.mapAsync(GPUMapMode.READ).then(this.onMapped, this.onMapFailed);
+    }
+    /** Record the histogram, the average and (when the readback buffer is free) the copy. */
+    encode(encoder, color, width, height, low, high) {
+        if (color !== this.boundColor) {
+            this.boundColor = color;
+            this.histGroup = this.device.createBindGroup({
+                label: 'pass:post-exposure-histogram',
+                layout: this.histLayout,
+                entries: [
+                    { binding: 0, resource: color },
+                    { binding: 1, resource: { buffer: this.histBuffer } },
+                    { binding: 2, resource: { buffer: this.params } },
+                ],
+            });
+        }
+        this.paramData[0] = low;
+        this.paramData[1] = high;
+        this.device.queue.writeBuffer(this.params, 0, this.paramData);
+        encoder.clearBuffer(this.histBuffer);
+        const h = encoder.beginComputePass(this.histDesc);
+        h.setPipeline(this.histogram);
+        h.setBindGroup(0, this.histGroup);
+        h.dispatchWorkgroups(Math.ceil(width / 16), Math.ceil(height / 16));
+        h.end();
+        const a = encoder.beginComputePass(this.avgDesc);
+        a.setPipeline(this.average);
+        a.setBindGroup(0, this.averageGroup);
+        a.dispatchWorkgroups(1);
+        a.end();
+        if (!this.pending) {
+            encoder.copyBufferToBuffer(this.resultBuffer, 0, this.readBuffer, 0, 16);
+            this.pending = true;
+        }
+    }
+    /** Forget a stale bind group (the colour texture was replaced). */
+    invalidate() {
+        this.boundColor = null;
+        this.histGroup = null;
+    }
+    destroy() {
+        this.histBuffer.destroy();
+        this.resultBuffer.destroy();
+        this.readBuffer.destroy();
+        this.params.destroy();
+    }
+}

package/dist/post/index.d.ts

@@ -0,0 +1,12 @@
+export { aoProjectedRadius } from './ao.js';
+export { type Ease, easeIn, easeInOut, easeLinear, easeOut, PostBlender } from './blend.js';
+export { adaptExposure, EXPOSURE_BINS, EXPOSURE_LOG_MAX, EXPOSURE_LOG_MIN, exposureAverage, exposureBin, exposureBinLog, exposureHistogram, exposureTarget, } from './exposure.js';
+export { createLensDirtTexture, lensDirtTexels } from './lens-dirt.js';
+export { createLutTexture, identityLut, type LutFn, type LutSize, lutTexels } from './lut.js';
+export { motionVelocity } from './motion-blur.js';
+export { PostStack } from './post-stack.js';
+export type { AberrationSettings, AoSettings, BloomSettings, DofSettings, ExposureSettings, FxaaSettings, GodRaySettings, GradeSettings, GrainSettings, LensDirtSettings, LutSettings, MistSettings, MotionBlurMode, MotionBlurSettings, OutlineSettings, PostFrameState, PostQuality, PostQualityTier, PostSettings, PostSettingsPatch, RGB, SharpenSettings, SsrSettings, TaaHistoryFilter, TaaReprojection, TaaSettings, Tonemap, VignetteSettings, WhiteBalanceSettings, } from './settings.js';
+export { applyPostPatch, cinematicPostSettings, clonePostSettings, defaultPostQuality, godRaySource, lowPostQuality, neutralPostSettings, postQualityFor, } from './settings.js';
+export { ssrEdgeFade, ssrRoughnessFade, ssrStep, ssrSurfaceWeight } from './ssr.js';
+export { halton, TAA_AUX_FORMAT, TAA_MAX_FEEDBACK, Taa, taaBlendWeight, taaCatmullRomWeights, taaRejects, taaReprojection, } from './taa.js';
+export { planckianXy, whiteBalanceMatrix } from './white-balance.js';

package/dist/post/index.js

@@ -0,0 +1,11 @@
+export { aoProjectedRadius } from './ao.js';
+export { easeIn, easeInOut, easeLinear, easeOut, PostBlender } from './blend.js';
+export { adaptExposure, EXPOSURE_BINS, EXPOSURE_LOG_MAX, EXPOSURE_LOG_MIN, exposureAverage, exposureBin, exposureBinLog, exposureHistogram, exposureTarget, } from './exposure.js';
+export { createLensDirtTexture, lensDirtTexels } from './lens-dirt.js';
+export { createLutTexture, identityLut, lutTexels } from './lut.js';
+export { motionVelocity } from './motion-blur.js';
+export { PostStack } from './post-stack.js';
+export { applyPostPatch, cinematicPostSettings, clonePostSettings, defaultPostQuality, godRaySource, lowPostQuality, neutralPostSettings, postQualityFor, } from './settings.js';
+export { ssrEdgeFade, ssrRoughnessFade, ssrStep, ssrSurfaceWeight } from './ssr.js';
+export { halton, TAA_AUX_FORMAT, TAA_MAX_FEEDBACK, Taa, taaBlendWeight, taaCatmullRomWeights, taaRejects, taaReprojection, } from './taa.js';
+export { planckianXy, whiteBalanceMatrix } from './white-balance.js';

package/dist/post/lens-dirt.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Lens dirt (ws/post-3): a procedural `rgba8unorm` texture of speckles and smudges the
+ * composite multiplies into the bloom term (`bloom × (1 + dirt × intensity)`). Pass it as
+ * `settings.bloom.dirt = { texture, intensity }`.
+ */
+/**
+ * The texels of a `size × size` dirt map (rgba8, greyscale, alpha 255), deterministic in
+ * `seed`: ~`size / 2` soft speckles of a few px and a handful of long faint smudges, strongest
+ * toward the corners so the centre of the frame stays clean.
+ */
+export declare function lensDirtTexels(size: number, seed: number): Uint8Array;
+/** A `size × size` `rgba8unorm` dirt texture on `device` (uploaded once; destroy it yourself). */
+export declare function createLensDirtTexture(device: GPUDevice, size?: number, seed?: number): GPUTexture;

package/dist/post/lens-dirt.js

@@ -0,0 +1,91 @@
+/**
+ * Lens dirt (ws/post-3): a procedural `rgba8unorm` texture of speckles and smudges the
+ * composite multiplies into the bloom term (`bloom × (1 + dirt × intensity)`). Pass it as
+ * `settings.bloom.dirt = { texture, intensity }`.
+ */
+function hash(seed, i) {
+    // Two rounds of a 32-bit integer mix; returns 0..1.
+    let x = (Math.imul(seed | 0, 0x9e3779b1) ^ Math.imul(i + 1, 0x85ebca6b)) >>> 0;
+    x = Math.imul(x ^ (x >>> 15), 0x2c1b3c6d) >>> 0;
+    x = Math.imul(x ^ (x >>> 12), 0x297a2d39) >>> 0;
+    return ((x ^ (x >>> 15)) >>> 0) / 4294967296;
+}
+/**
+ * The texels of a `size × size` dirt map (rgba8, greyscale, alpha 255), deterministic in
+ * `seed`: ~`size / 2` soft speckles of a few px and a handful of long faint smudges, strongest
+ * toward the corners so the centre of the frame stays clean.
+ */
+export function lensDirtTexels(size, seed) {
+    const n = Math.max(1, Math.floor(size));
+    const img = new Float32Array(n * n);
+    let k = 0;
+    const speckles = Math.max(4, n >> 1);
+    for (let i = 0; i < speckles; i++) {
+        const cx = hash(seed, k++) * n;
+        const cy = hash(seed, k++) * n;
+        const r = 0.5 + hash(seed, k++) * hash(seed, k++) * (n / 40);
+        const a = 0.3 + hash(seed, k++) * 0.7;
+        stamp(img, n, cx, cy, r, r, 0, a);
+    }
+    const smudges = 6 + Math.floor(hash(seed, k++) * 6);
+    for (let i = 0; i < smudges; i++) {
+        const cx = hash(seed, k++) * n;
+        const cy = hash(seed, k++) * n;
+        const len = n * (0.08 + hash(seed, k++) * 0.2);
+        const wid = n * (0.01 + hash(seed, k++) * 0.02);
+        const ang = hash(seed, k++) * Math.PI;
+        stamp(img, n, cx, cy, len, wid, ang, 0.08 + hash(seed, k++) * 0.12);
+    }
+    const out = new Uint8Array(n * n * 4);
+    for (let y = 0; y < n; y++) {
+        for (let x = 0; x < n; x++) {
+            // Vignette the dirt: full at the corners, a third in the centre.
+            const dx = (x + 0.5) / n - 0.5;
+            const dy = (y + 0.5) / n - 0.5;
+            const edge = 0.35 + 0.65 * Math.min(1, Math.hypot(dx, dy) * 1.6);
+            const v = Math.round(Math.min(1, img[y * n + x] * edge) * 255);
+            const o = (y * n + x) * 4;
+            out[o] = v;
+            out[o + 1] = v;
+            out[o + 2] = v;
+            out[o + 3] = 255;
+        }
+    }
+    return out;
+}
+/** Add a soft ellipse (`rx` along `angle`, `ry` across) of peak `amount` at `(cx, cy)`. */
+function stamp(img, n, cx, cy, rx, ry, angle, amount) {
+    const reach = Math.ceil(Math.max(rx, ry)) + 1;
+    const x0 = Math.max(0, Math.floor(cx - reach));
+    const x1 = Math.min(n - 1, Math.ceil(cx + reach));
+    const y0 = Math.max(0, Math.floor(cy - reach));
+    const y1 = Math.min(n - 1, Math.ceil(cy + reach));
+    const c = Math.cos(angle);
+    const s = Math.sin(angle);
+    for (let y = y0; y <= y1; y++) {
+        for (let x = x0; x <= x1; x++) {
+            const dx = x + 0.5 - cx;
+            const dy = y + 0.5 - cy;
+            const u = (dx * c + dy * s) / rx;
+            const v = (-dx * s + dy * c) / ry;
+            const d = u * u + v * v;
+            if (d >= 1)
+                continue;
+            const f = 1 - d;
+            img[y * n + x] = Math.min(1, img[y * n + x] + amount * f * f);
+        }
+    }
+}
+/** A `size × size` `rgba8unorm` dirt texture on `device` (uploaded once; destroy it yourself). */
+export function createLensDirtTexture(device, size = 256, seed = 1) {
+    const n = Math.max(1, Math.floor(size));
+    const texture = device.createTexture({
+        label: 'post-lens-dirt',
+        size: [n, n],
+        format: 'rgba8unorm',
+        usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST,
+    });
+    const texels = lensDirtTexels(n, seed);
+    device.queue.writeTexture({ texture }, texels, { bytesPerRow: n * 4, rowsPerImage: n }, [n, n]);
+    return texture;
+}

package/dist/post/lut.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 3D colour lookup tables for `PostSettings.lut` (ws/post-2): a `size`³ `rgba8unorm` texture
+ * the composite samples trilinearly with the graded colour as the coordinate (red along x,
+ * green along y, blue along z). Build one from a function with `createLutTexture`, or start
+ * from `identityLut` and edit its texels.
+ */
+export type LutSize = 16 | 32;
+/** Maps an input colour (each 0..1) to an output colour (each 0..1, clamped on write). */
+export type LutFn = (r: number, g: number, b: number) => readonly [number, number, number];
+/**
+ * The texels `createLutTexture` uploads: `size`³ RGBA8 values, red fastest, then green, then
+ * blue (one `size`×`size` slice per blue step). Exported so a LUT can be checked or edited on the
+ * CPU before upload.
+ */
+export declare function lutTexels(size: LutSize, fn: LutFn): Uint8Array;
+/** Make and upload a `size`³ LUT from `fn`. Destroy it with `texture.destroy()` when done. */
+export declare function createLutTexture(device: GPUDevice, size: LutSize, fn: LutFn): GPUTexture;
+/** A LUT that leaves colours alone: the starting point for a graded one. */
+export declare function identityLut(device: GPUDevice, size: LutSize): GPUTexture;

package/dist/post/lut.js

@@ -0,0 +1,50 @@
+/**
+ * 3D colour lookup tables for `PostSettings.lut` (ws/post-2): a `size`³ `rgba8unorm` texture
+ * the composite samples trilinearly with the graded colour as the coordinate (red along x,
+ * green along y, blue along z). Build one from a function with `createLutTexture`, or start
+ * from `identityLut` and edit its texels.
+ */
+/**
+ * The texels `createLutTexture` uploads: `size`³ RGBA8 values, red fastest, then green, then
+ * blue (one `size`×`size` slice per blue step). Exported so a LUT can be checked or edited on the
+ * CPU before upload.
+ */
+export function lutTexels(size, fn) {
+    const n = size;
+    const out = new Uint8Array(n * n * n * 4);
+    const step = 1 / (n - 1);
+    let o = 0;
+    for (let b = 0; b < n; b++) {
+        for (let g = 0; g < n; g++) {
+            for (let r = 0; r < n; r++) {
+                const c = fn(r * step, g * step, b * step);
+                out[o] = quantize(c[0]);
+                out[o + 1] = quantize(c[1]);
+                out[o + 2] = quantize(c[2]);
+                out[o + 3] = 255;
+                o += 4;
+            }
+        }
+    }
+    return out;
+}
+/** Make and upload a `size`³ LUT from `fn`. Destroy it with `texture.destroy()` when done. */
+export function createLutTexture(device, size, fn) {
+    const texture = device.createTexture({
+        label: 'post-lut',
+        size: [size, size, size],
+        dimension: '3d',
+        format: 'rgba8unorm',
+        usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST,
+    });
+    device.queue.writeTexture({ texture }, lutTexels(size, fn), { bytesPerRow: size * 4, rowsPerImage: size }, [size, size, size]);
+    return texture;
+}
+/** A LUT that leaves colours alone: the starting point for a graded one. */
+export function identityLut(device, size) {
+    return createLutTexture(device, size, identity);
+}
+const identity = (r, g, b) => [r, g, b];
+function quantize(v) {
+    return Math.round(Math.min(1, Math.max(0, v)) * 255);
+}

package/dist/post/motion-blur.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The screen-space velocity (uv units, +x right, +y down) of the pixel at `(u, v)` with clip
+ * depth `depth`, through `reproj` (current clip → previous clip): where the point was minus
+ * where it is. Written to `out[0..1]`; the shader's `velocity` does the same.
+ */
+export declare function motionVelocity(out: {
+    [i: number]: number;
+}, reproj: ArrayLike<number>, u: number, v: number, depth: number): typeof out;
+export declare const MOTION_BLUR_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 velocityTex: texture_2d<f32>;\n\nfn velocity(uv: vec2f, d: f32) -> vec2f {\n  let prev = P.reproj * vec4f(uv.x * 2.0 - 1.0, 1.0 - uv.y * 2.0, d, 1.0);\n  if (prev.w <= 0.0) {\n    return vec2f(0.0);\n  }\n  let pn = prev.xy / prev.w;\n  return vec2f(pn.x * 0.5 + 0.5, 0.5 - pn.y * 0.5) - uv;\n}\n\n@fragment fn fs_main(in: FullscreenIn) -> @location(0) vec4f {\n  let uv = in.uv;\n  let d = textureSampleLevel(depthTex, nearest, uv, 0u);\n  var v = vec2f(0.0);\n  if (P.motionBlur.w > 0.5) {\n    // The target holds where the pixel is minus where it was; the gather is symmetric, but keep\n    // the camera path's sign (where it was minus where it is).\n    v = -textureSampleLevel(velocityTex, nearest, uv, 0.0).xy;\n  }\n  if (dot(v, v) < 1e-12) {\n    v = velocity(uv, d);\n  }\n  var vel = v * P.motionBlur.y;\n  // Cap the smear at a tenth of the screen so a teleport does not wipe the frame.\n  let len = length(vel);\n  if (len > 0.1) {\n    vel *= 0.1 / len;\n  }\n  let n = i32(P.motionBlur.z);\n  var sum = vec3f(0.0);\n  for (var i = 0; i < n; i++) {\n    let f = (f32(i) + 0.5) / f32(n) - 0.5;\n    sum += textureSampleLevel(colorTex, linSamp, uv + vel * f, 0.0).rgb;\n  }\n  return vec4f(sum / f32(n), 1.0);\n}\n";

package/dist/post/motion-blur.js

@@ -0,0 +1,78 @@
+/**
+ * Motion blur (ws/post-3, object velocity since ws/post-4): a scene-size `DepthPass` that
+ * averages `P.motionBlur.z` taps of the scene colour along each pixel's velocity, scaled by
+ * `P.motionBlur.y`. The composite reads the result as its scene colour, so the blur sits
+ * before bloom.
+ *
+ * The velocity: in `'object'` mode with a velocity target (`P.motionBlur.w`, `@binding(5)`,
+ * `PostInputs.velocity`, uv motion since last frame) the pixel's own value, so a moving or
+ * skinned object smears under a still camera; a pixel the target holds no motion for (zero:
+ * nothing that writes velocity drew there) falls back to the camera: its depth reprojected
+ * through `P.reproj` (current clip → previous clip, the matrix TAA keeps). Without the target,
+ * and in `'camera'` mode, every pixel takes the camera's.
+ */
+import { mat4 } from '../core/math.js';
+import { WGSL_POST_UNIFORMS } from './settings.js';
+const clip = new Float32Array(3);
+/**
+ * The screen-space velocity (uv units, +x right, +y down) of the pixel at `(u, v)` with clip
+ * depth `depth`, through `reproj` (current clip → previous clip): where the point was minus
+ * where it is. Written to `out[0..1]`; the shader's `velocity` does the same.
+ */
+export function motionVelocity(out, reproj, u, v, depth) {
+    const w = mat4.transformPoint(clip, reproj, u * 2 - 1, 1 - v * 2, depth);
+    if (w <= 0) {
+        out[0] = 0;
+        out[1] = 0;
+        return out;
+    }
+    const pu = clip[0] * 0.5 + 0.5;
+    const pv = 0.5 - clip[1] * 0.5;
+    out[0] = pu - u;
+    out[1] = pv - v;
+    return out;
+}
+export const MOTION_BLUR_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 velocityTex: texture_2d<f32>;
+
+fn velocity(uv: vec2f, d: f32) -> vec2f {
+  let prev = P.reproj * vec4f(uv.x * 2.0 - 1.0, 1.0 - uv.y * 2.0, d, 1.0);
+  if (prev.w <= 0.0) {
+    return vec2f(0.0);
+  }
+  let pn = prev.xy / prev.w;
+  return vec2f(pn.x * 0.5 + 0.5, 0.5 - pn.y * 0.5) - uv;
+}
+
+@fragment fn fs_main(in: FullscreenIn) -> @location(0) vec4f {
+  let uv = in.uv;
+  let d = textureSampleLevel(depthTex, nearest, uv, 0u);
+  var v = vec2f(0.0);
+  if (P.motionBlur.w > 0.5) {
+    // The target holds where the pixel is minus where it was; the gather is symmetric, but keep
+    // the camera path's sign (where it was minus where it is).
+    v = -textureSampleLevel(velocityTex, nearest, uv, 0.0).xy;
+  }
+  if (dot(v, v) < 1e-12) {
+    v = velocity(uv, d);
+  }
+  var vel = v * P.motionBlur.y;
+  // Cap the smear at a tenth of the screen so a teleport does not wipe the frame.
+  let len = length(vel);
+  if (len > 0.1) {
+    vel *= 0.1 / len;
+  }
+  let n = i32(P.motionBlur.z);
+  var sum = vec3f(0.0);
+  for (var i = 0; i < n; i++) {
+    let f = (f32(i) + 0.5) / f32(n) - 0.5;
+    sum += textureSampleLevel(colorTex, linSamp, uv + vel * f, 0.0).rgb;
+  }
+  return vec4f(sum / f32(n), 1.0);
+}
+`;