wgpu-kit 0.9.10 → 1.0.0

package/dist/packs/particles/presets.js

@@ -0,0 +1,75 @@
+/** 粒子包的字段布局(species 独立成 u32 缓冲,方便按需着色) */
+export const PARTICLE_FIELDS = {
+    pos: 'vec2f',
+    vel: 'vec2f',
+    species: 'u32',
+};
+/** 精选力矩阵(4×4,行=施加者,列=承受者;正值吸引)。调参原则:对角 0,正负平衡。 */
+export const FORCE_PRESETS = {
+    /** 经典细胞:小团簇 + 缓慢迁移(spike 验证过的矩阵) */
+    cells: [
+        0.0, 0.6, -0.4, 0.0,
+        -0.4, 0.0, 0.7, -0.2,
+        0.5, -0.5, 0.0, 0.6,
+        -0.3, 0.4, -0.6, 0.0,
+    ],
+    /** 蛇形:链状结构与游动 */
+    snakes: [
+        0.0, 0.7, 0.1, -0.5,
+        -0.3, 0.0, 0.8, -0.1,
+        0.2, -0.4, 0.0, 0.7,
+        -0.6, 0.2, -0.3, 0.0,
+    ],
+    /** 轨道:环带与漩涡感 */
+    orbitals: [
+        0.0, -0.5, 0.4, 0.2,
+        0.5, 0.0, -0.6, 0.1,
+        -0.3, 0.6, 0.0, -0.4,
+        0.1, -0.2, 0.5, 0.0,
+    ],
+    /** 病毒:捕食结构,红吃绿 */
+    viruses: [
+        0.0, 0.9, -0.6, 0.1,
+        -0.5, 0.0, 0.3, -0.8,
+        0.7, 0.2, 0.0, -0.3,
+        -0.2, 0.8, 0.4, 0.0,
+    ],
+};
+/** mulberry32:种子可复现(seed 支持字符串散列,URL 分享友好) */
+export function mulberry32(seed) {
+    let s = seed | 0;
+    return () => {
+        s = (s + 0x6D2B79F5) | 0;
+        let t = Math.imul(s ^ (s >>> 15), 1 | s);
+        t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+export function hashSeed(seed) {
+    let h = 2166136261;
+    for (let i = 0; i < seed.length; i++) {
+        h ^= seed.charCodeAt(i);
+        h = Math.imul(h, 16777619);
+    }
+    return h >>> 0;
+}
+/** 随机力矩阵(从种子生成,保证可复现) */
+export function randomMatrix(seed) {
+    const rand = mulberry32(seed ^ 0x9E3779B9);
+    const m = Array.from({ length: 16 }, () => Math.round((rand() * 2 - 1) * 100) / 100);
+    for (let i = 0; i < 4; i++)
+        m[i * 4 + i] = 0;
+    return m;
+}
+export function resolveMatrix(forces, seed) {
+    if (forces === 'random')
+        return randomMatrix(seed);
+    if (typeof forces === 'string') {
+        const preset = FORCE_PRESETS[forces];
+        if (!preset) {
+            throw new Error(`未知力矩阵预设 "${forces}",可用: ${Object.keys(FORCE_PRESETS).join(', ')}, random`);
+        }
+        return preset;
+    }
+    return forces;
+}

package/dist/packs/particles/render.js

@@ -0,0 +1,116 @@
+import { GpuContext } from "../../core/context.js";
+import { Buffer } from "../../core/buffer.js";
+import { CompileError } from "../../core/errors.js";
+import { renderWgsl } from "./wgsl.js";
+let nextId = 0;
+const ids = new WeakMap();
+const bufKey = (b) => {
+    let id = ids.get(b);
+    if (id === undefined) {
+        id = ++nextId;
+        ids.set(b, id);
+    }
+    return id;
+};
+/**
+ * 粒子渲染器:instanced quad + storage 只读直通(compute 产物零拷贝进 vertex 阶段)。
+ * 属于粒子包内部实现(不进 core);等第二、第三个包出现同类需求再考虑上提。
+ */
+export class ParticlesRenderer {
+    #ctx;
+    #gpuCtx;
+    #format;
+    #pipeline;
+    #quad;
+    #idx;
+    #species;
+    #vel;
+    #colorMode;
+    #rs;
+    #bgCache = new Map();
+    #count;
+    constructor(ctx, gpuCtx, format, pipeline, quad, idx, species, count, rs, vel, colorMode) {
+        this.#ctx = ctx;
+        this.#gpuCtx = gpuCtx;
+        this.#format = format;
+        this.#pipeline = pipeline;
+        this.#quad = quad;
+        this.#idx = idx;
+        this.#species = species;
+        this.#count = count;
+        this.#rs = rs;
+        this.#vel = vel;
+        this.#colorMode = colorMode;
+    }
+    static async create(canvas, opts) {
+        const ctx = await GpuContext.get();
+        const gpuCtx = canvas.getContext('webgpu');
+        if (!gpuCtx)
+            throw new Error('canvas.getContext("webgpu") 返回空:该 canvas 已被其他后端占用?');
+        const format = navigator.gpu.getPreferredCanvasFormat();
+        gpuCtx.configure({ device: ctx.device, format, alphaMode: 'opaque' });
+        const module = ctx.device.createShaderModule({ code: renderWgsl(4, opts.color, opts.pointSize), label: 'particles-render' });
+        const rsUniform = ctx.device.createBuffer({ size: 16, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST });
+        ctx.device.queue.writeBuffer(rsUniform, 0, new Float32Array([1 / opts.worldHalf, 0, 0, 0]));
+        const info = await module.getCompilationInfo();
+        const errors = info.messages.filter((m) => m.type === 'error');
+        if (errors.length > 0)
+            throw new CompileError('particles-render', errors.map((m) => ({ line: m.lineNum + 1, msg: m.message })), 0);
+        const pipeline = ctx.device.createRenderPipeline({
+            layout: 'auto',
+            vertex: {
+                module, entryPoint: 'vs',
+                buffers: [{ arrayStride: 8, attributes: [{ shaderLocation: 0, offset: 0, format: 'float32x2' }] }],
+            },
+            fragment: {
+                module, entryPoint: 'fs',
+                targets: [{ format, blend: { color: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha' }, alpha: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha' } } }],
+            },
+            primitive: { topology: 'triangle-list' },
+        });
+        const quad = ctx.device.createBuffer({ size: 8 * 4, usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST });
+        ctx.device.queue.writeBuffer(quad, 0, new Float32Array([-1, -1, 1, -1, -1, 1, 1, 1]));
+        const idx = ctx.device.createBuffer({ size: 6 * 2, usage: GPUBufferUsage.INDEX | GPUBufferUsage.COPY_DST });
+        ctx.device.queue.writeBuffer(idx, 0, new Uint16Array([0, 1, 2, 2, 1, 3]));
+        return new ParticlesRenderer(ctx, gpuCtx, format, pipeline, quad, idx, opts.species, opts.count, rsUniform, opts.vel ?? null, opts.color);
+    }
+    /** 渲染一帧(pos 来自 PingPong 当前侧;可传入覆盖数量) */
+    render(pos, vel = null, count = this.#count) {
+        const key = `${bufKey(pos.gpuBuffer)}:${vel ? bufKey(vel.gpuBuffer) : 0}`;
+        let bg = this.#bgCache.get(key);
+        if (!bg) {
+            bg = this.#ctx.device.createBindGroup({
+                layout: this.#pipeline.getBindGroupLayout(0),
+                entries: [
+                    { binding: 0, resource: { buffer: pos.gpuBuffer } },
+                    // 各 binding 按管线 layout 裁剪:velocity 模式的着色器不读 species,
+                    // 物种模式不读 vel——auto layout 会剔除未使用的绑定,bind group 必须同步
+                    ...(this.#colorMode === 'species' ? [{ binding: 1, resource: { buffer: this.#species.gpuBuffer } }] : []),
+                    ...(this.#colorMode === 'velocity' && this.#vel && vel ? [{ binding: 2, resource: { buffer: vel.gpuBuffer } }] : []),
+                    { binding: 3, resource: { buffer: this.#rs } },
+                ],
+            });
+            this.#bgCache.set(key, bg);
+        }
+        const enc = this.#ctx.device.createCommandEncoder();
+        const pass = enc.beginRenderPass({
+            colorAttachments: [{
+                    view: this.#gpuCtx.getCurrentTexture().createView(),
+                    clearValue: { r: 0.012, g: 0.014, b: 0.024, a: 1 },
+                    loadOp: 'clear', storeOp: 'store',
+                }],
+        });
+        pass.setPipeline(this.#pipeline);
+        pass.setBindGroup(0, bg);
+        pass.setVertexBuffer(0, this.#quad);
+        pass.setIndexBuffer(this.#idx, 'uint16');
+        pass.drawIndexed(6, count);
+        pass.end();
+        this.#ctx.device.queue.submit([enc.finish()]);
+    }
+    destroy() {
+        this.#quad.destroy();
+        this.#idx.destroy();
+        this.#bgCache.clear();
+    }
+}

package/dist/packs/particles/wgsl.js

@@ -0,0 +1,175 @@
+/**
+ * 粒子模拟 WGSL 生成器。
+ * mode 是"路径对比驱动设计"的落点:
+ *  - n2    每线程全量扫一遍:最简单,≤2 万粒子
+ *  - tiled workgroup 共享内存分块加载:全局读取减少 64×,数万粒子(S3 基准)
+ *  - grid  spatial hash 两遍:10 万+(S4)
+ */
+export const WORKGROUP = 64;
+export function simWgsl(mode, speciesCount) {
+    const tiled = mode === 'tiled';
+    const common = /* wgsl */ `
+struct Params {
+  count: u32,
+  _pad0: u32,
+  dt: f32,
+  rMax: f32,
+  beta: f32,
+  forceFactor: f32,
+  friction: f32,
+  worldHalf: f32,
+  wrapEdge: f32,
+  gridSize: u32,
+  cells: u32,
+  maxCand: u32,
+};
+@group(0) @binding(0) var<uniform> params: Params;
+@group(0) @binding(1) var<storage, read> matrix: array<f32>;
+@group(0) @binding(2) var<storage, read> species: array<u32>;
+@group(0) @binding(3) var<storage, read> posIn: array<vec2f>;
+@group(0) @binding(4) var<storage, read> velIn: array<vec2f>;
+@group(0) @binding(5) var<storage, read_write> posOut: array<vec2f>;
+@group(0) @binding(6) var<storage, read_write> velOut: array<vec2f>;
+
+fn force(r: f32, a: f32) -> f32 {
+  if (r < params.beta) { return a / params.beta - 1.0; }
+  if (r < 1.0) { return a * (1.0 - abs(2.0 * r - 1.0 - params.beta) / (1.0 - params.beta)); }
+  return 0.0;
+}
+`;
+    // interact:lid 仅 tiled 模式需要(workgroup 内分块加载坐标)
+    const interactSig = tiled
+        ? 'fn interact(myIdx: u32, mySp: u32, myPos: vec2f, lid: u32) -> vec2f {'
+        : 'fn interact(myIdx: u32, mySp: u32, myPos: vec2f) -> vec2f {';
+    const body = tiled ? tiledBody(speciesCount) : n2Body(speciesCount);
+    const main = /* wgsl */ `
+@compute @workgroup_size(${WORKGROUP})
+fn main(@builtin(global_invocation_id) gid: vec3u${tiled ? ', @builtin(local_invocation_id) lid: vec3u' : ''}) {
+  let i = gid.x;
+  // 注意:workgroupBarrier 要求 uniform control flow——
+  // 越界线程也必须参与 barrier 循环,只能在最终写入处 guard(tiled 尾部 workgroup 的经典坑)
+  let ok = i < params.count;
+  let myIdx = min(i, params.count - 1u);
+  let mySp = species[myIdx];
+  let myPos = posIn[myIdx];
+  var accel = interact(myIdx, mySp, myPos${tiled ? ', lid.x' : ''});
+  accel = accel * params.forceFactor * params.rMax;
+  if (ok) {
+    var vel = (velIn[i] + accel * params.dt) * params.friction;
+    var pos = myPos + vel * params.dt;
+    let span = params.worldHalf * 2.0;
+    if (params.wrapEdge > 0.5) {
+      pos = ((pos + params.worldHalf) % span + span) % span - params.worldHalf;
+    } else {
+      pos = clamp(pos, vec2f(-params.worldHalf), vec2f(params.worldHalf));
+    }
+    posOut[i] = pos;
+    velOut[i] = vel;
+  }
+}
+`;
+    return `${common}${tiled ? TILE_DECLS : ''}\n${interactSig}${body}\n}\n${main}`;
+}
+function n2Body(speciesCount) {
+    return /* wgsl */ `
+  var accel = vec2f(0.0, 0.0);
+  let rMax2 = params.rMax * params.rMax;
+  for (var j = 0u; j < params.count; j++) {
+    if (j == myIdx) { continue; }
+    let rel = posIn[j] - myPos;
+    let d2 = dot(rel, rel);
+    if (d2 > rMax2) { continue; }   // 距离平方 early-out:绝大多数对免开方
+    let d = sqrt(d2);
+    let r = d / params.rMax;
+    if (r > 0.0 && r < 1.0) {
+      let f = force(r, matrix[mySp * ${speciesCount}u + species[j]]);
+      accel = accel + rel / d * f;
+    }
+  }
+  return accel;
+  `;
+}
+function tiledBody(speciesCount) {
+    return /* wgsl */ `
+  var accel = vec2f(0.0, 0.0);
+  let rMax2 = params.rMax * params.rMax;
+  let tiles = (params.count + ${WORKGROUP}u - 1u) / ${WORKGROUP}u;
+  for (var t = 0u; t < tiles; t++) {
+    let loadIdx = t * ${WORKGROUP}u + lid;
+    tilePos[lid] = posIn[min(loadIdx, params.count - 1u)];
+    tileSp[lid] = species[min(loadIdx, params.count - 1u)];
+    workgroupBarrier();
+    let tileLen = min(${WORKGROUP}u, params.count - t * ${WORKGROUP}u);
+    for (var k = 0u; k < ${WORKGROUP}u; k++) {
+      if (k >= tileLen) { break; }
+      let j = t * ${WORKGROUP}u + k;
+      if (j == myIdx) { continue; }
+      let rel = tilePos[k] - myPos;
+      let d2 = dot(rel, rel);
+      if (d2 > rMax2) { continue; } // 距离平方 early-out
+      let d = sqrt(d2);
+      let r = d / params.rMax;
+      if (r > 0.0 && r < 1.0) {
+        let f = force(r, matrix[mySp * ${speciesCount}u + tileSp[k]]);
+        accel = accel + rel / d * f;
+      }
+    }
+    workgroupBarrier();
+  }
+  return accel;
+  `;
+}
+/** tiled 模式的 workgroup 共享内存声明 */
+export const TILE_DECLS = /* wgsl */ `
+var<workgroup> tilePos: array<vec2f, ${WORKGROUP}>;
+var<workgroup> tileSp: array<u32, ${WORKGROUP}>;
+`;
+/** 渲染着色器:instanced quad + storage 只读直通(spike 验证的形态) */
+export function renderWgsl(speciesCount, colorMode, pointSize) {
+    const palette = colorMode === 'species'
+        ? `const PALETTE = array<vec3f, ${speciesCount}>(
+  vec3f(1.00, 0.42, 0.24),
+  vec3f(0.36, 0.86, 0.56),
+  vec3f(0.36, 0.58, 1.00),
+  vec3f(0.98, 0.80, 0.30),
+);`
+        : '';
+    const colorExpr = colorMode === 'velocity'
+        ? /* wgsl */ `
+  let speed = length(vel[inst]);
+  let t = 1.0 - exp(-speed * 40.0);
+  out.color = mix(vec3f(0.20, 0.32, 0.55), vec3f(1.0, 0.85, 0.45), t);
+  out.color = mix(out.color, vec3f(1.0, 0.95, 0.9), smoothstep(0.6, 1.0, t));`
+        : /* wgsl */ `
+  let sp = min(species[inst], ${speciesCount - 1}u);
+  out.color = PALETTE[sp];`;
+    const velBinding = colorMode === 'velocity' ? '\n@group(0) @binding(2) var<storage, read> vel: array<vec2f>;' : '';
+    return /* wgsl */ `
+struct VsOut {
+  @builtin(position) clip: vec4f,
+  @location(0) uv: vec2f,
+  @location(1) color: vec3f,
+};
+${palette}
+@group(0) @binding(0) var<storage, read> pos: array<vec2f>;
+@group(0) @binding(1) var<storage, read> species: array<u32>;${velBinding}
+@group(0) @binding(3) var<uniform> rs: vec4f; // x = 1/worldHalf(相机缩放;binding 2 留给 velocity 模式的 vel)
+
+@vertex
+fn vs(@location(0) corner: vec2f, @builtin(instance_index) inst: u32) -> VsOut {
+  var out: VsOut;
+  out.clip = vec4f((pos[inst] + corner * ${pointSize.toFixed(4)}) * rs.x, 0.0, 1.0);
+  out.uv = corner;
+  ${colorExpr}
+  return out;
+}
+
+@fragment
+fn fs(in: VsOut) -> @location(0) vec4f {
+  let d = length(in.uv);
+  if (d > 1.0) { discard; }
+  let alpha = smoothstep(1.0, 0.35, d);
+  return vec4f(in.color * alpha, alpha);
+}
+`;
+}

package/dist/react/index.js

@@ -0,0 +1,36 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useRef } from 'react';
+import { particles } from "../packs/particles/index.js";
+export function ParticleCanvas(props) {
+    const { className, style, onReady, ...config } = props;
+    const canvasRef = useRef(null);
+    useEffect(() => {
+        let raf = 0;
+        let disposed = false;
+        let sim = null;
+        void (async () => {
+            sim = await particles(config);
+            if (disposed || !canvasRef.current) {
+                sim.destroy();
+                return;
+            }
+            await sim.attach(canvasRef.current);
+            onReady?.(sim);
+            const loop = () => {
+                if (disposed)
+                    return;
+                sim?.tick();
+                raf = requestAnimationFrame(loop);
+            };
+            raf = requestAnimationFrame(loop);
+        })();
+        return () => {
+            disposed = true;
+            cancelAnimationFrame(raf);
+            sim?.destroy();
+            sim = null;
+        };
+        // 刻意只在挂载时启动一次;config 变化请用 key 重建(声明式约定)
+    }, []);
+    return (_jsx("canvas", { ref: canvasRef, className: className, style: { width: '100%', height: '100%', display: 'block', background: '#05070c', ...style } }));
+}

package/dist/vite.js

@@ -1,30 +1,29 @@
-// src/vite.ts
-function wgpuKitHotReload() {
-  return {
-    name: "wgpu-kit:hot-reload",
-    handleHotUpdate(ctx) {
-      if (!ctx.file.endsWith(".wgsl")) return;
-      void (async () => {
-        const code = await ctx.read();
-        ctx.server.ws.send({ type: "custom", event: "wgpu-kit:kernel", data: { file: ctx.file, code } });
-      })();
-      return [];
-    }
-  };
+export function wgpuKitHotReload() {
+    return {
+        name: 'wgpu-kit:hot-reload',
+        handleHotUpdate(ctx) {
+            if (!ctx.file.endsWith('.wgsl'))
+                return;
+            void (async () => {
+                const code = await ctx.read();
+                ctx.server.ws.send({ type: 'custom', event: 'wgpu-kit:kernel', data: { file: ctx.file, code } });
+            })();
+            return []; // 阻止 Vite 默认整页刷新,替换由 hotKernel 接管
+        },
+    };
 }
-function hotKernel(kernel, hot, file) {
-  if (!hot) return;
-  const suffix = file.slice(file.lastIndexOf("/"));
-  hot.on("wgpu-kit:kernel", (data) => {
-    const d = data;
-    if (typeof d?.code === "string" && typeof d.file === "string" && d.file.endsWith(suffix)) {
-      void kernel.replace(d.code).catch((e) => {
-        console.error("[wgpu-kit] \u70ED\u91CD\u8F7D\u5931\u8D25,\u4FDD\u7559\u65E7\u7248 kernel:", e.message);
-      });
-    }
-  });
+/** 把 kernel 注册进热重载:对应 .wgsl 文件一变,自动 kernel.replace */
+export function hotKernel(kernel, hot, file) {
+    if (!hot)
+        return;
+    const suffix = file.slice(file.lastIndexOf('/'));
+    hot.on('wgpu-kit:kernel', (data) => {
+        const d = data;
+        if (typeof d?.code === 'string' && typeof d.file === 'string' && d.file.endsWith(suffix)) {
+            void kernel.replace(d.code).catch((e) => {
+                // 热更新编译失败不打断运行,保留旧版并在控制台说人话
+                console.error('[wgpu-kit] 热重载失败,保留旧版 kernel:', e.message);
+            });
+        }
+    });
 }
-export {
-  hotKernel,
-  wgpuKitHotReload
-};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wgpu-kit",
-  "version": "0.9.10",
+  "version": "1.0.0",
   "description": "Browser GPGPU middle layer: 100k particles in 5 lines. WebGPU compute without the boilerplate.",
   "type": "module",
   "license": "MIT",