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。

每帧更新 Uniform 矩阵并复用绘制管线的数据流

完整示例:旋转三角形

创建 index.html,将以下内容完整保存。示例使用顶点索引在 WGSL 内生成三个顶点,省去顶点缓冲区,以便只观察 Uniform 的作用。Canvas 为 480×480 像素,旋转速度设为每秒 1 弧度。

html
<!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 启动本地服务,避免直接打开文件时遇到安全上下文限制:

bash
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。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

用 Uniform 更新每帧变换参数

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通