Web 图形与 3D / 系统课时
创建计算管线并派发工作组
创建计算管线并派发工作组
本课把 130 个整数交给 GPU 并行处理,让每个元素变成自身编号的 3 倍,再将结果读回浏览器控制台。你将掌握 WGSL 计算入口、ComputePipeline 创建、工作组派发,以及输出校验的完整操作。
学习目标
- 区分工作组大小与派发的工作组数量,算出实际调用次数。
- 创建计算管线和 Storage Buffer 绑定,编码并提交计算任务。
- 回读 GPU 结果,处理末尾不足一组时的越界调用。
计算线程怎样分组
@compute 将 WGSL 函数声明为计算入口,@workgroup_size(64) 指定每个工作组有 64 次着色器调用。dispatchWorkgroups(3) 派发的是 3 个工作组,并不是 3 个线程,总调用数为 3 × 64 = 192。
本例要处理 130 个 u32,所以工作组数量为 Math.ceil(130 / 64) = 3。前两组各覆盖 64 项,第三组仅前 2 项有效。WGSL 的 @builtin(global_invocation_id) 提供全局调用坐标:一维任务读取 gid.x 作为数组下标,写入前通过 arrayLength(&values) 检查边界。不能假定派发后的调用数量刚好等于元素数量。
计算管线、绑定组与数据回读
着色器在 @group(0) @binding(0) 声明可写存储数组,JS 则用同一绑定编号把 GPUBuffer 交给管线。createComputePipelineAsync() 指定计算入口 main;layout: "auto" 会根据 WGSL 声明推导资源布局,可通过 pipeline.getBindGroupLayout(0) 创建匹配的绑定组。
GPU 计算结果先留在 STORAGE | COPY_SRC 缓冲区中,再通过 copyBufferToBuffer() 复制到 COPY_DST | MAP_READ 回读缓冲区。不能直接对只有 STORAGE 用途的缓冲区调用 mapAsync(GPUMapMode.READ);WebGPU 对可映射缓冲区的用途组合有限制。

在浏览器运行完整示例
在支持 WebGPU 的浏览器中打开 HTTPS 页面或通过 localhost 访问本地页面,打开开发者工具 Console,粘贴运行以下 JavaScript。它不需要 Canvas,也不需要第三方库;数组长度和工作组大小都在代码中明确设置。
async function runCompute() {
if (!navigator.gpu) throw new Error("当前环境不支持 WebGPU");
const adapter = await navigator.gpu.requestAdapter();
if (!adapter) throw new Error("没有可用的 WebGPU 适配器");
const device = await adapter.requestDevice();
const count = 130;
const workgroupSize = 64;
const bytes = count * Uint32Array.BYTES_PER_ELEMENT;
const shader = device.createShaderModule({ code: `
@group(0) @binding(0)
var<storage, read_write> values: array<u32>;
@compute @workgroup_size(64)
fn main(@builtin(global_invocation_id) gid: vec3<u32>) {
let i = gid.x;
// 最后一组有多余调用,必须先检查边界。
if (i >= arrayLength(&values)) { return; }
values[i] = i * 3u;
}
` });
const pipeline = await device.createComputePipelineAsync({
layout: "auto",
compute: { module: shader, entryPoint: "main" }
});
const storage = device.createBuffer({
size: bytes,
usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC
});
const readback = device.createBuffer({
size: bytes,
usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ
});
const bindGroup = device.createBindGroup({
layout: pipeline.getBindGroupLayout(0),
entries: [{ binding: 0, resource: { buffer: storage } }]
});
const encoder = device.createCommandEncoder();
const pass = encoder.beginComputePass();
pass.setPipeline(pipeline);
pass.setBindGroup(0, bindGroup);
const groups = Math.ceil(count / workgroupSize);
pass.dispatchWorkgroups(groups);
pass.end();
// 先计算再复制;提交后等待回读缓冲区映射成功。
encoder.copyBufferToBuffer(storage, 0, readback, 0, bytes);
device.queue.submit([encoder.finish()]);
await readback.mapAsync(GPUMapMode.READ);
const result = new Uint32Array(readback.getMappedRange().slice(0));
readback.unmap();
console.log(`工作组数: ${groups}`);
console.log(`前 8 项: ${Array.from(result.slice(0, 8)).join(", ")}`);
console.log(`末尾 2 项: ${Array.from(result.slice(-2)).join(", ")}`);
storage.destroy();
readback.destroy();
}
runCompute().catch(console.error);预期输出:
工作组数: 3
前 8 项: 0, 3, 6, 9, 12, 15, 18, 21
末尾 2 项: 384, 387核对运行边界与常见问题
把 count 改成 128 后,预计只派发 2 个工作组,末尾两项应变为 378, 381;改成 129 则仍派发 3 组。修改 WGSL 中的 @workgroup_size(64) 时,也必须同步修改 JS 的 workgroupSize,否则覆盖范围可能不足或过多。
- 报错
navigator.gpu不可用:检查浏览器对 WebGPU 的支持情况,以及页面是否处于 HTTPS 或localhost安全上下文。 - 管线创建或绑定验证失败:核对
entryPoint: "main"、WGSL 的@group(0) @binding(0)与 JS 的getBindGroupLayout(0)、binding: 0是否一致。 - 结果不完整或越界:确认用向上取整计算工作组数,且 GPU 端在访问数组前检查
i >= arrayLength(&values)。 - 任务规模增大:比较
workgroupSize与device.limits.maxComputeInvocationsPerWorkgroup、maxComputeWorkgroupSizeX,同时确保派发的每个维度不超过maxComputeWorkgroupsPerDimension;超出时应分批或改为二维调度。
dispatchWorkgroups() 只是把工作派发命令记录进计算通道;真正提交由 device.queue.submit() 完成。只有回读缓冲区成功映射后,CPU 才能可靠地检查这批结果。