WebGPU 开发入门：从设备初始化到渲染一帧

一、序言：

我多次尝试入门 WebGL / WebGPU。结果都是“学而不入”，白白浪费时间。说起来，直到改用 AI 学习——有问必答，还能逐行解释——反而更快了。

卡住我的痛点：

1. API 太多、太抽象。 误区在于以为需要记住成百上千的调用，其实 WebGPU 的 API 是从 Vulkan、Metal、DirectX 抽象出的公共最小集主要调用只需几条。真正难的是缺乏显卡渲染概念——概念一通，API 全部串起来了。怎么说呢，
2. 需要大量三维数学。老实说， 这也是夸张的说法。入门只需了解二维/三维矩阵和颜色两块基础；其余可以交给 AI，

这篇文章假设一个最简单的游戏画面来演示 WebGPU 的用法：人物站在草地上。手里的武器轻轻摆动，剑身外环绕着流动的法术光环，头顶无数粒子往天上飞。人物不做运动是为了把逻辑减到最少，同时又能看到显卡渲染的完整流程。

全程需牢记的三个概念：

1. 显卡渲染的一切都从三维建模开始。 任何渲染都是先建立顶点，再着色。法术光环就是先做一个圆环薄网格，再在片元着色器里实现特效。
2. 分清 CPU 与 GPU 各自运行什么。 哪些 buffer / 资源写进显存,哪些数据与命令留在普通内存. 这将在第二章到第三章主要说明。
3. 每帧只更新 uniform 等小资源，接下来重新创建命令清单。 顶点数据一次写入显存后不再动；话说回来，每帧变动只有矩阵、时间等小数据。

下面按“初始化 → 建数据 → 绑参数 → 建管线 → 渲染一帧”的顺序，用 raw/ 源码走一遍。

二、初始化设备

至于三层对象，GPU → Adapter → Device

if {
// 浏览器不支持
return;}
const adapter = await navigator.gpu.requestAdapter;const device = await adapter.requestDevice;const context = canvas.getContext;话说回来，const format = navigator.gpu.getPreferredCanvasFormat;按理说，context.configure({
device。format,alphaMode: "opaque"
});

• : 浏览器暴露 WebGPU 的入口，不存在说明浏览器不支持。
• : 对应一块物理 GPU，回答“这块显卡支持什么”。
• : 逻辑设备,所有 ///是默认提交队列。
• : 画布上下文。
• : 画布颜色纹理的像素格式，常见 "bgra8unorm" 或 "rgba8unorm"。

 让浏览器创建一条与画布尺寸匹配的交换链,即向底层图形 API申请同尺寸的颜色纹理放在显存里。 时 OS 合成器读取这张纹理显示到屏幕。

监听画面 resize

function resize {
const dpr = Math.min;const w = Math.floor;const h = Math.floor;老实说，canvas.width = w;canvas.height = h;context.configure;return { w,h };}
function recreateDepth {
if depthTexture.destroy;depthTexture = device.createTexture({
说到size，format: DEPTH_FORMAT。// "depth24plus"
usage的观点是，GPUTextureUsage.RENDER_ATTACHMENT,});depthView = depthTexture.createView;}

• : CSS 尺寸。
• : 实际物理像素，需要乘以 dpr.
• #resize 步骤：
  1. 按 devicePixelRatio 调整 canvas 实际尺寸；

If you ignore resize handling:

• The rendered image will be stretched or only fill old region.
• Mismatched depth attachment sizes cause WebGPU validation errors.

The depth texture records “每个像素当前最近的表面离相机多远”，用于遮挡。它是显存里的纹理，使用  得到的  供渲染管线使用——后续章节会细讲。

三、创建 Buffer：把模型和材质送进显存

The scene’s grass,character。weapon and aura are generated by  as CPU‑side arrays . To render m we first copy m into GPU memory:

const vertexBuffer = device.createBuffer({
从size来看，mesh.vertices.byteLength,usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST,});device.queue.writeBuffer;const indexBuffer = device.createBuffer({
size的观点是，mesh.indices.byteLength。usage: GPUBufferUsage.INDEX | GPUBufferUsage.COPY_DST,});device.queue.writeBuffer;

Main.js calls this four times to upload four meshes .

顶点的存储方式与 shaderLocation 的作用

A vertex buffer is just a byte stream;GPU does not know which bytes represent position vs normal vs UV. Two pieces of information are needed:

• The layout in memory .
• The mapping from bytes to shader inputs .

交错存储的观点是，一个顶点 20 字节

// 每个顶点占用字节数
// 偏移:
// pos.x pos.y pos.z nor.x nor.y nor.z uv.x uv.y
// |------12B------|------12B------|---8B---|

Each vertex refore occupies 20 bytes . The interleaved layout is cache‑friendly for GPU.

VERTEX_LAYOUT：告诉 GPU 怎么切字节

