Web 图形与 3D / 系统课时

配置 WebGPU 画布上下文

配置 WebGPU 画布上下文

获得 GPU 设备后,还需要把它连接到网页画布,才能显示渲染结果。本课将获取 GPUCanvasContext、选择首选纹理格式、配置画布尺寸与透明度,并通过一次清屏渲染验证配置是否成功。完成后,你会得到一个能够接收 WebGPU 绘制命令的画布。

学习目标

  • 获取 webgpu 画布上下文,理解它与 GPU 设备、呈现纹理的关系。
  • 使用 getPreferredCanvasFormat() 和 configure() 设置纹理格式、设备与透明度模式。
  • 运行完整的清屏示例,并检查画布尺寸、显示效果和常见配置错误。

理解画布上下文与呈现纹理

HTML 的 <canvas> 只是页面中的显示区域。WebGPU 不会自动把 GPU 的渲染结果送到这个区域,必须先获取 GPUCanvasContext,再指定用于渲染的 GPUDevice 和呈现纹理格式。

这几个对象承担不同职责:

  • HTMLCanvasElement:决定画布在页面中的位置,以及绘图缓冲区的宽度和高度。
  • GPUCanvasContext:管理与画布关联的呈现纹理,提供 configure() 和 getCurrentTexture()。
  • GPUDevice:创建渲染资源、编码命令并通过队列提交 GPU 工作。
  • GPUTexture:当前帧的呈现目标,通过 createView() 获得可用于颜色附件的纹理视图。

WebGPU 画布上下文、GPU 设备与呈现纹理的数据流

配置与绘制是两个独立阶段。调用 configure() 只是建立画布的呈现配置,不等于已经绘制内容。真正更新画面,需要获取当前纹理、创建渲染通道并提交命令。

这里还有一个重要区别:getCurrentTexture() 返回的是当前帧的呈现纹理,不应该将它长期保存并在后续帧反复使用。每次绘制都应重新获取当前纹理。

配置纹理格式与透明度

调用 canvas.getContext('webgpu') 可以获得 WebGPU 画布上下文。该方法可能返回 null,因此必须先检查结果,再调用 configure()。

最小配置需要指定两个字段:device 和 format。普通网页还建议明确指定 alphaMode,避免透明合成效果不符合预期。

配置项 推荐取值 实际作用
device 已申请的 GPUDevice 指定用于渲染的设备
format navigator.gpu.getPreferredCanvasFormat() 选择适合当前平台的呈现纹理格式
alphaMode 'opaque' 显示时忽略 Alpha,适用于普通不透明画布
usage 省略,使用默认值 默认包含 GPUTextureUsage.RENDER_ATTACHMENT

getPreferredCanvasFormat() 通常返回 bgra8unorm 或 rgba8unorm。两者主要区别是颜色通道在纹理中的排列,不能根据操作系统名称随意猜测。使用浏览器返回的首选格式,通常可以减少额外的格式转换开销。

透明度模式有两个常用选择:

  • opaque:呈现时将画布视为不透明,即使输出颜色的 Alpha 小于 1,也不会让底下的网页背景透出来。
  • premultiplied:允许按预乘 Alpha 方式与页面内容合成。例如半透明红色可以使用 [0.5, 0, 0, 0.5] 表示,其 RGB 分量已经乘过 Alpha。

普通游戏画面、独立图形视口建议先使用 opaque。如果要把 WebGPU 特效透明叠加在网页元素上方,才需要考虑 premultiplied,并正确处理颜色和 Alpha。

运行完整的画布配置示例

下面使用原生 HTML 和 JavaScript,不依赖 Three.js 或其他图形库。示例会申请 GPU 设备,配置画布并清除成青绿色,以确认呈现链路已经连通。

准备一款支持 WebGPU 的现代浏览器,以及 Python 3。新建目录,将下面的完整内容保存为 index.html。随后在该目录运行 python3 -m http.server 8000,通过浏览器访问 http://localhost:8000/。部分 Windows 环境需要将命令中的 python3 改为 python。

预期结果:本地 HTTP 服务在端口 8000 提供页面。localhost 被浏览器视为可信的本地来源;正式部署则应使用 HTTPS。不要直接依赖 file:// 路径运行本示例。

html
<!doctype html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>WebGPU 画布配置</title>
  <style>
    body { font: 16px/1.5 system-ui; padding: 20px; }
    canvas { display: block; width: min(100%, 640px); height: auto; }
  </style>
