Web 图形与 3D / 系统课时
用 Uniform 更新每帧变换参数
用 Uniform 更新每帧变换参数
让一个三角形连续旋转,同时避免每帧重新创建着色器、绑定组和图形管线。做法是把 CPU 计算的 4×4 变换矩阵写进 Uniform Buffer,让顶点着色器读取最新矩阵;最终得到可在浏览器中运行的动画。
学习目标
- 计算
mat4x4<f32>的缓冲区大小,并正确声明 WGSL Uniform 绑定。 - 使用
GPUQueue.writeBuffer()每帧上传变换矩阵。 - 复用图形管线与 Bind Group,验证旋转效果及常见绑定错误。
矩阵布局与资源关系
WGSL 的 mat4x4<f32> 含 16 个 f32,每个 4 字节,共 64 字节,对齐要求为 16 字节。这个示例只放一份矩阵,所以 Uniform Buffer 的 size 设为 64,并启用 GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST:前者允许着色器读取,后者允许队列写入。
顶点着色器通过 @group(0) @binding(0) 找到这块缓冲区,对每个顶点计算 model * vec4(position, 0.0, 1.0)。Bind Group 持有对 GPUBuffer 的引用,而不是创建时的矩阵快照;修改缓冲区内容无需重新生成 Bind Group 或 Pipeline。

完整示例:旋转三角形
创建 index.html,将以下内容完整保存。示例使用顶点索引在 WGSL 内生成三个顶点,省去顶点缓冲区,以便只观察 Uniform 的作用。Canvas 为 480×480 像素,旋转速度设为每秒 1 弧度。
<!doctype html>
<html lang="zh-CN">
<head>
<meta charset="utf-8">
<title>WebGPU Uniform 动画</title>
</head>
<body>
<canvas id="gpuCanvas" width="480" height="480"></canvas>
<script type="module">
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 canvas = document.querySelector("#gpuCanvas");
const context = canvas.getContext("webgpu");
if (!context) throw new Error("无法获取 WebGPU 画布上下文");
const format = navigator.gpu.getPreferredCanvasFormat();
context.configure({ device, format, alphaMode: "opaque" });
const shader = device.createShaderModule({
code: `
struct Params {
model: mat4x4<f32>,
};
@group(0) @binding(0) var<uniform> params: Params;
@vertex
fn vsMain(@builtin(vertex_index) i: u32) -> @builtin(position) vec4<f32> {
let positions = array<vec2<f32>, 3>(
vec2<f32>(0.0, 0.6),
vec2<f32>(-0.6, -0.6),
vec2<f32>(0.6, -0.6)
);
return params.model * vec4<f32>(positions[i], 0.0, 1.0);
}
@fragment
fn fsMain() -> @location(0) vec4<f32> {
return vec4<f32>(0.1, 0.58, 0.63, 1.0);
}
`,
});
// 管线与绑定组只创建一次,不放进动画循环
const pipeline = device.createRenderPipeline({
layout: "auto",
vertex: { module: shader, entryPoint: "vsMain" },
fragment: { module: shader, entryPoint: "fsMain", targets: [{ format }] },
primitive: { topology: "triangle-list" },
});
const uniformBuffer = device.createBuffer({
size: 64,
usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
});
const bindGroup = device.createBindGroup({
layout: pipeline.getBindGroupLayout(0),
entries: [{ binding: 0, resource: { buffer: uniformBuffer } }],
});
const matrix = new Float32Array(16);
function frame(timeMs) {
const angle = timeMs * 0.001;
const c = Math.cos(angle);
const s = Math.sin(angle);
// WGSL 矩阵按列存储:前两列表示绕 Z 轴旋转
matrix.set([
c, s, 0, 0,
-s, c, 0, 0,
0, 0, 1, 0,
0, 0, 0, 1,
]);
device.queue.writeBuffer(uniformBuffer, 0, matrix);
const encoder = device.createCommandEncoder();
const pass = encoder.beginRenderPass({
colorAttachments: [{
view: context.getCurrentTexture().createView(),
clearValue: { r: 0.97, g: 0.98, b: 1, a: 1 },
loadOp: "clear",
storeOp: "store",
}],
});
pass.setPipeline(pipeline);
pass.setBindGroup(0, bindGroup);
pass.draw(3);
pass.end();
device.queue.submit([encoder.finish()]);
requestAnimationFrame(frame);
}
requestAnimationFrame(frame);
</script>
</body>
</html>预期结果:在支持 WebGPU 的浏览器中打开该页面,浅色背景上出现青绿色三角形并持续逆时针旋转,约 6.28 秒转一圈;整个动画期间复用同一个 pipeline、bindGroup 和 uniformBuffer。
运行、验证与排错
在 index.html 所在目录使用 Python 3 启动本地服务,避免直接打开文件时遇到安全上下文限制:
python3 -m http.server 5173预期结果:进程持续运行并监听本机 5173 端口。访问 http://localhost:5173 后看到旋转三角形;终端显示的监听地址可能因系统不同而变化。
验证更新链路时,将 const angle = timeMs * 0.001 暂改为 const angle = 0 并刷新,三角形应保持静止。恢复后又开始旋转,说明位置变化来自逐帧写入的矩阵,而不是重新创建管线。
- 画面不动:确认
writeBuffer()在frame()内,并在每帧提交绘制命令前调用;同时检查pass.setBindGroup(0, bindGroup)。 - 出现 GPU 验证错误:确认缓冲区带有
COPY_DST、容量至少 64 字节,且 WGSL 绑定编号与entries中的binding: 0相同。 - 矩阵结果不对:
Float32Array应按列主序排列;把行主序数据直接传给 WGSL,会使旋转方向或变换组合不符合预期。
这里使用固定偏移 0 的 64 字节绑定,不需要把缓冲区强行扩成 256 字节。使用 动态 Uniform 偏移 才需要额外满足设备的 minUniformBufferOffsetAlignment。