js export const VERTEX_STRIDE = 5 * Float32Array.BYTES_PER_ELEMENT;// 20 export const VERTEX_LAYOUT = { arrayStride: VERTEX_STRIDE。attributes:,};

• `arrayStride`: byte distance 娱乐ween consecutive vertices.
• `attributes`: for each attribute we specify its byte offset inside a vertex and its WGSL type . Offsets + stride guarantee perfect alignment.

shaderLocation：JS 缓冲 ↔ WGSL 入参的“插头”

wgsl @vertex fn vs_main( @location position : vec3f。@location normal : vec3f,@location uv : vec2f,) -> VSOut {…说起来，}

The numbers after @location must match shaderLocation values in VERTEX_LAYOUT. If y don’t line up pipeline creation will fail—this is where many beginners hit a wall.

createBuffer 的两个关键属性

• `size`: byte length of buffer .
• `usage`: a bitmask describing how buffer will be used. Common flags:

  枚举	用途		本 demo 使用情况
  `GPUBufferUsage.VERTEX`	顶点缓冲
  `GPUBufferUsage.INDEX`	索引缓冲
  `GPUBufferUsage.UNIFORM`	uniform 常量				`GPUBufferUsage.STORAGE`	storage 缓冲			`GPUBufferUsage.COPY_DST`	允许 writeBuffer/copy 写入			`GPUBufferUsage.COPY_SRC`	允许拷出			`GPUBufferUsage.MAP_READ|WRITE`	CPU 映射读写		writeBuffer：真实写入显存 js device.queue.writeBuffer;The call copies a `Float32Array` from ordinary memory into a GPU‑visible buffer that carries `COPY_DST` flag. The copy is queued on `device.queue`;because rendering commands share same queue y will see updated contents when executed. uniform buffer：为什么每个物体一个？js const UNIFORM_SIZE = 256;// 示例大小，留有对齐余量 const groundUB = createUniformBuffer;怎么说呢，const charUB = createUniformBuffer;const weaponUB = createUniformBuffer;Uniforms hold per‑frame constants such as view‑proj matrix、model matrix、时间或颜色。每个物体都有独立的 model 矩阵。 所以 **每个物体一个 uniform buffer** 更直观，也避免了多对象间的数据竞争。 ：createTexture 与 writeTexture js // 创建纹理 const tex = device.createTexture({ size的观点是。format:"rgba8unorm",usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST,});// 上传像素数据 device.queue.writeTexture( { texture: tex }。pixels,{ bytesPerRow:w*4 },);其实，Common texture usage flags: # 使用标志 含义 # 示例场景 `TEXTURE_BINDING` 供 shader采样 `RENDER_ATTACHMENT` 作为颜色/深度附件被渲染 `STORAGE_BINDING` compute read/write `COPY_DST` 允许写入 `COPY_SRC` 允许拷出 `RENDER_ATTACHMENT` 深度缓冲专用 四、创建 BindGroup：把资源“插”给 shader BindGroupLayout 与 BindGroup *BindGroupLayout*：声明“第 n 组、第 m 槽”上的资源类型。 *BindGroup*：将具体的 GPUBuffers / GPUSamplers / GPUTextures 塞进这些槽位。 Shader 中使用 @group @binding 声明要取哪个组哪槽的数据；对应的 BindGroupLayout 就是该声明的类型化描述，而 BindGroup 则是填充实际对象。 至于layout。"auto" 与 getBindGroupLayout js // pipelines/opaque.js – 创建管线时使用自动布局： const opaquePipeline = device.createRenderPipeline({ 再看layout，"auto",vertex:{…},fragment:{…},primitive:{…},depthStencil:{…},})， // main.js – 创建对应 BindGroup： const groundBG = device.createBindGroup({ 至于layout。opaquePipeline.getBindGroupLayout,entries:,}); Setting layout:"auto" lets browser infer required bind groups directly from WGSL source. Later you retrieve that inferred layout via pipeline.getBindGroupLayout and use it when constructing concrete BindGroups. This guarantees shader ↔ bind group 自动对齐—any type mismatch throws an error at creation time instead of producing visual glitches later. entries：一个组里可以有多个槽 js entries: 多个组则通过不同的 编号区分。本 demo 为简化，每个组仅包含一个 uniform binding，但机制完全相同。说起来， 为什么每个物体一个 BindGroup？ 因为每帧每个物体都有独立的 uniform 内容。为每个对象创建自己的 uniform buffer + BindGroup即可在渲染时切换绑定，从而让 shader “看到”对应对象的数据。BindGroup 本身非常轻量，仅保存对已上传显存资源的引用。 createRenderPipeline 各属性 js const module = device.createShaderModule; const opaquePipeline = device.createRenderPipeline({ layout的观点是，"auto",// 自动生成 BindGroupLayout vertex:{ module,entryPoint:"vsmain",buffers:,// 顶点布局 },fragment:{ module。entryPoint:"fs_main",targets:,// 输出颜色格式 },primitive:{ topology:"triangle-list",// 三角形列表 cullMode:"back",// 背面剔除 },depthStencil:{ 再看format，"depth24plus",depthWriteEnabled:true,depthCompare:"less",}}); 再看属性说明， *vertex*: 指定顶点着色器入口还有如何解析顶点缓冲 . *fragment*: 指定片元着色器入口还有输出目标颜色格式 . *primitive*: 控制几何装配方式与背面剔除策略。法术光环使用 `cullMode:"none"` 因为需要双面可见。 *depthStencil*: 深度缓冲格式与比较规则 . *layout*: 将前面的 BindGroupLayout 接入管线，使得绑定时能够匹配。 Shader 模块仅负责编译 WGSL；其实，同一模块可同时包含 VS 和 FS。通过不同 entryPoints 指定。不过， VERTEX_LAYOUT 映射 js export const VERTEX_LAYOUT={ arrayStride:20。attributes: }; WGSL 必须严格按照此顺序声明输入： Thus arrayStride tells how many bytes each vertex occupies;offset tells where each attribute lives inside that stride;shaderLocation links directly to WGSL’s @location. 一张表看清三层对应关系 数据类型 CPU/API侧 WGSL侧 顶点属性 VERTEX_LAYOUT.attributes.shaderLocation @location 在 VS 入参 每帧常量 BindGroup.entries → Buffer @group @binding var u : Uniforms VS 输出→FS VSOut结构体中的 @builtin、@location fragment.targets 对应 RenderPass 色彩附件 深度附件 depthStencil.format ↔ depthView 自动产生 @builtin.z 用于深度比较 保持这些对应关系一致，是防止花屏或验证错误的关键。 每帧只更新 uniform，不重传顶点 js function frame{ computeMatrices;// 更新 viewProj & model 矩阵 fillOpaqueUniform;// writeBuffers → uniform buffers fillCharUniform;fillWeaponUniform; renderFrame;// 创建并提交命令清单 } requestAnimationFrame; 顶点和索引缓冲自首次上传后保持不变。仅有矩阵和时间等小数据会每帧更新——正是序言中强调的概念：“每帧更新 uniform，接下来创建命令清单”。 命令清单只是“记菜单” js const encoder = device.createCommandEncoder; /* Compute Pass – 粒子模拟 */ const computePass = encoder.beginComputePass;computePass.setPipeline;computePass.setBindGroup;computePass.dispatchWorkgroups);computePass.end; /* Render Pass – 绘制 */ const colorView = context.getCurrentTexture.createView;const renderPass = encoder.beginRenderPass({ colorAttachments:,depthStencilAttachment:{ view : depthView。depthClearValue :1.0,depthLoadOp :"clear",depthStoreOp :"store" } }); /* Opaque batch */ renderPass.setPipeline;老实说，renderPass.setBindGroup;其实，renderPass.setVertexBuffer;不过，renderPass.setIndexBuffer;renderPass.drawIndexed; /* …同理绘制角色和武器 ，*/ /* Aura batch / renderPass.setPipeline;/ ，bind groups & draws …*/ /* Particles batch */ renderPass.setPipeline;renderPass.draw; renderPass.end; device.queue.submit]); All calls merely write commands into ordinary memory. No pixel is processed yet—recording is extremely fast. 从类比来看， ⚙️ createCommandEncoder → 打开一本空白菜单 🖊️ setBindGroup/drawIndexed → 在菜单上写“来一份草地、一份角色” 🚚 submit → 把整张单子交给厨房烹饪。建议记住这个比喻，以免误以为绘制已经发生。 After ,command list becomes a immutable which is handed to . JavaScript returns immediately without waiting for GPU completion. GPU 执行细节 – 批次 & 流水线并行 A batch is defined by one continuous block 娱乐ween two calls. Demo 中共有 three batches: Batch # Pipeline 包含 draw 1 opaque Pipeline 2 aura Pipeline 3 particles Pipeline Within a batch: The vertex shader runs **in parallel** on thousands of vertices. The rasterizer converts triangles to fragments. The fragment shader runs **in parallel** on all fragments. The output merger performs depth test & blending before writing to attachments. Different draws can overlap in hardware pipelines but must respect batch boundaries because switching pipelines changes shaders & fixed‑function state which requires completing all previous work first. This explains *** transparent objects are drawn after opaque objects—blending needs already written background colors. format 链：从画布到管线必须一致 js const format = navigator.gpu.getPreferredCanvasFormat;context.configure; // 在 pipeline 中 fragment:{ targets: // 必须和 swapchain 格式匹配 } Three places must agree on same pixel format: context.configure: swapchain texture format. pipeline.fragment.targets.format: fragment 输出目标格式. beginRenderPass: 实际写入哪张颜色纹理. \end{ol> If any step mismatches validation fails instantly. 两个附件的观点是，colorView 与 depthView js const colorView = context.getCurrentTexture.createView; colorView: 来自交换链当前帧的颜色纹理，所有且混合后的片元最终写这里接下来由浏览器呈现到屏幕。 ...