Web 图形与 3D / 系统课时

创建图形管线并声明阶段入口

创建图形管线并声明阶段入口

已有 GPU 设备和 WGSL 着色器,还不能直接在画布上绘制。需要通过图形管线指定顶点与片元阶段的入口、颜色目标格式和图元组装方式,再把管线绑定到渲染通道。本例最终会绘制一个青绿色三角形,并演示如何复用管线。

学习目标

  • 正确配置 vertex、fragment、primitive 和 layout。
  • 区分管线创建、渲染通道编码和绘制命令。
  • 排查入口名称、附件格式和图元状态不匹配的问题。

组合阶段与固定状态

device.createShaderModule() 将 WGSL 代码组织为 GPUShaderModule;device.createRenderPipeline() 再引用该模块和具体阶段入口,生成 GPURenderPipeline。同一模块可以同时包含 @vertex 和 @fragment 函数,但 entryPoint 必须准确匹配函数名。

本例采用 vertex.entryPoint: "vsMain" 和 fragment.entryPoint: "fsMain";片元着色器的 @location(0) 颜色输出对应 fragment.targets[0]。targets[0].format 必须与渲染通道所用颜色附件的纹理格式兼容。直接呈现到画布时,使用与 context.configure() 相同的 format 最稳妥。

primitive.topology: "triangle-list" 表示每三个顶点形成一个独立三角形。cullMode: "none" 禁止面剔除,避免首次练习因顶点绕序而看不到图形。没有缓冲区绑定时可先用 layout: "auto",本例的顶点坐标也不需要 vertex.buffers,因为它们由 vertex_index 在着色器内生成。

图形管线阶段入口与渲染通道的关系

完整页面创建并使用管线

将以下内容保存为 index.html。在文件所在目录运行 python3 -m http.server 8000,使用支持 WebGPU 的浏览器访问 http://localhost:8000;localhost 属于允许使用 WebGPU 的安全上下文之一。本例不依赖 Three.js,也不需要顶点缓冲区。

html
<!doctype html>
<html lang="zh-CN">
<head><meta charset="utf-8"><title>WebGPU 三角形管线</title></head>
<body>
<canvas id="gpu" width="640" height="360"></canvas>
<p id="status">正在初始化</p>
<script type="module">
async function main() {
  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 context = document.querySelector("#gpu").getContext("webgpu");
  if (!context) throw new Error("无法获取 WebGPU 画布上下文");

  const format = navigator.gpu.getPreferredCanvasFormat();
  context.configure({ device, format, alphaMode: "opaque" });
  const shader = device.createShaderModule({
    code: `
      @vertex
      fn vsMain(@builtin(vertex_index) i: u32) -> @builtin(position) vec4f {
        // 三个内置顶点索引直接对应裁剪空间坐标
        let p = array<vec2f, 3>(
          vec2f(-0.65, -0.60), vec2f(0.65, -0.60), vec2f(0.0, 0.65)
        );
        return vec4f(p[i], 0.0, 1.0);
      }
      @fragment
      fn fsMain() -> @location(0) vec4f {
        return vec4f(0.0, 0.68, 0.60, 1.0);
      }
    `
  });

  // 入口名称对应 WGSL;颜色目标格式沿用画布配置
  const pipeline = device.createRenderPipeline({
    layout: "auto",
    vertex: { module: shader, entryPoint: "vsMain" },
    fragment: { module: shader, entryPoint: "fsMain", targets: [{ format }] },
    primitive: { topology: "triangle-list", cullMode: "none" }
  });

  const encoder = device.createCommandEncoder();
  const pass = encoder.beginRenderPass({
    colorAttachments: [{
      view: context.getCurrentTexture().createView(),
      clearValue: { r: 0.98, g: 0.98, b: 0.98, a: 1 },
      loadOp: "clear",
      storeOp: "store"
    }]
  });
  pass.setPipeline(pipeline);
  pass.draw(3);
  pass.end();
  device.queue.submit([encoder.finish()]);
  document.querySelector("#status").textContent = "已提交三角形绘制";
}
main().catch((error) => {
  document.querySelector("#status").textContent = error.message;
  console.error(error);
});
</script>
</body>
</html>

预期结果:640×360 的画布呈现浅色背景和一个青绿色三角形,下方显示“已提交三角形绘制”。这是页面可见结果,而不是固定的控制台日志。若设备申请失败,页面会显示错误信息;可在开发者工具 Console 查看详情。

管线复用与逐帧资源的边界

创建管线并不会自动绘制。真正提交绘制的是 beginRenderPass()、setPipeline(pipeline)、draw(3)、end() 和 device.queue.submit()。示例只绘制一帧;在动画中应把命令编码和提交放入每帧循环,而不是反复执行 createRenderPipeline()。

管线可以跨帧复用,但每次绘制都应为当前画布纹理调用 context.getCurrentTexture().createView()。管线里的颜色目标格式、采样数需要与实际渲染通道附件兼容;本例省略 multisample,默认采样数为 1。未来添加深度测试时,还要同时提供 depthStencil 状态和渲染通道的深度附件。

根据现象定位配置错误

  • 管线创建报验证错误:核对 entryPoint 是否分别写为 vsMain、fsMain,以及 WGSL 函数是否标注 @vertex、@fragment。错误名称如 vertexMain 不会自动匹配。
  • 绘制阶段出现附件不兼容错误:检查 fragment.targets[0].format 和画布配置所用格式;不要把 bgra8unorm 写死后又在其他设备上使用不同的画布格式。
  • 只看到清屏颜色:先检查 draw(3) 和 triangle-list;如果改用了 cullMode: "back",还需检查三个顶点的绕序。首次排障可恢复为 none。
  • 每帧卡顿或创建失败:确认没有在动画循环中重复创建相同管线。只有着色器代码或影响管线兼容性的固定状态变化时,才创建对应的新管线。

只需保留一个成功创建的 GPURenderPipeline,就能在后续帧反复绑定它;具体绘制哪些顶点、把结果写到哪张当前纹理,仍由每次渲染通道的命令决定。

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

目录与阅读设置

阅读设置

17

记录一个想法

创建图形管线并声明阶段入口

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

登录哪都通