bgfx レンダリング・エンジンのシェーダーのデバッグ

2019.07.23
ゲーム

この記事は、インテル® デベロッパー・ゾーンに公開されている「Shader Debugging for BGFX Rendering Engine」(https://software.intel.com/en-us/articles/shader-debugging-for-bgfx-rendering-engine) の日本語参考訳です。

この記事の PDF 版はこちらからご利用になれます。

リアルタイム・レンダリング・グラフィックスの開発では、シェーダーコードがますます複雑になっており、経験と試行錯誤に基づく単純な開発とデバッグ手法では、もはや実際のニーズを満たすことができません。デバッグツールは、シェーダーのデバッグにおいて重要な役割を果たすだけでなく、グラフィックス開発においても重要です。

bgfx は主要なグラフィックス API をカプセル化する、優れたクロスプラットフォームの抽象化レンダリング・エンジンです。この記事では、Windows* プラットフォーム上の bgfx で Microsoft* Visual Studio* と RenderDoc (英語) を使用して DX11 シェーダーコードをデバッグします。

準備

  1. bfgx ソースコードをクローン化します。 
    git clone git://github.com/bkaradzic/bx.git
git clone git://github.com/bkaradzic/bimg.git
git clone git://github.com/bkaradzic/bgfx.git
  2. GENie を使用して、サンプルとツールを含む Microsoft* Visual Studio* プロジェクト・ファイルを生成します。 
    cd bgfx
..\bx\tools\bin\windows\genie.exe --with-tools --with-examples vs2017

プロジェクトの生成に関する詳細は、–help コマンドライン・パラメーターで確認できます。

生成された bgfx/.build/projects/vs2017 ディレクトリーにある bgfx.sln を Visual Studio* 2017 で開きます。図 1 に示すように、Visual Studio* ソリューションにはサンプルとツール・プロジェクトがすでに含まれています。

Visual Studio* プロジェクト・ファイルに含まれるサンプルとツール
図 1. Visual Studio* プロジェクト・ファイルに含まれるサンプルとツールの一部

この記事の基となる example-37-gpudrivenrendering プロジェクトは、計算シェーダーを使用します。デバッグではこの計算シェーダーに注目します。shaderc というフォルダー名の別のプロジェクトには、bgfx シェーダーソースをターゲット API ランタイム向けのシェーダーバイナリーにコンパイルする bgfx シェーダー・コンパイラーがあります。

次に、Visual Studio* でプロジェクトをビルドします。コンパイル済みのサンプルプログラムと shaderc.exe は、bgfx/.build/win64_vs2017/bin ディレクトリーにあります。Visual Studio* で debug モードを選択し、生成される各アプリケーション名に「Debug」が追加されることを確認します (図 2)。

ファイルリストでハイライト表示されたアプリケーション
図 2. debug モードでコンパイルしたこの記事で使用する 2 つのアプリケーション (水色でハイライト表示)

example-37-gpudrivenrendering サンプルプログラムのテスト

ターゲット・サンプル・プログラムを直接ダブルクリックして開始することはできません。スタートアップ・ディレクトリーを bgfx/examples/runtime に設定する必要があります。このディレクトリーには、アプリケーションがロードする必要があるリソースファイルが含まれています。Visual Studio* では、プロジェクトの設定でデバッグ用の作業ディレクトリーがすでに設定されているため、簡単 にデバッグできます (図 3)。

デバッグ構成のプロパティー
図 3. [プロパティ] > [デバッグ] > [作業ディレクトリ] に \examples\runtime が設定されている

サンプルプログラムを実行すると、図 4 のような画面が表示されます。

プロジェクトの実行例
図 4. example-37-gpudrivenrenderingDebug の実行画面

DX11 シェーダーの再コンパイル

デフォルトでは、bxfx DX11 シェーダーファイルは bgfx/examples/runtime/shaders/dx11 にあります。これらのシェーダーファイルのうち、サフィックスが .bin のものはデバッグ情報を含まず、すでに最適化されています。デバッグツールで有用な情報が得られるように、これらの DX11 シェーダーを再コンパイルして、デバッグ情報を含め、最適化を無効にします。デバッグの例として、cs_gdr_downscale_hi_z シェーダーを使用します。

現在のディレクトリーを bgfx/src に設定します。これは、シェーダーのコンパイルに含まれる共通のシェーダー・ソースファイルがこのディレクトリーにあるためです。このステップをスキップすると、シェーダーはこれらの共通ファイルを見つけることができません。

cd bgfx/src

次のコマンドを実行してデバッグするシェーダーをコンパイルします。

..\.build\win64_vs2017\bin\shadercDebug.exe -f ..\examples\37-gpudrivenrendering\cs_gdr_downscale_hi_z.sc -o ..\examples\runtime\shaders\dx11\cs_gdr_downscale_hi_z.bin --type c -p cs_5_0 --platform windows --debug -O 0

説明:

  • ShadercDebug.exe は、bgfx シェーダー・コンパイラーです。例ではデバッグバージョンを使用しているため、サフィックス Debug が付いています。
  • cs_gdr_downscale_hi_z.sc は、テストに使用する計算シェーダーのソースコードです。
  • cs_gdr_downscale_hi_z.bin は、コンパイル済みのバイナリーです。
  • –type c は、ターゲットを計算シェーダーにコンパイルします。
  • -p cs_5_0 は、計算シェーダー・プロファイル 5.0 でシェーダーを生成します。
  • –platform windows は、Windows* 向けであることを指定します。
  • –debug -O 0 は、デバッグモードを指定し、最適化を無効にします。

Microsoft* Visual Studio* でのシェーダーのデバッグ

bgfx プロジェクトを開いて [デバッグ] > [グラフィックス] > [グラフィックス デバッグの開始] を選択し (図 5)、example-37-gpudrivenrendering サンプルプログラムをグラフィカル・デバッグ・モードで起動します。

[デバッグ] タブのオプション
図 5. [デバッグ] タブから [グラフィクス] > [グラフィックス デバッグの開始] を選択して (または Alt + F5 キーを押して) サンプルプロジェクトを開始

diagsession ビュー (図 6) で [フレームのキャプチャ] ボタンをクリックするか、ゲームウィンドウで Print Screen キーを押してグラフィックス・フレームをキャプチャーできます。

フレームのキャプチャー方法
図 6. [フレームのキャプチャ] (赤い丸で囲った部分) をクリックするか、Print Screen キーを押してフレームを収集

レンダーウィンドウを閉じるか、[収集を停止] ボタンをクリックして収集を停止します。サムネイルをダブルクリックすると、キャプチャーしたフレームが Graphics Analyzer で開きます (図 7)。

グラフィック・アナライザーのパネル
図 7. Graphics Analyzer のイベントリスト、コールスタック、パイプライン・ステージ、その他のパネル

さまざまなパネルが表示されますが、最も重要なものは [イベント リスト]、[コール スタック]、[パイプライン ステージ]、[オブジェクト テーブル] などです。[イベント リスト] でディスパッチ・インターフェイス・イベントに関連する計算シェーダーを展開して、展開されたサブリストから [CS シェーダー] を選択します。プログラムはデバッグモードでコンパイルされているため、ソースパネルが開き、ターゲットシェーダーのソースコードが表示されます。

次に、ターゲットシェーダーの下にある緑色のデバッグ矢印 (上記の赤線で囲まれた部分) をクリックして、シェーダーのデバッグを開始します。Visual Studio* で通常どおりシェーダーをデバッグできます。[ステップ イン] (F11 キー)、[ステップ オーバー] (F10 キー)、[ステップ アウト] (Shift + F11 キー) で変数の値を監視できます。

シェーダーのデバッグに RenderDoc を使用

RenderDoc は、オープンソースの強力なグラフィックス開発およびデバッグツールです。https://renderdoc.org/ (英語) から最新バージョンをダウンロードしてインストールします。

図 8 に示すように、RenderDoc で gpudrivenrenderingDebug.exe を起動します。[Working Directory] を examples/runtime ディレクトリーに設定します。[Launch] をクリックして gpudrivenrendering プログラムを実行します。

RenderDoc インターフェイス
図 8. RenderDoc でパスと作業ディレクトリーを指定して example-37-gpudrivenrenderingDebug.exe を起動

gpudrivenrendering ウィンドウにカーソルを合わせて、F11 キーを押してグラフィックス・フレームをキャプチャーします。生成されるプレビューをダブルクリックしてフレームを開きます (図 9)。

キャプチャーされたフレームの例
図 9. [Captures collected:] セクションに表示されたキャプチャーされたフレーム

開いたフレームで、図 10 のステップ 1、2、3 の順にクリックして、計算シェーダーのデバッグモードを開始します。変数、レジスター、定数、リソースだけでなく、逆アセンブリー (図 10b) や HLSL (図 10c) を確認できます。これでデバッグは終了です。

計算シェーダーの開始ステップ
図 10a. ステップ 1、2、3 の順にクリックして計算シェーダーのデバッグモードを開始

逆アセンブリーの確認タブ
図 10b. このタブで逆アセンブリーを確認

[Debug] タブのオプション
図 10c. このタブを使用して HLSL でデバッグ

RenderDoc のドキュメントでは、計算シェーダーのデバッグサポートは実験的なものであることが明記されています。

「This feature is highly experimental and is provided with no guarantees yet! It may work on simple shaders which is why it is available. （この機能は実験的なものであり、保証されていません。単純なシェーダーでは動作する可能性があるため提供しています。）」

まとめ

ハードウェア・プラットフォームとグラフィックス API は多種多様なため、異なるツールを使用し、特定のケースに適した開発およびデバッグ手法を採用する必要があります。実際のレンダリング・エンジンから開始して、この記事では Visual Studio* と RenderDoc を使用して Windows* プラットフォームでシェーダーをデバッグする方法を 詳しく紹介しました。ここで紹介した内容は、ほかのプラットフォームやグラフィックス API でもある程度参考になるでしょう。

関連情報

bgfx プロジェクト・ファイル (GitHub*) (英語)
bgfx ビルド (GitHub*) (英語)
shaderc (GitHub*) (英語)
Microsoft* Visual Studio* のグラフィックス診断に関する情報
RenderDoc を使用してシェーダーをデバッグする方法 (英語)

コンパイラーの最適化に関する詳細は、最適化に関する注意事項を参照してください。

タイトルとURLをコピーしました