Web 图形与 3D / 系统课时
用存储缓冲区读写数组
用存储缓冲区读写数组
把 JavaScript 中的 8 个浮点数上传到 GPU,让计算着色器逐项执行“乘 2 加 1”,再把结果读回浏览器控制台。本课会区分只读输入、可写输出与回读缓冲区,完成一次可验证的 WebGPU 数组处理。
学习目标
- 用 WGSL 声明只读与可写的存储数组,并正确绑定到计算管线。
- 按字节数创建缓冲区、上传输入,并派发足够的工作组。
- 从 GPU 回读计算结果,识别资源标志和数组越界错误。
明确访问权限与数据路径
WGSL 的 array<f32> 是运行时长度的存储数组;每个 f32 占 4 字节。本例有 8 个元素,因此每个缓冲区需要 8 × 4 = 32 字节。输入用 var<storage, read> 声明,着色器只能读取;输出用 var<storage, read_write> 声明,着色器能够写入。两者的 @binding 编号必须与 JavaScript 创建的绑定组一致。
| 缓冲区 | GPUBufferUsage |
作用 |
|---|---|---|
输入 input |
STORAGE、COPY_DST |
CPU 写入,GPU 只读 |
输出 output |
STORAGE、COPY_SRC |
GPU 写入,随后复制 |
回读 readback |
COPY_DST、MAP_READ |
接收复制结果,供 JS 读取 |
在 JavaScript 中,资源标志使用按位或运算符组合,例如 GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST。不能在输出存储缓冲区上直接附加 MAP_READ;必须先复制到独立的回读缓冲区。

运行逐元素计算
使用支持 WebGPU 的浏览器,在 HTTPS 或 http://localhost 页面打开开发者工具控制台,粘贴并执行以下完整 JavaScript。程序不需要画布,输出只写到控制台;若当前环境没有 WebGPU,会抛出明确错误。
(async () => {
if (!navigator.gpu) throw new Error("当前页面不支持 WebGPU");
const adapter = await navigator.gpu.requestAdapter();
if (!adapter) throw new Error("没有可用的 GPU 适配器");
const device = await adapter.requestDevice();
const values = new Float32Array([1, 2, 3, 4, 5, 6, 7, 8]);
const byteSize = values.byteLength; // 8 个 f32,共 32 字节
const input = device.createBuffer({
size: byteSize,
usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
});
const output = device.createBuffer({
size: byteSize,
usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC,
});
// 映射读取与 STORAGE 不可直接组合,使用单独的回读缓冲区
const readback = device.createBuffer({
size: byteSize,
usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ,
});
device.queue.writeBuffer(input, 0, values);
const shader = device.createShaderModule({
code: `
@group(0) @binding(0) var<storage, read> src: array<f32>;
@group(0) @binding(1) var<storage, read_write> dst: array<f32>;
@compute @workgroup_size(64)
fn main(@builtin(global_invocation_id) id: vec3<u32>) {
let i = id.x;
// 64 个线程覆盖 8 个元素,其余线程必须退出
if (i >= arrayLength(&src)) { return; }
dst[i] = src[i] * 2.0 + 1.0;
}`,
});
const pipeline = device.createComputePipeline({
layout: "auto",
compute: { module: shader, entryPoint: "main" },
});
const group = device.createBindGroup({
layout: pipeline.getBindGroupLayout(0),
entries: [
{ binding: 0, resource: { buffer: input } },
{ binding: 1, resource: { buffer: output } },
],
});
const encoder = device.createCommandEncoder();
const pass = encoder.beginComputePass();
pass.setPipeline(pipeline);
pass.setBindGroup(0, group);
pass.dispatchWorkgroups(Math.ceil(values.length / 64));
pass.end();
// GPU 运算结束后按队列顺序复制到可映射缓冲区
encoder.copyBufferToBuffer(output, 0, readback, 0, byteSize);
device.queue.submit([encoder.finish()]);
await readback.mapAsync(GPUMapMode.READ);
const result = new Float32Array(readback.getMappedRange().slice(0));
console.log(Array.from(result).join(", "));
readback.unmap();
input.destroy();
output.destroy();
readback.destroy();
})().catch(console.error);预期输出:
3, 5, 7, 9, 11, 13, 15, 17每项按 y = 2x + 1 计算,例如输入 4 得到 9。writeBuffer 负责把 32 字节放入输入缓冲区;dispatchWorkgroups(1) 派发 1 组、每组 64 次调用;mapAsync 完成后,JavaScript 才能安全读取回读缓冲区。本例输出整数可由 f32 精确表示,因此控制台结果确定。
校验数组边界与常见错误
本例的 @builtin(global_invocation_id) 提供全局调用坐标,id.x 对应数组索引。实际数组长度若改为 130,工作组数量应为 Math.ceil(130 / 64) = 3,产生 192 次调用;最后 62 次须由 i >= arrayLength(&src) 跳过。这里的数组长度来自绑定缓冲区的有效字节范围,不是工作组大小。
- 若出现
navigator.gpu不存在,先确认 HTTPS 或 localhost、安全上下文及浏览器 WebGPU 支持情况。 - 若创建绑定组或管线时发生校验错误,对照 WGSL 的
@group(0) @binding(0/1)、读写权限和GPUBufferUsage.STORAGE;layout: "auto"仍要求绑定资源类型相符。 - 若复制或读取失败,检查输出是否具有
COPY_SRC、回读是否同时具有COPY_DST | MAP_READ,并确认是在queue.submit后等待mapAsync完成,再复制映射内存与调用unmap()。
实际处理粒子位置、速度或图像数值时,可以把输入换成更长的 Float32Array,同时更新缓冲区字节数和派发组数。让不同调用处理不同索引,并确保每个输出元素只有预期的写入者,就能从这个示例扩展出无数据竞争的逐元素 GPU 计算。