演练：以编程方式捕获图形信息

你可以使用 Visual Studio 图形诊断以编程方式从 Direct3D 应用中捕获图形信息。

编程捕获对于从不调用 Present 的程序中的调试计算着色器尤其有用，或者当在手动测试中难以预料和捕获呈现问题，但是可以通过使用有关运行时的应用状态信息，以编程方式进行预测时也尤其有用。

DirectX 11.2 中的编程捕获

本部分演练演示了使用 DirectX 11.2 API 的应用中的编程捕获，它使用可靠捕获方法。 有关如何在使用更早版的 DirectX 的应用中使用编程捕获的信息，请参阅本演练后面的 Programmatic capture in DirectX 11.1 and earlier。

本部分显示如何完成这些任务：

• 准备你的应用以使用编程捕获

• 获取 IDXGraphicsAnalysis 接口

• 捕获图形信息

准备你的应用以使用编程捕获

准备你的 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，则应用将不会启动。

  备注

  如果你的计算机上安装了 DirectX SDK（2010 年 6 月），并且你的项目的包括路径包含 %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 使用 Visual Studio 的远程工具来提供捕获功能。 将运行应用的计算机必须安装远程工具，即使你要在本地计算机上使用编程捕获也是如此。 在本地计算机上执行编程捕获时，不必运行 Visual Studio。

若要在正在计算机上运行的应用中使用远程捕获 API，首先，你必须在该计算机上安装 Visual Studio 的远程工具。 不同版本的远程工具支持不同的硬件平台。 有关如何安装远程工具的信息，请参阅 Microsoft 下载网站上的远程工具下载页。

或者，Visual Studio 将安装必需的组件来为 32 位应用执行远程捕获。

准备你的应用以使用编程捕获

若要使用图形诊断工具，首先，你必须捕获它所依赖的图形信息。 通过使用 CaptureCurrentFrame API，可采用编程方式捕获该信息。

准备你的应用以采用编程方式捕获图形信息

1. 确保 vsgcapture.h 标头包含在应用的源代码中。 它可能仅包含在一个位置中（例如，位于你将在其中调用编程捕获 API 的源代码文件中）或者包含在预编译的头文件中，以从多个源代码文件中调用 API。

2. 在应用的源代码中，无论何时你想要捕获当前帧的其余部分，都请调用 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\。

捕获图形信息

在准备好应用以用于编程捕获并有选择地配置好图形日志文件的位置和名称之后，请生成该应用，然后运行或调试它以捕获数据；当使用编程捕获 API 时，请不要从 Visual Studio 中启动图形诊断。 图形日志将写入你指定的位置。 如果你想要保留此版本的日志，请将它移动到另一个位置；否则，当你再次运行该应用时，会对其进行重写。

后续步骤

本演练演示了如何采用编程方式捕获图形信息。 下一步，请考虑此选项：

• 了解如何使用图形诊断工具分析捕获的图形信息。 请参阅图形诊断概述。

请参见

任务

演练：捕获图形信息

概念

捕获图形信息