逐步解說：以程式設計方式擷取圖形資訊

發行項
06/10/2015

您可以使用 Visual Studio 圖形診斷，透過程式設計方式從 Direct3D 應用程式擷取圖形資訊。

程式設計擷取特別適用於偵錯絕不會呼叫 Present 的程式中的計算著色器，或是，當呈現問題很難預期以及在手動測試中擷取，但是可以在執行階段使用應用程式狀態資訊，透過程式設計方式進行預測。

DirectX 11.2 中的程式設計擷取

這部分的逐步解說示範如何在使用 DirectX 11.2 API 的應用程式中，進行程式設計擷取 (使用穩固擷取方法)。如需如何在使用舊版 DirectX 的應用程式中，使用程式設計擷取的詳細資訊，請參閱本逐步解說稍後的 Programmatic capture in DirectX 11.1 and earlier。

本節顯示如何執行這些工作：

準備應用程式以使用程式設計擷取
取得 IDXGraphicsAnalysis 介面
擷取圖形資訊

注意事項
先前的程式設計擷取實作依賴 Visual Studio 遠端工具來提供擷取功能，但是 DirectX 11.2 支援直接擷取。因此，在使用 DirectX 11.2 API 的應用程式中進行程式設計擷取，已經不再需要安裝遠端工具。

準備應用程式以使用程式設計擷取

準備 Direct3D 11.2 應用程式以使用程式設計擷取，是一個兩步驟流程。一定要先包括程式設計擷取所需的標頭檔，然後在應用程式的原始程式碼中定義 IDXGraphicsAnalysis 介面。

包括程式設計擷取標頭

將這些標頭併入您將定義 IDXGraphicsAnalysis 介面的原始程式檔中：

#include <DXGItype.h>
#include <dxgi1_2.h>
#include <dxgi1_3.h>

重要

請勿包括標頭檔 vsgcapture.h (其支援 DirectX 11.1 (含) 以前版本中的程式設計擷取)，以在 DirectX 11.2 應用程式中執行程式設計擷取。此標頭與 DirectX 11.2 不相容。如果在包括 d3d11_2 標頭之後包括此檔案，則編譯器會發出警告。如果在 d3d11_2 前面包括 vsgcapture.h，則不會啟動應用程式。

注意事項
如果在電腦上安裝 2010 年 6 月 DirectX SDK，而且專案的 Include 路徑包含 %DXSDK_DIR%include\x86，請將它移至 Include 路徑結尾。請對程式庫路徑執行相同的處理。

定義 IDXGraphicsAnalysis 介面

在包括標頭檔的相同檔案中，定義 IDXGraphicsAnalysis 介面。

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

為了方便起見，您可以在新的標頭檔中執行這些步驟，然後將它包括在應用程式中需要它的位置。

取得 IDXGraphicsAnalysis 介面

您需要先建立 DXGI 偵錯介面的介面，才能從 DirectX 11.2 擷取圖形資訊。

取得 IDXGraphicsAnalysis 介面

請使用下列程式碼將 IDXGraphicsAnalysis 介面連結到 DXGI 偵錯介面。
```
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 不支援這類介面。

注意事項
如果應用程式未在圖形診斷下執行 (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 使用 Visual Studio 的遠端工具來提供擷取功能。要執行應用程式的電腦必須已安裝遠端工具，即使在本機電腦上使用程式設計擷取也是一樣。當您在本機電腦上執行程式設計擷取時，不需要執行 Visual Studio。

若要在於電腦上執行的應用程式中使用遠端擷取 API，則需要先在該電腦上安裝 Visual Studio 遠端工具。不同版本的遠端工具支援不同的硬體平台。如需如何安裝遠端工具的詳細資訊，請參閱 Microsoft 下載網站的遠端工具下載頁面。

或者，Visual Studio 會安裝必要元件來執行 32 位元應用程式的遠端擷取。

注意事項
因為 ARM 裝置的 Windows 8 不支援大部分的 Windows 桌面應用程式 (包括 Visual Studio)，所以搭配程式設計擷取 API 使用 Visual Studio 遠端工具，是在 ARM 裝置上擷取圖形診斷的唯一方式。

準備應用程式以使用程式設計擷取

若要使用圖形診斷工具，您需要先擷取它所依賴的圖形資訊。您可以使用 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\使用者名稱\AppData\Local\Packages\套件系列名稱\TempState\ 這類位置中。針對桌面應用程式，暫存目錄的位置是每位使用者特有的，而且通常位於 C:\Users\使用者名稱\AppData\Local\Temp\ 這類位置中。

注意事項
若要寫入至特定位置，您必須具有寫入至該位置的權限；否則會發生錯誤。請記住，在寫入資料的位置方面，Windows 市集應用程式的限制多於桌面應用程式，而且可能需要進行額外設定才能寫入至特定位置。

擷取圖形資訊

準備好應用程式，以供進行程式設計擷取，並選擇性地設定圖形記錄檔的位置和名稱之後，請建置應用程式，然後執行它，或對它進行偵錯以擷取資料；當您使用程式設計擷取 API 時，請勿從 Visual Studio 啟動圖形診斷。圖形記錄會寫入至您指定的位置。如果您想要保留這版的記錄檔，請將它移至另一個位置；否則，將會於再次執行應用程式時遭到覆寫。

提示

使用程式設計擷取時，還是可以手動擷取圖形資訊；如果應用程式在焦點中，則只需要按 Print Screen 鍵。您可以使用此技術，擷取程式設計擷取 API 未擷取到的其他圖形資訊。

後續步驟

此逐步解說示範如何透過程式設計方式擷取圖形資訊。下一步是考慮此選項：

了解如何使用圖形診斷工具分析擷取到的圖形資訊。請參閱圖形診斷概觀。

共用方式為

逐步解說：以程式設計方式擷取圖形資訊

DirectX 11.2 中的程式設計擷取

準備應用程式以使用程式設計擷取

包括程式設計擷取標頭

定義 IDXGraphicsAnalysis 介面

取得 IDXGraphicsAnalysis 介面

取得 IDXGraphicsAnalysis 介面

擷取圖形資訊

擷取圖形資訊

DirectX 11.1 (含) 以前版本中的程式設計擷取

準備電腦以使用程式設計擷取

準備應用程式以使用程式設計擷取

準備應用程式以透過程式設計方式擷取圖形資訊

設定圖形記錄檔的名稱和位置

設定圖形記錄檔的名稱和位置

擷取圖形資訊

後續步驟

請參閱

工作

概念

其他資源