WebGPU中的调试与查询本文讨论的几项特性都不是渲染流程中不可或缺的一环但它们能显著提升开发效率、渲染性能和调试体验调试组和错误作用域帮助定位问题视口/剪刀矩形和遮挡查询则有助于优化渲染性能。这些接口目前在 WebGPU 规范中大多标注为Limited availability尚未成为 Baseline 特性使用前应留意浏览器兼容性。调试组很多创建 WebGPU 对象的方法都接受一个可选的label属性出错时浏览器会在错误信息中显示这个标签帮助定位是哪个对象出了问题。除了给单个对象打标签应用还可以在指令流中插入调试信息。这一能力由GPUDebugCommandsMixin定义GPUCommandEncoder、GPURenderPassEncoder、GPUComputePassEncoder、GPURenderBundleEncoder都实现了这组方法因此下面介绍的三个方法在渲染通道编码器、计算通道编码器和渲染包编码器中同样可用pushDebugGroup(groupLabel)开始一个使用指定标签命名的调试组此后所有编码的指令都会归入这个组直到对应的popDebugGroup()被调用为止popDebugGroup()结束最近一次通过pushDebugGroup()开始的调试组insertDebugMarker(markerLabel)在指令序列的某个位置插入一个标记调试组信息主要用于遥测telemetry也可能被浏览器开发者工具、GPUError消息等用来辅助调试目前不会影响渲染结果本身。调试组以栈的形式管理因此可以形成层级结构组中嵌套组。以渲染通道为例// 创建指令编码器constencoderdevice.createCommandEncoder();// 开始一个调试组encoder.pushDebugGroup(绘制三角形);// 创建渲染通道编码器并定义渲染constpassEncodercommandEncoder.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机制使用步骤有三调用device.pushErrorScope(filter)将一个错误作用域压入栈中执行一个或多个可能产生错误的操作调用device.popErrorScope()将错误作用域出栈并检查是否发生了错误pushErrorScope(filter)接受一个字符串参数filter用来指定这个作用域要捕获哪一类错误取值只有三种filter 取值捕获的错误类型说明validationGPUValidationError调用某个 API 时传入了不合法的参数或状态属于可预测、可复现的编程错误out-of-memoryGPUOutOfMemoryErrorGPU 或系统内存不足以完成请求的操作是否发生依赖于运行设备和当时的资源占用情况internalGPUInternalError与底层实现或系统相关的错误例如着色器过于复杂导致管线创建失败popErrorScope()返回一个PromiseGPUError | null如果作用域内没有捕获到匹配的错误Promise 会 resolve 为null否则 resolve 为对应错误类型的实例GPUValidationError、GPUOutOfMemoryError或GPUInternalError它们都继承自GPUError都拥有一个只读的message属性用来描述错误原因。需要注意的是如果设备在此期间丢失popErrorScope()返回的 Promise 会被 reject。device.pushErrorScope(validation);constsamplerdevice.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浮点数视口左上角相对于附件的 x 坐标单位像素y浮点数视口左上角相对于附件的 y 坐标单位像素width浮点数视口的宽度height浮点数视口的高度minDepth浮点数视口的最小深度值取值范围[0, 1]maxDepth浮点数视口的最大深度值取值范围[0, 1]且必须大于等于minDepth校验规则要求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、模板测试和深度测试。如果只有很少的片段通过测试说明对应物体在当前视角下大部分被遮挡应用可以据此选择绘制更简单的替代模型或跳过复杂着色器以提升性能。创建并使用遮挡查询大致需要六步创建一个查询集GPUQuerySet并在创建渲染通道编码器时通过occlusionQuerySet属性引用它创建一个用于接收查询结果的缓冲区调用渲染通道编码器的beginOcclusionQuery(queryIndex)方法开始记录某一次绘制的遮挡查询完成相应的绘制指令后调用endOcclusionQuery()结束这次查询调用命令编码器的resolveQuerySet()将查询结果解析并写入指定缓冲区不再需要查询集时调用其destroy()方法释放资源创建查询集constquerySetdevice.createQuerySet({label:Query Set 0,count:4,// 该查询集能容纳的查询数量需为正整数type:occlusion});count只需是一个正整数规范并未要求它必须大于 1实际使用中通常按照场景中需要参与遮挡剔除判断的物体数量来设置。关联渲染通道occlusionQuerySet是在调用beginRenderPass()时通过描述符指定的一次渲染通道只能关联一个遮挡查询集constrenderPassencoder.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()时已经指定了occlusionQuerySetqueryIndex小于查询集的count同一渲染通道中这个queryIndex尚未被写入过当前没有正在进行中的遮挡查询即不能在未调用endOcclusionQuery()前再次调用beginOcclusionQuery()一个渲染通道中可以多次执行开始查询—绘制—结束查询的过程只要每次使用不同的queryIndex即可这样就能分别统计场景中不同物体的可见片段数量。读取查询结果查询结果不会自动出现在 CPU 可读的内存中需要先调用命令编码器的resolveQuerySet()把查询集中的结果解析并拷贝进一个 GPU 缓冲区resolveQuerySet(querySet,firstQuery,queryCount,destination,destinationOffset)参数类型描述querySetGPUQuerySet要解析的查询集firstQuery无符号整数从查询集的第几个查询开始解析queryCount无符号整数要解析的查询数量destinationGPUBuffer接收结果的目标缓冲区destinationOffset无符号整数结果写入目标缓冲区的字节偏移调用该方法需要满足以下条件否则会产生GPUValidationErrordestination的usage必须包含GPUBufferUsage.QUERY_RESOLVE标志firstQuery小于查询集中查询的总数firstQuery queryCount小于等于查询集中查询的总数destinationOffset必须是 256 的倍数destinationOffset 8 × queryCount小于等于目标缓冲区的大小每个查询结果占 8 字节由于带有QUERY_RESOLVE标志的缓冲区通常不能直接映射读取实际使用中一般还需要再创建一个可映射的缓冲区通过copyBufferToBuffer把解析结果拷贝过去后再读取// 创建用于接收解析结果的缓冲区不可直接映射constresolveBufferdevice.createBuffer({size:32,// 4个查询 × 8字节usage:GPUBufferUsage.QUERY_RESOLVE|GPUBufferUsage.COPY_SRC});// 创建可映射读取的缓冲区constresultBufferdevice.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);constresultsnewBigUint64Array(resultBuffer.getMappedRange());console.log(results);// 每个元素表示对应查询中通过测试的样本数resultBuffer.unmap();查询结果以 64 位无符号整数形式存储因此读取时应使用BigUint64Array其中每个元素代表对应绘制操作中通过深度/模板等测试的片段样本数量。不再需要查询集时可以调用querySet.destroy()释放底层资源。