WGSL中mat3x3f矩阵占用48字节的内存对齐原理与JS传输实践

在编写 WebGPU 应用时，很多开发者从 WebGL 或 CPU 端的矩阵库（如 gl-matrix）过渡过来时，都会遇到一个非常经典的报错：Uniform 缓冲区的大小与 WGSL 结构体定义不匹配。

最让人困惑的地方在于：一个 3D 空间中的 3x3 浮点数矩阵（在 WGSL 中通常写作 mat3x3<f32> 或 mat3x3f），数学上只有 9 个元素。每个单精度浮点数 f32 占用 4 字节，那么 $9 \times 4 = 36$ 字节。然而，WGSL 规范却强制要求该类型在内存中占用 48 字节。

这消失的 12 字节去哪了？本文将从 WebGPU 规范、GPU 硬件对齐机制以及前端数据流传输三个维度，彻底剖析这一底层的对齐原理。

一、 为什么 GPU 如此执着于“对齐”？

在 CPU 端，现代编译器也会进行内存对齐（Memory Alignment），以提高内存读取效率。但在 GPU 端，这种需求被放大到了极致。

GPU 是高度并行的处理器，其内存控制器通常以 128 位（16 字节）为基本单位进行数据吞吐。一个 16 字节的块可以完美容纳一个 vec4<f32>（4 个 4 字节浮点数）。如果数据没有按照 16 字节对齐，GPU 的向量寄存器在读取时就需要跨越多个内存边界，导致额外的时钟周期消耗，甚至在某些硬件架构上直接引发异常。

为了兼顾不同 GPU 硬件（如 Vulkan、Metal、DirectX 12）的底层限制，WGSL（WebGPU Shading Language）制定了极其严格的 Host-shareable（主机共享） 类型对齐规则。

二、 WGSL 的矩阵对齐公式

在 WGSL 规范中，矩阵（Matrix）被明确定义为列向量的数组（An array of column vectors）。

也就是说，一个 mat3x3<f32> 并不是一个扁平的、拥有 9 个元素的数组，而是 3 个 vec3<f32> 向量。

我们来看 WGSL 规范中关于向量和矩阵的尺寸（Size）与对齐（Align）规定：

注意 vec3<f32> 的特殊之处：它的尺寸是 12 字节（3个f32），但它的对齐量却是 16 字节。这意味着，任何 vec3<f32> 在内存中定位时，其起始地址必须是 16 的倍数。

矩阵尺寸计算公式

对于一个具有 $C$ 列、$R$ 行的矩阵 matCxR<T>：

1. 它的对齐量等于其列向量 vecR<T> 的对齐量。对于 mat3x3，其列是 vec3，所以对齐量是 16 字节。
2. 矩阵中相邻列之间的偏移量（列步长 Column Stride）必须是对齐量的整数倍。因此，每列的步长为 16 字节。
3. 矩阵的总体尺寸计算公式为：
   $$\text{Size} = \text{ColumnStride} \times (C - 1) + \text{SizeOf}(\text{vecR})$$
   代入 mat3x3<f32> 的数据：
   $$\text{Size} = 16 \times (3 - 1) + 12 = 32 + 12 = 44 \text{ 字节}$$

等等，算出来不是 44 字节吗？为什么实际占用是 48 字节？

这里有一个关键的结构体对齐闭环规则：任何类型的尺寸（Size）如果被用在结构体成员或数组中，它的最终占用空间必须圆整（Round up）到它自身对齐量（Alignment）的倍数。

因为 mat3x3f 自身的对齐量是 16 字节，44 字节并不是 16 的倍数。为了满足对齐要求，编译器会在矩阵的末尾强制追加 4 字节的填充（Padding），使其最终尺寸达到 48 字节。

三、 内存布局直观对照表

为了更直观地理解，我们可以将 mat3x3f 在显存中的字节分布展开。

假设该矩阵在内存中从偏移量 0x00 开始存储：

从上表可以清晰地看出，mat3x3 在底层其实被当作了 array<vec4<f32>, 3> 来处理。那三个原本不存在的 w 分量，就是导致内存膨胀到 48 字节的根本原因。

四、 在 JavaScript 中如何正确填充数据？

在 CPU 端（JavaScript），我们通常使用 Float32Array 来向 GPU 缓冲区写入数据。如果我们直接往里面塞入一个长度为 9 的扁平数组，GPU 读到的数据就会完全错位。

错误的做法（会导致画面扭曲或报错）：

// 只有 9 个元素，GPU 会将后续不属于该矩阵的内存数据强行读入
const badMatrix = new Float32Array([
  1, 0, 0, // col 0
  0, 1, 0, // col 1
  0, 0, 1  // col 2
]);
device.queue.writeBuffer(uniformBuffer, 0, badMatrix);

正确的做法（手动补齐 48 字节）：

你必须在每一列的末尾手动补上一个占位符（通常是 0），使每列的数据长度凑满 4 个 f32：

// 12 个元素，刚好 48 字节
const correctMatrix = new Float32Array([
  1, 0, 0, 0, // col 0 + padding
  0, 1, 0, 0, // col 1 + padding
  0, 0, 1, 0  // col 2 + padding
]);
device.queue.writeBuffer(uniformBuffer, 0, correctMatrix);

五、 最佳实践：为什么更推荐直接使用 mat4x4？

虽然 WGSL 允许你使用 mat3x3 并通过手动填充数据来适配，但在实际的 3D 图形开发中，主流的 WebGPU 最佳实践通常是直接在着色器和 CPU 端统一使用 mat4x4f（4x4 矩阵，64 字节）。

原因如下：

1. 零心智负担：mat4x4f 的每一列本身就是 vec4f，天然就是 16 字节对齐，不需要在 JS 端写各种 tricky 的 + padding 逻辑。
2. 硬件友好：现代 GPU 内部的矩阵乘法指令（如 Tensor Cores 或 SIMD 向量单元）对 4x4 矩阵进行了专属的硬件级优化。在很多架构上，计算一个 mat4x4 的延迟和计算 mat3x3 是完全一样的。
3. 兼容性极佳：3D 变换（旋转、平移、缩放、投影）在齐次坐标系下本身就需要 4x4 矩阵支撑。即使你只需要 3x3 的法线矩阵（Normal Matrix），在写入 Uniform Buffer 时用 mat4x4 传入，在 WGSL 中再通过 let normalMatrix = mat3x3f(u.model[0].xyz, u.model[1].xyz, u.model[2].xyz) 截取，也是一种更干净、更不容易出错的设计。