Exemplarische Vorgehensweise: Programmgesteuertes Erfassen von Grafikinformationen

Sie können die Visual Studio-Grafikdiagnose zur programmgesteuerten Erfassung von Grafikinformationen aus einer Direct3D-App verwenden.

Die programmgesteuerte Erfassung ist im Allgemeinen sinnvoll zum Debugging von Compute-Shadern in Programmen, die niemals Present aufrufen, oder wenn ein Renderingproblem schwer durch manuelles Testen zu antizipieren und zu erfassen ist, aber programmgesteuert mithilfe von Informationen über den Status der App zur Laufzeit vorhergesagt werden kann.

Programmgesteuerte Erfassung in DirectX 11.2

In diesem Teil der exemplarischen Vorgehensweise wird die programmgesteuerte Erfassung in Apps gezeigt, die die API DirectX 11.2 verwenden, in der die Methode der stabilen Erfassung zur Anwendung kommt. Informationen zur Verwendung der programmgesteuerten Erfassung in Apps, die frühere Versionen von DirectX verwenden, finden Sie unter Programmatic capture in DirectX 11.1 and earlier weiter unten in diesem Artikel.

In diesem Abschnitt wird gezeigt, wie folgende Aufgaben ausgeführt werden:

• Vorbereiten Ihrer App für die Verwendung der programmgesteuerten Erfassung

• Abrufen der Schnittstelle IDXGraphicsAnalysis

• Aufzeichnen von Grafikinformationen

Vorbereiten Ihrer App für die Verwendung der programmgesteuerten Erfassung

Die Vorbereitung Ihrer Direct3D 11.2-App der Verwendung der programmgesteuerten Erfassung ist ein Prozess in zwei Schritten. Stellen Sie zuerst sicher, dass die Header-Dateien vorhanden sind, die für die programmgesteuerte Erfassung erforderlich sind, und definieren Sie dann die Schnittstelle IDXGraphicsAnalysis im Quellcode Ihrer App.

So schließen Sie die Header für die programmgesteuerte Erfassung ein

• Schließen Sie diese Header in die Quelldatei ein, in der Sie die IDXGraphicsAnalysis-Schnittstelle definieren:

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

  Wichtig

  Schließen Sie nicht die Header-Datei vsgcapture.h ein – diese unterstützt die programmgesteuerte Erfassung in DirectX 11.1 und früheren Versionen –, um die programmgesteuerte Erfassung in Ihren DirectX 11.2-Apps durchzuführen.Dieser Header ist nicht mit DirectX 11.2 kompatibel.Wenn diese Datei eingeschlossen wird, nachdem der Header d3d11_2 eingeschlossen wurde, gibt der Compiler eine Warnung aus.Wenn vsgcapture.h vor d3d11_2 eingeschlossen wird, startet die App nicht.

  Hinweis

  Wenn die DirectX SDK vom Juni 2010 auf Ihrem Computer installiert wurde und der Include-Pfad Ihres Projekts %DXSDK_DIR%include\x86 enthält, verschieben Sie diesen Teil an das Ende des Include-Pfads.Gehen Sie beim Bibliothekspfad genauso vor.

So definieren Sie die IDXGraphicsAnalysis-Schnittstelle

• Definieren Sie die IDXGraphicsAnalysis-Schnittstelle in derselben Datei, in die Sie die Headerdateien eingeschlossen haben.

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

Der Einfachheit halber können Sie diese Schritte in einer neuen Header-Datei ausführen und diese dann dort einschließen, wo Sie sie in Ihrer App benötigen.

Abrufen der Schnittstelle IDXGraphicsAnalysis

Bevor Sie Grafikinformationen von DirectX 11.2 erfassen können, müssen Sie eine Schnittstelle zur DXGI-Debugschnittstelle erstellen.

So rufen Sie die IDXGraphicsAnalysis-Schnittstelle ab

