Web 图形与 3D / 系统课时

创建 BindGroup 绑定共享资源

创建 BindGroup 绑定共享资源

一次 WebGPU 计算可能要同时读取参数和写入数组。本篇将两个 GPUBuffer 组合进同一个 BindGroup,让 WGSL 按固定编号访问资源,再执行一次计算并读回结果。完成后,你能核对声明、布局、实际缓冲区和管线位置是否一致。

学习目标

  • 区分 BindGroupLayout 的资源契约与 BindGroup 的实际资源绑定。
  • 对齐 WGSL 的 @group、@binding 与 JavaScript 中的编号和可见阶段。
  • 运行包含 Uniform 和 Storage Buffer 的计算,并验证四个输出值。

对齐组号、绑定号与资源类型

@group(0) 指资源组位于管线布局的第 0 个槽位,编码时必须调用 pass.setBindGroup(0, bindGroup)。组内 @binding(0)、@binding(1) 则分别对应布局与资源表中的 binding: 0、binding: 1。组号和绑定号是两套独立编号,不能互换。

WGSL 声明 Layout 资源类型 Buffer 用途 可见阶段
@group(0) @binding(0) var<uniform> uniform UNIFORM COMPUTE
@group(0) @binding(1) var<storage, read_write> storage STORAGE COMPUTE

BindGroupLayout 规定编号、资源种类、最小绑定大小和着色器阶段;BindGroup 则把具体缓冲区填进这些槽位。管线使用该布局,计算通道再绑定对应的 BindGroup,WGSL 才能访问缓冲区。这里两个资源都在计算着色器中使用,因此 visibility 设为 GPUShaderStage.COMPUTE。

WGSL 绑定声明、布局、资源组与计算管线的对应关系

运行两个缓冲区的完整示例

在支持 WebGPU 的浏览器中打开 HTTPS 页面或本机 http://localhost 页面,将以下 JavaScript 粘贴到开发者工具控制台。示例创建 16 字节的参数缓冲区与结果缓冲区:参数 [2, 1, 0, 0] 表示用 2 × 索引 + 1 计算四个结果;结果通过只用于读回的缓冲区传回 CPU。

js
async function runBindGroupDemo() {
  if (!navigator.gpu) throw new Error("当前环境不支持 WebGPU");
  const adapter = await navigator.gpu.requestAdapter();
  if (!adapter) throw new Error("未获得 GPUAdapter");
  const device = await adapter.requestDevice();

  const shader = device.createShaderModule({
    code: `
      struct Params { scaleAndOffset: vec4<f32>, };
      @group(0) @binding(0) var<uniform> params: Params;
      @group(0) @binding(1) var<storage, read_write> output: array<f32>;

      @compute @workgroup_size(4)
      fn main(@builtin(global_invocation_id) id: vec3<u32>) {
        if (id.x < 4u) {
          output[id.x] = f32(id.x) * params.scaleAndOffset.x
                       + params.scaleAndOffset.y;
        }
      }
    `,
  });

  // 布局只声明资源契约,不包含实际缓冲区。
  const layout = device.createBindGroupLayout({
    entries: [
      { binding: 0, visibility: GPUShaderStage.COMPUTE,
        buffer: { type: "uniform", minBindingSize: 16 } },
      { binding: 1, visibility: GPUShaderStage.COMPUTE,
        buffer: { type: "storage", minBindingSize: 16 } },
    ],
  });
  const pipeline = device.createComputePipeline({
    layout: device.createPipelineLayout({ bindGroupLayouts: [layout] }),
    compute: { module: shader, entryPoint: "main" },
  });

  const paramsBuffer = device.createBuffer({
    size: 16, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
  });
  const outputBuffer = device.createBuffer({
    size: 16, usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC,
  });
  const readback = device.createBuffer({
    size: 16, usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ,
  });
  device.queue.writeBuffer(paramsBuffer, 0, new Float32Array([2, 1, 0, 0]));

  // BindGroup 将布局槽位与实际 GPUBuffer 对应起来。
  const bindGroup = device.createBindGroup({
    layout,
    entries: [
      { binding: 0, resource: { buffer: paramsBuffer } },
      { binding: 1, resource: { buffer: outputBuffer } },
    ],
  });
  const encoder = device.createCommandEncoder();
  const pass = encoder.beginComputePass();
  pass.setPipeline(pipeline);
  pass.setBindGroup(0, bindGroup); // 与 WGSL 的 @group(0) 对应
  pass.dispatchWorkgroups(1);
  pass.end();

  // Storage Buffer 不直接映射读取,先复制到 MAP_READ 缓冲区。
  encoder.copyBufferToBuffer(outputBuffer, 0, readback, 0, 16);
  device.queue.submit([encoder.finish()]);
  await readback.mapAsync(GPUMapMode.READ);
  console.log(Array.from(new Float32Array(readback.getMappedRange())));
  readback.unmap();
  paramsBuffer.destroy();
  outputBuffer.destroy();
  readback.destroy();
}
runBindGroupDemo().catch(console.error);

预期输出(浏览器控制台显示为数组,呈现形式可能略有差异):

text
[1, 3, 5, 7]

@workgroup_size(4) 配合 dispatchWorkgroups(1) 启动四个调用,索引依次为 0~3。两个绑定的有效范围都是 16 字节;Uniform 用一个 vec4<f32> 避免了结构体对齐歧义,Storage 保存四个 f32。数据先由 CPU 写入参数缓冲区,计算着色器写入结果缓冲区,最后经过复制和映射读回。

排查布局不匹配

如果结果未出现,先检查浏览器是否支持 WebGPU、页面是否处于安全上下文,再查看开发者工具中的 GPUValidationError。WebGPU 校验失败可能发生在创建管线、创建资源组或提交绘制与计算命令时,不能只看 JavaScript 是否抛出异常。

  • 绑定号不一致:WGSL 使用 @binding(1),但布局或 BindGroup 填了 binding: 2。修正三处编号,并确保布局中的每个条目都有对应资源。
  • 访问类型不一致:var<storage, read_write> 需要布局的 buffer.type: "storage" 和缓冲区的 GPUBufferUsage.STORAGE;只读 Storage 对应 read-only-storage。
  • 阶段或组槽错误:当前着色器在 COMPUTE 阶段访问资源,布局不能仅暴露给 FRAGMENT;@group(0) 也不能用 setBindGroup(1, ...) 代替。
  • 绑定大小或偏移错误:本例两个绑定均从偏移 0 开始、大小为 16 字节。非零 Uniform 或 Storage 绑定偏移须分别满足 device.limits.minUniformBufferOffsetAlignment、minStorageBufferOffsetAlignment;不要假设任何字节偏移都合法。

复用资源组的边界

同一批 GPUBuffer 可以在多次 dispatchWorkgroups 中通过原 BindGroup 重复绑定,不需要每帧重新创建布局。只更新参数时,可以在后续提交前调用 device.queue.writeBuffer(paramsBuffer, 0, ...);但示例末尾已销毁缓冲区,继续复用前必须保留它们并延后清理。

如果两个渲染阶段都要读取同一 Uniform,可把对应条目的 visibility 写成 GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT,前提是管线着色器的声明与布局匹配。改变资源种类、绑定数量或布局结构时,应重新检查管线布局和资源组的兼容性。BindGroup 复用的是绑定关系,不会复制缓冲区内容。

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

目录与阅读设置

阅读设置

17

记录一个想法

创建 BindGroup 绑定共享资源

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

登录哪都通