GPUDump ビューア ツール

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 + / を使用します。

コマンドが起動されたら、中間レンダリング リソースをディスクにコピーする必要があります。これを処理するには、メモリ不足エラーが発生しないように制限するため、キャプチャ速度のバランスをとります。これにより、再現できたプロセスをクラッシュしないで、珍しいあるいは再現が困難なアーティファクトの信頼のおけるデータをダンプで収集できます。

GlobalDefinitions.Add("ALLOW_CONSOLE_IN_SHIPPING=1");
GlobalDefinitions.Add("ALLOW_DUMPGPU_IN_SHIPPING=1");

GPU ダンプの保存場所

GPU ダンプを実行するとき、デフォルトでは、プロジェクト ルート ディレクトリの「Saved/GPUDumps」に格納されます。デスクトップ プラットフォームでは、出力が完了すると自動で、このダンプの場所がファイル エクスプローラーで開きます。

Staged (ステージ処理済み) ビルドでは、ステージの保存ディレクトリに次のパス形式で保存されます。[ステージ処理済みディレクトリ] / [プラットフォーム名] / [プロジェクト名] / Saved / GPUDumps

モバイル プラットフォーム ダンプ保存場所

モバイル プラットフォームでは、GPU ダンプは次の場所に保存されます。

ダンプ設定

作成された GPU ダンプは、次のコマンドでニーズに合わせて調整できます。

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 はウェブ アプリケーションで、一般的なブラウザベースのページやアプリケーションと同様の機能があります。GPUDumpViewer で作業するときの簡単なヒントを次に示します。

• 簡単にアクセスできるように、どのリンクもクリック可能で、専用のタブで開くことができます。

• 進むおよび戻るボタンによるナビゲーションで、前に見たページの間を移動します。

• キャプチャを他のユーザーと共有する場合、パネルとダンプの部分に直接リンクするため、# 部分の後のリンクを共有できます。たとえば、#display_output_resource(96,'0000000067e1bfa0.mip0'); です。

1. タイトル バーと各パネル

2. パスとリソース ツリー

3. ビューア

タイトル バーと各パネル

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

情報パネル

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

CVars パネル

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

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 値をキャプチャして保持します。

さらに詳しく調査したいテクスチャの部分については、マウス ホイールを使用して、テクスチャをズームイン (アウト) できます。ズームインしたとき、右クリックしながらドラッグして、テクスチャを動き回らせることができます。

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

1. テクスチャ記述子

2. カスタマイズするための WebGL 2.0 ビジュアライゼーション シェーダー

3. リソースを変更するパス

4. リソースを読み取るパス

テクスチャ記述子

Texture Descriptor (テクスチャ記述子) は現在表示されているテクスチャに関する情報を表示します。これは FRDGBuilder::CreateTexture() でセットアップするものです。

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 クイック リファレンス カード のリンクは、コンパイル ウィンドウの下部にリンクされます。

変更され、読み取られるパス

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` 形式が使用されます。