• Verwenden Sie den folgenden Code, um die IDXGraphicsAnalysis-Schnittstelle an die DXGI-Debugschnittstelle anzuschließen.

  IDXGraphicsAnalysis* pGraphicsAnalysis;
  HRESULT getAnalysis = DXGIGetDebugInterface1(0, __uuidof(pGraphicsAnalysis), reinterpret_cast<void**>(&pGraphicsAnalysis));
  

  Prüfen Sie unbedingt das von DXGIGetDebugInterface1 zurückgegebene HRESULT, um sicherzugehen, dass Sie eine gültige Schnittstelle verwenden:

  if (FAILED(getAnalysis))
  {
      // Abort program or disable programmatic capture in your app.
  }
  

  Hinweis

  Wenn die App unter der Grafikdiagnose (Alt+F5 in Visual Studio) nicht läuft, gibt DXGIGetDebugInterface1 einen Fehler zurück: E_NOINTERFACE Eine solche Schnittstelle wird nicht unterstützt.

Aufzeichnen von Grafikinformationen

Wenn Sie nun über eine gültige IDXGraphicsAnalysis-Schnittstelle verfügen, können Sie BeginCapture und EndCapture verwenden, um Grafikinformationen zu erfassen.

So erfassen Grafikinformationen

• Verwenden Sie BeginCapture, um mit der Erfassung von Grafikinformationen zu beginnen:

  ...
  pGraphicsAnalysis->BeginCapture();
  ...
  

  Die Erfassung beginnt sofort, wenn BeginCapture aufgerufen wird; es wird auf den nächsten Frame gewartet. Die Erfassung stoppt, wenn der aktuelle Frame dargestellt wird oder wenn Sie EndCapture aufrufen:

  ...
  pGraphicsAnalysis->EndCapture();
  ...
  

Programmatische Erfassung in DirectX 11.1 und früher

In diesem Teil der exemplarischen Vorgehensweise wird die programmgesteuerte Erfassung in Apps gezeigt, die die API DirectX 11.1 verwenden, in der die Methode der Legacy-Erfassung zur Anwendung kommt. Informationen zur Verwendung der programmgesteuerten Erfassung in Apps, die DirectX 11.2 verwenden, finden Sie unter Programmatic capture in DirectX 11.2 weiter oben in diesem Artikel.

In diesem Teil werden folgende Aufgaben vorgestellt:

• Vorbereiten Ihres Computers für die Verwendung der programmgesteuerten Erfassung

• Vorbereiten Ihrer App für die Verwendung der programmgesteuerten Erfassung

• Konfigurieren des Namens und des Ortes der Grafikprotokolldatei

• Verwenden der CaptureCurrentFrame-API

Vorbereiten Ihres Computers für die Verwendung der programmgesteuerten Erfassung

Die API für die programmgesteuerte Erfassung verwendet Remote-Tools für Visual Studio, um die Erfassungsfunktionen bereitzustellen. Auf dem Computer, auf dem die App läuft, müssen die Remote-Tools installiert sein, auch wenn Sie die programmgesteuerte Erfassung auf Ihrem lokalen Computer anwenden. Visual Studio muss nicht laufen, wenn Sie die programmgesteuerte Erfassung auf einem lokalen Computer durchführen.

Um die APIs für die Remote-Erfassung in einer App zu verwenden, die auf einem Computer läuft, müssen Sie zuerst die Remote-Tools für Visual Studio auf diesem Computer installieren. Verschiedene Versionen der Remote-Tools unterstützen verschiedene Hardwareplattformen. Informationen zur Installation der Remote-Tools finden Sie auf der Download-Seite für die Remote Tools auf der Download-Website von Microsoft.

Alternativ werden durch Visual Studio die erforderlichen Komponenten zur Durchführung der Remote-Erfassung für 32-Bit-Apps installiert.

Vorbereiten Ihrer App für die Verwendung der programmgesteuerten Erfassung

Sie müssen zunächst die benötigten Grafikinformationen erfassen, um die Grafikdiagnosetools verwenden zu können. Sie können die Informationen mithilfe der CaptureCurrentFrame-API programmgesteuert erfassen.

So bereiten Sie Ihre App für die programmgesteuerte Erfassung von Grafikinformationen vor

