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 过渡。

WGSL 顶点输出、光栅化插值与片元输入的字段映射

片元函数的返回值也标注 @location(0),但这里指的是颜色附件 0,不等于上面的跨阶段颜色位置。它们属于不同接口命名空间;即使编号都写 0,也不能理解为同一个存储槽。

运行完整的 WGSL 三角形

将下面内容保存为 index.html。页面在 WGSL 字符串里声明两个输入输出结构体,用矩阵缩放顶点位置,再将三种顶点颜色送入片元阶段。不需要额外的顶点缓冲区或 Bind Group,便于单独检查阶段接口。

html
<!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:// 运行方式。

bash
python3 -m http.server 8000

预期结果:终端显示 HTTP 服务正在监听 8000 端口(具体监听地址可能不同)。浏览器打开 http://localhost:8000,应该看到上述三角形。若出现“当前环境不支持 WebGPU”,先检查浏览器 WebGPU 支持情况与安全上下文,再查看开发者工具 Console。

可以只改一处接口来验证管线检查是否有效:

  1. 将 FragmentIn.tint 的 @location(0) 改为 @location(1)。顶点阶段没有对应的 @location(1) 输出,创建管线应失败;恢复 0 即可。
  2. 将 FragmentIn.tint 的类型从 vec3f 改为 vec4f。编号虽然相同,但跨阶段类型不一致,也应触发管线验证错误。
  3. 如果画布只显示背景,核查 vsMain、fsMain 是否与管线的 entryPoint 完全一致,并检查 Console 里的 WGSL 编译或 GPU 验证错误。

把颜色字段从 color 改名为 tint 而保持 @location(0) 和 vec3f 不变,仍应能正确绘制;这个小实验能直接证明跨阶段连接依赖的是接口位置和类型,而非结构体成员名。

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

目录与阅读设置

阅读设置

17

记录一个想法

用 WGSL 类型组织阶段接口

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

登录哪都通