</head>
<body>
  <canvas id="gpuCanvas" width="640" height="360"></canvas>
  <p id="status">正在初始化 WebGPU...</p>

  <script type="module">
    async function main() {
      if (!window.isSecureContext || !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('#gpuCanvas');
      const context = canvas.getContext('webgpu');
      if (!context) throw new Error('无法获取 WebGPU 画布上下文');

      // 将 CSS 显示尺寸转换为绘图缓冲区尺寸,并限制像素倍率
      const rect = canvas.getBoundingClientRect();
      const dpr = Math.min(window.devicePixelRatio || 1, 2);
      const limit = device.limits.maxTextureDimension2D;
      canvas.width = Math.max(1, Math.min(limit, Math.round(rect.width * dpr)));
      canvas.height = Math.max(1, Math.min(limit, Math.round(rect.height * dpr)));

      const format = navigator.gpu.getPreferredCanvasFormat();
      context.configure({
        device,
        format,
        alphaMode: 'opaque'
      });

      // 当前纹理的视图作为本帧渲染通道的颜色附件
      const view = context.getCurrentTexture().createView();
      const encoder = device.createCommandEncoder();
      const pass = encoder.beginRenderPass({
        colorAttachments: [{
          view,
          clearValue: { r: 0.06, g: 0.40, b: 0.48, a: 1 },
          loadOp: 'clear',
          storeOp: 'store'
        }]
      });

      pass.end();
      // 命令编码完成后提交给 GPU 默认队列
      device.queue.submit([encoder.finish()]);
      document.querySelector('#status').textContent =
        `清屏命令已提交;格式:${format}`;
    }

    main().catch(error => {
      console.error(error);
      document.querySelector('#status').textContent =
        `初始化失败:${error.message}`;
    });
  </script>
</body>
</html>

预期结果:浏览器页面出现一块青绿色画布,而不是原始的透明或空白区域。画布下方显示类似状态:

text
清屏命令已提交;格式:bgra8unorm

上面的格式只是示例。实际也可能是 rgba8unorm,应以浏览器返回值为准。

这段代码没有创建顶点数据或调用 draw()。颜色来自渲染通道的 clearValue,因为 loadOp: 'clear' 会在通道开始时清除颜色附件,storeOp: 'store' 则保留结果供画布呈现。

如果画布确实变成青绿色,就证明设备申请、画布配置、当前纹理获取和命令提交这几个环节已经连通。仅看到状态文字还不够,因为它表示命令已经提交,不保证 GPU 后续执行一定没有错误。

检查画布尺寸与呈现边界

Canvas 存在两套不同的尺寸:CSS 显示尺寸和绘图缓冲区尺寸。前者决定页面布局,后者决定实际渲染像素数量。

例如画布显示宽度为 640 CSS 像素、高度为 360 CSS 像素,设备像素比为 2,那么使用完整设备像素比时,绘图缓冲区应设置为 1280 × 720。

这时缓冲区包含 921600 个像素,而不是 230400 个像素,像素数量变为原来的四倍。分辨率更高通常更清晰,但也会增加渲染和内存带宽成本。

示例使用 Math.min(devicePixelRatio, 2) 将有效像素倍率限制到最多 2,并使用 device.limits.maxTextureDimension2D 限制每个维度的最大尺寸。对于本示例的 640×360 CSS 画布,通常不会碰到设备尺寸上限。

检查尺寸时,可以在浏览器开发者工具的 Console 中查看 document.querySelector('#gpuCanvas').width 和 .height。在显示尺寸为 640×360、有效 DPR 为 2 的情况下,预期分别得到 1280 和 720。

还可以做一次透明度验证:将配置中的 alphaMode 改为 'premultiplied',同时将清屏颜色改为 { r: 0, g: 0, b: 0, a: 0 },刷新后画布应呈透明状态,能看到页面背景。恢复 'opaque' 后,即使使用透明清屏颜色,最终显示也应是不透明的。

定位配置失败与黑屏

如果运行后没有出现青绿色画布,按照实际报错定位,不要同时修改设备选择、纹理格式和着色器设置。

现象 常见原因 修复方式
navigator.gpu 不存在 浏览器不支持,或当前页面不满足安全上下文要求 换支持 WebGPU 的浏览器,使用 HTTPS 或 localhost
requestAdapter() 返回 null 当前环境没有可用的 WebGPU 适配器 检查 GPU 驱动、浏览器图形加速和平台支持情况
getContext('webgpu') 返回 null 该画布无法创建 WebGPU 上下文,例如此前已获取其他不兼容的上下文类型 新建 Canvas,不要在同一画布混用 2d、webgl2 与 webgpu
出现纹理尺寸或验证错误 缓冲区尺寸为零、超过设备限制,或后续颜色附件格式不匹配 检查 width、height、设备限制和实际纹理格式
状态显示已提交,但画面仍空白 命令提交后出现 GPU 验证错误,或画布被 CSS 隐藏、覆盖 打开 Console 检查错误,同时检查画布实际尺寸和可见性

调试时可以通过 context.getConfiguration() 检查当前配置。该方法在尚未配置时返回 null;配置成功后可以读取实际的 format、alphaMode 和关联设备等信息。

当需要更换 GPU 设备时,应使用新设备重新调用 configure()。设备丢失后不能继续假定旧设备和相关资源有效,需要处理设备丢失并重新建立所需资源。

可参考 MDN:GPUCanvasContext.configure() 核对参数定义,以及 WebGPU Samples:Resize Canvas 查看持续调整画布大小的实现。

完成验证后,保留示例中的 device、context 和 format。后续创建图形渲染管线时,将使用这个 format 配置片元输出目标,并在渲染通道中绑定当前呈现纹理视图,让实际绘制的几何图形显示到画布上。

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

目录与阅读设置

阅读设置

17

记录一个想法

配置 WebGPU 画布上下文

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

登录哪都通