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;必须先复制到独立的回读缓冲区。

存储数组从主机上传到 GPU 计算并回读的数据流

运行逐元素计算

使用支持 WebGPU 的浏览器,在 HTTPS 或 http://localhost 页面打开开发者工具控制台,粘贴并执行以下完整 JavaScript。程序不需要画布,输出只写到控制台;若当前环境没有 WebGPU,会抛出明确错误。

js
(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);

预期输出:

text
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 计算。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

用存储缓冲区读写数组

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通