WebGPU中的调试与查询

本文讨论的几项特性都不是渲染流程中不可或缺的一环，但它们能显著提升开发效率、渲染性能和调试体验：调试组和错误作用域帮助定位问题，视口/剪刀矩形和遮挡查询则有助于优化渲染性能。这些接口目前在 WebGPU 规范中大多标注为Limited availability（尚未成为 Baseline 特性），使用前应留意浏览器兼容性。

调试组

很多创建 WebGPU 对象的方法都接受一个可选的label属性，出错时浏览器会在错误信息中显示这个标签，帮助定位是哪个对象出了问题。

除了给单个对象打标签，应用还可以在指令流中插入调试信息。这一能力由GPUDebugCommandsMixin定义，GPUCommandEncoder、GPURenderPassEncoder、GPUComputePassEncoder、GPURenderBundleEncoder都实现了这组方法，因此下面介绍的三个方法在渲染通道编码器、计算通道编码器和渲染包编码器中同样可用：

• pushDebugGroup(groupLabel)：开始一个使用指定标签命名的调试组，此后所有编码的指令都会归入这个组，直到对应的popDebugGroup()被调用为止
• popDebugGroup()：结束最近一次通过pushDebugGroup()开始的调试组
• insertDebugMarker(markerLabel)：在指令序列的某个位置插入一个标记

调试组信息主要用于遥测（telemetry），也可能被浏览器开发者工具、GPUError消息等用来辅助调试，目前不会影响渲染结果本身。

调试组以栈的形式管理，因此可以形成层级结构（组中嵌套组）。以渲染通道为例：

// 创建指令编码器constencoder=device.createCommandEncoder();// 开始一个调试组encoder.pushDebugGroup("绘制三角形");// 创建渲染通道编码器并定义渲染constpassEncoder=commandEncoder.beginRenderPass(renderPassDescriptor);passEncoder.setPipeline(renderPipeline);passEncoder.setVertexBuffer(0,vertexBuffer);passEncoder.draw(3);passEncoder.end();// 结束调试组encoder.popDebugGroup();// 向GPU提交编码的指令device.queue.submit([encoder.finish()]);

insertDebugMarker比调试组更轻量，用于标记一系列指令中的某个具体点，但它不能像调试组那样嵌套：

commandEncoder.insertDebugMarker("准备渲染三角形");

校验规则：调用popDebugGroup()时，编码器的调试栈不能为空（即之前必须有对应的pushDebugGroup()调用），否则会产生一个GPUValidationError，并且当前编码器（GPUCommandEncoder、GPURenderPassEncoder等）会立即失效。

错误处理

WebGPU 大部分方法都是"即发即弃"的：调用出错不会像 JavaScript 异常那样立刻抛出，而是异步地产生一个GPUError。为了能够精确捕获某一段代码可能产生的错误，WebGPU 提供了错误作用域（error scope）机制，使用步骤有三：

1. 调用device.pushErrorScope(filter)，将一个错误作用域压入栈中
2. 执行一个或多个可能产生错误的操作
3. 调用device.popErrorScope()，将错误作用域出栈并检查是否发生了错误

pushErrorScope(filter)接受一个字符串参数filter，用来指定这个作用域要捕获哪一类错误，取值只有三种：

popErrorScope()返回一个Promise<GPUError | null>：如果作用域内没有捕获到匹配的错误，Promise 会 resolve 为null；否则 resolve 为对应错误类型的实例（GPUValidationError、GPUOutOfMemoryError或GPUInternalError），它们都继承自GPUError，都拥有一个只读的message属性用来描述错误原因。需要注意的是，如果设备在此期间丢失，popErrorScope()返回的 Promise 会被 reject。

