Web 图形与 3D / 系统课时
映射线程索引到数据位置
映射线程索引到数据位置
计算着色器会同时启动许多调用,但每次调用都必须知道自己负责哪个数据元素。本课以 10 个浮点数、每组 4 次调用为例,完成索引映射、越界保护、GPU 计算与结果回读,让每个有效调用只处理一个数组位置。
学习目标
- 区分
workgroup_id、local_invocation_id与global_invocation_id的含义。 - 根据
@workgroup_size和数组长度计算工作组数量。 - 给存储缓冲区访问添加边界检查,并核对计算结果。
分清工作组与调用索引
一次计算调度先划分为多个工作组,每组再包含固定数量的调用(invocation)。WGSL 入口函数可通过 @builtin(...) 获得索引,三个变量的类型都是 vec3<u32>:
| 内建变量 | 表示什么 | 一维示例 |
|---|---|---|
workgroup_id |
当前工作组在调度网格中的坐标 | 第 3 组的 x=2 |
local_invocation_id |
当前调用在组内的坐标 | 第 2 个调用的 x=1 |
global_invocation_id |
当前调用在整次调度中的坐标 | x=2×4+1=9 |
当入口声明 @workgroup_size(4) 时,每组 X 方向有 4 次调用,Y、Z 方向默认各为 1。此时全局 X 索引等于「工作组 X 坐标 × 4 + 组内 X 坐标」。对于一维数组,直接使用 global_invocation_id.x 作为元素下标最简洁;它不是 CPU 线程编号,也不能据此推断执行先后顺序。
计算覆盖范围并过滤越界
假设数组有 10 个元素,工作组大小为 4,调用 dispatchWorkgroups(Math.ceil(10 / 4)) 会启动 3 个工作组、共 12 次调用。全局索引为 0~9 的调用各处理一个元素;索引 10、11 没有对应数据,必须提前返回。

工作组数量用向上取整,而不是向下取整,否则最后两个元素不会被处理。数组长度不一定是工作组大小的整数倍,因此在计算着色器内应先检查 i >= arrayLength(&data),再访问 data[i]。其中 arrayLength 返回当前存储缓冲区绑定范围内运行时数组的元素数量,而不是这次调度启动的调用数量。
运行一个数组翻倍示例
在支持 WebGPU 的浏览器中打开 HTTPS 页面或本机 localhost 页面,按 F12 打开开发者工具的 Console,粘贴整段 JavaScript 并执行。示例使用长度为 10 的 Float32Array,每个有效 GPU 调用将一个元素乘以 2,再复制回可读取的缓冲区。
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([0, 1, 2, 3, 4, 5, 6, 7, 8, 9]);
const byteSize = values.byteLength;
const storage = device.createBuffer({
size: byteSize,
usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC,
});
const readback = device.createBuffer({
size: byteSize,
usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ,
});
device.queue.writeBuffer(storage, 0, values);
const module = device.createShaderModule({ code: `
@group(0) @binding(0)
var<storage, read_write> data: array<f32>;
@compute @workgroup_size(4)
fn main(@builtin(global_invocation_id) gid: vec3<u32>) {
let i = gid.x;
// 最后一个工作组有多余调用,禁止它们访问数组。
if (i >= arrayLength(&data)) { return; }
data[i] = data[i] * 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: storage } }],
});
const encoder = device.createCommandEncoder();
const pass = encoder.beginComputePass();
pass.setPipeline(pipeline);
pass.setBindGroup(0, bindGroup);
// 这里传的是工作组数 3,而不是调用总数 10。
pass.dispatchWorkgroups(Math.ceil(values.length / 4));
pass.end();
encoder.copyBufferToBuffer(storage, 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();
storage.destroy();
readback.destroy();
device.destroy();
}
main().catch(console.error);预期输出:
0, 2, 4, 6, 8, 10, 12, 14, 16, 18输出恰好有 10 个数字,说明 global_invocation_id.x 与数组元素一一对应,多出来的两次调用被过滤。若 navigator.gpu 不存在,先确认浏览器支持 WebGPU,且页面运行在安全上下文;无法获得适配器时,换用支持 WebGPU 的设备或浏览器环境,不要通过删除边界检查来掩盖问题。
二维数据不能只检查线性下标
处理宽 5、高 3 的图像时,全局调用坐标为 (x, y),线性数组位置是 y * 5 + x。如果工作组大小改为 @workgroup_size(4, 4),则需要调度 dispatchWorkgroups(2, 1),覆盖 8×4 个坐标,但只有 5×3 个有效像素。
应先要求 x < 5 且 y < 3,再计算线性下标。例如 (5, 1) 虽然能算出下标 10(仍落在 15 个元素范围内),其 X 坐标却已超出当前行;只检查 index < 15 会错误改写下一行的元素。索引映射的边界应与原始数据维度一致。