threejs-visual-validation

ビジュアル検証

洗練されたフレームではなく、主張を検証します。各判定は宣言された単一の主張に限定し、見た目の証拠を仕組み、タイミング、ライフサイクルの証明の代わりにしないでください。仕組みの正しさと失敗の特徴は対象のスキルが定義し、このスキルではそれらを反証する方法を定義します。

1. すべての主張を事前に宣言する

各主張について、次の項目を記録します。

• 分類：ビジュアル、仕組み、時間、パフォーマンス、GPU の帰属、リソース、またはライフサイクル。
• 不変条件と正しさの情報源。
• 観測対象と、それを切り分ける診断方法。
• ネイティブドメインのメトリクス、単位、アラインメント、マスク、集計方法。
• 候補の確認前に固定する合格基準。
• ブロッキングとなる失敗と必要な証拠。

主張の根拠となるすべての数値に Authored、Derived、Measured、Gated のいずれかのラベルを付け、単位と情報源を記録します。不明な値は不明のままにします。

すべての主張に直接的な反証方法があり、最終画像のみを根拠とする主張がなくなったら、この手順は完了です。

2. 実行を固定する

CPU 側のみの数値、バイトレイアウト、またはメタデータに関する主張では、レンダラーへの依存関係を捏造せず、実際の実行環境を固定します。こうした結果は、GPU シェーダー、レンダリング画像、または対象のパフォーマンスに関する主張の証明にはなりません。レンダラーに依存する主張には、以下の初期化済みバックエンドの基準が適用されます。

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.' );
}

canonical WebGPU を利用できない場合は、そのブロッカーを記録します。ユーザーがその分岐を明示的に求めた場合に限り、$threejs-compatibility-fallbacks に進みます。

記録した状態から実行を再現でき、初期化済みバックエンドの真実が推測ではなく取得されていれば、この手順は完了です。

3. 生成メカニズムをキャプチャする

固定した状態で、実際のパイプラインをキャプチャします。

• ビジュアルまたは仕組みに関する主張では、主張された原因を切り分けるために必要な最終表示、ポスト処理なしの表示、寄与表示。
• 宣言された主張に必要な深度、法線、速度、フィールド、履歴、マスク、リソース、またはパスの診断のみ。
• ビジュアルまたは仕組みに関する主張を伴わないパフォーマンス、GPU の帰属、リソース、またはライフサイクルに関する主張では、その主張に必要な生成トレースと診断のみ。
• 履歴とリセットのエッジを含む、パス／ディスパッチの所有関係グラフ。

HDR の処理は、単一のトーンマップ／出力変換の所有者に到達するまでシーンリニアのままにします。診断モードでは実際の出力ノードを切り替え、必要に応じてグラフを無効化してください。ラベルだけの切り替えでは何も証明できません。

必要なすべての成果物を、生成したパス、ディスパッチ、リソース、出力の所有者までたどれるようになったら、この手順は完了です。

4. ネイティブドメインで測定する

固定したメトリクスと基準を用いて、各観測対象を宣言された正解と比較します。ビジュアルまたは仕組みに関する主張では、重要な最終画像と診断画像を直接確認します。空でないキャプチャやスカラーの要約は、データが届いたことを示すだけです。全体統計で局所的な失敗が隠れる可能性がある場合は、誤差マップまたは最悪の区間を保存します。

パディングされた WebGPU のテクスチャからバッファへのコピーをデコードする場合は、コピーのエンコーダーに渡した実際の整数値 bytesPerRow を使い、アラインメント済み読み戻しヘルパーを使用します。幅やバッファ全体の長さから行ストライドを求めてはいけません。

メトリクスの選択、アラインメント済み WebGPU 読み戻し、対象のタイミング、リソースモデル、ライフサイクルの確認については、グラフィックス検証プロトコルを参照してください。宣言された主張に使用するセクションのみを読み込みます。

すべての測定値について、ドメイン、単位、情報源、サンプル範囲、固定済みの基準、裏付けとなる成果物が明らかになったら、この手順は完了です。

5. 条件付きの状態を検証する

主張の検証に必要な分岐のみを実行します。

• 時間的特性：決定論的なカメラ／オブジェクト／状態の変更の下で、リセット、初回応答、定常状態、無効化／非表示化、および復旧を確認します。
• パフォーマンス：指定されたターゲットで、初回と最終的な持続時間のウィンドウを確認します。
• GPU の帰属：フレッシュフレーム／スコープ付きのレンダーおよびコンピュートのタイムスタンプを取得し、クリティカルパス外で範囲を限定して解決し、収集オーバーヘッドを記録します。
• リソース：主張に見合った、常駐、一時、アタッチメント、アップロード／読み戻し、およびトラフィックの証拠を確認します。
• ライフサイクル：リソースが横ばいになるか増加傾向を示すまで、サイズ変更／DPR、品質／デバッグの切り替え、履歴のリセット、ティアダウン、および破棄／再作成を繰り返します。

renderer.computeAsync()は処理を投入するものであり、GPU の完了を証明するものではありません。 CPU から確認できる完了には、実際の読み戻し／マップが必要です。一方、GPU コストにはタイムスタンプの証拠が必要です。

このステップは、主張で指定されたすべての状態遷移について、必要な変更前／変更後の診断結果がそろい、その主張がリセットまたはリソースに関する場合は、リセットポリシーまたは上限が確認できるリソースの結果もそろった時点で完了です。

6. 主張ごとに判定を返す

各主張に、以下の判定をちょうど1つ割り当てます。

• PASS：必要なアーティファクトがすべてそろい、固定されたすべてのゲートを通過しています。
• FAIL：ブロッキング障害が発生したか、ゲートに失敗しました。
• INSUFFICIENT_EVIDENCE：必要な証拠または機能を利用できません。

必要な GPU タイムスタンプがない場合、GPU コストに関する主張の判定はINSUFFICIENT_EVIDENCEになります。CPU フレーム時間やプレゼンテーションの周期を GPU タイミングとして扱ってはなりません。 裏付けのない主張と、それを解消するために必要な具体的な証拠を報告してください。

検証は、宣言されたすべての主張に判定が1つずつ割り当てられ、それぞれの判定が直接的な証拠に基づいている時点で完了です。実行時にレンダリング結果が生成される場合は、出力を生成する唯一の所有者を特定してください。宣言された時間的状態については、決定論的なリセットを確認してください。上限が確認できることを求めるのは、リソースまたはライフサイクルに関する主張に限ります。