wgpu-kit 0.9.10

package/dist/index.js

@@ -0,0 +1,484 @@
+// src/core/errors.ts
+var WgpuKitError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = new.target.name;
+  }
+};
+var WebGPUUnavailableError = class extends WgpuKitError {
+  constructor(reason) {
+    super(
+      `\u5F53\u524D\u73AF\u5883\u4E0D\u53EF\u7528 WebGPU: ${reason}
+  \u6392\u67E5:\u2460 \u6D4F\u89C8\u5668\u9700 Chrome/Edge 113+ \u6216 Safari 18+;\u2461 \u65E0\u5934\u73AF\u5883\u9700\u5F00\u542F WebGPU;\u2462 \u68C0\u67E5 GPU \u9A71\u52A8\u4E0E\u786C\u4EF6\u52A0\u901F\u8BBE\u7F6E\u3002
+  \u53EF\u7528 navigator.gpu \u662F\u5426\u5B58\u5728\u5FEB\u901F\u5224\u65AD\u3002`
+    );
+  }
+};
+var CompileError = class extends WgpuKitError {
+  constructor(kernelName, messages, userCodeOffset) {
+    const mapped = messages.map((m) => {
+      const userLine = m.line - userCodeOffset;
+      const where = userLine > 0 ? `\u7528\u6237\u4EE3\u7801\u7B2C ${userLine} \u884C` : `\u751F\u6210\u4EE3\u7801\u7B2C ${m.line} \u884C(\u5E93\u7684\u95EE\u9898,\u6B22\u8FCE\u62A5 issue)`;
+      return `  ${where}: ${m.msg}`;
+    }).join("\n");
+    super(`kernel "${kernelName}" WGSL \u7F16\u8BD1\u5931\u8D25:
+${mapped}`);
+  }
+};
+var UsageError = class extends WgpuKitError {
+};
+
+// src/core/context.ts
+var GpuContext = class _GpuContext {
+  device;
+  adapterInfo;
+  constructor(device, adapterInfo) {
+    this.device = device;
+    this.adapterInfo = adapterInfo;
+  }
+  static #singleton = null;
+  static get() {
+    if (!_GpuContext.#singleton) {
+      _GpuContext.#singleton = _GpuContext.#create().catch((e) => {
+        _GpuContext.#singleton = null;
+        throw e;
+      });
+    }
+    return _GpuContext.#singleton;
+  }
+  static async #create() {
+    if (typeof navigator === "undefined" || !("gpu" in navigator) || !navigator.gpu) {
+      throw new WebGPUUnavailableError("navigator.gpu \u4E0D\u5B58\u5728");
+    }
+    const adapter = await navigator.gpu.requestAdapter({ powerPreference: "high-performance" });
+    if (!adapter) throw new WebGPUUnavailableError("requestAdapter() \u8FD4\u56DE null");
+    const info = adapter.info;
+    const label = info ? [info.vendor, info.architecture, info.description].filter(Boolean).join(" / ") || "unknown" : "unknown";
+    const requiredLimits = {};
+    const want = [
+      "maxStorageBuffersPerShaderStage",
+      "maxStorageBuffersInVertexStage",
+      "maxStorageBufferBindingSize"
+    ];
+    for (const key of want) {
+      const supported = adapter.limits[key];
+      if (typeof supported === "number") requiredLimits[key] = supported;
+    }
+    const device = await adapter.requestDevice({ label: "wgpu-kit", requiredLimits });
+    return new _GpuContext(device, label);
+  }
+  /** device lost 时 reject;调用方可 await 做清理/提示 */
+  get lost() {
+    return this.device.lost;
+  }
+  /** 等待队列中已提交的全部 GPU 工作完成(测试/读回前同步用) */
+  async sync() {
+    await this.device.queue.onSubmittedWorkDone();
+  }
+};
+
+// src/core/layout.ts
+var TYPES = {
+  f32: { size: 4, align: 4, comps: 1, typed: "Float32Array", wgsl: "f32" },
+  i32: { size: 4, align: 4, comps: 1, typed: "Int32Array", wgsl: "i32" },
+  u32: { size: 4, align: 4, comps: 1, typed: "Uint32Array", wgsl: "u32" },
+  vec2f: { size: 8, align: 8, comps: 2, typed: "Float32Array", wgsl: "vec2f" },
+  vec2i: { size: 8, align: 8, comps: 2, typed: "Int32Array", wgsl: "vec2i" },
+  vec2u: { size: 8, align: 8, comps: 2, typed: "Uint32Array", wgsl: "vec2u" },
+  vec3f: { size: 12, align: 16, comps: 3, typed: "Float32Array", wgsl: "vec3f" },
+  vec4f: { size: 16, align: 16, comps: 4, typed: "Float32Array", wgsl: "vec4f" }
+};
+function alignTo(offset, align) {
+  return Math.ceil(offset / align) * align;
+}
+function planUniform(entries) {
+  const fields = [];
+  let cursor = 0;
+  for (const [name, kind] of entries) {
+    const def = TYPES[kind];
+    cursor = alignTo(cursor, def.align);
+    fields.push({ name, kind, offset: cursor });
+    cursor += def.size;
+  }
+  return { fields, size: alignTo(Math.max(cursor, 1), 16) };
+}
+var PACKERS = {
+  f32: (v, o, x) => v.setFloat32(o, x, true),
+  i32: (v, o, x) => v.setInt32(o, x, true),
+  u32: (v, o, x) => v.setUint32(o, x, true)
+};
+function packUniform(layout, values) {
+  const buf = new ArrayBuffer(layout.size);
+  const view = new DataView(buf);
+  for (const f of layout.fields) {
+    const pack = PACKERS[f.kind];
+    if (!pack) {
+      throw new Error(`uniform \u5B57\u6BB5 ${f.name} \u7684\u7C7B\u578B ${f.kind} \u6682\u4E0D\u652F\u6301(\u5F53\u524D\u4EC5\u652F\u6301\u6807\u91CF)`);
+    }
+    const v = values[f.name];
+    if (v === void 0) throw new Error(`\u7F3A\u5C11 uniform \u503C: ${f.name}`);
+    if (typeof v !== "number" || !Number.isFinite(v)) {
+      throw new Error(`uniform \u503C ${f.name} \u5FC5\u987B\u662F\u6709\u9650\u6570\u5B57,\u6536\u5230: ${String(v)}`);
+    }
+    pack(view, f.offset, v);
+  }
+  return buf;
+}
+
+// src/core/buffer.ts
+var TYPED_CTORS = {
+  Float32Array,
+  Int32Array,
+  Uint32Array
+};
+var Buffer = class _Buffer {
+  kind;
+  length;
+  gpuBuffer;
+  #ctx;
+  #byteLength;
+  #staging = null;
+  constructor(ctx, kind, length, gpuBuffer) {
+    this.#ctx = ctx;
+    this.kind = kind;
+    this.length = length;
+    this.gpuBuffer = gpuBuffer;
+    this.#byteLength = length * TYPES[kind].size;
+  }
+  static async create(kind, length) {
+    if (!Number.isInteger(length) || length <= 0) {
+      throw new UsageError(`Buffer \u957F\u5EA6\u5FC5\u987B\u662F\u6B63\u6574\u6570,\u6536\u5230: ${String(length)}`);
+    }
+    const def = TYPES[kind];
+    if (!def) throw new UsageError(`\u672A\u77E5\u7C7B\u578B "${String(kind)}",\u53EF\u7528: ${Object.keys(TYPES).join(", ")}`);
+    const ctx = await GpuContext.get();
+    const gpuBuffer = ctx.device.createBuffer({
+      size: length * def.size,
+      usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC | GPUBufferUsage.COPY_DST,
+      label: `wgpu-kit Buffer<${kind}>[${length}]`
+    });
+    return new _Buffer(ctx, kind, length, gpuBuffer);
+  }
+  /** 校验并写入(CPU → GPU) */
+  write(data) {
+    const ctor = TYPED_CTORS[TYPES[this.kind].typed];
+    if (!(data instanceof ctor)) {
+      throw new UsageError(`Buffer<${this.kind}>.write \u9700\u8981 ${TYPES[this.kind].typed},\u6536\u5230 ${data.constructor?.name ?? typeof data}`);
+    }
+    const expected = this.length * TYPES[this.kind].comps;
+    if (data.length !== expected) {
+      throw new UsageError(`Buffer<${this.kind}>[${this.length}].write \u9700\u8981 ${expected} \u4E2A\u5206\u91CF,\u6536\u5230 ${data.length}`);
+    }
+    this.#ctx.device.queue.writeBuffer(this.gpuBuffer, 0, data);
+  }
+  /** GPU → CPU:内部 staging buffer + mapAsync,mapAsync 的异步陷阱由库承担 */
+  async read() {
+    const def = TYPES[this.kind];
+    if (!this.#staging) {
+      this.#staging = this.#ctx.device.createBuffer({
+        size: this.#byteLength,
+        usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ,
+        label: `wgpu-kit staging[${this.length}]`
+      });
+    }
+    const enc = this.#ctx.device.createCommandEncoder();
+    enc.copyBufferToBuffer(this.gpuBuffer, 0, this.#staging, 0, this.#byteLength);
+    this.#ctx.device.queue.submit([enc.finish()]);
+    await this.#staging.mapAsync(GPUMapMode.READ);
+    const ab = this.#staging.getMappedRange().slice(0);
+    this.#staging.unmap();
+    if (def.typed === "Float32Array") return new Float32Array(ab);
+    if (def.typed === "Int32Array") return new Int32Array(ab);
+    return new Uint32Array(ab);
+  }
+  destroy() {
+    if (this.#staging) {
+      this.#staging.destroy();
+      this.#staging = null;
+    }
+    this.gpuBuffer.destroy();
+  }
+};
+
+// src/core/kernel.ts
+var RESERVED = /* @__PURE__ */ new Set(["count"]);
+var nextBufferId = 0;
+var bufferIds = /* @__PURE__ */ new WeakMap();
+function bufId(b) {
+  let id = bufferIds.get(b);
+  if (id === void 0) {
+    id = ++nextBufferId;
+    bufferIds.set(b, id);
+  }
+  return id;
+}
+function generateElementKernel(spec) {
+  const name = spec.name ?? "kernel";
+  const workgroupSize = spec.workgroupSize ?? 64;
+  if (!Number.isInteger(workgroupSize) || workgroupSize < 1 || workgroupSize > 512) {
+    throw new UsageError(`workgroupSize \u5FC5\u987B\u5728 1..512,\u6536\u5230: ${String(workgroupSize)}`);
+  }
+  const state = Object.entries(spec.state ?? {});
+  const inputs = Object.entries(spec.inputs ?? {});
+  const uniforms = Object.entries(spec.uniforms ?? {});
+  if (state.length + inputs.length === 0) {
+    throw new UsageError(`elementKernel "${name}" \u81F3\u5C11\u9700\u8981\u4E00\u4E2A state \u6216 inputs \u5B57\u6BB5`);
+  }
+  for (const [uName] of uniforms) {
+    if (RESERVED.has(uName)) throw new UsageError(`uniform \u540D "${uName}" \u662F\u4FDD\u7559\u540D(count \u7531\u5E93\u81EA\u52A8\u6CE8\u5165)`);
+  }
+  const seen = new Set([...state, ...inputs, ...uniforms].map(([n]) => n));
+  if (seen.size !== state.length + inputs.length + uniforms.length) {
+    throw new UsageError(`elementKernel "${name}" \u7684 state/inputs/uniforms \u5B58\u5728\u91CD\u540D\u5B57\u6BB5`);
+  }
+  if (typeof spec.code !== "string" || spec.code.trim().length === 0) {
+    throw new UsageError(`elementKernel "${name}" \u7F3A\u5C11 code(\u7528\u6237 WGSL \u51FD\u6570)`);
+  }
+  const uniformEntries = [...uniforms, ["count", "u32"]];
+  const uniformLayout = planUniform(uniformEntries);
+  const header = [];
+  header.push("// \u7531 wgpu-kit elementKernel \u751F\u6210");
+  header.push("struct Params {");
+  for (const [n, k] of uniformEntries) header.push(`  ${n}: ${TYPES[k].wgsl},`);
+  header.push("};");
+  header.push("@group(0) @binding(0) var<uniform> params: Params;");
+  let binding = 1;
+  for (const [n, k] of state) header.push(`@group(0) @binding(${binding++}) var<storage, read_write> ${n}: array<${TYPES[k].wgsl}>;`);
+  for (const [n, k] of inputs) header.push(`@group(0) @binding(${binding++}) var<storage, read> ${n}: array<${TYPES[k].wgsl}>;`);
+  header.push("");
+  header.push(`@compute @workgroup_size(${workgroupSize})`);
+  header.push("fn main(@builtin(global_invocation_id) gid: vec3u) {");
+  header.push("  let idx = gid.x;");
+  header.push("  if (idx >= params.count) { return; }");
+  const uniformArgs = uniforms.map(([n]) => `params.${n}`).join(", ");
+  header.push(`  userFn(idx${uniformArgs ? ", " + uniformArgs : ""});`);
+  header.push("}");
+  const userCodeLineOffset = header.length;
+  const source = [...header, spec.code].join("\n");
+  return {
+    normalized: { name, workgroupSize, state, inputs, uniforms, code: spec.code },
+    source,
+    uniformLayout,
+    userCodeLineOffset
+  };
+}
+function elementKernel(spec) {
+  const first = generateElementKernel(spec);
+  const uniformLayout = first.uniformLayout;
+  let normalized = first.normalized;
+  let source = first.source;
+  let userCodeLineOffset = first.userCodeLineOffset;
+  const uniformBufferName = `${normalized.name}:uniform`;
+  let pipelinePromise = null;
+  const bindGroupCache = /* @__PURE__ */ new Map();
+  let uniformBuffer = null;
+  const compilePipeline = async () => {
+    const ctx = await GpuContext.get();
+    const device = ctx.device;
+    const module = device.createShaderModule({ code: source, label: normalized.name });
+    const info = await module.getCompilationInfo();
+    const errors = info.messages.filter((m) => m.type === "error");
+    if (errors.length > 0) {
+      throw new CompileError(
+        normalized.name,
+        errors.map((m) => ({ line: m.lineNum, msg: m.message })),
+        userCodeLineOffset
+      );
+    }
+    return device.createComputePipeline({ layout: "auto", compute: { module, entryPoint: "main" } });
+  };
+  async function getPipeline() {
+    if (!pipelinePromise) {
+      pipelinePromise = compilePipeline().catch((e) => {
+        pipelinePromise = null;
+        throw e;
+      });
+    }
+    return pipelinePromise;
+  }
+  return {
+    get name() {
+      return normalized.name;
+    },
+    get source() {
+      return source;
+    },
+    get uniformLayout() {
+      return first.uniformLayout;
+    },
+    get workgroupSize() {
+      return normalized.workgroupSize;
+    },
+    async replace(code) {
+      const regen = generateElementKernel({ ...spec, code });
+      const savedSource = source;
+      const savedOffset = userCodeLineOffset;
+      source = regen.source;
+      userCodeLineOffset = regen.userCodeLineOffset;
+      try {
+        const p = await compilePipeline();
+        pipelinePromise = Promise.resolve(p);
+        bindGroupCache.clear();
+      } catch (e) {
+        source = savedSource;
+        userCodeLineOffset = savedOffset;
+        throw e;
+      }
+    },
+    async run(resources, uniforms = {}) {
+      const ctx = await GpuContext.get();
+      const device = ctx.device;
+      const pipeline = await getPipeline();
+      const ordered = [];
+      for (const [key] of [...normalized.state, ...normalized.inputs]) {
+        const buf = resources[key];
+        if (!buf) throw new UsageError(`kernel "${normalized.name}".run \u7F3A\u5C11\u8D44\u6E90 "${key}"`);
+        const want = [...normalized.state, ...normalized.inputs].find(([n]) => n === key)?.[1];
+        if (buf.kind !== want) {
+          throw new UsageError(`\u8D44\u6E90 "${key}" \u7C7B\u578B\u4E0D\u5339\u914D: \u9700\u8981 ${want},\u6536\u5230 ${buf.kind}`);
+        }
+        ordered.push({ key, buffer: buf });
+      }
+      const count = ordered[0]?.buffer.length ?? 0;
+      for (const { key, buffer } of ordered) {
+        if (buffer.length !== count) {
+          throw new UsageError(`\u8D44\u6E90 "${key}" \u957F\u5EA6 ${buffer.length} \u4E0E "${ordered[0].key}" \u7684 ${count} \u4E0D\u4E00\u81F4`);
+        }
+      }
+      const uBytes = packUniform(uniformLayout, { ...uniforms, count });
+      if (!uniformBuffer) {
+        uniformBuffer = device.createBuffer({
+          size: uniformLayout.size,
+          usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+          label: uniformBufferName
+        });
+      }
+      device.queue.writeBuffer(uniformBuffer, 0, uBytes);
+      const cacheKey = ordered.map(({ key, buffer }) => `${key}:${bufId(buffer.gpuBuffer)}`).join("|");
+      let bg = bindGroupCache.get(cacheKey);
+      if (!bg) {
+        const entries = [{ binding: 0, resource: { buffer: uniformBuffer } }];
+        ordered.forEach(({ buffer }, i) => entries.push({ binding: i + 1, resource: { buffer: buffer.gpuBuffer } }));
+        bg = device.createBindGroup({ layout: pipeline.getBindGroupLayout(0), entries });
+        bindGroupCache.set(cacheKey, bg);
+      }
+      const enc = device.createCommandEncoder();
+      const pass = enc.beginComputePass();
+      pass.setPipeline(pipeline);
+      pass.setBindGroup(0, bg);
+      pass.dispatchWorkgroups(Math.ceil(count / normalized.workgroupSize));
+      pass.end();
+      device.queue.submit([enc.finish()]);
+    },
+    destroy() {
+      pipelinePromise = null;
+      bindGroupCache.clear();
+      uniformBuffer?.destroy();
+      uniformBuffer = null;
+    }
+  };
+}
+
+// src/core/pingpong.ts
+var PingPong = class _PingPong {
+  #sides;
+  #names;
+  #length;
+  #kinds;
+  #index = 0;
+  constructor(names, kinds, length, a, b) {
+    this.#names = names;
+    this.#kinds = kinds;
+    this.#length = length;
+    this.#sides = [a, b];
+  }
+  static async create(kinds, length) {
+    const names = Object.keys(kinds);
+    if (names.length === 0) throw new Error("PingPong \u81F3\u5C11\u9700\u8981\u4E00\u4E2A\u5B57\u6BB5");
+    const make = async () => {
+      const side = {};
+      for (const name of names) side[name] = await Buffer.create(kinds[name], length);
+      return side;
+    };
+    return new _PingPong(names, kinds, length, await make(), await make());
+  }
+  /** 当前帧的数据侧(渲染/读回用) */
+  get current() {
+    return this.#sides[this.#index];
+  }
+  /** 另一侧(kernel 写入目标) */
+  get other() {
+    return this.#sides[1 - this.#index];
+  }
+  /** 帧末翻转 */
+  swap() {
+    this.#index = 1 - this.#index;
+  }
+  /** 以 (写侧, 读侧) 调用 fn 后自动 swap 的语法糖 */
+  async runWith(fn) {
+    await fn(this.other, this.current);
+    this.swap();
+  }
+  destroy() {
+    for (const side of this.#sides) for (const b of Object.values(side)) b.destroy();
+  }
+  /** 克隆一份同构 PingPong(同字段同长度) */
+  async clone() {
+    return _PingPong.create(this.#kinds, this.#length);
+  }
+  get names() {
+    return this.#names;
+  }
+};
+
+// src/core/raw.ts
+function rawKernel(code, entryPoint = "main", label = "rawKernel") {
+  if (typeof code !== "string" || code.trim().length === 0) throw new UsageError("rawKernel \u9700\u8981 WGSL \u4EE3\u7801");
+  let pipelinePromise = null;
+  return {
+    async run(entries, workgroups) {
+      if (!Number.isInteger(workgroups) || workgroups < 1) {
+        throw new UsageError(`rawKernel.run \u7684 workgroups \u5FC5\u987B\u662F\u6B63\u6574\u6570,\u6536\u5230 ${String(workgroups)}`);
+      }
+      const ctx = await GpuContext.get();
+      if (!pipelinePromise) {
+        pipelinePromise = (async () => {
+          const module = ctx.device.createShaderModule({ code, label });
+          const info = await module.getCompilationInfo();
+          const errors = info.messages.filter((m) => m.type === "error");
+          if (errors.length > 0) {
+            pipelinePromise = null;
+            throw new CompileError(label, errors.map((m) => ({ line: m.lineNum, msg: m.message })), 0);
+          }
+          return ctx.device.createComputePipeline({ layout: "auto", compute: { module, entryPoint } });
+        })();
+      }
+      const pipeline = await pipelinePromise;
+      const bg = ctx.device.createBindGroup({ layout: pipeline.getBindGroupLayout(0), entries });
+      const enc = ctx.device.createCommandEncoder();
+      const pass = enc.beginComputePass();
+      pass.setPipeline(pipeline);
+      pass.setBindGroup(0, bg);
+      pass.dispatchWorkgroups(workgroups);
+      pass.end();
+      ctx.device.queue.submit([enc.finish()]);
+    },
+    destroy() {
+      pipelinePromise = null;
+    }
+  };
+}
+export {
+  Buffer,
+  CompileError,
+  GpuContext,
+  PingPong,
+  TYPES,
+  UsageError,
+  WebGPUUnavailableError,
+  WgpuKitError,
+  elementKernel,
+  packUniform,
+  planUniform,
+  rawKernel
+};

package/dist/interop/three.d.ts

@@ -0,0 +1,37 @@
+import type { ParticlesSim } from '../packs/particles/index.ts';
+/**
+ * three.js 互通(interop)—— 快照模式,零依赖、通用任何渲染器(WebGL/WebGPU)。
+ *
+ * const { points, update } = threePoints(sim, THREE, { size: 0.02 });
+ * scene.add(points);
+ * // 每帧渲染前:
+ * await update();
+ *
+ * 原理:从 GPU 读回位置快照填进 BufferAttribute(每帧一次 readback)。
+ * 零拷贝的 TSL storage 直通路径在路线图上(对渲染器有强绑定,不在 MVP 承诺内)。
+ */
+/** three.js 最小表面(按需注入,避免硬依赖) */
+export interface ThreeAPI {
+    Points: new (geometry: unknown, material: unknown) => unknown;
+    BufferGeometry: new () => unknown;
+    BufferAttribute: new (array: Float32Array, itemSize: number) => {
+        set: (arr: ArrayLike<number>) => void;
+        needsUpdate: boolean;
+    };
+    PointsMaterial: new (params: {
+        size?: number;
+        color?: number;
+        sizeAttenuation?: boolean;
+    }) => unknown;
+}
+export interface ThreePointsHandle {
+    /** 加进场景的 THREE.Points 实例 */
+    points: unknown;
+    /** 同步一帧位置快照(await;每帧调用) */
+    update(): Promise<void>;
+    dispose(): void;
+}
+export declare function threePoints(sim: ParticlesSim, THREE: ThreeAPI, opts?: {
+    size?: number;
+    color?: number;
+}): ThreePointsHandle;