Web 图形与 3D / 系统课时
用 WGSL 类型组织阶段接口
用 WGSL 类型组织阶段接口
顶点着色器需要同时输出位置和颜色,片元着色器才能在三角形内部生成渐变。接口中的字段类型、@location 或 @builtin 标错,常会导致渲染管线验证失败。下面用一张接口关系图和一个可运行页面,把 vec、mat、struct 的职责与数据传递对应起来。
学习目标
- 区分
vec、mat、struct在 WGSL 中的用途,并正确构造坐标与颜色。 - 使用
@builtin(position)、@builtin(vertex_index)和@location定义阶段接口。 - 运行渐变三角形,验证顶点输出与片元输入的类型和位置是否匹配。
用类型表达数据含义
vec2f 是 vec2<f32> 的简写,适合二维位置;vec3f 对应 RGB 颜色;vec4f 则可以放齐次裁剪坐标 (x, y, z, w) 或带透明度的 RGBA。顶点位置最终必须写成 @builtin(position) 的 vec4f,只有二维坐标时可补上 z = 0、w = 1。
矩阵 mat4x4f 有四列,每列是一个 vec4f。例如对角线为 0.85、0.85、1、1 的矩阵乘上位置向量,会把三角形在 x、y 方向分别缩放到原来的 85%,不改变颜色。WGSL 用 matrix * vector 的顺序进行这一运算。
struct 把相关字段组织成一个类型,但字段名本身不负责连接着色器阶段。例如 VertexOut 可以同时保存 position: vec4f 与 color: vec3f;前者通过内建语义交给光栅化器,后者通过用户自定义位置编号传给片元阶段。这里的结构体是阶段接口,不涉及 uniform/storage 缓冲区的内存对齐规则。
对齐顶点输出和片元输入
调用 draw(3) 时,@builtin(vertex_index) 给顶点入口依次提供 0、1、2(非索引绘制且首顶点为 0)。顶点着色器据此选择三组坐标和颜色。@builtin(position) 接收变换后的裁剪空间位置,光栅化器据此确定三角形覆盖的像素。
对于颜色,顶点输出的 @location(0) color: vec3f 与片元输入的 @location(0) tint: vec3f 相连;字段名可以不同,但对应位置、数值类型及插值约定必须兼容。浮点颜色默认进行透视正确插值。本例三个顶点的 w 都为 1,因此三角形内部会形成平滑的 RGB 过渡。

片元函数的返回值也标注 @location(0),但这里指的是颜色附件 0,不等于上面的跨阶段颜色位置。它们属于不同接口命名空间;即使编号都写 0,也不能理解为同一个存储槽。
运行完整的 WGSL 三角形
将下面内容保存为 index.html。页面在 WGSL 字符串里声明两个输入输出结构体,用矩阵缩放顶点位置,再将三种顶点颜色送入片元阶段。不需要额外的顶点缓冲区或 Bind Group,便于单独检查阶段接口。
<!doctype html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>WGSL 阶段接口</title>
</head>
<body>
<canvas id="canvas" width="640" height="360"></canvas>
<p id="status">正在初始化 WebGPU…</p>
<script type="module">
const status = document.querySelector("#status");
async function main() {
if (!navigator.gpu) throw new Error("当前环境不支持 WebGPU");
const adapter = await navigator.gpu.requestAdapter();
if (!adapter) throw new Error("未获取 GPUAdapter");
const device = await adapter.requestDevice();
const canvas = document.querySelector("#canvas");
const context = canvas.getContext("webgpu");
if (!context) throw new Error("无法获取 WebGPU 画布上下文");
const format = navigator.gpu.getPreferredCanvasFormat();
context.configure({ device, format, alphaMode: "opaque" });
const module = device.createShaderModule({ code: `
struct VertexOut {
@builtin(position) position: vec4f,
@location(0) color: vec3f,
};
struct FragmentIn {
@location(0) tint: vec3f,
};
@vertex
fn vsMain(@builtin(vertex_index) vertexIndex: u32) -> VertexOut {
// 三个索引直接取数据,避免顶点缓冲区干扰接口验证。
let positions = array<vec2f, 3>(
vec2f(-0.75, -0.60),
vec2f( 0.75, -0.60),
vec2f( 0.00, 0.75)
);
let colors = array<vec3f, 3>(
vec3f(1.0, 0.1, 0.1),
vec3f(0.1, 1.0, 0.1),
vec3f(0.1, 0.2, 1.0)
);
// WGSL 矩阵以列构造,x、y 缩放为 85%。
let model = mat4x4f(
vec4f(0.85, 0.0, 0.0, 0.0),
vec4f(0.0, 0.85, 0.0, 0.0),
vec4f(0.0, 0.0, 1.0, 0.0),
vec4f(0.0, 0.0, 0.0, 1.0)
);
var out: VertexOut;
out.position = model * vec4f(positions[vertexIndex], 0.0, 1.0);
out.color = colors[vertexIndex];
return out;
}
@fragment
fn fsMain(input: FragmentIn) -> @location(0) vec4f {
// 片元输入由 location 匹配,tint 不必与 color 同名。
return vec4f(input.tint, 1.0);
}
` });
const pipeline = await device.createRenderPipelineAsync({
layout: "auto",
vertex: { module, entryPoint: "vsMain" },
fragment: { module, entryPoint: "fsMain", targets: [{ format }] },
primitive: { topology: "triangle-list" }
});
const encoder = device.createCommandEncoder();
const pass = encoder.beginRenderPass({
colorAttachments: [{
view: context.getCurrentTexture().createView(),
clearValue: { r: 1, g: 1, b: 1, a: 1 },
loadOp: "clear",
storeOp: "store"
}]
});
pass.setPipeline(pipeline);
pass.draw(3);
pass.end();
device.queue.submit([encoder.finish()]);
status.textContent = "已提交:三顶点渐变三角形";
}
main().catch(error => {
console.error(error);
status.textContent = `错误:${error.message}`;
});
</script>
</body>
</html>预期结果:在支持 WebGPU 的浏览器中,白色画布中央出现一个缩小到 85% 的三角形,三个角分别偏红、绿、蓝,内部颜色平滑过渡;画布下方显示“已提交:三顶点渐变三角形”。实际绘制由 GPU 异步执行,提示文字表示命令已提交。
验证接口匹配与常见失败
准备 Python 3,在 index.html 所在目录启动本地服务;localhost 属于允许使用 WebGPU 的安全上下文。不要依赖直接双击文件的 file:// 运行方式。
python3 -m http.server 8000预期结果:终端显示 HTTP 服务正在监听 8000 端口(具体监听地址可能不同)。浏览器打开 http://localhost:8000,应该看到上述三角形。若出现“当前环境不支持 WebGPU”,先检查浏览器 WebGPU 支持情况与安全上下文,再查看开发者工具 Console。
可以只改一处接口来验证管线检查是否有效:
- 将
FragmentIn.tint的@location(0)改为@location(1)。顶点阶段没有对应的@location(1)输出,创建管线应失败;恢复 0 即可。 - 将
FragmentIn.tint的类型从vec3f改为vec4f。编号虽然相同,但跨阶段类型不一致,也应触发管线验证错误。 - 如果画布只显示背景,核查
vsMain、fsMain是否与管线的entryPoint完全一致,并检查 Console 里的 WGSL 编译或 GPU 验证错误。
把颜色字段从 color 改名为 tint 而保持 @location(0) 和 vec3f 不变,仍应能正确绘制;这个小实验能直接证明跨阶段连接依赖的是接口位置和类型,而非结构体成员名。