webgpu

WebGPU

まず、観測可能な最小の GPU 出力を作成し、その後で拡張します。WebGPU の各機能を、次の 5 つの明確な契約として扱います。

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. サイズ変更、入力、シミュレーションのタイミング、読み戻し、後処理を、一度に 1 つずつ追加します。
9. 想定するワークロードで正しさが安定してから、プロファイルを取得します。

次の不変条件を維持する

• adapter.featuresとadapter.limitsは利用可能な候補として扱います。デバイスで利用できるのは、requestDevice()で要求し、許可された機能のみです。
• 「すべての構造体は 16 バイト境界に配置される」という考えをパッキング規則にしないでください。AlignOf、SizeOf、メンバーのオフセット、配列ストライド、ユニフォーム固有の制約を計算してください。
• 過剰にディスパッチされた各コンピュート呼び出しでは、リソースにアクセスする前に範囲をチェックしてください。
• 参加するワークグループ内で、workgroupBarrier()とstorageBarrier()を一様な制御フローに置いてください。
• ワークロードによって記述子が実際に変化しない限り、毎フレームバッファー、テクスチャ、サンプラー、バインドグループ、パイプラインを作成しないでください。
• アニメーションやポインター操作のループ中に、GPU から CPU への全量読み戻しを避けてください。GPU 上で結果を小さく上限付きにまとめ、小さなステージングバッファーをマップしてください。
• createShaderModule()に渡す WGSL は、実行可能な入力として扱ってください。バンドルされ、レビュー済みのシェーダーソースを優先し、デフォルトでは、ネットワークから取得した WGSL やエンドユーザーが提供した WGSL をアプリケーションで実行時にコンパイルしないでください。
• 描画された CSS サイズと DPR に基づいてキャンバスのバッキングストアをサイズ変更し、デバイスの上限に収まるよう制限して、変更がない場合は代入をスキップしてください。
• シェーダーのコンパイルメッセージ、捕捉されていないエラー、パイプラインの検証失敗、device.lostを通知してください。
• リソースを破棄する前にアニメーションとオブザーバーを停止し、所有するキャンバスコンテキストの設定を解除して、必要に応じてデバイスを破棄してください。

ワークロードに応じてパターンを選ぶ

ワークロード	まず試すもの
独立したパーティクルやレコード	ストレージバッファー、ガード付きの1次元ディスパッチ、インスタンス描画
近傍を参照するパーティクル	ペアごとの処理を行う前に、空間ビニングまたはタイル化した近傍領域を使用
セルオートマトンやステンシル	ピンポン状態、2次元ディスパッチ、固定シミュレーション周期
軌跡、ぼかし、反復画像処理	ピンポンテクスチャと明示的なコンピュート／レンダーパス
ポストプロセス	中間テクスチャにレンダリングしてから合成
対話的な検査	GPU フィルター／コンパクトパスと、サイズに上限を設けたステージング読み戻し
生成シェーダーやモジュール型シェーダー	安定したバインディング契約、合成されたパスフェーズ、コンパイル診断

まずは移植性の高いコアパスから始めましょう。shader-f16、タイムスタンプクエリ、サブグループ、ストレージフォーマット、言語拡張、引き上げた上限は、暗黙の必須要件ではなく、オプションの高速化機能として扱ってください。

必要な詳細を読む

• アダプター、デバイス、機能、上限、キャンバス設定、ロスト処理、クリーンアップについては、initialization-and-lifecycle.md を読んでください。
• ホスト共有バッファーを定義またはデバッグする前に、wgsl-data-layout.md を読んでください。
• ワークグループ、ピンポン状態、固定ステップ、グリッド、バリア、サイズに上限を設けた読み戻しについては、compute-patterns.md を読んでください。
• キャンバスのサイズ設定、インスタンス描画、中間ターゲット、フィードバックについては、rendering-patterns.md を読んでください。
• コンパイルメッセージ、エラースコープ、ラベル、プロファイリング、症状に基づく診断については、debugging-and-performance.md を読んでください。
• ビジュアルやシミュレーションのアイデアをパスグラフに落とし込む場合は、creative-recipes.md を読んでください。
• フォールバックやオプション機能を選ぶ場合は、compatibility.md を読んでください。
• 不安定な API や最近追加された API を最新の一次情報源で確認するには、current-sources.md を使ってください。

結果を検証する

• 現行の @webgpu/types に対してホストコードを型チェックしてください。@ts-nocheck でエラーを隠さないでください。
• WebGPU 対応ブラウザーで実行し、コンパイルメッセージと捕捉されなかったエラーを確認してください。
• サイズがゼロまたは非表示の状態での起動、リサイズ、DPR の変更、バックグラウンドタブでのタイミング、終了後の再作成をテストしてください。
• navigator.gpu を利用できない環境で、フォールバックまたはエラー表示 UI をテストしてください。
• バッファーサイズ、コピーオフセット、bytes-per-row、動的オフセット、ディスパッチ回数、デバイスの上限を確認してください。
• 起動時と定常状態を目視で確認するか、数値に上限があることをアサートしてください。
• 読み戻しとデバッグ計測を無効にして、パフォーマンスを比較してください。
• 既存コードをレビューする場合は、細かな最適化より先に、正しさとライフサイクル上の危険を報告してください。