Web 图形与 3D / 系统课时
异步读回 GPU 计算结果
异步读回 GPU 计算结果
GPU 的计算结果不会自动变成 JavaScript 数组。本课用八个浮点数演示一次完整读回:先让计算着色器把每个值乘以 2,再将输出复制到可读暂存缓冲区,等待映射成功后检查结果,最后释放映射。
学习目标
- 区分计算输出缓冲区与 CPU 读回暂存缓冲区的用途标志。
- 使用
copyBufferToBuffer、mapAsync和getMappedRange读取结果。 - 验证八个计算值,并排查映射与字节对齐错误。
为什么需要暂存缓冲区
计算着色器写入的缓冲区要声明 GPUBufferUsage.STORAGE,作为复制源还要加 COPY_SRC。CPU 读回缓冲区则使用 MAP_READ | COPY_DST。WebGPU 不允许把 MAP_READ 与 STORAGE 随意组合在同一缓冲区,因此不能直接映射本例的计算输出。
本例有 8 个 f32,每个占 4 字节,三个缓冲区都分配 32 字节。GPU 先写输出,再用 copyBufferToBuffer(output, 0, staging, 0, 32) 拷贝;CPU 只在 mapAsync(GPUMapMode.READ) 完成后读取暂存区。

运行完整计算与读回示例
在支持 WebGPU 的浏览器中,打开 HTTPS 页面或 http://localhost 页面,在开发者工具 Console 执行以下 JavaScript。代码独立创建设备、输入缓冲、计算管线与暂存缓冲;不依赖其他课时的变量。
async function main() {
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 byteLength = values.byteLength;
const input = device.createBuffer({
size: byteLength,
usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST
});
const output = device.createBuffer({
size: byteLength,
usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC
});
const staging = device.createBuffer({
size: byteLength,
usage: GPUBufferUsage.MAP_READ | GPUBufferUsage.COPY_DST
});
device.queue.writeBuffer(input, 0, values);
const module = 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(4)
fn main(@builtin(global_invocation_id) id: vec3<u32>) {
if (id.x >= arrayLength(&src)) { return; }
dst[id.x] = src[id.x] * 2.0;
}`
});
const pipeline = device.createComputePipeline({
layout: "auto",
compute: { module, entryPoint: "main" }
});
const bindGroup = 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, bindGroup);
pass.dispatchWorkgroups(2);
pass.end();
// 同一命令序列中先计算,再复制 32 字节的输出。
encoder.copyBufferToBuffer(output, 0, staging, 0, byteLength);
device.queue.submit([encoder.finish()]);
// 映射会等待 GPU 对暂存缓冲区的写入结束。
await staging.mapAsync(GPUMapMode.READ);
const result = Array.from(new Float32Array(staging.getMappedRange()));
staging.unmap(); // result 已复制,解除映射后仍能使用
console.log(JSON.stringify(result));
input.destroy();
output.destroy();
staging.destroy();
}
main().catch(console.error);预期输出:
[2,4,6,8,10,12,14,16]每个工作组运行 4 个调用,dispatchWorkgroups(2) 总共覆盖 8 个元素;global_invocation_id.x 指向数组下标。命令编码器依次记录计算与复制,queue.submit 提交整批工作。mapAsync 返回 Promise,成功后才能使用 getMappedRange。
验证映射与内存边界
关键检查是比较输出长度与数值:应恰好有 8 项,第一项为 2、最后一项为 16。getMappedRange 得到的 ArrayBuffer 会在 unmap 时失效,所以示例先用 Array.from 复制数据,再解除映射;不能保存原始映射视图供以后读取。
如果出现校验错误,按以下顺序检查:
navigator.gpu不存在:确认使用支持 WebGPU 的浏览器和安全上下文(HTTPS 或 localhost)。- 复制失败:源缓冲必须带
COPY_SRC,目标必须带COPY_DST,且源偏移、目标偏移和复制大小均为 4 字节的倍数。本例全部为0或32。 mapAsync拒绝或报验证错误:目标必须带MAP_READ;显式映射偏移须按 8 字节对齐,映射大小须按 4 字节对齐,范围不得超过缓冲区大小。例如mapAsync(GPUMapMode.READ, 8, 24)可映射本例后六项。- 数据仍未就绪:确认先执行
queue.submit,再await staging.mapAsync(GPUMapMode.READ);不要省略await,也不要在缓冲区映射期间交给 GPU 使用。