1. Stellen Sie sicher, dass der Header vsgcapture.h im Quellcode für die App enthalten ist. Dieser kann an nur einem Ort eingeschlossen werden – z. B. in der Quellcodedatei, in der Sie die API für die programmgesteuerte Erfassung aufrufen, oder in einer vorkompilierten Headerdatei zum Aufrufen der API aus mehreren Quellcodedateien.

2. Rufen Sie im Quellcode für die App immer dann, wenn Sie den Rest des aktuellen Frames erfassen möchten, g_pVsgDbg->CaptureCurrentFrame() auf. Mit dieser Methode werden keine Parameter übernommen und keine Werte zurückgegeben.

Konfigurieren des Namens und des Ortes der Grafikprotokolldatei

Das Grafikprotokoll wird an dem Ort erstellt, der durch die Makros DONT_SAVE_VSGLOG_TO_TEMP und VSG_DEFAULT_RUN_FILENAME definiert ist.

So konfigurieren Sie den Namen und den Ort der Grafikprotokolldatei

• Fügen Sie vor der Zeile #include <vsgcapture.h> Folgendes ein, um zu verhindern, dass das Grafikprotokoll in das Temp-Verzeichnis geschrieben wird:

  #define DONT_SAVE_VSGLOG_TO_TEMP
  

  Sie können diesen Wert definieren, um das Grafikprotokoll an einen Ort zu schreiben, der sich im Arbeitsverzeichnis befindet, oder in einen absoluten Pfad, wenn die Definition von VSG_DEFAULT_RUN_FILENAME ein absoluter Pfad ist.

• Fügen Sie vor der Zeile #include <vsgcapture.h> Folgendes ein, um das Grafikprotokoll an einem anderen Ort zu speichern oder ihm einen anderen Dateinamen zu geben:

  #define VSG_DEFAULT_RUN_FILENAME <filename>
  

  Wenn Sie diesen Schritt nicht ausführen, lautet der Dateiname default.vsglog. Wenn Sie DONT_SAVE_VSGLOG_TO_TEMP nicht definiert haben, ist der Speicherort der Datei relativ zum Temp-Verzeichnis; andernfalls ist er relativ zum Arbeitsverzeichnis oder an einem anderen Speicherort, wenn Sie einen absoluten Dateinamen angegeben haben.

Bei Windows Store-Apps ist der Ort des Temp-Verzeichnisses für jeden Benutzer und jede App spezifisch, und der Pfad lautet normalerweise C:\Benutzer\Benutzername\AppData\Local\Packages\Paketfamilienname\TempState\. Bei Desktop-Apps ist der Ort des Temp-Verzeichnisses für jeden Benutzer spezifisch, und der Pfad lautet normalerweise C:\Benutzer\Benutzername\AppData\Local\Temp\.

Erfassung der Grafikinformationen

Wenn Sie die App für die programmgesteuerte Erfassung vorbereitet und optional den Speicherort und den Namen der Grafikprotokolldatei konfiguriert haben, erstellen Sie die App, und führen Sie sie dann aus, oder debuggen Sie sie, um die Daten zu erfassen; starten Sie nicht die Grafikdiagnose aus Visual Studio, wenn Sie die API für die programmgesteuerte Erfassung verwenden. Das Grafikprotokoll wird in den von Ihnen angegebene Speicherort geschrieben. Wenn Sie diese Version des Protokolls behalten möchten, verschieben Sie sie an einen anderen Speicherort; andernfalls wird sie überschrieben, wenn Sie die App erneut ausführen.

Nächste Schritte

In dieser exemplarische Vorgehensweise wurde veranschaulicht, wie Grafikinformationen programmatisch erfasst werden. Im nächsten Schritt haben Sie folgende Möglichkeit:

• Erfahren Sie, wie Sie erfasste Grafikinformationen mithilfe der Grafikdiagnose-Tools analysieren können. Siehe Übersicht über die Grafikdiagnose.

Siehe auch

Aufgaben

Exemplarische Vorgehensweise: Erfassen von Grafikinformationen

Konzepte

Erfassen von Grafikinformationen