threejs-compatibility-fallbacks

Three.js の互換性フォールバック

フォールバックは、明示的に承認されたプロダクトブランチとして扱います。正規の WebGPU／TSL 作業と、ネイティブ WebGPU の品質調整は、引き続きそれぞれの担当スキルが担います。

1. ブランチを有効にする

実装を選択する前に、次のすべてを記録します。

• 利用できない WebGPU のフォールバックを求める、ユーザーからの明示的なリクエスト。
• 初期化済みの非 WebGPU バックエンドが明確に特定されたこと、または指定されたターゲットで再現可能な機能関連の初期化エラーが発生したこと。どちらの状態が発生したかを記録し、isWebGPUBackend プロパティが存在しないことからバックエンドを推測しないでください。
• 正規の担当者と正確な機能。
• 視覚、物理、時間、インタラクション、パフォーマンス、保守性に関する損失について、合意された範囲。
• 互換性ブランチの保守担当者。

バックエンドの識別は、await renderer.init() が成功した後にのみ確認します。r185 では、renderer.backend.isWebGLBackend === true によって、初期化済みの WebGL バックエンドを明確に識別できます。フラグが存在しない、または不明であることは、証拠になりません。初期化が拒否された場合は、その正確なエラーを記録し、初期化済みバックエンドの識別は不明のままにします。アプリケーションや設定の例外は、利用できないハードウェアの問題に見せかけず、デバッグに回してください。WebGPU が初期化された場合は、正規の担当者に戻してください。明示的なフォールバックのリクエストがない場合は、正規のブロッカーを報告します。インストール済み API の初期化済み、または部分初期化状態向けのクリーンアップ手順を使って、プローブのリソースとリスナーをクリーンアップします。異なるレンダラースタックを使う場合は、新しいキャンバスを別途用意してください。

この手順は、有効化に必要な 5 つの事実が記録され、正規の実装が変更されていない状態で完了です。

2. 正規の動作を分類する

正規機能の幾何、放射測定、色、時間、インタラクション、状態の所有権、ライフサイクルに関する不変条件を列挙します。それぞれを次のように分類します。

• preserved：同じ量と証明が引き続き適用されます。
• weakened：量は維持したうえで、変更された誤差、サポート範囲、更新頻度、陳腐化、または適用範囲を明記し、新しいゲートを固定します。
• removed：機能をサポート対象外とし、それに依存する主張を削除します。

システム間の境界では、維持とは、同じ単位、座標系／原点、時間間隔とサンプル位相、所有者、生成側／消費側のバージョン、サポート範囲／フィルター、有効性／陳腐化／誤差、レートと積分値の意味、一方向または双方向の反応範囲、安定した識別情報、不変の前フレーム／現フレームの表示状態、リセット動作、GPU 完了への依存関係を保つことを意味します。意味が異なる近似は、weakened または removed とします。安定フレームにおける GPU から CPU への読み戻しは、フレームクリティカルな処理経路の外に置いてください。

この手順は、正規の主張すべてに処置が 1 つだけ割り当てられ、weakened または removed の行すべてにユーザーが認識できる影響が記載された状態で完了です。

3. 誠実な表現を最初に選択する

各機能について、次の順序で選択します。

1. インタラクションをなくせる場合は、事前計算済みまたは静的な正規出力。
2. CPU／オフラインでの生成。アップロード頻度、レイテンシー、割り当て、失われる動的な挙動を明記します。
3. 対応する UI とドキュメントを更新し、関連する主張を削除したうえで機能を削除。
4. 保守について明示的な承認を得た後に、隔離されたレガシーブランチを使用。

利用できない機能から選択する際は、 ダウングレード判断マトリックスを参照してください。レガシー／API ブランチを実装または検証する場合に限り、 r185 API マップを参照し、各シンボルをインストール済みのリビジョンで再検証してください。

この手順は、選択した表現が、すべての preserved 不変条件と、固定されたゲートを持つすべての weakened 不変条件を満たす最初の行であり、残る損失がすべて明示されている状態で完了です。

4. 所有権を分離する

互換性ブランチに、独立したインポート、ビルド／デプロイのエントリーポイント、テスト、アーティファクト、機能ゲート、保守責任者を割り当てます。ブランチ内のシーングラフ信号とトーンマップ／出力変換の責任者は、それぞれ一つにします。カラーとデータのテクスチャ領域、リソースの作成／リセット／リサイズ／破棄、正規アセットと互換性アセットの境界を記録します。

ノードレンダラーのブランチで GPU タイムスタンプが必要な場合は、初期化前に trackTimestamp: true を指定して構築します。従来の WebGLRenderer にはそのオプションも resolveTimestampsAsync() API もありません。独自にサポートされ、検証済みのタイマー クエリ計測を用意するか、証拠不十分との判定が必要です。レガシーブランチで WebGPURenderer( { forceWebGL: true } ) を使用できるのは、アクティベーション後に限られます。このブランチは正規レンダラーではなく、互換性製品のままです。一貫性のあるスタックを一つ選択します。WebGL バックエンドを使用する WebGPURenderer は、ノードマテリアル／TSL と RenderPipeline のモデルを維持し、WebGLRenderer は従来の ShaderMaterial と EffectComposer の API を使用します。forceWebGL を指定しても、前者が後者に変わるわけではありません。互換性のないマテリアル、パス、レンダーターゲット、レンダラー固有のリソースを、これらのスタック間で共有しないでください。古い GPU オブジェクトを保持せず、明示的なブランチアダプターを通じてアプリケーションの状態を維持し、コントロールを復元します。

互換性エントリーポイントを無効化または削除しても、正規ビルドとランタイムグラフが変わらず、ブランチが所有するすべてのリソースに単一の所有者と破棄経路がある状態になれば、このステップは完了です。

5. 変更後の主張を検証する

$threejs-visual-validation がインストールされている場合、維持または弱化した主張ごとにこれを呼び出します。この検証担当を使用する場合は、正規の証拠を真実として扱い、主張を裏付けるビュー、トレース、診断情報だけを取得します。また、該当するリセット、リサイズ／DPR、遷移、ティアダウン、破棄／再作成の経路を実行します。永続リソースは、宣言したウォームアップ後に上限値で安定する必要があります。

検証担当が存在しない場合は、その旨を報告し、該当する主張について INSUFFICIENT_EVIDENCE を返します。このスキル内に代替の検証を構築しないでください。タイムスタンプがない場合も、必要な GPU 処理の帰属判定は INSUFFICIENT_EVIDENCE となります。表示時間や CPU 実行時間は、エンドツーエンドの証拠にすぎません。

残存するすべての主張に判定があり、削除した主張が製品の説明から除かれ、出力変換の責任者が一つに定まり、ライフサイクル／リソースに関する主張が検証で上限値に達するか失敗する、または不足している証拠を明示した INSUFFICIENT_EVIDENCE のままになれば、このステップは完了です。

出力

機能ごとに1行を返します。

機能	対象	維持	弱化	削除	表現	検証

アクティベーションの事実、分離したエントリーポイントと保守責任者、出力の責任者、ライフサイクルの結果、サポート対象外の主張、不足している検証担当、および各 INSUFFICIENT_EVIDENCE 判定に必要な正確な証拠も記録します。