validate-urp-render-graph-renderer-feature

スキル：Unity URP Render Graph レンダラーフィーチャーの検証

目的

Unity 6 以降の URP Render Graph ScriptableRendererFeature と、それに関連するパス実装をレビューし、マテリアルのバインド、リソースの接続、Render Graph テクスチャの作成、静的レンダー関数の構造、グローバルリソースの公開、API／バージョンの使用に関する問題を確認します。

使用する場面

次のような場合にこのスキルを使用します。

• AI が生成した Unity URP Render Graph レンダラーフィーチャーのコードをレビューする場合
• カスタム ScriptableRendererFeature を組み込む前に検証する場合
• Render Graph のリソース接続やパス設定でよくあるミスを確認する場合
• 一見妥当でも疑わしい Render Graph パス実装を診断する場合
• カスタムのラスター／ブリット／コピー パスで、最適な Render Graph ヘルパー API が使われているかをレビューする場合

入力

このスキルでは、次の入力を想定します。

• Unity のバージョン
• URP のバージョン
• レビュー対象の Render Graph レンダラーフィーチャーコード
  • ScriptableRendererFeature
  • 関連するパスコード
  • またはその両方
• 意図する動作
• 想定される入力／出力（分かる場合）
• 任意の制約
  • プロジェクトの規約
  • 必須のパスタイプ
  • 既知のリソース
  • 必須のマテリアル／シェーダープロパティ

出力形式

スキルは次の構成で結果を返す必要があります。

1. 検証の概要

実装についての簡潔な総合評価。

2. 確認された問題

提供されたコードから直接裏付けられる具体的な問題。

3. 可能性のある問題／リスクの高い前提

コンテキストの不足や情報が不完全な場合に発生し得る問題。

4. 推奨する修正

各問題に対する最小限で的を絞った修正。

5. 修正済みコード例

役立つ場合は、修正済みの短いコード例。

6. 不足している情報

より確度の高い検証に必要な情報。

検証チェックリスト

1. マテリアルのバインド

次の点を確認します。

• マテリアルが明確に宣言されている
• 必要に応じて、シリアライズされたマテリアルが適切に公開されている
• マテリアルがパスに正しく渡されている
• 必要な箇所で null が処理されている
• 宣言されたマテリアルが実際に使用されている
• 必要なマテリアル入力がすべて実行前にバインドされている
• シェーダーが入力テクスチャを想定している場合、主要な入力テクスチャが明示的にバインドされている
• 補助テクスチャとパラメーターテクスチャも明示的にバインドされている
• テクスチャ／プロパティのバインド名が、シェーダーの想定するプロパティ名と一致している

次の場合は問題として指摘します。

• マテリアルが宣言または渡されているが、実際には使用されていない
• メインの入力テクスチャが省かれ、二次テクスチャやパラメーターだけがバインドされている
• パスがマスク／ノイズ／補助テクスチャをバインドしている一方で、主要なカラー／入力テクスチャをバインドしていない
• 必須のシェーダープロパティが設定されず、存在すると仮定されている
• プロパティ名に一貫性がない、または曖昧である
• パスのパターン上、明示的なバインドが必要なのに、暗黙的なメインテクスチャのバインドに依存している

次のようなパターンを優先します。

1. マテリアルが明確に作成または割り当てられている
2. 主要なソーステクスチャが明示的にバインドされている
3. すべての補助テクスチャが明示的にバインドされている
4. プロパティ名に一貫性があり、意図が明確である
5. null やリソース不足のケースが適切に処理または報告されている

2. テクスチャリソースの接続

次の点を確認してください。

• サンプリング／読み取りテクスチャ、書き込み先、補助テクスチャが明確に区別されている
• UseTexture(...) で使用するテクスチャが読み取りアクセスに適している
• SetRenderAttachment(...) で使用するテクスチャが書き込み先として適している
• ソース、デスティネーション、補助リソースを混同していない
• 想定されるテクスチャがすべて明示的に接続されている
• マテリアルを使用する場合、テクスチャのプロパティ名が明示的で一貫している
• 実装がテクスチャの利用可能性を独自に仮定していない
• 複数テクスチャのリソース使用が暗黙的ではなく、明示的に処理されている

