Walkthrough: Capturing Graphics Information Programmatically

  • Article

This walkthrough demonstrates how to use the Visual Studio Graphics Diagnostics to programmatically capture graphics information from a Direct3D app.

This walkthrough illustrates these tasks:

  • Preparing your computer to use programmatic capture.

  • Preparing your app to use programmatic capture.

  • Configuring the name and location of the graphics log file.

  • Using the CaptureCurrentFrame API.

Preparing your computer to use programmatic capture

The programmatic capture API uses Remote Tools for Visual Studio to provide capture functionality. The computer where the app will run must have the remote tools installed, even when you are using programmatic capture on your local computer. Visual Studio doesn't have to be running when you perform programmatic capture on a local computer.

To use the remote capture APIs in an app that's running on a computer, you first have to install the Remote Tools for Visual Studio on that computer. Different versions of the remote tools support different hardware platforms. For information about how to install the remote tools, see the Remote Tools download page on the Microsoft downloads website.

Alternatively, Visual Studio installs the necessary components to perform remote capture for 32 bit apps.

Note

Because most Windows desktop apps—including Visual Studio—are not supported on Windows 8 for ARM devices, using Remote Tools for Visual Studio together with the programmatic capture API is the only way to capture graphics diagnostics on ARM devices.

Preparing your app to use programmatic capture

To use the Graphics Diagnostics tools, you first have to capture the graphics information that it relies on. You can programmatically capture the information by using the CaptureCurrentFrame API.

To prepare your app to capture graphics information programmatically

  1. Make sure that the vsgcapture.h header is included in the source code for the app. It can be included in just one location, for example, in the source code file where you will call the programmatic capture API, or in a precompiled header file to call the API from multiple source code files.

  2. In the source code for the app, whenever you want to capture the remainder of the current frame, call g_pVsgDbg->CaptureCurrentFrame(). This method takes no parameters and doesn't return a value.

Configuring the name and location of the graphics log file

The graphics log is created in the location that's defined by the DONT_SAVE_VSGLOG_TO_TEMP and VSG_DEFAULT_RUN_FILENAME macros.

To configure the name and location of the graphics log file

  • To prevent the graphics log from being written to the temp directory, before the #include <vsgcapture.h> line, add this:

    #define DONT_SAVE_VSGLOG_TO_TEMP

    You can define this value to write the graphics log to a location that's relative to the working directory, or to an absolute path if the definition of VSG_DEFAULT_RUN_FILENAME is an absolute path.

  • To save the graphics log to a different location, or give it a different file name, before the #include <vsgcapture.h> line, add this:

    #define VSG_DEFAULT_RUN_FILENAME <filename>

    If you don't perform this step, the file name is default.vsglog. If you didn't define DONT_SAVE_VSGLOG_TO_TEMP, then the location of the file is relative to the temp directory; otherwise, it's relative to the working directory or in another location if you specified an absolute file name.

For Windows Store apps, the location of the temp directory is specific to each user and app, and is typically found in a location such as C:\users\username\AppData\Local\Packages\package family name\TempState\. For desktop apps, the location of the temp directory is specific to each user and is typically found in a location such as C:\Users\username\AppData\Local\Temp\.

Note

To write to a specific location, you must have permissions to write to that location; otherwise, an error occurs. Keep in mind that Windows Store apps are more restricted than desktop apps about where they can write data, and might require additional configuration to write to certain locations.

Capturing the graphics information

After you have prepared the app for programmatic capture and optionally configured the location and name of the graphics log file, build the app and then run or debug it to capture data; do not start graphics diagnostics from Visual Studio when using the programmatic capture API. The graphics log is written to the location that you specified. If you want to keep this version of the log, move it to another location; otherwise, it will be overwritten when you run the app again.

Tip

You can still capture graphics information manually while using programmatic capture by pressing Print Screen with the app in focus. You can use this to capture additional graphics information that is not captured by your use of the programmatic capture API.

Next Steps

This walkthrough demonstrated how to capture graphics information programmatically. As a next step, consider this option:

  • Learn how to analyze captured graphics information by using the Graphics Diagnostics tools. See Graphics Diagnostics.

See Also

Tasks

Walkthrough: Capturing Graphics Information Manually

Concepts

Capturing Graphics Information