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()获得可用于颜色附件的纹理视图。

配置与绘制是两个独立阶段。调用 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:// 路径运行本示例。
<!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>预期结果:浏览器页面出现一块青绿色画布,而不是原始的透明或空白区域。画布下方显示类似状态:
清屏命令已提交;格式: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 配置片元输出目标,并在渲染通道中绑定当前呈现纹理视图,让实际绘制的几何图形显示到画布上。