次の場合は問題として指摘してください。

• 入力／読み取りリソースとして想定されているテクスチャが、正当な理由なく書き込み先として使用されている
• デスティネーション／書き込み先と、サンプリング入力を混同している
• 補助テクスチャの取得元や接続方法が明確でない
• 必要なテクスチャリソースがパスの設定から欠落している
• 読み取り／書き込みリソースの役割が曖昧または一貫していない

3. 実行構造／静的レンダー関数

次の点を確認してください。

• レンダー関数が static として宣言されている
• 実行構造が、対象のパスタイプと API のスタイルに適合している
• パスデータが実行処理に正しく接続されている
• リソースが適切なステージでアクセスされている
• 実行ロジックが意図したレンダーパスの動作と一貫している
• レンダー関数が使用するすべての PassData フィールドが、現在の記録に対するパス設定時に明示的に割り当てられている
• 実装がデフォルト値や、以前に割り当てられた PassData の状態に依存していない
• PassData に格納されたリソースハンドルが、現在のフレーム／パスの記録に対して新しく割り当てられ、以前の使用時の古い状態のまま残されていない

次の場合は問題として指摘してください。

• レンダー関数が static ではない
• API のパターンで静的レンダー関数が想定されているにもかかわらず、インスタンスメソッドを使用している
• 静的関数に渡されるパスデータ／コンテキストではなく、インスタンスの状態を通じてパスデータや必須リソースにアクセスしている
• 実行フローが、想定されるレンダーグラフやパスの実行パターンと一致していない
• レンダー関数で読み取られる PassData フィールドが、パス設定時に明確に割り当てられていない
• 一部の PassData フィールドのみが再割り当てされ、ほかのフィールドに以前のプール使用時の古い値が残る可能性がある
• PassData に格納されたリソースハンドルが、再割り当ての不足により以前のフレームやパスから残存する可能性がある
• 記録のたびにパスデータが完全に初期化されないため、実装が無効または古いハンドルを使用するおそれがある

次を優先してください。

• 各 RecordRenderGraph(...) 呼び出し時に、パスで使用するすべての PassData フィールドを明示的に割り当てる
• PassData を永続的な状態ではなく、記録ごとの一時データとして扱う
• プールされたパスデータオブジェクトの部分的な初期化を避ける

4. レンダーグラフの記述子の検証

次の点を確認してください。

• 適切なグラフ由来の記述子をそのまま使用できる場合、実装がデフォルトで新しい TextureDesc を作成していない
• テクスチャをアクティブなレンダーターゲットに一致させる必要がある場合、次のように、まず関連するレンダーグラフリソースから記述子を取得している
  • resourceData.activeColorTexture.GetDescriptor(renderGraph)
  • または、ほかの適切な既存のグラフに紐づくリソース
• 記述子の取得後に変更するのは、実際に異なる必要があるフィールドだけである
• 名前、深度ビット、フォーマット、MSAA などの記述子フィールドを、意図的に保持するか、意図的に上書きしている
• 記述子データを手動で再構築する場合、具体的な要件に基づいている

次の場合は問題として指摘してください。

• グラフ由来の記述子の再利用をまず試みずに、新しい TextureDesc を作成している
• デフォルトで幅と高さを新しい記述子構造体に手動でコピーしている
• より正確なレンダーグラフ由来の記述子が利用可能なのに、主な取得元として cameraTargetDescriptor を使用している
• MSAA、グラフィックスフォーマット、アクティブなレンダーターゲットとの互換性などの重要なプロパティが誤って失われている
• 記述子の再構築が、ソースリソースから変更する必要がある場合ではなく、単なる手軽な方法として使われている

推奨ルール：

