webgpu

WebGPU

先构建最小的可观测 GPU 结果，再逐步扩展。将每项 WebGPU 功能视为五个明确的契约：

1. 能力契约：基线、可选功能和限制，以及回退方案。
2. 数据契约：WGSL 类型、字节偏移、步长、使用标志。
3. 通道契约：读取、写入、顺序、乒乓缓冲区所有权。
4. 呈现契约：画布格式、物理尺寸、透明度和颜色。
5. 生命周期契约：创建、调整大小、错误、丢失和销毁。

为新的浏览器项目复制完整的 Vite 起始模板。其中包含一个经过类型化的计算与渲染粒子场，支持乒乓缓冲区、编译诊断、尺寸调整、指针交互、设备丢失报告和清理。

从资源和通道图入手

编写 WGSL 之前，先列出持久资源和各通道的所有权：

CPU seed ─writeBuffer─> state A
                         │
state A ─compute step─> state B ─render─> canvas
state B ─compute step─> state A ─render─> canvas

对于每个通道，记录：

• 入口点和调度／绘制维度；
• 绑定和着色器可见性；
• 读取、写入或复制的资源；
• 通道执行后成为权威状态的内容；
• 边界保护和同步假设。

如果某个通道需要读取先前状态，同时生成下一状态，请使用不同的资源。通道边界会对命令排序，但无法让包含跨调用原地读取的算法变得确定。

按此顺序构建

1. 确定不支持 WebGPU 时应采用回退、降级模式，还是明确报错。
2. 请求适配器，并仅请求工作负载实际使用的可选功能和提升后的限制。
3. 定义 WGSL 结构体，并计算精确的主机端偏移和数组步长。
4. 分配持久资源并为其添加标签。
5. 编译着色器模块，检查 getCompilationInfo()，然后创建管线。
6. 创建稳定的绑定组，或仅在资源变化时重建绑定组。
7. 编码一个最小通道、提交并验证可见输出或数值输出。
8. 每次只添加一项功能：尺寸调整、输入、模拟计时、读取回读和拆除。
9. 只有在目标工作负载下的正确性稳定后，才进行性能分析。

保持以下不变量

• 将 adapter.features 和 adapter.limits 视为可能具备的能力。设备仅提供在 requestDevice() 时请求并获准的能力。
• 绝不能将“所有结构体都按 16 字节对齐”作为打包规则。应计算 AlignOf、SizeOf、成员偏移、数组步长和 uniform 特有的约束。
• 在访问资源前，为每个过度调度的计算调用添加边界保护。
• 在参与该工作组的统一控制流中使用 workgroupBarrier() 和 storageBarrier()。
• 除非工作负载确实改变了资源描述符，否则不要每帧都创建缓冲区、纹理、采样器、绑定组或管线。
• 避免在动画或指针循环中进行完整的 GPU 到 CPU 回读。在 GPU 上压缩有界结果，并映射一个小型暂存缓冲区。
• 将传递给 createShaderModule() 的 WGSL 视为可执行输入。优先使用已打包且经过审核的着色器源；默认不要让应用在运行时编译从网络获取或由最终用户提供的 WGSL。
• 根据画布渲染后的 CSS 尺寸和 DPR 调整其后备存储，将尺寸限制在设备上限内，并跳过无变化的赋值。
• 显示着色器编译消息、未捕获的错误、管线验证失败和 device.lost。
• 在销毁资源前停止动画和观察器；在适当情况下取消配置所拥有的画布上下文并销毁设备。

根据工作负载选择模式

工作负载	从以下模式入手
独立粒子或记录	存储缓冲区、带保护的 1D 调度、实例化渲染
基于邻居的粒子	在成对计算之前进行空间分箱或邻域分块
元胞自动机或模板	Ping-pong 状态、2D 调度、固定模拟节奏
拖尾、模糊或迭代图像	Ping-pong 纹理和显式计算/渲染阶段
后期处理	渲染到中间纹理，然后进行合成
交互式检查	GPU 筛选/压缩阶段，加上有界暂存读取回传
生成式或模块化着色器	稳定的绑定约定、组合式阶段流程、编译诊断

从可移植的核心路径入手。将 shader-f16、时间戳查询、子组、存储格式、语言扩展和提高的限制作为可选加速功能，而不是默默要求的条件。

查阅合适的细节

• 阅读 initialization-and-lifecycle.md，了解适配器、设备、功能、限制、画布配置、丢失和清理。
• 在定义或调试主机可共享缓冲区之前，阅读 wgsl-data-layout.md。
• 阅读 compute-patterns.md，了解工作组、Ping-pong 状态、固定步长、网格、屏障和有界读取回传。
• 阅读 rendering-patterns.md，了解画布尺寸、实例化、中间目标和反馈。
• 阅读 debugging-and-performance.md，了解编译消息、错误作用域、标签、性能分析和基于症状的诊断。
• 将视觉或模拟构想转换为阶段图时，阅读 creative-recipes.md。
• 选择回退方案或可选功能时，阅读 compatibility.md。
• 使用 current-sources.md，对照持续更新的主要来源验证不稳定或近期新增的 API。

验证结果

• 使用当前的 @webgpu/types 对主机代码进行类型检查；不要用 @ts-nocheck 隐藏错误。
• 在支持 WebGPU 的浏览器中运行，并检查编译消息和未捕获的错误。
• 测试零尺寸/隐藏状态下的启动、调整大小、DPR 变化、后台标签页计时，以及拆除和重新创建。
• 在 navigator.gpu 不可用的情况下，测试回退或错误 UI。
• 确认缓冲区大小、复制偏移量、每行字节数、动态偏移量、调度次数和设备限制。
• 通过视觉检查启动阶段和稳定状态，或断言数值结果有界。
• 在禁用读取回传和调试插桩的情况下比较性能。
• 审查现有代码时，先报告正确性和生命周期方面的风险，再考虑微优化。