Web 图形与 3D / 系统课时
上传顶点数组到 GPU 缓冲区
上传顶点数组到 GPU 缓冲区
把三角形坐标从 JavaScript 上传到 GPU 后,绘制管线才能读取这些数据。本篇用 Float32Array 准备三个二维顶点,创建带正确用途标记的 GPUBuffer,通过 queue.writeBuffer() 写入,再读回确认内容没有错位。
学习目标
- 算清顶点数量、字节数和顶点步长。
- 创建可写入且可作为顶点输入的 GPU 缓冲区。
- 验证上传结果,并对齐后续绘制管线的顶点布局。
组织坐标与字节布局
使用三个裁剪空间顶点 (0, 0.5)、(-0.5, -0.5)、(0.5, -0.5) 组成三角形。每个顶点只有 x、y 两个 float32 分量,按顶点顺序连续存储,不包含颜色、UV 或索引。
| 顶点 | 坐标 (x, y) |
GPU 缓冲区字节范围 |
|---|---|---|
| 0 | (0, 0.5) |
0~7 |
| 1 | (-0.5, -0.5) |
8~15 |
| 2 | (0.5, -0.5) |
16~23 |
一个 float32 占 4 字节,因此每个顶点占 8 字节,三个顶点共 6 个浮点数、24 字节。用 vertices.byteLength 创建缓冲区,比误用表示元素个数的 vertices.length 更可靠。
GPUBufferUsage.VERTEX 允许缓冲区充当顶点输入;GPUBufferUsage.COPY_DST 允许 writeBuffer() 写入。本次额外加上 COPY_SRC,只是为了把上传内容复制出来核验,普通静态网格不必总保留这一用途。

写入 GPU 并核对数据
在支持 WebGPU 的浏览器里打开 HTTPS 或 localhost 页面,进入开发者工具 Console 运行以下完整 JavaScript。代码申请设备、写入 24 字节,然后使用独立读回缓冲区验证;验证读回不是每次绘制必需的操作。
async function main() {
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 vertices = new Float32Array([
0, 0.5,
-0.5, -0.5,
0.5, -0.5,
]);
const vertexBuffer = device.createBuffer({
size: vertices.byteLength,
// COPY_SRC 仅用于本例的读回校验
usage: GPUBufferUsage.VERTEX |
GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC,
});
device.queue.writeBuffer(vertexBuffer, 0, vertices);
// 先复制到允许映射读取的暂存缓冲区
const readback = device.createBuffer({
size: vertices.byteLength,
usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ,
});
const encoder = device.createCommandEncoder();
encoder.copyBufferToBuffer(
vertexBuffer, 0, readback, 0, vertices.byteLength
);
device.queue.submit([encoder.finish()]);
await readback.mapAsync(GPUMapMode.READ);
const copied = new Float32Array(readback.getMappedRange()).slice();
readback.unmap();
console.log(`bytes=${vertices.byteLength}`);
console.log(`vertices=${Array.from(copied).join(",")}`);
// 验证程序结束;用于真实绘制时应保留 vertexBuffer
readback.destroy();
vertexBuffer.destroy();
}
main().catch(console.error);预期输出:
bytes=24
vertices=0,0.5,-0.5,-0.5,0.5,-0.5queue.writeBuffer() 本身不返回上传后的数据,调用完成也不代表画面已经绘制。这里提交复制命令,等待 mapAsync(GPUMapMode.READ) 后才读取,因此能核验 GPU 缓冲区中的实际内容。
对接绘制管线与排除错误
在真正的绘制代码中不要立即销毁 vertexBuffer。要在渲染通道调用 setVertexBuffer(0, vertexBuffer),并让管线第 0 个顶点缓冲布局使用 arrayStride: 8、stepMode: "vertex";属性配置为 shaderLocation: 0、offset: 0、format: "float32x2",对应 WGSL 中 @location(0) 的二维浮点输入。上传本身不会创建管线或发出绘制命令。
- 写入时报用途校验错误:确认目标缓冲区具有
COPY_DST,且未处于映射状态或已销毁。 - 数据写入越界:检查
size >= 24;writeBuffer()的目标偏移是字节数,需为 4 的倍数。传入Float32Array时,可选的源dataOffset和size则按元素计数。 - 读回正确但图形变形:检查顶点步长是否误写成
2,以及管线是否把两个float32解释为float32x2。 - 修改 CPU 数组后 GPU 没变化:修改
Float32Array不会自动同步;需要再次调用queue.writeBuffer()。
完成上述核验后,去掉仅供测试的 COPY_SRC 与读回流程,就得到常规的顶点缓冲区上传路径。