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]。

@group(0) @binding(0) 和 @binding(1) 是着色器资源槽位编号,不是写入权限。真正决定 Shader 端读写能力的是 uniform、storage 后面的访问模式;创建缓冲区时还必须提供与绑定类型匹配的 usage。
运行计算并核对写回值
在支持 WebGPU 的浏览器中打开 HTTPS 页面或 http://localhost,将以下 JavaScript 粘贴到开发者工具 Console 执行。代码使用 16 字节 Uniform 保存一个 vec4<f32>,前两个分量充当缩放和偏移量;16 字节 Storage 保存四个连续的 f32。计算工作组包含四个调用,分别处理一个数组元素。
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 状态):
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 查询,避免把某台设备的上限写死。