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,也不需要顶点缓冲区。
<!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,就能在后续帧反复绑定它;具体绘制哪些顶点、把结果写到哪张当前纹理,仍由每次渲染通道的命令决定。