Capturing Graphics Information

Article
02/21/2014

You can capture graphics information to use with Visual Studio Graphics Diagnostics tools to diagnose rendering problems in DirectX-based apps.

You can capture graphics information either manually or programmatically. To capture manually, run the app from Visual Studio and then choose the Capture Frame button. To capture programmatically, use the capture API, which is included in Visual Studio, in the source code of your app to specify when frames should be captured.

You can also prevent graphics information from being captured from your app.

Capturing graphics information manually

Use the Capture Frame button on the Graphics Diagnostics toolbar to manually capture a frame of graphics information from a running Direct3D app. To capture multiple frames, choose the button multiple times. Before you can capture frames manually, you have to start the app from Visual Studio and have Graphics Diagnostics enabled.

Visual Studio uses the information that's captured to recreate the captured frames later so that you can use the Graphics Diagnostics tools to examine them in detail.

To start an app with Graphics Diagnostics enabled

On the menu bar, choose Debug, Graphics, Start Diagnostics. (Keyboard: Press Alt+F5)

After Graphics Diagnostics hooks an app, you can capture graphics information for as many frames as you want. Each time you initiate a capture, the Direct3D events that occur during the next frame are recorded, together with the Direct3D objects and resources that support them. Recording begins immediately after the current frame is presented and ends when the frame you want to capture is presented.

To capture a frame of graphics information

On the Graphics Diagnostics toolbar, choose the Capture Frame button.
On the keyboard, Press Print Screen.

When the first frame is captured, Visual Studio creates a graphics log to hold the information. Additional captured frames are added to this log. If you close the graphics log (.vsglog) document in Visual Studio while the app is running, you can't capture any more frames of graphics information, but you can continue to debug it by using the Visual Studio debugger. To capture more graphics information, stop debugging the app and then use the Start Diagnostics command to start the app again.

Capturing graphics information programmatically

Sometimes it's impractical or impossible to rely on manual capture to collect information about a rendering problem that you are trying to solve. For example, certain kinds of problems might be too intermittent to be reproduced manually, but the program conditions that cause it might be well-known; or you might have to collect graphics information on a system that doesn't support manual capture because it doesn't support Visual Studio, as is the case with Windows RT devices. For these scenarios, Visual Studio includes an API that you can call programmatically to capture graphics information to a log. After the program has finished running, you can open the graphics log in Visual Studio to investigate the problems that were recorded.

For information about how to enable programmatic capture in your app and how to configure the machine that will run it to support programmatic capture, see Walkthrough: Capturing Graphics Information Programmatically.

Preventing capture of graphics information

Before you publish your app, you can disable Graphics Diagnostics and other profiling tools to prevent users from discovering how your app uses the Direct3D API. This information could be used illicitly. For more information, see How to: Disable Graphics Diagnostics in Your App.

Graphics log documents

Graphics log documents store the graphics information that's gathered during a Graphics Diagnostics capture session. A capture session can be initiated manually or programmatically. Graphics logs contain one or more frames that were captured from a running DirectX graphics application. For each captured frame, a list of every Direct3D event that occurred during the frame is recorded. This includes supporting Direct3D events that occurred previously—for example, graphics device creation—and supporting shaders, models, textures, and other graphics resources. Because each graphics log is self-contained, these frames can be recreated, at any time, step-by-step, and without external information or references. You can share graphics logs, and you can examine problems on a machine other than the one that was used to capture the data or develop the code. Also, you can examine old graphics logs even when the models and textures have been changed in development. When you use Graphics Diagnostics to diagnose graphics problems, you can examine any Direct3D API call and its associated state, individual vertices in buffers, and even how individual pixels are affected by draw calls.

Note

Although a graphics log captures most of the relevant information internally, additional information is required to fully utilize some Graphics Diagnostics features. For example, to make full use of the graphics call stack feature, you also have to have the program database (.pdb) file and the app's source code, and to debug HLSL shader source code, you also have to have the shader source code (if the shader is compiled by using the D3D11.1 shader compiler and debugging information is enabled, then the shader source code will be embedded in the graphics log during capture).

Note

You can extract, modify, and save copies of meshes and textures from a graphics log by using graphics tools that are a part of Visual Studio. However, the contents of the graphics log are not affected by these modifications. For information about these graphics tools, see Working with 3-D Assets for Games and Apps.