チュートリアル: プログラムによるグラフィックス情報のキャプチャ

[アーティクル]
06/10/2015

Visual Studio のグラフィックス診断を使用すると、Direct3D アプリケーションからプログラムによってグラフィックス情報をキャプチャできます。

Present を呼び出さないプログラムでコンピューターシェーダーをデバッグする場合、またはレンダリングの問題を予測すること、および手動テストでキャプチャすることは難しいけれども、実行時にアプリケーションの状態に関する情報を使用してプログラムで予測できる場合には、プログラムによるキャプチャは特に有用です。

DirectX 11.2 のプログラムによるキャプチャ

このチュートリアルのパートでは、DirectX 11.2 API を使用するアプリケーションでのプログラムによるキャプチャについて説明します。ここでは、ロバストキャプチャの方法を使用します。 DirectX の以前のバージョンを使用しているアプリケーションでプログラムによるキャプチャを使用する方法については、このチュートリアルで後述の「Programmatic capture in DirectX 11.1 and earlier」を参照してください。

このセクションでは、次のタスクを実行する方法を示します。

プログラムによるキャプチャを使用するためにアプリケーションを準備する
IDXGraphicsAnalysis インターフェイスを取得する
グラフィックス情報をキャプチャする

注意

プログラムによるキャプチャの以前の実装では、Remote Tools for Visual Studio を利用してキャプチャ機能を提供していましたが、DirectX 11.2 はキャプチャを直接サポートしています。このため、DirectX 11.2 API を使用するアプリケーションには、プログラムによるキャプチャのために Remote Tools をインストールする必要がありません。

プログラムによるキャプチャを使用するためにアプリケーションを準備する

プログラムによるキャプチャを使用するために Direct3D 11.2 アプリケーションを準備するには、2 段階のプロセスがあります。最初に、プログラムによるキャプチャで必要なヘッダーファイルが含まれていることを確認します。次にアプリケーションのソースコードに IDXGraphicsAnalysis インターフェイスを定義します。

プログラムによるキャプチャのヘッダーをインクルードするには

IDXGraphicsAnalysis インターフェイスを定義するソースファイルに、次のヘッダーをインクルードします。
```
#include <DXGItype.h>
#include <dxgi1_2.h>
#include <dxgi1_3.h>
```
重要

DirectX 11.2 アプリケーションでプログラムによるキャプチャを実行するには、ヘッダーファイル vsgcapture.h をインクルードしないでください。このファイルは DirectX 11.1 以前のプログラムによるキャプチャをサポートしています。このヘッダーは DirectX 11.2 で使用することはできません。d3d11_2 ヘッダーがインクルードされた後にこのファイルがインクルードされると、コンパイラは警告を発行します。d3d11_2 の前に vsgcapture.h がインクルードされていると、アプリケーションは開始しません。

注意

コンピューターに 2010 DirectX SDK がインストールされており、プロジェクトのインクルードパスに %DXSDK_DIR%include\x86 が含まれている場合は、%DXSDK_DIR%include\x86 をインクルードパスの最後に移動します。ライブラリパスでも同様にします。

IDXGraphicsAnalysis インターフェイスを定義するには

ヘッダーファイルをインクルードしたのと同じファイルで、IDXGraphicsAnalysis インターフェイスを定義します。

interface DECLSPEC_UUID("9f251514-9d4d-4902-9d60-18988ab7d4b5") DECLSPEC_NOVTABLE
IDXGraphicsAnalysis : public IUnknown
{
    STDMETHOD_(void, BeginCapture)() PURE;
    STDMETHOD_(void, EndCapture)() PURE;
};

使いやすくするために、新しいヘッダーファイルでこれらのステップを実行し、その後で、アプリケーションで必要な個所にヘッダーファイルをインクルードすることができます。

IDXGraphicsAnalysis インターフェイスを取得する

DirectX 11.2 からグラフィックス情報をキャプチャする前に、DXGI デバッグインターフェイスに対するインターフェイスを作成する必要があります。

IDXGraphicsAnalysis インターフェイスを取得するには

以下のコードを使用して、DXGI デバッグインターフェイスに対して IDXGraphicsAnalysis インターフェイスをフックします。
```
IDXGraphicsAnalysis* pGraphicsAnalysis;
HRESULT getAnalysis = DXGIGetDebugInterface1(0, __uuidof(pGraphicsAnalysis), reinterpret_cast<void**>(&pGraphicsAnalysis));
```
使用する前に正しいインターフェイスを取得できるように、DXGIGetDebugInterface1 から返される HRESULT を必ずチェックします。
```
if (FAILED(getAnalysis))
{
    // Abort program or disable programmatic capture in your app.
}
```
注意

