DumpGPU はプラットフォームに依存しないコンソール コマンドで、キャプチャしたフレームの中間レンダリング リソース バイナリをディスクにダンプ出力します。ダンプは、.json および .bin ファイルで格納され、軽量ウェブページ ビューアを使用して参照できます。

このコマンドには次のようなメリットがあります。
- サードパーティ GPU デバッグ ツールをインストールする、またはエディタを再起動することなく、すべてのビルドで利用できます。
- ダンプは対応プラットフォームから取得できます。
- Windows D3D11, D3D12, Vulkan
- Linux Vulkan
- Mac Metal, AGX
- PlayStation 4 および PlayStation 5
- XboxOne、Xbox Series X/S
- Nintendo Switch
- iOS および Android
- Chrome および WebGL 2.0 対応 GPU をサポートするプラットフォームからインターフェースをブラウズできます。
- アーティファクトが発生したとき、どのユーザーでも GPU ダンプを出力できるシンプルなものでプラットフォームに依存しません。
- エディタで作業している間に、予期しない、再現が困難な問題に遭遇したアーティストに最適です。
- リソース バイナリをブラウズするときの干渉を最小化します。
- プラットフォーム GPU キャプチャでは、リソースを分析するために、適切な SDK や開発キットが必要になることがあります。GPUDump ビューアではデベロッパーがバグを優先度に応じて適切に選別できるとともに、問題の必須コンテキストで任意のプラットフォームからリソースを確認できます。
- 新しいレンダラ機能を作成するグラフィック プログラマーには、実際に起こる内容を分析するために、高速に反復するワークフローがこのツールで実現します。
ダンププロセス
フレームの GPU ダンプを作成するプロセスを開始するには、DumpGPU
コマンドをコンソール ウィンドウに入力する、またはキーボード ショートカット CTRL + Shift + / を使用します。
コマンドが起動されたら、中間レンダリング リソースをディスクにコピーする必要があります。これを処理するには、メモリ不足エラーが発生しないように制限するため、キャプチャ速度のバランスをとります。これにより、再現できたプロセスをクラッシュしないで、珍しいあるいは再現が困難なアーティファクトの信頼のおけるデータをダンプで収集できます。
リソースがすでにダンプ出力されているかどうかを知るためにダンプに必要な永続メモリの量は、無視できるほどです。
リソースのダンプ出力に必要なメモリ量がシステムで利用可能なメモリを超える場合、リソースはダンプに出力されません。代わりに、警告がログに記録されます。
DumpGPU
コマンドは Debug、DebugGame、Development、Test の各ビルドで利用でき、Shipping ビルドの Project.Target.cs
で次のとおり有効にできます。
GlobalDefinitions.Add("ALLOW_CONSOLE_IN_SHIPPING=1");
GlobalDefinitions.Add("ALLOW_DUMPGPU_IN_SHIPPING=1");
シッピング ビルドのみで発生するレンダリング問題をテストしデバッグするために使用します。実際にプロジェクトを出荷するときに有効に しない でください。
GPU ダンプの保存場所
GPU ダンプを実行するとき、デフォルトでは、プロジェクト ルート ディレクトリの「Saved/GPUDumps
」に格納されます。デスクトップ プラットフォームでは、出力が完了すると自動で、このダンプの場所がファイル エクスプローラーで開きます。

