シェーダ コンパイル プロセスのデバッグ

シェーダ コンパイル プロセスのデバッグの概要です。

Windows
MacOS
Linux

開発中に、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 モードでエンジンとプロジェクトをビルドする必要があります。このモードでは、プロジェクトのコードをデバッグするためのシンボルが含まれます。

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

BuildConfiguration_SCW.png

  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\

ConsoleVariables.ini」ファイルでコンソール変数 r.DumpShaderDebugShortNames=1 が設定されているので、ファイル名が短くなるよう名前がコンパクトになっています。

例えば、このコンソール変数を有効にしなかった場合、パスは次のようになります。

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

シェーダ ダンプ フォルダの中には、生成されたバッチ ファイル、テキスト ファイル、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 を実行し、エンジンによってどのようにプラットフォーム コンパイラが呼び出されているかをステップ イインします。

ConsoleVariables.ini」ファイルでコンソール変数 r.DumpShaderDebugWorkerCommandLine=1 を有効にしている場合は、このコマンドラインを直接コピーできます。これにより、生成された usf ファイルの隣に「DirectCompile.txt」というファイルがダンプされます。

Select Skin
Light
Dark

Welcome to the new Unreal Engine 4 Documentation site!

We're working on lots of new features including a feedback system so you can tell us how we are doing. It's not quite ready for use in the wild yet, so head over to the Documentation Feedback forum to tell us about this page or call out any issues you are encountering in the meantime.

We'll be sure to let you know when the new system is up and running.

Post Feedback