(Visual Studio で Alt + F5 キーを押して) グラフィック診断でアプリケーションが実行されていない場合、DXGIGetDebugInterface1 は「E_NOINTERFACE インターフェイスがサポートされていません」のエラーを返します。

グラフィックス情報をキャプチャする

これで、正しい IDXGraphicsAnalysis インターフェイスを取得できたので、BeginCapture および EndCapture を使用してグラフィックス情報をキャプチャできます。

グラフィックス情報をキャプチャするには

グラフィックス情報のキャプチャを開始するには、BeginCapture を使用します。
```
...
pGraphicsAnalysis->BeginCapture();
...
```
BeginCapture が呼び出されるとキャプチャはすぐに始まり、次のフレームが開始するのを待ちません。現在のフレームが表示されたとき、またはEndCapture を呼び出したときにキャプチャは停止します。
```
...
pGraphicsAnalysis->EndCapture();
...
```

DirectX 11.1 以前のプログラムによるキャプチャ

このチュートリアルのパートでは、DirectX 11.1 API を使用するアプリケーションでのプログラムによるキャプチャについて説明します。ここでは、レガシーキャプチャの方法を使用します。 DirectX 11.2 を使用するアプリケーションでプログラムによるキャプチャを使用する方法については、このチュートリアルで前述の「Programmatic capture in DirectX 11.2」を参照してください。

ここでは、次のタスクについて説明します。

プログラムによるキャプチャを使用するためにコンピューターを準備する
プログラムによるキャプチャを使用するためにアプリケーションを準備する
グラフィックスログファイルの名前と場所を設定する
CaptureCurrentFrame API の使用

プログラムによるキャプチャを使用するためにコンピューターを準備する

プログラムキャプチャ API は、Remote Tools for Visual Studio を使用してキャプチャ機能を提供します。ローカルコンピューターでプログラムによるキャプチャを使用している場合でも、アプリケーションが実行されるコンピューターにリモートツールをインストールしておく必要があります。ローカルコンピューターでプログラムによるキャプチャを行う場合は、Visual Studio を実行させる必要はありません。

コンピューターで実行しているアプリケーションでリモートキャプチャ API を使用するには、まず Remote Tools for Visual Studio を対象のコンピューターにインストールする必要があります。リモートツールのバージョンによって、サポートしているハードウェアプラットフォームも異なります。リモートツールのインストール方法の詳細については、Microsoft のダウンロード Web サイトで「Remote Tools download page」を参照してください。

または Visual Studio で、32 ビットアプリケーション向けのリモートキャプチャを実行するのに必要なコンポーネントをインストールします。

注意

Visual Studio も含めて大半の Windows デスクトップアプリケーションは、Windows 8 for ARM デバイスでサポートされていないため、ARM デバイスでグラフィックス診断をキャプチャするには、Remote Tools for Visual Studio をプログラムキャプチャ API と一緒に使用する方法しかありません。

プログラムによるキャプチャを使用するためにアプリケーションを準備する

グラフィックス診断ツールを使用するには、まず依存するグラフィックス情報をキャプチャする必要があります。 CaptureCurrentFrame API を使用して、プログラムによって情報をキャプチャできます。

グラフィックス情報をプログラムによってキャプチャするためにアプリケーションを準備するには

vsgcapture.h ヘッダーがアプリケーションのソースコードにインクルードされていることを確認します。このヘッダーは、プログラムキャプチャ API を呼び出すソースコードファイルや、複数のソースコードファイルから API を呼び出すためのコンパイル済みヘッダーファイルの中で、決まった場所にのみインクルードできます。
アプリケーション用のソースコードで、現行のフレームの残りをキャプチャしようとするたびに、g_pVsgDbg->CaptureCurrentFrame() を呼び出します。この方法では、パラメーターを使用しないため戻り値がありません。

グラフィックスログファイルの名前と場所を設定する

グラフィックスログは、DONT_SAVE_VSGLOG_TO_TEMP および VSG_DEFAULT_RUN_FILENAME マクロで定義されている場所に作成されます。

グラフィックスログファイルの名前と場所を構成するには