Staged (ステージ処理済み) ビルドでは、ステージの保存ディレクトリに次のパス形式で保存されます。[ステージ処理済みディレクトリ] / [プラットフォーム名] / [プロジェクト名] / Saved / GPUDumps
すべてのダンプは非圧縮の raw リソースです。つまり多くのディスク容量を占めることがあります。ただし、Zip ファイルとして大幅に圧縮できます。たとえば、The Matrix:Awakensのテクニカル デモで生成されるダンプは、非圧縮で約 8Gb で、Zip 圧縮では 2.2Gb です。
ダンプを Zip 圧縮するのは、他のユーザーとデータを共有するときに便利です。
モバイル プラットフォーム ダンプ保存場所
モバイル プラットフォームでは、GPU ダンプは次の場所に保存されます。
モバイル プラットフォーム | 保存場所のファイル パス |
---|---|
iOS | [アプリ コンテナへのパス]/Documents/[プロジェクト名]/Saved/GPUDumps/ |
Android | /storage/emulated/0/UnrealGame/[プロジェクト名]/[プロジェクト名]/Saved/GPUDumps/ |
ダンプ設定
作成された GPU ダンプは、次のコマンドでニーズに合わせて調整できます。
コンソール変数 | 説明 |
---|---|
r.DumpGPU.Root |
レンダリング依存関係グラフ (RDG:Render Dependency Graph) パスのサブセットを選択し、ドロー イベントとそれらが属する親のスコープにも続いてダンプを出力します。これを有効にすると、分離されたレンダリング機能で反復するとき、必要なパスでダンプ出力するだけで、ダンプ プロセスを大幅に加速できます。たとえば、ポストプロセス パスに対してのみダンプ出力するには、r.DumpGPU.Root="PostProcessing" を入力します。 |
r.DumpGPU.Viewer.Visualize |
ビューアで名前に基づいて、特定のリソースを自動で開きます。たとえば、`r.DumpGPU.Viewer.Visualize "<リソース名>" を入力します。 |
r.DumpGPU.Directory |
GPU ダンプは大量のディスク容量を占めることがあります。ConsoleVariables.ini コンフィギュレーション ファイルでこのコマンドを使用して、単一の場所にすべての GPU ダンプを保存するディレクトリを指定できます。`r.DumpGPU.Directory="[X:/File/Path/Name]" のように場所を指定します。 |
DumpGPU コマンドが GPUDumpViewer をコピーする方法
GPUDumpViewer ソース コードはエンジン ソースとともに利用できます。場所は /Engine/Extras/GPUDumpViewer
です。
シッピング以外のビルドで、GPUDumpViewer は自動的にステージ処理ディレクトリにコピーされます。それから、DumpGPU コマンドがフレームをダンプ出力するために呼び出されると、ファイルがステージ処理済みディレクトリからダンプ処理ディレクトリにコピーされます。
ステージ処理されたシッピングをビルドする場合、GPUDumpViewer の HTML ソースはダンプ処理ディレクトリにコピーされません。ステージ処理済みディレクトリに見つからないからです。この場合、リポジトリの //Engine/Extras/GPUDumpViewer
アプリケーションをダンプ処理ディレクトリにコピーして、ダンプを開くことができます。
GPU ダンプ ビューア
GPU ダンプ ビューアは HTML ウェブベース アプリケーションです。このビューアから、Unreal Engine のレンダラがどのように動作しているのかの情報にアクセスできます。
まず GPU ダンプが出力されたら、オペレーティングシステムは保存されたダンプがあるフォルダを開きます。OpenGPUDumpViewer.bat
ファイルをダブルクリックすることで、ビューアを Chrome で開くことができます。

起動すると、新しい Chrome ウィンドウが開き、GPUDumpViewer が動作します。

GPUDumpViewer ウェブ アプリケーションは、Chrome の新しいシークレット ウィンドウで開きます。
GPUDumpViewer はウェブ アプリケーションで、一般的なブラウザベースのページやアプリケーションと同様の機能があります。GPUDumpViewer で作業するときの簡単なヒントを次に示します。
- 簡単にアクセスできるように、どのリンクもクリック可能で、専用のタブで開くことができます。
- 進むおよび戻るボタンによるナビゲーションで、前に見たページの間を移動します。
- キャプチャを他のユーザーと共有する場合、パネルとダンプの部分に直接リンクするため、# 部分の後のリンクを共有できます。たとえば、
#display_output_resource(96,'0000000067e1bfa0.mip0');
です。
GPUDumpViewer を開くと、メインの表示領域に多数のヒントやコツが順に表示されます。

