Unreal Engine 5 ドキュメントは Epic Developer Community に移動しました

開発中に、Unreal Engine からプラットフォームのシェーダ コンパイラに送信されている内容を確認することをお勧めします。このページの情報を活用すると、それに関連した問題をデバッグできるようになります。

中間シェーダをダンプできるようにする

エンジンのインストールからデバッグを開始できるようにするには、「 Engine/Config 」フォルダにある「 ConsoleVariables.ini 」コンフィギュレーション ファイルでいくつかの事前定義コンソール変数を有効にする必要があります。 [Startup] セクションに、次の一連のコンソール変数があります。それらは、以下のように記述されています。

[Startup]

; Uncomment to get detailed logs on shader compiles and the opportunity to retry on errors
r.ShaderDevelopmentMode=1
; Uncomment to dump shaders in the Saved folder
; Warning: leaving this on for a while will fill your hard drive with many small files and folders
r.DumpShaderDebugInfo=1
; When this is enabled, SCW crashes will print out the list of jobs in the current worker
r.ShaderCompiler.DumpQueuedJobs=1
; When this is enabled, when dumping shaders an additional file to use with ShaderCompilerWorker -direct mode will be generated
r.DumpShaderDebugWorkerCommandLine=1
; When this is enabled, shader compiler warnings are emitted to the log for all shaders as they are loaded (either from the DDC or from a shader compilation job).
r.ShaderCompiler.EmitWarningsOnLoad=1

ShaderCompileWorker をデバッグ モードでビルドする

デフォルトで、 UnrealBuildTool (UBT) はツール用のプロジェクトを生成します。これは常に Development モードでコンパイルされます。デバッグするには、 Debug モードでエンジンとプロジェクトをビルドする必要があります。このモードでは、プロジェクトのコードをデバッグするためのシンボルが含まれます。

プロジェクトをデバッグ モードでビルドするには、次の操作を実行する必要があります

1. Visual Studio で Configuration Manager (構成マネージャー) を使用してソリューションのプロパティを変更します。構成マネージャーは [Build (ビルド)] メニューから開くことができます。

2. [ShaderCompileWorker] (SCW) ドロップダウンを [Debug_Program] に設定します。

中間ファイルを生成する

シェーダをデバッグするには、まず実際のデバッグ対象となるファイルを生成する必要があります。それには、中間シェーダをダンプするためのコンソール変数を有効にして、後続のコンパイルで生成されたファイルをダンプできるようにする必要があります。

「 Engine/Shaders 」フォルダにある「 Common.usf 」ファイルにスペースを追加するか、ほとんど影響のない変更を加えて、すべてのシェーダの再ビルドを強制します。その後、エディタを再実行します。この操作によって、すべてのシェーダの再コンパイルがトリガーされ、プロジェクトの「 Saved/ShaderDebugInfo 」フォルダにすべての中間ファイルがダンプされます。

特定のマテリアルをデバッグしている場合は、変更をトリガーするためにどのような変更 (ノードを移動するなど、ほとんど影響のない変更) を加えてもかまいません。ツールバーを使用してマテリアルに変更を 保存 するか 適用 して、シェーダ ファイルを再びダンプします。

ダンプされたシェーダのフォルダ構造

ダンプされたシェーダによって生成されるフォルダ パスには、関連情報が含まれています。ダンプされたシェーダのパスの例を見て、各部を分析してみましょう。

D:\UE4\Samples\Games\TappyChicken\Saved\ShaderDebugInfo\PCD3D_SM5\M_Egg\LocalVF\BPPSFNoLMPolicy\BasePassPixelShader.usf

最初の部分は、プロジェクトのルート パスです。この場合、「Tappy Chicken」という名前のプロジェクトのルートです。

D:\UE4\Samples\Games\TappyChicken\

パスの次の部分は、ダンプされたシェーダの保存先です。

D:\UE4\Samples\Games\TappyChicken\ Saved\ShaderDebugInfo \

すべてのシェーダ形式およびプラットフォームに対して、サブフォルダが作成されます。次のパスは、 PC D3D Shader Model 5 に対するサブフォルダが作成されています。

D:\UE4\Samples\Games\TappyChicken\Saved\ShaderDebugInfo\ PCD3D_SM5 \

マテリアルごとのフォルダと、「 Global 」という特別なフォルダが作成されます。ここで見るデバッグ シェーダは、 M_Egg マテリアルのものです。

D:\UE4\Samples\Games\TappyChicken\Saved\ShaderDebugInfo\PCD3D_SM5\ M_Egg \

シェーダはマップで頂点ファクトリ順にグループ化されます。これは大抵、メッシュ/コンポーネントのタイプに対応します。次のパスは、 LocalVF を指しています。これは、 Local Vertex Factory を表します。

D:\UE4\Samples\Games\TappyChicken\Saved\ShaderDebugInfo\PCD3D_SM5\M_Egg\ LocalVF \

パスの最後の部分は、マテリアルに使用される機能の順列です。

D:\UE4\Samples\Games\TappyChicken\Saved\ShaderDebugInfo\PCD3D_SM5\M_Egg\LocalVF\ BPPSFNoLMPolicy \

シェーダ ダンプ フォルダの中には、生成されたバッチ ファイル、テキスト ファイル、usf ファイルがあります。

• usf ファイルは、プリプロセッサの後に実行される、プラットフォームのコンパイラに送られる最終的なシェーダ コードです。

• バッチ ファイルは、プラットフォームのコンパイラを呼び出し、中間コードを確認するために使用されます。

• 「 DirectCompile.txt 」というテキスト ファイルは、ShaderCompileWorker を使用してデバッグするためのコマンドラインを含んでいます。

ShaderCompileWorker を使用してデバッグする

ShaderCompileWorker で、プラットフォームのコンパイラへの呼び出しをデバッグできます。それには、次のコマンドラインを使用します。

PathToGeneratedUsfFile -directcompile -format=ShaderFormat -ShaderType -entry=EntryPoint {plus platform specific switches}

• PathToGeneratedUsfFile は、「ShaderDebugInfo」フォルダの最終的な usf ファイルです。

• ShaderFormat は、デバッグする必要があるシェーダ プラットフォーム形式です (この場合、PCD3D_SM5)。

• ShaderType は、vs/ps/gs/hs/ds/cs を指定できます。それぞれ、以下に示すシェーダ タイプの 1 つに対応します。

  短縮されたフォルダ名	シェーダ タイプ
  vs	頂点シェーダ
  ps	ピクセル シェーダ
  gs	ジオメトリ シェーダ
  hs	ハル シェーダ
  ds	ドメイン シェーダ
  cs	コンピュータ シェーダ

• EntryPoint は、usf ファイルでのこのシェーダのエントリ ポイントの関数名です。

例：

D:\UE4\Samples\Games\TappyChicken\Saved\ShaderDebugInfo\PCD3D_SM5\M_Egg\LocalVF\BPPSFNoLMPolicy\BasePassPixelShader.usf -format =PCD3D_SM5 -ps -entry =Main

「 D3D11ShaderCompiler.cpp 」の CompileD3D11Shader() 関数にブレークポイントを追加する場合は、このコマンドラインを使用して SCW を実行し、エンジンによってどのようにプラットフォーム コンパイラが呼び出されているかをステップ イインします。