wgpu-kit 1.0.1 → 1.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +4 -2
  2. package/README.zh-CN.md +36 -41
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -3,9 +3,11 @@
3
3
  **Browser GPGPU middle layer. 200,000 particles at 142fps — in 5 lines of code.**
4
4
  All the WebGPU boilerplate — device, buffers, pipelines, dispatch, readbacks — wrapped into two simple API layers.
5
5
 
6
+ [![CI](https://github.com/nanfengw0w/wgpu-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/nanfengw0w/wgpu-kit/actions/workflows/ci.yml) [![npm](https://img.shields.io/npm/v/wgpu-kit)](https://www.npmjs.com/package/wgpu-kit) [![license MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
7
+
6
8
  [**API Reference**](docs/API.md) · [中文文档](README.zh-CN.md) · **[LIVE DEMO](https://nanfengw0w.github.io/wgpu-kit/)** · Changelog: [releases](https://github.com/nanfengw0w/wgpu-kit/releases)
7
9
 
8
- ![wgpu-kit particle life](docs/assets/hero.gif)
10
+ ![wgpu-kit particle life](hero.gif)
9
11
 
10
12
  ## Quick start
11
13
 
@@ -62,7 +64,7 @@ dispatch, readbacks, error line-mapping — all handled by the library.
62
64
  | `wgpu-kit/media` | canvas recording (webm/mp4) |
63
65
  | `wgpu-kit/vite` | WGSL kernel hot reload |
64
66
 
65
- ![life quartet](docs/assets/life-quartet.png)
67
+ ![life quartet](life-quartet.png)
66
68
 
67
69
  *The life pack: Turing patterns / Physarum / Boids / Tentacles — [open the demo](https://nanfengw0w.github.io/wgpu-kit/life.html).*
68
70
 
package/README.zh-CN.md CHANGED
@@ -1,18 +1,21 @@
1
1
  # wgpu-kit
2
2
 
3
- > **Browser GPGPU middle layer. 132,000 particles at 142fps — in 5 lines of code.**
4
- > 浏览器 GPGPU 中间层:WebGPU 计算的全套样板,打包成两层简单 API。
3
+ > 浏览器创意编程 GPU 工具包:20 万粒子物理 120fps,只需 5 行代码。
4
+ > WebGPU 计算的全套样板——设备、缓冲、管线、dispatch、双缓冲、读回、错误行号映射——打包成两层简单 API。
5
5
 
6
- **状态:公测就绪(v0.9.5)· 演示:[playground](playground/index.html) · [生命合集](playground/life.html) · [画廊](playground/gallery.html)**
7
- · **[API 参考(中文)](docs/API.zh-CN.md)** · [API Reference (English)](docs/API.md)
6
+ [![CI](https://github.com/nanfengw0w/wgpu-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/nanfengw0w/wgpu-kit/actions/workflows/ci.yml) [![npm](https://img.shields.io/npm/v/wgpu-kit)](https://www.npmjs.com/package/wgpu-kit) [![license MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
8
7
 
9
- ## Quick start
8
+ English: [README.md](README.md) · [API 参考(中文)](docs/API.zh-CN.md) · [API Reference (English)](docs/API.md) · **[在线演示](https://nanfengw0w.github.io/wgpu-kit/)**
9
+
10
+ ![wgpu-kit particle life](hero.gif)
11
+
12
+ ## 快速开始
10
13
 
11
14
  ```bash
12
- npm i wgpu-kit # 首次发布前:git clone + npm run build
15
+ npm i wgpu-kit
13
16
  ```
14
17
 
15
- **5 行,10 万粒子**(领域包,开箱即用):
18
+ **5 行,10 万粒子:**
16
19
 
17
20
  ```ts
18
21
  import { particles } from 'wgpu-kit';
@@ -23,7 +26,7 @@ function frame() { sim.tick(); requestAnimationFrame(frame); }
23
26
  frame();
24
27
  ```
25
28
 
26
- **自定义 GPU 计算**(kernel 核心,写"单个元素怎么变"就行):
29
+ **自定义 GPU 计算**——你只写"单个元素怎么变"的函数:
27
30
 
28
31
  ```ts
29
32
  import { elementKernel, Buffer } from 'wgpu-kit';
@@ -32,8 +35,8 @@ const pos = await Buffer.create('vec2f', 100_000);
32
35
  const vel = await Buffer.create('vec2f', 100_000);
33
36
 
34
37
  const integrate = elementKernel({
35
- state: { pos: 'vec2f' },
36
- inputs: { vel: 'vec2f' },
38
+ state: { pos: 'vec2f' },
39
+ inputs: { vel: 'vec2f' },
37
40
  uniforms: { dt: 'f32' },
38
41
  code: `
39
42
  fn userFn(idx: u32, dt: f32) {
@@ -44,55 +47,47 @@ const integrate = elementKernel({
44
47
  await integrate.run({ pos, vel }, { dt: 0.02 });
45
48
  ```
46
49
 
47
- 设备/缓冲/管线/绑定/dispatch/双缓冲/读回/错误行号映射——全部由库承担。
48
-
49
- ## 包家族
50
+ ## 入口一览
50
51
 
51
- | 入口 | 一句话 |
52
+ | 导入 | 用途 |
52
53
  | --- | --- |
53
- | `wgpu-kit` | elementKernel 核心 + Buffer/PingPong/rawKernel |
54
- | `wgpu-kit/particles` | 粒子生命:力矩阵预设/随机宇宙、grid 邻域、热更新、快照分享 |
55
- | `wgpu-kit/life` | 人工生命:图灵斑图 / 粘菌 / Boids / 软体触手 |
56
- | `wgpu-kit/fields` | 向量场平迹(数据可视化) |
54
+ | `wgpu-kit` | elementKernel 核心 + Buffer / PingPong / rawKernel |
55
+ | `wgpu-kit/particles` | 粒子生命:力矩阵预设、自适应世界、热更新 |
56
+ | `wgpu-kit/life` | 图灵斑图 / 粘菌 / Boids / 软体触手 |
57
+ | `wgpu-kit/fields` | 向量场平迹 |
57
58
  | `wgpu-kit/image` | GPU 滤镜管线(blur/sharpen/edge/…) |
58
59
  | `wgpu-kit/react` | `<ParticleCanvas />` |
59
60
  | `wgpu-kit/three` | three.js 快照互通 |
60
- | `wgpu-kit/media` | 画布录制(一键产视频素材) |
61
- | `wgpu-kit/vite` | kernel 热重载插件(WGSL 改动毫秒级生效) |
61
+ | `wgpu-kit/media` | 画布录制(webm/mp4) |
62
+ | `wgpu-kit/observe` | GPU 计时 / 设备诊断 / 画布助手 |
63
+ | `wgpu-kit/vite` | WGSL kernel 热重载 |
62
64
 
63
- ## 数字(可复现,非营销)
64
-
65
- | 指标 | 数值 | 环境 |
66
- | --- | --- | --- |
67
- | 粒子模拟(端到端) | **131,072 粒子 @ 142fps** | RTX 4060 Laptop,playground 实测 |
68
- | 粒子计算(纯 GPU) | grid@131k = **0.89 ms/帧** | 同上,headless 基准 |
69
- | 邻域算法对比 | grid 比 O(N²) tiling 快 **6.7×**@16k,近似 O(N) | 同会话基准 |
70
- | 库体积 | core gzip **5.34 kB**;+particles **10.27 kB** | gzip -c |
65
+ ![life quartet](life-quartet.png)
71
66
 
72
- 完整基准数据与复现命令:[docs/benchmarks.md](docs/benchmarks.md)。
67
+ *life 包:图灵斑图 / 粘菌 / Boids / 软体触手 — [打开演示](https://nanfengw0w.github.io/wgpu-kit/life.html)。*
73
68
 
74
- ## 为什么
69
+ ## 数字(全部可复现)
75
70
 
76
- 浏览器里用 GPU,今天只有四条路:纯 JS(慢)、裸写 WebGPU(~150 行仪式代码)、three.js TSL(锁引擎)、gpu.js(WebGL 时代,停滞)。"**简单 + 快 + 引擎无关**"的专用 WebGPU 计算库是空位。
71
+ | 指标 | 数值 | 环境 |
72
+ | --- | --- | --- |
73
+ | 粒子端到端 | 200,000 @ 122fps / 66,000 @ 144fps | RTX 4060 Laptop,playground 实测 |
74
+ | 粒子计算(grid) | 16k→262k 平坦,3.0→3.3ms/帧 | headless 基准 |
75
+ | 邻域算法 | grid 近似 O(N),66k 时比暴力快 8.5× | 同会话 A/B |
76
+ | 库体积 | core gzip ~10kB(共享上下文构建) | gzip |
77
77
 
78
78
  ## 三条设计铁律
79
79
 
80
80
  1. **第二层 5 分钟出活,第一层不封顶**——`rawKernel` 与原生 `GPUBuffer` 逃生舱常开;
81
- 2. **错误说人话**——WGSL 编译失败精确映射回你的代码行;
82
- 3. **基准即文档**——所有宣传数字可复现,性能预算进 CI(`npm run build` 自动核对体积)。
81
+ 2. **错误说人话**——WGSL 编译失败映射回你的代码行号;
82
+ 3. **基准即文档**——所有数字可复现;gzip 体积预算由 `npm run build` 强制核对。
83
83
 
84
84
  ## 支持矩阵
85
85
 
86
86
  | 浏览器 | 状态 |
87
87
  | --- | --- |
88
- | Chrome / Edge 113+(含无头) | ✅ 本项目全部验证在此完成(RTX 4060,D3D 后端) |
89
- | Safari 18+ | 🔶 WebGPU 可用即应工作;未在本项目环境实测,issue 欢迎 |
90
- | Firefox | 🔶 同上 |
91
- | WebGL2 / 无 WebGPU | ❌ 不做降级(ADR-1);打开 [detect 页](playground/detect.html)可诊断 |
92
-
93
- ## 项目方法论
94
-
95
- 这不是一个"写完就算"的仓库:**每个阶段完成后,由无头浏览器在真实 GPU 上运行结构化探针验证,验证日志、路径对比、事故复盘全部入档**。从裸 WebGPU spike 到 13 万粒子,共 6 个阶段、7 个版本标签、38 项自动化探针。
88
+ | Chrome / Edge 113+(含无头) | ✅ 全部验证在此完成(RTX 4060,D3D 后端) |
89
+ | Safari 18+ / Firefox | 🔶 WebGPU 可用即应工作;未实测,issue 欢迎 |
90
+ | WebGL2 / 无 WebGPU | ❌ 不做降级(设计决策);`detect.html` 可诊断 |
96
91
 
97
92
  ## 许可
98
93
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "wgpu-kit",
3
- "version": "1.0.1",
3
+ "version": "1.0.2",
4
4
  "description": "Browser GPGPU middle layer: 100k particles in 5 lines. WebGPU compute without the boilerplate.",
5
5
  "type": "module",
6
6
  "license": "MIT",