- タイトル バーと各パネル
- パスとリソース ツリー
- ビューア
タイトル バーと各パネル
メインのタイトル バーには、簡単なリファレンス情報、つまりダンプが作成されたときに使用していた、プロジェクト名、オペレーティング システム、RHI、ビルドなどが表示されます。これにはクリック可能な情報パネルも含まれます。プロジェクト、使用されたコンソール変数、プロジェクトのログのコピーに関する一般情報などです。

情報パネル
[Infos (情報)] パネルには GPU ダンプの概要が含まれます。システム、各ドライバー、エンジン ビルドなどの便利な情報、さらにバック バッファの最終イメージのスクリーンショットが見つかります。

CVars パネル
[CVars] パネルには、レンダリング コンソール変数の検索可能なリストが含まれます。 — .r.*
や .sg.*
で始まるもの、RHI キーワードを含むものがあります。 — ダンプが発生する前に実行されたものです。

コンソール変数はフレームの最初にキャプチャされます。したがって、ゲームプレイがランタイム時に CVars を切り替える場合に一部が変更を受けることがあります。
Log パネル
[Log (ログ)] パネルにはプロジェクトのログのコピーがあります。ダンプが完了したときにダンプとともに保存されるものです。これも、ダンプ プロセスで発行される警告があるかどうかを調べる場所です。

ビューア
表示領域には、選択したときに異なるパス、テクスチャ、バッファに関する情報が表示されます。
パス ビューア
ドロー イベント階層の Pass をクリックすると、パスが読み取り、変更するリソースのみが表示されます。テクスチャまたはバッファかどうか、最初の出力リソースが自動で開きます。

パス名のとなり (ビューアの一番上) に、[Pass Parameters (パスパラメータ)] ボタンがあります。

これをクリックすると、raw パス パラメータが表示されます。大抵の場合、パス パラメータはシェーダー パラメータです。たとえば、FComputerShaderUtils::AddPass()
または FPixelShaderUtils::AddPass()
が使用されたときです。
パス パラメータにより、CPU の NaN インスタンスが、シェーダー パラメータを通じて、シェーダーに影響しないことを検証できます。

テクスチャ ビューア
Texture が Pass ビューの Input Resources または Output Resources リストで選択されると、ビューアでピクセルを視覚化できます。

WebGL 2.0 のキャンバスでは、raw リソース バイナリ (RHI がダンプのディレクトリにコピー) をロードし、シンプルな WebGL ピクセル シェーダーで表示することにより、テクスチャを表示できます。32 ビット UINT テクスチャなど、WebGL でサポートされない形式では、背後で追加の作業が実行され、ピクセル形式を正確にシミュレートします。
Texture ビューアには、表示されたテクスチャの上部に複数のボタンがあります。

- ビューアに表示されているテクスチャのサイズを設定、または単にウィンドウに合わせます。
-
Copy to clipboard (クリップボードにコピー) で現在表示されているテクスチャと関連リソース情報をクリップボードにコピーします。テキスト エディタやメールに貼り付けると、次のようになります。
- 次のとおりテクスチャ表示モードを変更する 3 つのボタンがあります。Visualization は標準テクスチャ表示モード用、または NaN (非数) および Inf (無限) 表示モードで、ピクセル エラーのタイプを識別できます。
テクスチャの上にマウス カーソルを合わせると、カーソル テクセル位置の現在の RGBA 値が返ります。マウスを左クリックすると、テクセル位置の RGBA 値をキャプチャして保持します。
Cursor Texel Pos および Selected Texel Pos に表示される値には、ピクセル形式エンコードで許可される精度の桁数を超えるものが含まれます。これは javascript で 倍精度浮動小数形式 を使用して、ウェブページがテクセルをデコードするからです。
さらに詳しく調査したいテクスチャの部分については、マウス ホイールを使用して、テクスチャをズームイン (アウト) できます。ズームインしたとき、右クリックしながらドラッグして、テクスチャを動き回らせることができます。

