SuperAPI AI 工具集

webgpu-errors-validation

编程与开发

查看项目

更新于 10-15 22:18

技能介绍

用途:在 WebGPU 调用验证失败、需要用错误作用域捕获错误,或处理 uncapturederror 事件时使用。WebGPU 错误是异步且具有传染性的,与 WebGL 的同步 gl.getError() 不同。

主要能力:错误分三类,GPUValidationError(API 用法无效,过滤字符串 "validation")、GPUOutOfMemoryError(分配失败,"out-of-memory")、GPUInternalError(驱动或实现故障,"internal")。每个错误都带可读的 message。device.pushErrorScope(filter) 入栈作用域,device.popErrorScope() 返回 Promise<GPUError | null>,弹出首个匹配过滤器类型的错误或 null;uncapturederror 事件在设备上触发未被作用域捕获的错误。作用域为 LIFO 栈,只捕获匹配过滤器类型的错误。

必要用法:用 pushErrorScope/popErrorScope 括住可疑调用,并 await popErrorScope()。初始化时添加一个 uncapturederror 监听作为兜底遥测,例如 device.addEventListener("uncapturederror", (event) => console.error(event.error.constructor.name, event.error.message))。要捕获某一调用的任意错误,可嵌套压入三种过滤器并按逆序弹出。过滤字符串需与错误类型匹配,"validation" 作用域不会捕获内存不足错误。

适用场景:针对具体调用点定位失败;诊断管线、资源创建等 API 误用;对未括住错误做最后兜底日志。着色器 WGSL 编译错误不是 GPUError,应改用 shaderModule.getCompilationInfo()。

限制与注意事项:popErrorScope 返回 Promise,禁止同步读取;uncapturederror 无法指出调用点;每个 push 必须配对 pop,否则会静默吞掉后续错误;应优先修第一个错误,后序错误多为连带结果;WebGPU 没有 getError() 等价物;需配合给描述符设置 label 才能让 message 指明对象。版本支持 WebGPU 1.0-stable(Chrome 113+、Safari 26+、Firefox 141+)。