Web 图形与 3D / 系统课时

区分只读参数与可写存储

区分只读参数与可写存储

模型变换参数通常由 CPU 提供,粒子位置等数组则可能由 GPU 逐帧更新。把它们都声明成 Uniform 会导致着色器无法写回数据。本课通过一次四元素计算,演示 Uniform Buffer 与 Storage Buffer 的声明、资源绑定、结果读取和选择边界。

学习目标

  • 依据数据规模、访问方和写入需求选择 Uniform 或 Storage Buffer。
  • 区分 WGSL 访问权限与 JavaScript 缓冲区的 usage 标记。
  • 运行计算着色器,验证 GPU 对 Storage Buffer 的写入结果。

按数据职责选择缓冲区

Uniform Buffer 适合供着色器读取的少量共享参数,例如相机矩阵、时间和光照系数;Storage Buffer 适合粒子状态、实例数组等较大数据集,也可以只读。两者都能由 JavaScript 通过 queue.writeBuffer() 上传,差异主要在着色器能否写入以及可用容量和布局约束。

比较项 Uniform Buffer Storage Buffer
WGSL 声明 var<uniform> var<storage, read> 或 var<storage, read_write>
着色器权限 只读 只读或读写
创建用途 GPUBufferUsage.UNIFORM GPUBufferUsage.STORAGE
典型内容 变换矩阵、帧参数 顶点相关数组、粒子位置和速度
单次绑定大小上限 device.limits.maxUniformBufferBindingSize device.limits.maxStorageBufferBindingSize

看懂 CPU 与 GPU 的访问方向

下图把主机上传、绑定、着色器读写和结果回读放到同一条数据链路中。示例将参数设为 scale = 2、bias = 1,只允许着色器读;存储数组从 [1, 2, 3, 4] 开始,计算阶段对每个元素执行 value * scale + bias,结果应为 [3, 5, 7, 9]。

Uniform 只读参数与 Storage 可写数组的数据流

@group(0) @binding(0) 和 @binding(1) 是着色器资源槽位编号,不是写入权限。真正决定 Shader 端读写能力的是 uniform、storage 后面的访问模式;创建缓冲区时还必须提供与绑定类型匹配的 usage。

运行计算并核对写回值

在支持 WebGPU 的浏览器中打开 HTTPS 页面或 http://localhost,将以下 JavaScript 粘贴到开发者工具 Console 执行。代码使用 16 字节 Uniform 保存一个 vec4<f32>,前两个分量充当缩放和偏移量;16 字节 Storage 保存四个连续的 f32。计算工作组包含四个调用,分别处理一个数组元素。

js
async function run() {
  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 params = new Float32Array([2, 1, 0, 0]);
  const values = new Float32Array([1, 2, 3, 4]);
  const uniform = device.createBuffer({
    size: params.byteLength,
    usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
  });
  const storage = device.createBuffer({
    size: values.byteLength,
    usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC,
  });
  const readback = device.createBuffer({
    size: values.byteLength,
    usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ,
  });
  device.queue.writeBuffer(uniform, 0, params);
  device.queue.writeBuffer(storage, 0, values);

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

@compute @workgroup_size(4)
fn main(@builtin(global_invocation_id) id: vec3<u32>) {
  let i = id.x;
  if (i < arrayLength(&values)) {
    values[i] = values[i] * params.x + params.y;
  }
}` });
  const pipeline = device.createComputePipeline({
    layout: "auto",
    compute: { module: shader, entryPoint: "main" },
  });
  const bindGroup = device.createBindGroup({
    layout: pipeline.getBindGroupLayout(0),
    entries: [
      { binding: 0, resource: { buffer: uniform } },
      { binding: 1, resource: { buffer: storage } },
    ],
  });

  const encoder = device.createCommandEncoder();
  const pass = encoder.beginComputePass();
  pass.setPipeline(pipeline);
  pass.setBindGroup(0, bindGroup);
  pass.dispatchWorkgroups(1);
  pass.end();
  // GPU 结果先复制到可 MAP_READ 的回读缓冲区。
  encoder.copyBufferToBuffer(storage, 0, readback, 0, values.byteLength);
  device.queue.submit([encoder.finish()]);

  await readback.mapAsync(GPUMapMode.READ);
  const output = new Float32Array(readback.getMappedRange().slice(0));
  readback.unmap();
  console.log(`result: ${Array.from(output).join(",")}`);
}
run().catch(console.error);

预期输出(Console 可能额外显示 Promise 状态):

text
result: 3,5,7,9

这里 uniform 没有 GPU 写入权限,GPU 只读取 params.x 和 params.y。storage 才在计算着色器中被更新;它带有 COPY_SRC,因此可以把写入结果复制到 readback。回读缓冲区只用 COPY_DST | MAP_READ,不能直接把带 STORAGE 用途的缓冲区映射为可读。

避开权限与内存布局错误

示例中的 vec4<f32> 占 16 字节,四个连续 f32 也占 16 字节,但这不代表任意 Uniform 结构都能按紧凑的 JavaScript 数组排列。WGSL 的成员对齐和数组步长有约束;例如 vec3<f32> 的对齐要求为 16 字节,不能把两个相邻 vec3 简单当作无填充的 24 字节布局处理。构建 CPU 侧字节布局时应逐字段核对偏移和步长。

常见错误及改法如下:

  • 想从着色器修改 Uniform:不可行。改为 var<storage, read_write> 并用 GPUBufferUsage.STORAGE;或由 CPU 更新 Uniform 后再提交新的 GPU 命令。
  • 只设置 GPUBufferUsage.STORAGE 就认为可写:还需在 WGSL 声明 read_write,且绑定布局允许读写。使用自动管线布局时会依据 WGSL 推断。
  • 在顶点阶段写 Storage:顶点阶段仅能只读访问 Storage。先用计算通道更新数组,再让后续绘制阶段读取。
  • 直接读取 GPU Storage 内容:使用 COPY_SRC 复制到 COPY_DST | MAP_READ 缓冲区,再等待 mapAsync() 完成,不能把 GPU 内存当作同步的 CPU 数组访问。

实际项目中,固定的相机和投影参数优先使用 Uniform;需要 GPU 积分更新的粒子位置、速度使用可写 Storage。两者的单次绑定容量和动态偏移对齐要求,分别通过 device.limits 查询,避免把某台设备的上限写死。

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

目录与阅读设置

阅读设置

17

记录一个想法

区分只读参数与可写存储

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

登录哪都通