表示されたテクスチャの下の領域には、テクスチャとそれがレンダリングされる方法に関する重要情報が表示されます。

- テクスチャ記述子
- カスタマイズするための WebGL 2.0 ビジュアライゼーション シェーダー
- リソースを変更するパス
- リソースを読み取るパス
テクスチャ記述子
Texture Descriptor (テクスチャ記述子) は現在表示されているテクスチャに関する情報を表示します。これは FRDGBuilder::CreateTexture()
でセットアップするものです。

この時点で、DumpGPU
コマンドは FRDGTexture
をダンプ出力するだけで、非 MSAA Texture2D のみをサポートします。これには深度、ステンシル、ミップ レベルが含まれます。Texture2DArray、Texture2DMS、Texture3D、TextureCube、TextureCubeArray はメタデータで、HTILE、CMask や CIE などはまだサポートされていません。
WebGL 2.0 ビジュアライゼーション シェーダー
WebGL 2.0 ビジュアライゼーションシェーダー は、上部ウィンドウにテクスチャを表示するためにコンパイルされたコード フラグメントを表示します。その下のコンパイル ログ ウィンドウには、発生したときにコンパイル エラーが表示されます。

WebGL 2.0 キャンバス ウィンドウは編集可能なテキストボックスで、WebGL 2.0 GLSL を作成するために使用できます。テクスチャを視覚化しデコードするためにカスタマイズできます。たとえば、画像がチャンネル当たり複数ビットの情報で圧縮されている、または異なる色空間を使用するときです。このフィールドに入力したコードは自動的に再コンパイルされ、エラーが表示されます。
WebGL 2.0 シェーダーの構文は Unreal Engine のものと異なります。Unreal Engine では Unreal Shader Format (.usf) と Unreal Shader Header (.ush) ファイルを使用し、内部レンダリング コードと HLSL を作成するために使用されます。GLSL 構文の WebGL 2.0 クイック リファレンス カード のリンクは、コンパイル ウィンドウの下部にリンクされます。
fetchTexel(uv)
は標準 GLSL ではありません。代わりに、WebGL2.0 で一般にサポートされないピクセル形式を自動で処理するカスタム関数です。
変更され、読み取られるパス
2 つのウィンドウが一番下にあり、選択したリソースを変更しているパス用と、選択したリソースから読み取るパス用です。どちらかのパス リストで、ビューアで表示するためにパスをクリックします。

バッファ ビューア
パス Input Resources または Output Resources リストで表示するためにテクスチャが選択されると、Buffer (バッファ) ビューアは、記述子とビジュアライゼーション コンテンツがリストされます。

Buffer Descriptor (バッファ記述子) には選択リソースに関する情報 (名前、サイズ、記述子、使用量など) がリストされます。

Buffer Visualization (バッファビジュアライゼーション) にはバッファのアドレスが 10 進数または 0x が先頭に付いた 16 進数値としてリストされます。

[Address (アドレス)] テキスト フィールドに 10 進数または 0x のプレフィックスの値を入力して、特定アドレスにジャンプできます。

リストの形式はカスタマイズでき、次の形式をサポートします。
- Float, Half
- Int, short, char
- Uint, ushort, char
- hex() または bin()、16 進数またはバイナリで上記形式のいずれかを表示します。
GPUDumpViewer ではデータの解釈方法を把握していないので、バッファのデフォルト設定は、hex(uint)
形式を使用したデータ ビジュアライゼーションです。ただし DrawIndirect
使用フラグがない場合です。このときはUint
形式が使用されます。
テンプレート化された FRDGBufferDesc::Create*()
関数は、シェーダー パラメータ構造体で FRDGBuffer
を作成するために使用できます。バッファのコンテンツを参照するのが便利になります。
このバッファは、記述子 NumElements
が 1 より大きいとき、行ごとではなく、列ごとにメンバーを表示するように自動で切り替わります。