シェーダー デバッグのワークフロー

シェーダーのデバッグのためのワークフローとプロパティのリファレンス。

シェーダーをデバッグするうえで重要なステップは、コンソール変数 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.Symbolsr.Shaders.ExtraData に分割されました。これにより、最終的なシェーダー データを変更することなく、シッピング ビルド用のシンボルを生成できるため、エクスポートされたデバッグ情報をサポートするプラットフォームで特に役立ちます。

Unreal Engine のドキュメントを改善するために協力をお願いします!どのような改善を望んでいるかご意見をお聞かせください。
調査に参加する
キャンセル