device.pushErrorScope("validation");constsampler=device.createSampler({maxAnisotropy:0,// 非法值，maxAnisotropy 至少为 1});device.popErrorScope().then((error)=>{if(error){// error 是一个 GPUValidationError 实例console.error(`创建采样器时出错：${error.message}`);}});

错误作用域采用栈结构，同一时刻可以嵌套多个作用域，每个作用域只捕获与自己filter匹配的第一个错误，未被任何作用域捕获的错误会继续向外层传播。

如果一个错误没有被任何错误作用域捕获，GPUDevice会触发uncapturederror事件（GPUDevice继承自EventTarget），可以借此兜底记录所有未被主动捕获的错误：

device.addEventListener("uncapturederror",(event)=>{// event.error 同样是 GPUValidationError / GPUOutOfMemoryError / GPUInternalError 之一console.error("未捕获的错误：",event.error.message);});

一般建议：对于开发阶段能预见、需要主动处理的错误（例如加载用户提供的着色器代码时可能出现的编译错误），使用错误作用域主动捕获；对于其他意外错误，用uncapturederror做统一兜底记录。

视口和剪刀矩形

默认情况下，WebGPU 会将渲染结果填满整个附件（例如整个 canvas）。如果只想让渲染结果显示在其中的一部分区域，可以调用GPURenderPassEncoder上的setViewport方法。它的签名是：

setViewport(x,y,width,height,minDepth,maxDepth)

校验规则要求x + width不能超过渲染附件的宽度，y + height不能超过渲染附件的高度（这里的"附件"指beginRenderPass时传入的颜色/深度模板附件对应纹理），否则会产生GPUValidationError。

// 只在canvas左半部分渲染passEncoder.setViewport(0,0,canvas.width/2,canvas.height,0,1);

除了设置视口，还可以定义一个称为剪刀矩形（scissor rectangle）的区域：光栅化阶段生成的片段一旦被变换到视口坐标系下，落在剪刀矩形之外的片段会被直接丢弃。方法签名为：

setScissorRect(x,y,width,height)

这四个参数都是无符号整数（像素单位），与setViewport不同。如果一次渲染通道中没有调用setScissorRect，默认值等价于(0, 0, 附件宽度, 附件高度)，即不裁剪任何内容。校验规则同样要求x + width不超过附件宽度、y + height不超过附件高度。

// 只保留canvas左上四分之一区域的渲染结果，其余部分被丢弃passEncoder.setScissorRect(0,0,canvas.width/2,canvas.height/2);

视口决定了几何图形如何被缩放、映射到目标区域；剪刀矩形则单纯做"裁剪显示"，二者可以配合使用——例如把视口设置为整个canvas，再用剪刀矩形限制实际显示的子区域。

遮挡查询（Occlusion Queries）

应用可以通过遮挡查询检查一次绘制中有多少片段样本通过了逐片段测试（包括剪刀测试、采样掩码、alpha-to-coverage、模板测试和深度测试）。如果只有很少的片段通过测试，说明对应物体在当前视角下大部分被遮挡，应用可以据此选择绘制更简单的替代模型或跳过复杂着色器，以提升性能。

创建并使用遮挡查询大致需要六步：

1. 创建一个查询集（GPUQuerySet），并在创建渲染通道编码器时通过occlusionQuerySet属性引用它
2. 创建一个用于接收查询结果的缓冲区
3. 调用渲染通道编码器的beginOcclusionQuery(queryIndex)方法，开始记录某一次绘制的遮挡查询
4. 完成相应的绘制指令后，调用endOcclusionQuery()结束这次查询
5. 调用命令编码器的resolveQuerySet()，将查询结果解析并写入指定缓冲区
6. 不再需要查询集时，调用其destroy()方法释放资源

创建查询集

constquerySet=device.createQuerySet({label:"Query Set 0",count:4,// 该查询集能容纳的查询数量，需为正整数type:"occlusion"});

count只需是一个正整数，规范并未要求它必须大于 1；实际使用中通常按照场景中需要参与遮挡剔除判断的物体数量来设置。

关联渲染通道

occlusionQuerySet是在调用beginRenderPass()时通过描述符指定的，一次渲染通道只能关联一个遮挡查询集：

constrenderPass=encoder.beginRenderPass({colorAttachments:[{/* … */}],occlusionQuerySet:querySet});

记录一次查询

// 在renderPass描述符指定的querySet中，开始索引为0的遮挡查询renderPass.beginOcclusionQuery(0);renderPass.setPipeline(renderPipeline);renderPass.setVertexBuffer(0,vertexBuffer);renderPass.draw(3);// 结束这次遮挡查询renderPass.endOcclusionQuery();

beginOcclusionQuery()只接受一个参数queryIndex，即本次查询要写入querySet中的哪个位置（索引从 0 开始）。调用时需要满足以下校验条件，否则会产生GPUValidationError并使渲染通道编码器失效：

• 当前渲染通道在beginRenderPass()时已经指定了occlusionQuerySet
• queryIndex小于查询集的count
• 同一渲染通道中，这个queryIndex尚未被写入过
• 当前没有正在进行中的遮挡查询（即不能在未调用endOcclusionQuery()前再次调用beginOcclusionQuery()）

一个渲染通道中可以多次执行"开始查询—绘制—结束查询"的过程，只要每次使用不同的queryIndex即可，这样就能分别统计场景中不同物体的可见片段数量。

读取查询结果

查询结果不会自动出现在 CPU 可读的内存中，需要先调用命令编码器的resolveQuerySet()，把查询集中的结果解析并拷贝进一个 GPU 缓冲区：

resolveQuerySet(querySet,firstQuery,queryCount,destination,destinationOffset)

调用该方法需要满足以下条件，否则会产生GPUValidationError：

• destination的usage必须包含GPUBufferUsage.QUERY_RESOLVE标志
• firstQuery小于查询集中查询的总数
• firstQuery + queryCount小于等于查询集中查询的总数
• destinationOffset必须是 256 的倍数
• destinationOffset + 8 × queryCount小于等于目标缓冲区的大小（每个查询结果占 8 字节）

由于带有QUERY_RESOLVE标志的缓冲区通常不能直接映射读取，实际使用中一般还需要再创建一个可映射的缓冲区，通过copyBufferToBuffer把解析结果拷贝过去后再读取：

// 创建用于接收解析结果的缓冲区（不可直接映射）constresolveBuffer=device.createBuffer({size:32,// 4个查询 × 8字节usage:GPUBufferUsage.QUERY_RESOLVE|GPUBufferUsage.COPY_SRC});// 创建可映射读取的缓冲区constresultBuffer=device.createBuffer({size:32,usage:GPUBufferUsage.COPY_DST|GPUBufferUsage.MAP_READ});// … 完成渲染通道的编码（renderPass.end()）之后 …// 将querySet中前4个查询的结果解析到resolveBuffer中encoder.resolveQuerySet(querySet,0,4,resolveBuffer,0);// 把结果从resolveBuffer拷贝到可映射的resultBufferencoder.copyBufferToBuffer(resolveBuffer,0,resultBuffer,0,32);device.queue.submit([encoder.finish()]);// 映射并读取查询结果awaitresultBuffer.mapAsync(GPUMapMode.READ);constresults=newBigUint64Array(resultBuffer.getMappedRange());console.log(results);// 每个元素表示对应查询中通过测试的样本数resultBuffer.unmap();

查询结果以 64 位无符号整数形式存储，因此读取时应使用BigUint64Array，其中每个元素代表对应绘制操作中通过深度/模板等测试的片段样本数量。不再需要查询集时，可以调用querySet.destroy()释放底层资源。