threejs-visual-validation

视觉验证

验证声明，而不是经过润色的画面。每项判定都应限定在一项明确声明内，不能用外观证据替代机制、时序或生命周期证明。所属主题技能定义机制真相和故障特征；本技能定义如何证伪这些内容。

1. 预先声明每项主张

对每项主张，记录：

• 类别：视觉、机制、时序、性能、GPU 归因、资源或生命周期；
• 不变量和真相来源；
• 可观测项及用于隔离该项的诊断手段；
• 原生领域指标、单位、对齐方式、掩码和聚合方式；
• 在检查候选结果之前固定的验收门槛；
• 阻断性故障和所需证据。

为每个用于支撑主张的数值标注 Authored、Derived、Measured 或 Gated，并记录其单位和来源。未知值应保持未知。

当每项主张都有直接的证伪方法，且没有任何主张仅由最终图像支撑时，此步骤即告完成。

2. 冻结运行环境

对于纯 CPU 侧的数值、字节布局或元数据主张，应冻结实际执行环境，不要凭空引入渲染器依赖。这类结果不能证明 GPU 着色器、渲染图像或目标性能主张。下文的已初始化后端门槛适用于依赖渲染器的主张。

冻结确切的 Three.js 版本、渲染器和已初始化后端、目标、浏览器/GPU、相机矩阵、随机种子、时间或确定性步进、视口、DPR、质量状态、资源以及颜色/输出图。在初始化之前构造渲染器时启用时间戳跟踪，只要声明的主张需要 GPU 计时：

const renderer = new WebGPURenderer( {
  trackTimestamp: gpuTimingRequirement === 'required'
} );

await renderer.init();

if ( renderer.backend.isWebGPUBackend !== true ) {
  throw new Error( 'Canonical WebGPU validation is unavailable on this target.' );
}

当无法使用规范 WebGPU 时，记录阻断因素。只有用户明确要求该分支时，才访问 $threejs-compatibility-fallbacks。

当运行可依据所记录的状态重复执行，且已捕获已初始化后端的真实状态而非推断状态时，此步骤即告完成。

3. 捕获实际生成机制

在冻结状态下捕获真实管线：

• 对于视觉或机制主张，捕获隔离所声明原因所需的最终视图、无后期处理视图和贡献视图；
• 仅捕获声明的主张所需的深度、法线、速度、场、历史、掩码、资源或通道诊断信息；
• 对于不涉及视觉/机制主张的性能、GPU 归因、资源或生命周期主张，仅捕获该主张所需的生成追踪和诊断信息；
• 通道/调度的归属图，包括历史数据和重置边。

HDR 处理应保持场景线性，直到由一个色调映射/输出变换负责人处理。诊断模式必须切换实际输出节点，并在必要时使图失效；仅切换标签无法证明任何内容。

当每项所需产物都能追溯到生成它的通道、调度、资源和输出负责人时，此步骤即告完成。

4. 在原生领域中测量

使用声明的冻结指标和门槛，将每个可观测项与其真相进行比较。对于视觉或机制主张，直接检查重要的最终图像和诊断图像；非空捕获或标量摘要只能证明数据已传输。若全局统计可能掩盖局部故障，应保存误差图或最差区间。

解码带填充的 WebGPU 纹理到缓冲区复制时，使用对齐读取辅助工具，并传入复制编码器实际使用的整数 bytesPerRow；切勿根据宽度或缓冲区总长度推算行跨度。

阅读图形验证协议，了解指标选择、对齐的 WebGPU 读取、目标计时、资源模型和生命周期检查。只加载声明的主张所需的章节。

当每个测量值都注明其领域、单位、来源、样本范围、冻结门槛和支持产物时，此步骤即告完成。

5. 验证条件状态

仅运行声明所需的分支：

• 时间状态：在确定性的摄像机／对象／状态变化下，验证重置、首次响应、稳态、失效／遮挡消失以及恢复；
• 性能：在指定目标上测量冷启动窗口和最终持续窗口；
• GPU 归因：获取新鲜帧／作用域的渲染和计算时间戳，并在有界的非关键路径上进行解析，同时记录采集开销；
• 资源：根据声明所需的证据，验证常驻、临时、附件、上传／回读和流量；
• 生命周期：重复调整大小／DPR、质量／调试状态转换、历史记录重置、拆除和释放／重新创建，直到资源达到平台期或呈上升趋势。

renderer.computeAsync() 会提交工作，但不能证明 GPU 已完成工作。 CPU 可见的完成状态需要实际的回读／映射，而 GPU 开销需要时间戳证据。

当声明中提到的每次状态转换都有所需的前后诊断结果，且涉及重置或资源的声明都有重置策略或有界资源结果时，此步骤即告完成。

6. 按声明给出结论

为每项声明恰好分配一个结论：

• PASS：所有必需的产物均存在，且所有已冻结的门槛均已通过；
• FAIL：发生了阻断性故障或未通过门槛；
• INSUFFICIENT_EVIDENCE：所需证据或能力不可用。

缺少必需的 GPU 时间戳时，GPU 开销相关声明应判为 INSUFFICIENT_EVIDENCE；CPU 帧时间和呈现节奏不能替代 GPU 计时。报告不受支持的声明，以及关闭这些声明所需的确切证据。

当每项已声明内容都有一个结论，且每个结论都对应直接证据时，验证即告完成。如果运行会生成渲染输出，请确定唯一的输出所有者；对于已声明的时间状态，检查确定性重置；仅对已声明的资源或生命周期声明要求有界平台期。