WebGPU 缓冲区（GPUBuffer）内存布局与数据对齐

WebGPU 缓冲区（GPUBuffer）内存布局与数据对齐

从 WebGL 迁移到 WebGPU 的前端开发者，遇到的第一个重大思维门槛通常不是 WGSL 语法，而是底层内存布局（Memory Layout）与结构体字节对齐（Alignment）规则。

在 WebGL 中，我们可以随意声明一个包含 vec3、float 和 mat4 的 Uniform 变量，底层驱动会在黑盒内部替我们搞定内存映射。但在 WebGPU 的现代显卡抽象中，为了榨干现代 GPU 架构的超宽内存总线吞吐（如 128-bit / 256-bit 内存通道），显卡要求开发者必须严格按照硬件物理字节对齐规范来打包 ArrayBuffer。

如果哪怕有 4 个字节的偏移错位，GPU 读取到的数据就会全盘乱套，导致着色器计算出满屏的 NaN 或者诡异扭曲的几何形变。

WGSL 内存对齐的两大铁律：对齐基数与结构体对齐

在 WGSL 规范中，每种数据类型都有两个核心属性：

常见基础类型的对齐规范如下表所示：

典型结构体踩坑剖析与内存填充（Padding）

考虑下面这个在 WGSL 中看似平常的 Uniform 结构体：

struct SceneUniforms {
cameraPos: vec3<f32>, // 偏移 0，大小 12，对齐 16
time: f32, // 偏移 12 还是 16？
lightDir: vec3<f32>, // 偏移多少？
shininess: f32, // 偏移多少？
};

我们来逐步推导其在显存中的物理排布：

如果结构体稍作调整，比如把 time 和 lightDir 调换位置，中间就会被迫产生 4 字节甚至 12 字节的空洞填充（Padding）！

TypeScript 端构建精准对齐的 ArrayBuffer

为了避免手动数字节出错，在前端我们可以封装一个严格遵循 WGSL 内存布局的序列化助手：

export class AlignedBufferWriter {
private buffer: ArrayBuffer;
private view: DataView;
private offset: number = 0;

constructor(byteLength: number) {
// WebGPU 要求 Uniform Buffer 的总大小通常必须是 16 的倍数
const alignedLength = Math.ceil(byteLength / 16) * 16;
this.buffer = new ArrayBuffer(alignedLength);
this.view = new DataView(this.buffer);
}

// 内部辅助：自动补齐到 alignOf 整数倍
private alignTo(alignOf: number) {
this.offset = Math.ceil(this.offset / alignOf) * alignOf;
}

writeF32(val: number) {
this.alignTo(4);
this.view.setFloat32(this.offset, val, true); // 小端序
this.offset += 4;
}

writeVec2(x: number, y: number) {
this.alignTo(8);
this.view.setFloat32(this.offset, x, true);
this.view.setFloat32(this.offset + 4, y, true);
this.offset += 8;
}

writeVec3(x: number, y: number, z: number) {
this.alignTo(16); // 强制对齐到 16 字节！
this.view.setFloat32(this.offset, x, true);
this.view.setFloat32(this.offset + 4, y, true);
this.view.setFloat32(this.offset + 8, z, true);
this.offset += 12; // 推进 12 字节，后续字段会再次根据其对齐基数调整
}

writeVec4(x: number, y: number, z: number, w: number) {
this.alignTo(16);
this.view.setFloat32(this.offset, x, true);
this.view.setFloat32(this.offset + 4, y, true);
this.view.setFloat32(this.offset + 8, z, true);
this.view.setFloat32(this.offset + 12, w, true);
this.offset += 16;
}

writeMat4(matrix16: Float32Array | number[]) {
this.alignTo(16);
for (let i = 0; i < 16; i++) {
this.view.setFloat32(this.offset + i * 4, matrix16[i], true);
}
this.offset += 64;
}

getBuffer(): ArrayBuffer {
return this.buffer;
}
}

GPUBufferUsage 与创建要点

在向 GPU 写入缓冲区时，确保指定了正确的 Usage 标志位：

export function uploadUniformBuffer(device: GPUDevice, writer: AlignedBufferWriter): GPUBuffer {
const rawBuffer = writer.getBuffer();

const gpuBuffer = device.createBuffer({
size: rawBuffer.byteLength,
usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
});

device.queue.writeBuffer(gpuBuffer, 0, rawBuffer);
return gpuBuffer;
}

掌握了显存字节对齐规律，就如同掌握了与底层 GPU 硬件直接对话的密码，让端侧高性能渲染与大模型计算在物理底层顺畅无阻。