シェーダーをデバッグするうえで重要なステップは、コンソール変数 r.Shaders.Symbols を有効にすることです。これによりエンジンは、 RenderDoc や PIX などのプラットフォーム固有のプログラムでデバッグするためにシェーダーを準備します。
このコンソール変数は、以下に挙げる他の変数とともに、プラットフォームごとにオーバーライドすることができます。これは、追加のシェーダーのコンパイルを制御するために重要です。
シェーダー デバッグのワークフロー
3 つのシェーダー デバッグワークフローの例を以下に説明します。どの場合でも、シェーダーをデバッグしたいプラットフォーム向けのエンジンの コンフィギュレーション ファイル を編集する必要があります。たとえば、Android 用のシェーダーをデバッグする場合、コンソール変数を「AndroidEngine.ini」ファイルに追加する必要があります。
例:プラットフォーム固有のシェーダー デバッガを使用する
プラットフォーム固有のシェーダー デバッガを使用して、そのプラットフォームでクックされたゲームのシェーダーをデバッグする必要があります。
以下のテキストを「[Platform]Engine.ini」ファイルに追加します。
[ShaderCompiler]
r.Shaders.Symbols=1
エディタまたは Unreal Build Tool (UBT) を使用して、そのプラットフォーム向けにゲームをクックします。そのプラットフォームで GPU キャプチャを作成します。シェーダー シンボル パスを求められたら、「Path/To/My/Project/Saved/ShaderSymbols/Platform」フォルダを指定します。
例:ビルド マシンのみがシンボルを Zip ファイルに書き込むようにする
特定のプラットフォーム用のシェーダー シンボルを常にビルドし、ビルド マシンのみがこのシンボルを .zip ファイルに書き込むようにする必要があります。
以下のテキストを「[Platform]Engine.ini」ファイルに追加します。
[ShaderCompiler]
r.Shaders.GenerateSymbols=1
[ShaderCompiler_BuildMachine]
r.Shaders.WriteSymbols=1
r.Shaders.WriteSymbols.Zip=1
これで、ビルド マシンが以下の .zip ファイルを生成します。Path/To/My/Project/Saved/ShaderSymbols/Platform/ShaderSymbols.zip.
例:シェーダーをローカルでデバッグする
グラフィック プログラマーが例 2 と同じ設定のプロジェクトで作業しており、グラフィック プログラマーがローカルでシェーダーをデバッグする必要があるとします。
この場合、ユーザーはローカルで「[Platform]Engine.ini」を編集し、以下を追加する必要があります。
[ShaderCompiler]
r.Shaders.WriteSymbols=1
プロジェクトをクックすると、シェーダーがすべて Path/To/My/Project/Saved/ShaderSymbols/Platform に大まかに書き込まれます。
コンソール変数の概要
シェーダー デバッグに使用できるコンソール変数は以下のとおりです。
| コンソール変数 | 説明 |
|---|---|
r.Shaders.Symbols |
シンボルを生成してシェーダーをデバッグできるようにします。プラットフォームに外部シンボルが必要な場合、外部シンボルがディスクに書き込まれ、その他の場合は、ランタイム時にロードされるシェーダー データ内に格納されます。プラットフォームごとにオーバーライドできます。 |
r.Shaders.ExtraData |
シェーダー名とその他すべてのプラットフォームごとの追加シェーダー データを生成します。この変数は、プラットフォームごとにオーバーライドできます。 |
r.Shaders.GenerateSymbols |
シンボルを生成しますが、ディスクには書き込まれません。この変数は、プラットフォームごとにオーバーライドできます。 |
r.Shaders.WriteSymbols |
プラットフォームが外部シンボルをサポートしている場合、外部シンボルが生成されたらディスクに書き込みます。この変数は、プラットフォームごとにオーバーライドできます。 |
r.Shaders.SymbolPathOverride |
プラットフォームが外部シンボルをサポートしている場合、このコンソール変数を使用して、外部シンボルの書き込み先をオーバーライドできます。 |
r.Shaders.WriteSymbols.Zip |
プラットフォームが外部シンボルをサポートしており、ディスクに書き込む必要がある場合は、個々のファイルではなく、単一の .zip ファイルに書き込まれます。 |
r.Shaders.AllowUniqueSymbols |
プラットフォームが外部シンボルをサポートしている場合、そのソース ファイルではなく、結果のシェーダーからシンボル ファイル名を生成します。シンボルのサイズが大幅に増加することがあるため、これを有効にすることはお勧めしません。 |
プラットフォーム オーバーライド
「[Platform]Engine.ini」ファイルに特別なセクションを追加することで、プラットフォームごとにシェーダー シンボルのコンソール変数をオーバーライドできます。
たとえば、Android プラットフォームでシェーダー シンボルのコンソール変数をオーバーライドしたい場合は、「AndroidEngine.ini」に以下のテキストを追加します。
[ShaderCompiler_BuildMachine]
Console variables go here.
UE4 からの変更点
Unreal Engine 5 では、シェーダーのデバッグに使用されるコンソール変数が変更されています。以下の表は、UE4 の以前のコンソール変数と UE5 で使用される新しい名前を強調しています。生成されたデータとデバッグ シェーダーを引き続き使用するには、プロジェクトを UE5 に移行する際に、これらのコンソール変数を使用するコンフィギュレーション ファイルを更新する必要があります。
| 古い名前 | 新しい名前 | 説明 |
|---|---|---|
r.Shaders.KeepDebugInfo |
r.Shaders.Symbols |
シンボルを生成してコンソール用のディスクに書き込むことで、シェーダーのデバッグを可能にします。PC シンボルは引き続きインラインで保存されます。 |
| 注釈を参照してください。 | r.Shaders.ExtraData |
シェーダー名とその他すべての「追加の」シェーダー データを生成します。 |
r.Shaders.PrepareExportedDebugInfo |
r.Shaders.GenerateSymbol |
シンボルを生成するものの、ディスクには書き込まれません (注：シンボルは DDC に格納されます)。 |
r.Shaders.ExportDebugInfo |
r.Shaders.WriteSymbols |
生成された場合にシンボルをディスクに書き込みます。 |
r.Shaders.AllowUniqueDebugInfo |
r.Shaders.AllowUniqueSymbols |
シェーダー ソースに基づいてシンボルの関連付けを生成します (デフォルトではオフ)。 |
r.Shaders.ExportDebugInfo.Zip |
.Shaders.WriteSymbols.Zip |
すべてのシンボルを単一の .zip ファイルとしてディスクに書き込むことができるようにします。 |
r.Shaders.KeepDebugInfo は、シンボルのみが必要な場合、ランタイム シェーダー データの変更 を除去するために、r.Shaders.Symbols と r.Shaders.ExtraData に分割されました。これにより、最終的なシェーダー データを変更することなく、シッピング ビルド用のシンボルを生成できるため、エクスポートされたデバッグ情報をサポートするプラットフォームで特に役立ちます。