跳到内容
LABS PRODUCTMIT LicenseWebGPU

vgpu

面向 WebGPU 的 TypeScript 库：带类型的着色器导入、极简的 GPU 优先 API，同一份代码可在浏览器、无头 Node 以及测试套件中运行。

快速开始完整文档 vgpu.sh ↗

核心特性

带类型的 WGSL 导入

.wgsl 文件像 TypeScript 模块一样导入和导出，反射机制自动保持绑定名称、类型与布局正确，无需手写声明。

唯一的 Gpu 上下文

init() 返回统一句柄；每个入口点（draw、effect、frame、surface、target……）都以它为第一个参数，没有隐藏的全局状态。

为精简而设计

未使用的声明在压缩前被剪除，一个完整的全屏效果压缩后仅 25 KB（gzip），体积预算由 CI 强制把关。

默认多运行时

浏览器、无头 Node（vgpu/node，基于 Dawn）以及为测试和 CI 构建的确定性 mock（vgpu/mock）共用同一套公开 API。

显式帧

frame(gpu, (f) => f.pass(target, effect)) —— 通道、清屏与绘制都是显式调用，绝不存在隐式的场景图状态。

面向 Agent

文档、示例画廊与着色器校验均可通过 CLI 运行，vgpu.sh 还发布了供 LLM 消费的 agents.md 与 llms.txt。

快速开始

bash
pnpm add vgpu
pnpm add -D @webgpu/types
ts
import { clock, init, effect, frameLoop, surface } from "vgpu";
import waveShader from "./wave.wgsl";

const gpu = await init();
const canvasSurface = surface(gpu, canvas, { dpr: [1, 2] });
const wave = effect(gpu, waveShader, { set: { speed: 2 } });

const time = clock(gpu);
frameLoop(gpu, (frame) => {
  wave.set({ time: time.time });
  frame.pass(canvasSurface, wave);
});

init() 获取适配器与设备并返回唯一的 Gpu 上下文；其余入口点都以它为第一个参数。surface 将画布封装为渲染目标并保持尺寸同步，设备像素比限制在 1 到 2 之间。effect 将着色器编译为全屏效果，uniform 可通过 WGSL 名称经由 set() 寻址——写入立即生效。

Node 快速开始

同一套 API 可在无头环境下针对 Dawn 支撑的设备运行：

ts
import { draw, frame, init, target } from "vgpu/node";
import triangleShader from "./triangle.wgsl";

const gpu = await init();
const colorTarget = target(gpu, { size: [256, 256], format: "rgba8unorm" });
const triangle = draw(gpu, { shader: triangleShader });

frame(gpu, (f) => f.pass(colorTarget, triangle));
const pixels = await colorTarget.read();
gpu.dispose();

vgpu/mock 会为同一份代码换上确定性的软件适配器，因此测试永远不需要真实 GPU。

带类型导入的 WGSL 模块

@vgpu/wgsl-std 以具名导出提供可复用的声明（哈希、噪声、颜色、采样……），任何 .wgsl 文件都可以导出自己的 fn、struct 或 const：

wgsl
// grain.wgsl
import { hash2 } from "@vgpu/wgsl-std/hash";

export fn grain(uv: vec2f, time: f32) -> f32 {
  return hash2(uv * time).x;
}

创意示例

以下示例均可从 CLI 拉取源码本地运行，完整列表见 npx vgpu examples search。

流体细胞

动态 Voronoi 镶嵌，发光边界随 time 游走。

无限回旋体

72 步 gyroid SDF 光线步进，菲涅尔边缘光，相机环绕。

电浆星云

5 层分形噪声域扭曲，暗底烧出橙色星云，点缀闪烁星点。

无头渲染

无头渲染

星云着色器经 vgpu/node 在 Dawn 下无头渲染的真实产物（bun scripts/render-examples.ts 生成）。

npx vgpu examples pull headless-png --out ./headless-png

文档

完整文档托管于 vgpu.sh。先从入门指南开始，再阅读性能实践手册；交互式示例可在浏览器中运行。同样的指南与 API 参考也随包发布，可通过 CLI 完全离线运行：

bash
npx vgpu docs cat getting-started.md
npx vgpu docs find effect

Agent 资源

vgpu 既能由人操作，也能由编码 Agent 操作。示例画廊可从 CLI 检索：

bash
npx vgpu examples search "raymarching"
npx vgpu examples pull <id> --out ./example

支持 skill 的 Agent 可安装 vgpu 的轻量文档路由：

bash
npx skills add vercel-labs/vgpu
bash
npx vgpu mcp
npx vgpu mcp --project-from-cwd

包

这是一个 monorepo。公开入口是 vgpu，其余部分要么支撑它，要么独立发布。

包说明
vgpu公开主 API：init、draw、compute、effect、frame、bundle、target、uniforms，以及 scene 与 core 子路径。
@vgpu/clivgpu 命令行二进制：文档、着色器 check、doctor，以及 Dawn/软件渲染器配置。
@vgpu/corevgpu/core 背后的底层 WebGPU 封装（Device、Buffer、Texture、绑定组）。
@vgpu/wgsl在打包前将 .wgsl 文件转换为 JS 模块，并解析 WGSL 到 WGSL 的导入。
@vgpu/wgsl-std标准 WGSL 工具模块（数学、颜色、采样、噪声、哈希……）。
@vgpu/adapter-nodevgpu/node 使用的 Dawn 支撑适配器。
@vgpu/adapter-mockvgpu/mock 使用的确定性 mock 适配器。
@vgpu/render位于主渲染表面之外、轻量的编辑/检查/工具/性能辅助模块。