グラフィックスログが一時ディレクトリに書き込まれないようにするために、#include <vsgcapture.h> 行の前に次の行を追加します。
```
#define DONT_SAVE_VSGLOG_TO_TEMP
```
この値を定義すると、作業ディレクトリに対して相対的な場所へグラフィックスログを書き込むことも、(VSG_DEFAULT_RUN_FILENAME の定義が絶対パスの場合は) 絶対パスへ書き込むこともできます。
グラフィックスログを別の場所へ保存するか、または別のファイル名を指定するには、#include <vsgcapture.h> 行の前に次の行を追加します。
```
#define VSG_DEFAULT_RUN_FILENAME <filename>
```
この手順を実行しない場合、ファイル名は default.vsglog になります。 DONT_SAVE_VSGLOG_TO_TEMP を定義しないと、ファイルの場所は一時ディレクトリに対して相対的なものになります。それ以外の場合は、作業ディレクトリに対して相対的な場所になるか、または絶対的なファイル名を指定した場合は別の場所になります。

Windows ストアのアプリケーションの場合、一時ディレクトリの場所は各ユーザーおよびアプリケーションに特有で、通常は C:\users\username\AppData\Local\Packages\package family name\TempState\ などの場所になります。デスクトップアプリケーションの場合、一時ディレクトリの場所は各ユーザーに特有で、通常は C:\Users\username\AppData\Local\Temp\ などの場所になります。

注意

特定の場所に書き込むには、その場所に対する書き込み権限を持っている必要があります。持っていない場合はエラーが発生します。Windows ストアのアプリケーションは、アプリケーションがデータを書き込める場所についてはデスクトップアプリケーションよりも制約が多く、特定の場所に書き込むためには追加の構成が必要な場合があります。

グラフィックス情報をキャプチャする

プログラムによるキャプチャのためのアプリケーションの準備が完了して、グラフィックスログファイルの場所と名前を選択的に構成したら、アプリケーションをビルドして実行またはデバッグし、データをキャプチャします。プログラムキャプチャ API を使用する場合は、Visual Studio からグラフィックス診断を開始しないでください。グラフィックスログは、指定した場所に書き込まれます。このバージョンのログを保持したい場合は、別の場所に移動します。それ以外の場合は、アプリケーションを再実行したときにログが上書きされます。

ヒント

プログラムによるキャプチャを使用している間でも、アプリケーションにフォーカスを置いた状態で [Print Screen] を押すだけでグラフィックス情報を手動でキャプチャできます。この方法を使用すると、プログラムキャプチャ API でキャプチャされていない追加のグラフィックス情報をキャプチャできます。

次の手順

このチュートリアルでは、プログラムでグラフィックス情報をキャプチャする方法を示しました。次の手順では、次のオプションを検討します。

グラフィックス診断ツールを使用してキャプチャされたグラフィックス情報を解析する方法について学習します。「グラフィックス診断の概要」を参照してください。

次の方法で共有

チュートリアル: プログラムによるグラフィックス情報のキャプチャ

DirectX 11.2 のプログラムによるキャプチャ

プログラムによるキャプチャを使用するためにアプリケーションを準備する

プログラムによるキャプチャのヘッダーをインクルードするには

IDXGraphicsAnalysis インターフェイスを定義するには

IDXGraphicsAnalysis インターフェイスを取得する

IDXGraphicsAnalysis インターフェイスを取得するには

グラフィックス情報をキャプチャする

グラフィックス情報をキャプチャするには

DirectX 11.1 以前のプログラムによるキャプチャ

プログラムによるキャプチャを使用するためにコンピューターを準備する

プログラムによるキャプチャを使用するためにアプリケーションを準備する

グラフィックス情報をプログラムによってキャプチャするためにアプリケーションを準備するには

グラフィックスログファイルの名前と場所を設定する

グラフィックスログファイルの名前と場所を構成するには

グラフィックス情報をキャプチャする

次の手順

参照

処理手順

概念

その他のリソース

次の方法で共有

チュートリアル: プログラムによるグラフィックス情報のキャプチャ

DirectX 11.2 のプログラムによるキャプチャ

プログラムによるキャプチャを使用するためにアプリケーションを準備する

プログラムによるキャプチャのヘッダーをインクルードするには

IDXGraphicsAnalysis インターフェイスを定義するには

IDXGraphicsAnalysis インターフェイスを取得する

IDXGraphicsAnalysis インターフェイスを取得するには

グラフィックス情報をキャプチャする

グラフィックス情報をキャプチャするには

DirectX 11.1 以前のプログラムによるキャプチャ

プログラムによるキャプチャを使用するためにコンピューターを準備する

プログラムによるキャプチャを使用するためにアプリケーションを準備する

グラフィックス情報をプログラムによってキャプチャするためにアプリケーションを準備するには

グラフィックス ログ ファイルの名前と場所を設定する

グラフィックス ログ ファイルの名前と場所を構成するには

グラフィックス情報をキャプチャする

次の手順

参照

処理手順

概念

その他のリソース

グラフィックスログファイルの名前と場所を設定する

グラフィックスログファイルの名前と場所を構成するには