wgpu-kit 0.9.11 → 1.0.0

package/dist/interop/three.js

@@ -0,0 +1,29 @@
+export function threePoints(sim, THREE, opts = {}) {
+    const { pos } = sim.buffers();
+    const count = pos.length;
+    const positions = new Float32Array(count * 3); // three 需要 vec3,z=0
+    const geometry = new THREE.BufferGeometry();
+    const attr = new THREE.BufferAttribute(positions, 3);
+    geometry.setAttribute('position', attr);
+    const material = new THREE.PointsMaterial({
+        size: opts.size ?? 0.015,
+        color: opts.color ?? 0x8fb4ff,
+        sizeAttenuation: true,
+    });
+    const points = new THREE.Points(geometry, material);
+    return {
+        points,
+        async update() {
+            const data = (await pos.read());
+            for (let i = 0; i < count; i++) {
+                positions[i * 3] = data[i * 2] ?? 0;
+                positions[i * 3 + 1] = data[i * 2 + 1] ?? 0;
+                positions[i * 3 + 2] = 0;
+            }
+            attr.needsUpdate = true;
+        },
+        dispose() {
+            sim.destroy();
+        },
+    };
+}

package/dist/media.js

@@ -0,0 +1,70 @@
+const CANDIDATES = [
+    // webm 在无头/软件编码环境下最可靠;mp4 的 isTypeSupported 可能"说行但编不动"
+    // (实测 headless Edge:mp4 协商成功但产物 0 字节),故排后
+    'video/webm;codecs=vp9',
+    'video/webm;codecs=vp8',
+    'video/webm',
+    'video/mp4;codecs=avc1.42E01E',
+    'video/mp4',
+];
+export function pickMime() {
+    if (typeof MediaRecorder === 'undefined')
+        return null;
+    for (const m of CANDIDATES) {
+        if (MediaRecorder.isTypeSupported(m))
+            return m;
+    }
+    return null;
+}
+export class CanvasRecorder {
+    #recorder = null;
+    #chunks = [];
+    #startedAt = 0;
+    #mime;
+    constructor() {
+        const mime = pickMime();
+        if (!mime)
+            throw new Error('当前环境不支持 MediaRecorder 录制(无可用编码)');
+        this.#mime = mime;
+    }
+    get mimeType() { return this.#mime; }
+    get recording() { return this.#recorder?.state === 'recording'; }
+    start(canvas, videoBitsPerSecond = 12_000_000) {
+        if (this.#recorder)
+            throw new Error('已在录制中');
+        const stream = canvas.captureStream(60);
+        this.#chunks = [];
+        this.#recorder = new MediaRecorder(stream, { mimeType: this.#mime, videoBitsPerSecond });
+        this.#recorder.ondataavailable = (e) => { if (e.data.size > 0)
+            this.#chunks.push(e.data); };
+        this.#startedAt = performance.now();
+        this.#recorder.start(250);
+    }
+    stop() {
+        return new Promise((ok, err) => {
+            const r = this.#recorder;
+            if (!r || r.state !== 'recording') {
+                err(new Error('没有进行中的录制'));
+                return;
+            }
+            r.onstop = () => {
+                const blob = new Blob(this.#chunks, { type: this.#mime });
+                this.#recorder = null;
+                if (blob.size === 0) {
+                    err(new Error(`录制产物为空(${this.#mime});编码器可能不可用,换浏览器或网络前重试`));
+                    return;
+                }
+                ok({ blob, mimeType: this.#mime, seconds: (performance.now() - this.#startedAt) / 1000, bytes: blob.size });
+            };
+            r.stop();
+        });
+    }
+}
+/** 触发浏览器下载(录完即得的最后一公里) */
+export function downloadBlob(blob, filename) {
+    const a = document.createElement('a');
+    a.href = URL.createObjectURL(blob);
+    a.download = filename;
+    a.click();
+    setTimeout(() => URL.revokeObjectURL(a.href), 5000);
+}

package/dist/observe.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 可观测性与健壮性助手(批次 2)。
+ * —— 评审指出的"最大产品级缺口":GPGPU 库却看不到"这帧 GPU 花了多少"。
+ */
+import { GpuContext } from './core/context.ts';
+/** 时间戳查询封装:测量一段 GPU 工作的真实耗时(毫秒)。
+ *  Chrome/Edge 支持 timestamp-query;不支持的浏览器 reject。 */
+export declare function timeGpu(fn: (ctx: GpuContext) => void | Promise<void>): Promise<number>;
+/** 设备诊断:注册错误/丢失回调;设备丢失时自动重建上下文并调用 onRebuild。
+ *  长跑页面(展览/大屏)的必需品。 */
+export declare function watchDevice(opts: {
+    onError?: (message: string, recoverable: boolean) => void;
+    onRebuild?: (ctx: GpuContext) => void;
+}): void;
+/** 推荐的画布 canvas 格式(一行助手的语义化封装)。 */
+export declare function preferredCanvasFormat(): GPUTextureFormat;
+/** 画布 resize(DPR 上限策略):宽高物理像素 = clientSize × min(dpr, cap)。
+ *  返回是否实际改变了尺寸(没变则无需重建)。 */
+export declare function resizeCanvas(canvas: HTMLCanvasElement, dprCap?: number): boolean;

package/dist/observe.js

@@ -0,0 +1,76 @@
+/**
+ * 可观测性与健壮性助手(批次 2)。
+ * —— 评审指出的"最大产品级缺口":GPGPU 库却看不到"这帧 GPU 花了多少"。
+ */
+import { GpuContext } from "./core/context.js";
+import { UsageError } from "./core/errors.js";
+/** 时间戳查询封装:测量一段 GPU 工作的真实耗时(毫秒)。
+ *  Chrome/Edge 支持 timestamp-query;不支持的浏览器 reject。 */
+export async function timeGpu(fn) {
+    const ctx = await GpuContext.get();
+    const device = ctx.device;
+    const featureOk = device.features.has('timestamp-query');
+    if (!featureOk)
+        throw new UsageError('timestamp-query 在当前设备不可用(需 Chrome/Edge + 支持时间戳的 GPU)');
+    const QUERY_POOL = 2;
+    const querySet = device.createQuerySet({ type: 'timestamp', count: QUERY_POOL });
+    const resolveBuf = device.createBuffer({
+        size: QUERY_POOL * 8,
+        usage: GPUBufferUsage.QUERY_RESOLVE | GPUBufferUsage.COPY_SRC,
+    });
+    const readBuf = device.createBuffer({ size: QUERY_POOL * 8, usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ });
+    // 新版 WebGPU 规范:时间戳通过 pass 的 timestampWrites 写入(无 encoder.writeTimestamp)
+    const enc = device.createCommandEncoder();
+    {
+        const p0 = enc.beginComputePass({ timestampWrites: { querySet, beginningOfPassWriteIndex: 0 } });
+        p0.end();
+    }
+    await fn(ctx);
+    {
+        const p1 = enc.beginComputePass({ timestampWrites: { querySet, beginningOfPassWriteIndex: 1 } });
+        p1.end();
+    }
+    enc.resolveQuerySet(querySet, 0, QUERY_POOL, resolveBuf, 0);
+    enc.copyBufferToBuffer(resolveBuf, 0, readBuf, 0, QUERY_POOL * 8);
+    device.queue.submit([enc.finish()]);
+    await readBuf.mapAsync(GPUMapMode.READ);
+    const times = new BigInt64Array(readBuf.getMappedRange().slice(0));
+    readBuf.unmap();
+    querySet.destroy();
+    resolveBuf.destroy();
+    readBuf.destroy();
+    // period = 1ns(按规范),换算毫秒
+    const deltaNs = Number(times[1] - times[0]);
+    return deltaNs / 1e6;
+}
+/** 设备诊断:注册错误/丢失回调;设备丢失时自动重建上下文并调用 onRebuild。
+ *  长跑页面(展览/大屏)的必需品。 */
+export function watchDevice(opts) {
+    void GpuContext.get().then((ctx) => {
+        ctx.device.addEventListener?.('uncapturederror', (e) => {
+            opts.onError?.(String(e.error?.message ?? e), true);
+        });
+        void ctx.lost.then((info) => {
+            opts.onError?.(`GPU device lost: ${info.reason}`, false);
+            // 丢失后重置单例,下一次 GpuContext.get() 走全新设备
+            GpuContext.resetForTests?.();
+            void GpuContext.get().then((fresh) => opts.onRebuild?.(fresh)).catch(() => undefined);
+        });
+    });
+}
+/** 推荐的画布 canvas 格式(一行助手的语义化封装)。 */
+export function preferredCanvasFormat() {
+    return navigator.gpu.getPreferredCanvasFormat();
+}
+/** 画布 resize(DPR 上限策略):宽高物理像素 = clientSize × min(dpr, cap)。
+ *  返回是否实际改变了尺寸(没变则无需重建)。 */
+export function resizeCanvas(canvas, dprCap = 2) {
+    const dpr = Math.min(window.devicePixelRatio || 1, dprCap);
+    const w = Math.max(1, Math.floor(canvas.clientWidth * dpr));
+    const h = Math.max(1, Math.floor(canvas.clientHeight * dpr));
+    if (canvas.width === w && canvas.height === h)
+        return false;
+    canvas.width = w;
+    canvas.height = h;
+    return true;
+}

package/dist/packs/fields/index.js

@@ -0,0 +1,230 @@
+import { GpuContext } from "../../core/context.js";
+import { Buffer } from "../../core/buffer.js";
+import { PingPong } from "../../core/pingpong.js";
+import { CompileError } from "../../core/errors.js";
+import { MapRenderer } from "../life/map.js";
+import { mulberry32 } from "../particles/presets.js";
+const FIELD_FNS = {
+    // 绕心漩涡:切向速度,离心得越远越慢
+    vortex: `
+fn fieldAt(p: vec2f, t: f32) -> vec2f {
+  let r = length(p) + 0.12;
+  return vec2f(-p.y, p.x) / r * 1.4;
+}`,
+    // curl noise:值噪声的旋度,无散度,像真实的湍流
+    curl: `
+fn hash(p: vec2f) -> f32 {
+  return fract(sin(dot(p, vec2f(127.1, 311.7))) * 43758.5453);
+}
+fn vnoise(p: vec2f) -> f32 {
+  let i = floor(p);
+  let f = fract(p);
+  let u = f * f * (3.0 - 2.0 * f);
+  return mix(mix(hash(i), hash(i + vec2f(1.0, 0.0)), u.x), mix(hash(i + vec2f(0.0, 1.0)), hash(i + vec2f(1.0, 1.0)), u.x), u.y);
+}
+fn fieldAt(p: vec2f, t: f32) -> vec2f {
+  let s = 2.2;
+  let e = 0.01;
+  let n1 = vnoise(p * s + vec2f(0.0, t * 0.15));
+  let n2 = vnoise(p * s + vec2f(17.3, t * 0.15));
+  let dx = vnoise(p * s + vec2f(e, 0.0) + vec2f(0.0, t * 0.15)) - n1;
+  let dy = vnoise(p * s + vec2f(0.0, e) + vec2f(17.3, t * 0.15)) - n2;
+  return normalize(vec2f(dy, -dx) / e + vec2f(1e-5));
+}`,
+    // 双涡:左右反向旋转,中间有剪切层
+    twin: `
+fn fieldAt(p: vec2f, t: f32) -> vec2f {
+  let s = select(-1.0, 1.0, p.x > 0.0);
+  let c = vec2f(0.55 * s, 0.0);
+  let r = length(p - c) + 0.1;
+  let swirl = vec2f(-(p - c).y, (p - c).x) / r;
+  return swirl * s * 1.3 + vec2f(0.0, sin(t * 0.4) * 0.2);
+}`,
+};
+const AWG = 32;
+export async function flow(config = {}) {
+    const { count: N = 131_072, mapSize = 1024, field = 'curl', speed = 0.004, decay = 0.045, deposit = 1.0, seed = 'flow', colormap = 'ice', } = config;
+    const seedHash = typeof seed === 'string' ? hashStr(seed) : (seed ?? 11);
+    const ctx = await GpuContext.get();
+    const device = ctx.device;
+    const posBuf = await Buffer.create('vec2f', N);
+    {
+        const rand = mulberry32(seedHash);
+        const p = new Float32Array(N * 2);
+        for (let i = 0; i < N; i++) {
+            p[i * 2] = rand() * 1.8 - 0.9;
+            p[i * 2 + 1] = rand() * 1.8 - 0.9;
+        }
+        posBuf.write(p);
+    }
+    const trail = await PingPong.create({ t: 'f32' }, mapSize * mapSize);
+    const trailA = trail.current.t;
+    const trailB = trail.other.t;
+    const uniform = device.createBuffer({ size: AWG, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST });
+    // 持久参数对象:每次全量写入(首版只写部分字段,未写字段被清零 → deposit=0 的教训)
+    const u = { count: N, pad: 0, speed, worldHalf: 1.0, deposit, time: 0, p0: 0, p1: 0 };
+    const writeUniform = () => {
+        const b = new ArrayBuffer(AWG);
+        const v = new DataView(b);
+        v.setUint32(0, u.count, true);
+        v.setUint32(4, u.pad, true);
+        v.setFloat32(8, u.speed, true);
+        v.setFloat32(12, u.worldHalf, true);
+        v.setFloat32(16, u.deposit, true);
+        v.setFloat32(20, u.time, true);
+        device.queue.writeBuffer(uniform, 0, b);
+    };
+    writeUniform();
+    const diffuseUniform = device.createBuffer({ size: 16, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST });
+    device.queue.writeBuffer(diffuseUniform, 0, new Uint32Array([mapSize, mapSize]));
+    device.queue.writeBuffer(diffuseUniform, 8, new Float32Array([1 - decay, 0]));
+    const compile = async (code, label) => {
+        const m = device.createShaderModule({ code, label });
+        const info = await m.getCompilationInfo();
+        const errors = info.messages.filter((x) => x.type === 'error');
+        if (errors.length > 0)
+            throw new CompileError(label, errors.map((x) => ({ line: x.lineNum, msg: x.message })), 0);
+        return m;
+    };
+    const mAdvect = await compile(advectWgsl(FIELD_FNS[field], mapSize), `fields-advect(${field})`);
+    const mDiffuse = await compile(diffuseWgsl(), 'fields-diffuse');
+    const pAdvect = device.createComputePipeline({ layout: 'auto', compute: { module: mAdvect, entryPoint: 'main' } });
+    const pDiffuse = device.createComputePipeline({ layout: 'auto', compute: { module: mDiffuse, entryPoint: 'main' } });
+    const bgAdvect = (t) => device.createBindGroup({
+        layout: pAdvect.getBindGroupLayout(0),
+        entries: [
+            { binding: 0, resource: { buffer: uniform } },
+            { binding: 1, resource: { buffer: posBuf.gpuBuffer } },
+            { binding: 2, resource: { buffer: t.gpuBuffer } },
+        ],
+    });
+    const bgDiffuse = (read, write) => device.createBindGroup({
+        layout: pDiffuse.getBindGroupLayout(0),
+        entries: [
+            { binding: 0, resource: { buffer: diffuseUniform } },
+            { binding: 1, resource: { buffer: read.gpuBuffer } },
+            { binding: 2, resource: { buffer: write.gpuBuffer } },
+        ],
+    });
+    let renderer = null;
+    let frame = 0;
+    let time = 0;
+    let lastFps = 0;
+    let fFrames = 0;
+    let fAcc = 0;
+    let fLast = performance.now();
+    return {
+        async attach(canvas) {
+            const dpr = Math.min(window.devicePixelRatio || 1, 2);
+            canvas.width = Math.max(1, Math.floor(canvas.clientWidth * dpr));
+            canvas.height = Math.max(1, Math.floor(canvas.clientHeight * dpr));
+            renderer = await MapRenderer.create(canvas, { width: mapSize, height: mapSize, maxV: 5.0, gamma: 0.65, colormap });
+        },
+        tick() {
+            time += 1 / 60;
+            u.time = time;
+            writeUniform();
+            const readT = trail.current.t;
+            const writeT = trail.other.t;
+            const enc = device.createCommandEncoder();
+            const pass = enc.beginComputePass();
+            pass.setPipeline(pAdvect);
+            pass.setBindGroup(0, bgAdvect(readT));
+            pass.dispatchWorkgroups(Math.ceil(N / 64));
+            pass.setPipeline(pDiffuse);
+            pass.setBindGroup(0, bgDiffuse(readT, writeT));
+            pass.dispatchWorkgroups(Math.ceil((mapSize * mapSize) / 64));
+            pass.end();
+            device.queue.submit([enc.finish()]);
+            renderer?.render(writeT);
+            trail.swap();
+            frame++;
+            fFrames++;
+            const now = performance.now();
+            fAcc += now - fLast;
+            fLast = now;
+            if (fAcc >= 500) {
+                lastFps = fFrames / (fAcc / 1000);
+                fFrames = 0;
+                fAcc = 0;
+            }
+        },
+        stats() { return { fps: lastFps }; },
+        async sampleTrail() { return (await trail.current.t.read()); },
+        destroy() {
+            posBuf.destroy();
+            trail.destroy();
+            uniform.destroy();
+            diffuseUniform.destroy();
+        },
+    };
+}
+function advectWgsl(fieldFn, mapSize) {
+    return /* wgsl */ `
+struct Params {
+  count: u32, _pad: u32,
+  speed: f32, worldHalf: f32, deposit: f32, time: f32,
+  _p0: f32, _p1: f32,
+};
+@group(0) @binding(0) var<uniform> params: Params;
+@group(0) @binding(1) var<storage, read_write> pos: array<vec2f>;
+@group(0) @binding(2) var<storage, read_write> trail: array<f32>;
+
+const TRAIL_W: u32 = ${mapSize}u;
+${fieldFn}
+
+@compute @workgroup_size(64)
+fn main(@builtin(global_invocation_id) gid: vec3u) {
+  let i = gid.x;
+  if (i >= params.count) { return; }
+  let p = pos[i];
+  let v = fieldAt(p, params.time) * params.speed;
+  var np = p + v;
+  let h = params.worldHalf * 0.98;
+  if (abs(np.x) > h || abs(np.y) > h) {
+    // 出界重生:随机撒回(确定性 hash,免额外随机源)
+    let r1 = fract(sin(f32(i) * 12.9898 + params.time * 78.233) * 43758.5453);
+    let r2 = fract(sin(f32(i) * 78.233 + params.time * 12.9898) * 24634.6345);
+    np = vec2f(r1, r2) * 1.8 - 0.9;
+  }
+  pos[i] = np;
+  let w = TRAIL_W;
+  let tx = min(u32((np.x * 0.5 + 0.5) * f32(w)), w - 1u);
+  let ty = min(u32((np.y * 0.5 + 0.5) * f32(w)), w - 1u);
+  let t = ty * w + tx;
+  trail[t] = trail[t] + params.deposit;
+}
+`;
+}
+function diffuseWgsl() {
+    return /* wgsl */ `
+@group(0) @binding(0) var<uniform> vp: vec4f; // w, h, keep, pad
+@group(0) @binding(1) var<storage, read> src: array<f32>;
+@group(0) @binding(2) var<storage, read_write> dst: array<f32>;
+
+@compute @workgroup_size(64)
+fn main(@builtin(global_invocation_id) gid: vec3u) {
+  let i = gid.x;
+  let w = u32(vp.x);
+  let h = u32(vp.y);
+  if (i >= w * h) { return; }
+  let x = i32(i % w);
+  let y = i32(i / w);
+  let c = src[i] * 2.0;
+  var s = c;
+  s = s + src[u32(clamp(y - 1, 0, i32(h) - 1)) * w + u32(clamp(x, 0, i32(w) - 1))];
+  s = s + src[u32(clamp(y + 1, 0, i32(h) - 1)) * w + u32(clamp(x, 0, i32(w) - 1))];
+  s = s + src[u32(clamp(y, 0, i32(h) - 1)) * w + u32(clamp(x - 1, 0, i32(w) - 1))];
+  s = s + src[u32(clamp(y, 0, i32(h) - 1)) * w + u32(clamp(x + 1, 0, i32(w) - 1))];
+  dst[i] = (s / 6.0 * 0.5 + src[i] * 0.5) * vp.z;
+}
+`;
+}
+function hashStr(s) {
+    let h = 2166136261;
+    for (let i = 0; i < s.length; i++) {
+        h ^= s.charCodeAt(i);
+        h = Math.imul(h, 16777619);
+    }
+    return h >>> 0;
+}

package/dist/packs/image/index.js

@@ -0,0 +1,250 @@
+import { GpuContext } from "../../core/context.js";
+import { CompileError } from "../../core/errors.js";
+const OPS = ['grayscale', 'invert', 'edge', 'blur', 'sharpen', 'brightness', 'contrast'];
+const OP_IDS = { grayscale: 0, invert: 1, edge: 2, blur: 3, sharpen: 4, brightness: 5, contrast: 6 };
+export async function applyImage(source, target, ops) {
+    if (ops.length === 0)
+        throw new Error('applyImage 需要至少一个算子');
+    const width = 'naturalWidth' in source ? source.naturalWidth : source.width;
+    const height = 'naturalHeight' in source ? source.naturalHeight : source.height;
+    const ctx = await GpuContext.get();
+    const device = ctx.device;
+    // 源纹理
+    const srcTex = device.createTexture({
+        size: [width, height],
+        format: 'rgba8unorm',
+        usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST | GPUTextureUsage.RENDER_ATTACHMENT,
+    });
+    // 上传走 2D getImageData + writeTexture(纯 CPU 路径):
+    // 实测 headless 里 copyExternalImageToTexture 从 canvas 上传拿不到内容(合成器限制)
+    const c2d = document.createElement('canvas');
+    c2d.width = width;
+    c2d.height = height;
+    const sctx = c2d.getContext('2d', { willReadFrequently: true });
+    sctx.drawImage(source, 0, 0);
+    const imageData = sctx.getImageData(0, 0, width, height);
+    device.queue.writeTexture({ texture: srcTex }, imageData.data, { bytesPerRow: width * 4, rowsPerImage: height }, [width, height]);
+    // 中间纹理池
+    const pool = [];
+    const temp = () => {
+        const t = pool.pop() ?? device.createTexture({
+            size: [width, height],
+            format: 'rgba8unorm',
+            usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.COPY_SRC,
+        });
+        return t;
+    };
+    const module = device.createShaderModule({ code: shader(), label: 'image-filters' });
+    const info = await module.getCompilationInfo();
+    const errors = info.messages.filter((m) => m.type === 'error');
+    if (errors.length > 0)
+        throw new CompileError('image-filters', errors.map((m) => ({ line: m.lineNum, msg: m.message })), 0);
+    const pipeline = device.createRenderPipeline({
+        layout: 'auto',
+        vertex: { module, entryPoint: 'vs' },
+        fragment: { module, entryPoint: 'fs', targets: [{ format: 'rgba8unorm' }] },
+        primitive: { topology: 'triangle-list' },
+    });
+    const makePass = (input, output, op) => {
+        const p = op;
+        const uniform = device.createBuffer({ size: 32, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST });
+        const ub = new ArrayBuffer(32);
+        const uv = new DataView(ub);
+        uv.setUint32(0, OP_IDS[op.op] ?? 0, true);
+        uv.setUint32(4, Math.max(1, Math.min(4, Math.round(p.radius ?? 1))), true);
+        uv.setFloat32(8, width, true);
+        uv.setFloat32(12, height, true);
+        uv.setFloat32(16, p.amount ?? 1, true);
+        uv.setFloat32(20, p.value ?? 0, true);
+        device.queue.writeBuffer(uniform, 0, ub);
+        const sampler = device.createSampler({ magFilter: 'linear', minFilter: 'linear' });
+        const bg = device.createBindGroup({
+            layout: pipeline.getBindGroupLayout(0),
+            entries: [
+                { binding: 0, resource: { buffer: uniform } },
+                { binding: 1, resource: sampler },
+                { binding: 2, resource: input.createView() },
+            ],
+        });
+        const enc = device.createCommandEncoder();
+        const pass = enc.beginRenderPass({
+            colorAttachments: output
+                ? [{ view: output.createView(), clearValue: { r: 0, g: 0, b: 0, a: 1 }, loadOp: 'clear', storeOp: 'store' }]
+                : [],
+        });
+        pass.setPipeline(pipeline);
+        pass.setBindGroup(0, bg);
+        pass.draw(3);
+        pass.end();
+        return enc.finish();
+    };
+    let cur = srcTex;
+    let passes = 0;
+    for (const op of ops) {
+        const out = temp();
+        device.queue.submit([makePass(cur, out, op)]);
+        if (cur !== srcTex)
+            pool.push(cur);
+        cur = out;
+        passes++;
+    }
+    // 最终结果上屏到目标 canvas
+    const gpuCtx = target.getContext('webgpu');
+    if (!gpuCtx)
+        throw new Error('目标 canvas.getContext("webgpu") 返回空');
+    const format = navigator.gpu.getPreferredCanvasFormat();
+    gpuCtx.configure({ device, format, alphaMode: 'opaque' });
+    const blit = device.createShaderModule({
+        code: `
+@group(0) @binding(0) var samp: sampler;
+@group(0) @binding(1) var tex: texture_2d<f32>;
+struct VsOut { @builtin(position) pos: vec4f, @location(0) uv: vec2f };
+@vertex fn vs(@builtin(vertex_index) v: u32) -> VsOut {
+  var p = array<vec2f, 3>(vec2f(-1.0, -1.0), vec2f(3.0, -1.0), vec2f(-1.0, 3.0));
+  var o: VsOut;
+  o.pos = vec4f(p[v], 0.0, 1.0);
+  o.uv = (p[v] + vec2f(1.0)) * 0.5;
+  o.uv.y = 1.0 - o.uv.y;
+  return o;
+}
+@fragment fn fs(i: VsOut) -> @location(0) vec4f {
+  let c = textureSample(tex, samp, i.uv);
+  return vec4f(c.rgb, 1.0);
+}
+`,
+        label: 'image-blit',
+    });
+    const blitPipeline = device.createRenderPipeline({
+        layout: 'auto',
+        vertex: { module: blit, entryPoint: 'vs' },
+        fragment: { module: blit, entryPoint: 'fs', targets: [{ format }] },
+        primitive: { topology: 'triangle-list' },
+    });
+    const enc = device.createCommandEncoder();
+    const pass = enc.beginRenderPass({
+        colorAttachments: [{ view: gpuCtx.getCurrentTexture().createView(), clearValue: { r: 0, g: 0, b: 0, a: 1 }, loadOp: 'clear', storeOp: 'store' }],
+    });
+    pass.setPipeline(blitPipeline);
+    pass.setBindGroup(0, device.createBindGroup({
+        layout: blitPipeline.getBindGroupLayout(0),
+        entries: [
+            { binding: 0, resource: device.createSampler({ magFilter: 'linear', minFilter: 'linear' }) },
+            { binding: 1, resource: cur.createView() },
+        ],
+    }));
+    pass.draw(3);
+    pass.end();
+    device.queue.submit([enc.finish()]);
+    srcTex.destroy();
+    for (const t of pool)
+        t.destroy();
+    const bytesPerRow = Math.ceil((width * 4) / 256) * 256;
+    const staging = device.createBuffer({ size: bytesPerRow * height, usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ });
+    return {
+        width,
+        height,
+        passes,
+        async readback() {
+            // cur = 最后一个输出纹理(不在销毁池里);按行 256B 对齐拷回
+            const enc = device.createCommandEncoder();
+            enc.copyTextureToBuffer({ texture: cur }, { buffer: staging, bytesPerRow, rowsPerImage: height }, [width, height]);
+            device.queue.submit([enc.finish()]);
+            await staging.mapAsync(GPUMapMode.READ);
+            const ab = staging.getMappedRange().slice(0);
+            staging.unmap();
+            staging.destroy();
+            return new Uint8Array(ab);
+        },
+    };
+}
+function shader() {
+    return /* wgsl */ `
+struct U {
+  op: u32, radius: u32,
+  w: f32, h: f32, amount: f32, value: f32,
+  _p0: u32, _p1: u32,
+};
+@group(0) @binding(0) var<uniform> u: U;
+@group(0) @binding(1) var samp: sampler;
+@group(0) @binding(2) var tex: texture_2d<f32>;
+
+struct VsOut { @builtin(position) pos: vec4f, @location(0) uv: vec2f };
+
+@vertex
+fn vs(@builtin(vertex_index) v: u32) -> VsOut {
+  var p = array<vec2f, 3>(vec2f(-1.0, -1.0), vec2f(3.0, -1.0), vec2f(-1.0, 3.0));
+  var o: VsOut;
+  o.pos = vec4f(p[v], 0.0, 1.0);
+  o.uv = (p[v] + vec2f(1.0)) * 0.5;
+  o.uv.y = 1.0 - o.uv.y;
+  return o;
+}
+
+fn lum(c: vec3f) -> f32 {
+  return dot(c, vec3f(0.2126, 0.7152, 0.0722));
+}
+
+@fragment
+fn fs(i: VsOut) -> @location(0) vec4f {
+  let c = textureSample(tex, samp, i.uv).rgb;
+  let op = u.op;
+
+  if (op == 0u) { // grayscale
+    let g = vec3f(lum(c));
+    return vec4f(g, 1.0);
+  }
+  if (op == 1u) { // invert
+    return vec4f(1.0 - c, 1.0);
+  }
+  if (op == 2u) { // edge (sobel 幅值)
+    let e = 1.0 / vec2f(u.w, u.h);
+    let t00 = textureSample(tex, samp, i.uv + vec2f(-e.x, -e.y)).rgb;
+    let t10 = textureSample(tex, samp, i.uv + vec2f(0.0, -e.y)).rgb;
+    let t20 = textureSample(tex, samp, i.uv + vec2f(e.x, -e.y)).rgb;
+    let t01 = textureSample(tex, samp, i.uv + vec2f(-e.x, 0.0)).rgb;
+    let t21 = textureSample(tex, samp, i.uv + vec2f(e.x, 0.0)).rgb;
+    let t02 = textureSample(tex, samp, i.uv + vec2f(-e.x, e.y)).rgb;
+    let t12 = textureSample(tex, samp, i.uv + vec2f(0.0, e.y)).rgb;
+    let t22 = textureSample(tex, samp, i.uv + vec2f(e.x, e.y)).rgb;
+    let sx = (t22 + 2.0 * t21 + t02) - (t00 + 2.0 * t01 + t20);
+    let sy = (t02 + 2.0 * t12 + t22) - (t00 + 2.0 * t10 + t20);
+    let g = sqrt(vec3f(dot(sx, sx) / 3.0 + dot(sy, sy) / 3.0));
+    return vec4f(clamp(g * u.amount, vec3f(0.0), vec3f(1.0)), 1.0);
+  }
+  if (op == 3u) { // box blur,radius 折叠成步长采样
+    let r = f32(u.radius);
+    let e = vec2f(1.0) / vec2f(u.w, u.h) * r;
+    var s = vec3f(0.0);
+    var n = 0.0;
+    for (var dy = -2; dy <= 2; dy++) {
+      for (var dx = -2; dx <= 2; dx++) {
+        s = s + textureSample(tex, samp, i.uv + vec2f(f32(dx), f32(dy)) * e * 0.6).rgb;
+        n = n + 1.0;
+      }
+    }
+    return vec4f(s / n, 1.0);
+  }
+  if (op == 4u) { // sharpen(3x3 卷积)
+    let e = vec2f(1.0) / vec2f(u.w, u.h);
+    let c0 = textureSample(tex, samp, i.uv).rgb;
+    let t00 = textureSample(tex, samp, i.uv + vec2f(-e.x, -e.y)).rgb;
+    let t10 = textureSample(tex, samp, i.uv + vec2f(0.0, -e.y)).rgb;
+    let t20 = textureSample(tex, samp, i.uv + vec2f(e.x, -e.y)).rgb;
+    let t01 = textureSample(tex, samp, i.uv + vec2f(-e.x, 0.0)).rgb;
+    let t21 = textureSample(tex, samp, i.uv + vec2f(e.x, 0.0)).rgb;
+    let t02 = textureSample(tex, samp, i.uv + vec2f(-e.x, e.y)).rgb;
+    let t12 = textureSample(tex, samp, i.uv + vec2f(0.0, e.y)).rgb;
+    let t22 = textureSample(tex, samp, i.uv + vec2f(e.x, e.y)).rgb;
+    let k = u.amount;
+    let acc = t00 + t10 + t20 + t01 + t21 + t02 + t12 + t22;
+    return vec4f(clamp(c0 * (1.0 + 8.0 * k) - acc * k, vec3f(0.0), vec3f(1.0)), 1.0);
+  }
+  if (op == 5u) { // brightness
+    return vec4f(clamp(c + vec3f(u.value), vec3f(0.0), vec3f(1.0)), 1.0);
+  }
+  // contrast
+  let g = vec3f(0.5);
+  return vec4f(clamp(g + (c - g) * u.value, vec3f(0.0), vec3f(1.0)), 1.0);
+}
+`;
+}