• グラフ由来の記述子をそのまま使用できない場合、またはテクスチャをソースリソースから意図的に変更する必要がある場合を除き、新しい TextureDesc を作成しないでください。

推奨パターン：

1. 関連するレンダーグラフリソースから記述子を取得する
2. 変更が必要なフィールドだけを変更する
3. 可能な限り、その派生記述子からテクスチャを作成する

例：

推奨

RenderTextureDescriptor desc = resourceData.activeColorTexture.GetDescriptor(renderGraph);
desc.depthBufferBits = 0;
desc.name = "New name";
// other desired paramters
passData.targetTexture = renderGraph.CreateTexture(desc);

5. 手動コピーのパスの簡素化

次の点を確認してください。

• 組み込みの Render Graph ヘルパーで十分な単純なテクスチャコピー処理を、完全なカスタムラスターパスとして実装していない
• 1 つのテクスチャを読み取り、変更せずに別のターゲットへ書き込むだけのパスを、適切な場合に簡素化している
• 対象の API／プラットフォーム環境に最も適した組み込みヘルパーを優先している
• 現在の環境では、より互換性の高い AddBlitPass(...) オーバーロードを優先すべき場合、デフォルトで AddCopyPass(...) を推奨していない

次の場合は問題として指摘してください。

• あるテクスチャを別のテクスチャにコピーするためだけにラスターパスが存在している
• パスでマテリアルを使用せず、カスタム処理も行っていない
• レンダー関数が単純なブリット／コピー相当の処理しか行っていない
• 組み込みのコピー／ブリットヘルパーで同じ動作をより直接的に表現できるのに、完全なカスタムラスターパスを使用している

次を優先してください。

• 推奨され、より互換性の高い方法である場合、単純なコピー相当の処理には適切な AddBlitPass(...) オーバーロードを使用する
• AddCopyPass(...) は、対象の API／プラットフォーム環境で明示的に適切かつサポートされている場合にのみ使用する
• コピーに追加のロジックや複雑な処理が必要な場合にのみ、カスタムラスターパスを使用する

6. 手動ブリットのパスの簡素化

次の点を確認してください。

• renderGraph.AddBlitPass(...) で同じ動作をより直接的に表現できる場合、単純なフルスクリーンのマテリアルブリットをカスタムラスターパスとして実装していない
• ブリットにカスタムラスターパスを使用するのは、追加のロジックや複雑な処理が実際に必要な場合に限られている
• 単純なソースからデスティネーションへのマテリアルブリットでは、利用可能な最も直接的なレンダーグラフヘルパーを使用している

次の場合は問題として指摘してください。

• ラスターパスが 1 つのソーステクスチャを読み取り、1 つのデスティネーションテクスチャに書き込んでいる
• パスでマテリアルを使用しているが、追加のカスタムパスロジックはない
• レンダー関数が単純なフルスクリーンブリットしか行っていない
• renderGraph.AddBlitPass(...) を使うほうが、同等の結果をより明確に表現できる

次を優先してください。

• 単純なフルスクリーンのマテリアルブリットには renderGraph.AddBlitPass(...) を使用する
• 追加のロジック、複数の処理、条件付きの動作、または特別な設定が実際に必要な場合にのみ、カスタムラスターパスを使用する

7. グローバルリソースの公開

以下を確認します。

• 明示的に要求されている場合、または下流のコンシューマーで明らかに必要な場合を除き、テクスチャやバッファーがグローバルに公開されていないこと
• レンダーグラフのパスでグローバル公開が必要な場合、実装で適切なレンダーグラフの公開メカニズムが使われていること
• レンダーグラフのリソース公開の代わりに、コマンドバッファーのグローバル状態を直接変更していないこと
• グローバル公開によって、正当な理由なくリソースのライフタイムが不必要に延長されたり、エイリアス化の機会が減ったりしていないこと

以下の場合は問題として指摘します。

• 明確なコンシューマーがないのに SetGlobalTextureAfterPass が使われている
• レンダーグラフのリソース公開が適切な方法であるにもかかわらず、レンダーグラフのパス内で context.cmd.SetGlobalTexture(...) が使われている
• パス間の明示的な接続の代わりに、利便性のためだけにグローバル公開が使われている
• 不必要に隠れた結合が導入されている
• 下流での UseGlobalTexture(...) や UseAllGlobalTextures() の使用によって、グローバル公開されたテクスチャが必要以上に長く保持され、メモリー負荷が増加したり、エイリアス化の機会が減ったりする可能性がある

以下を優先します。

• デフォルトではグローバル公開しない
• 可能な限りリソースを明示的に接続する
• レンダーグラフでのグローバル公開が真に必要な場合に限り、builder.SetGlobalTextureAfterPass(...) を使う
• リソースのライフタイムを、可能な限りローカルかつ短く保つ

8. レンダラー機能の入力宣言

以下を確認します。

• 必要に応じて、ScriptableRendererFeature とその関連パスが ConfigureInput(...) を使って必要なパイプライン入力を宣言していること
• 要求された入力フラグが、その機能の意図する動作と、実際に参照するリソースに合っていること
• 対象 API のパターンで宣言が必要な場合、パスが、宣言せずにパイプラインから提供される入力に依存していないこと
• 不要な入力がデフォルトで宣言されていないこと。特に、追加のコピー、中間リソース、または回避可能なパイプライン処理が発生する可能性がある場合

以下の場合は問題として指摘します。

• パスでパイプライン提供の入力を使っている、または使うことが明らかなのに、ConfigureInput(...) で宣言されていない
• 機能やパスで使われているように見えない入力を ConfigureInput(...) で要求している
• 宣言された入力フラグが、意図するエフェクトの動作に合っていない
• エフェクトの説明、コード、宣言された入力が、それぞれ矛盾する要件を示している
• 不要な入力宣言によって、追加のコピー、追加のパス処理、またはその他の回避可能なパフォーマンスコストが発生する可能性がある

分類の指針：

• 必要な入力を使っていることがコードから明らかなのに、その入力が宣言されていない場合は、確認済みの問題として扱います
• 意図するエフェクトから必要な入力が推測されるものの、表示されているコードだけではシェーダーやリソースの使用状況を完全に確認できない場合は、可能性の高い問題として扱います
• 不要な入力宣言によって追加のコピーや、その他の測定可能な実行時コストが発生する可能性が高い場合は、重要度を高くします

ガードレール

このスキルでは、以下を守る必要があります。

• 裏付けのない API を作り出さない
• 確認済みの問題と可能性の高い問題を区別する
• 広範囲な書き換えより、最小限で対象を絞った修正を優先する
• 各問題が重要である理由を説明する
• 隠れた結合や不要なグローバル状態を指摘する
• 確実に判断するには提示されたコードが不十分な場合、その旨を明示する

対象外

• 実行時の正しさを保証すること
• 必要な場合を除き、レンダラー機能全体を書き換えること
• 無関係なゲームプレイロジックを検証すること
• パスの接続やバインドに直接関係する場合を除き、シェーダー内部を検証すること

評価基準

検証が成功している場合、以下を満たします。

• 実際の接続や API の問題を見つける
• 疑わしいものの、十分にあり得る間違いを特定する
• 実行可能な修正を提示する
• 根拠のない断定を避ける
• 生成されたレンダーパスコードへの信頼性を高める

今後の拡張に関する注意事項

新たな問題が繰り返し見つかった場合は、次のようなルールを追加して、このチェックリストを拡張してください。

• パスの順序／挿入ポイントの検証
• リソースの有効期間とクリーンアップの確認
• 読み取り／書き込みの競合の検出
• 不要なコピーやメモリ割り当て
• カメラの深度／色への依存関係の検証
• マルチパスの依存関係の検証
• オーバーライドマテリアルの正確性
• パスの設定