Capturing Graphics Information

Article
04/28/2015

You can capture graphics information from your DirectX-based app so that you can use Visual Studio Graphics Diagnostics tools to diagnose rendering problems.

Capture methods

In Windows 8.1, the DirectX 11.2 runtime can capture graphics information internally on behalf of debugging tools like graphics diagnostics—this is known as robust capture. Before this support was added to the DirectX runtime, graphics information was captured by intercepting certain DirectX function calls to record arguments and other information before forwarding the calls to DirectX to be completed—this is called legacy capture.

Because the DirectX runtime takes exclusive responsibility for capturing graphics information in Windows 8.1, there is no need to update legacy capture to support DirectX 11.2, and therefore, legacy capture is deprecated. However, because the DirectX 11.2 runtime doesn't support versions of Windows prior to Windows 8.1, Visual Studio 2013 still supports legacy capture for apps that target Windows 8 and Windows 7.

Both methods record similar information and don't change how you capture graphics information or use the Graphics Diagnostics tools.

Robust capture

Robust capture supports Visual Studio 2013 graphics diagnostics on Windows 8.1, Windows RT 8.1, and Windows Phone 8.1. It supports DirectX 10.0 through DirectX 11.2 and can capture graphics information about new Direct3D 11.2 features—for example, tiled resources. However, it doesn't fully support all Direct3D 11.2 features—for example, you can't debug an HLSL shader that was created by using the HLSL shader linking feature. Robust capture uses a new capture API to support its programmatic capture scenarios.

Legacy capture

Legacy capture supports Visual Studio 2013 and Visual Studio 2012 graphics diagnostics on Windows 8, Windows RT 8, and Windows 7. It supports DirectX 10.0 through DirectX 11.1. Legacy capture doesn't support any Direct3D 11.2 features and is deprecated except for scenarios in which robust capture is not available. Legacy capture uses the capture API defined in the vsgcapture.h header file to support its programmatic capture scenarios. This kind of programmatic capture is also deprecated except for scenarios in which robust capture is not available.

Capturing graphics information

Capturing graphics information is a two-step process. First, run your app under Graphics Diagnostics, and then specify one or more frames to capture detailed information from.

To run your app under Graphics Diagnostics

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

While an app is running under Graphics Diagnostics, certain kinds of graphics information is captured all the time; this includes device set up, creation of the swap-chain, creation of graphics objects and resources, and other important events that affect more than one frame. At the same time, you can capture detailed information about specific frames; this includes draw calls and compute-shader dispatches, together with the Direct3D objects and resources that support them.

To capture a frame

In Visual Studio, on the Graphics Diagnostics toolbar, choose the Capture Frame button.
On the keyboard, press Print Screen.

Note

While an app is running under Graphics Diagnostics, the Print Screen key can only be used to capture a frame of graphics information; it doesn't perform its regular function. This remains in effect until you have stopped capturing graphics information—usually by stopping debugging or exiting the app normally—even if another application is in focus.
In Visual Studio 2013, Update 3 the interface for capturing frames has changed. In the Visual Studio capture interface, chose the Capture Frame button located above the Diagnostic session timeline, or choose the large Capture Frame button located below the Frames per second swim-lane and to the right of any previously-captured frames. Both buttons are highlighted in the image below.

When you're ready to examine the frames you've captured, Launch Visual Studio Graphics Analysis by following the Frame … link above the image thumbnails, or by double-clicking the thumbnail.

Only whole frames can be captured, so when you initiate a capture, it’s really the graphics information from the next frame that's recorded. Recording begins immediately after the frame in which you initiated capture is presented and ends when the captured frame is presented. You can capture as many frames as you want while the app is running under Graphics Diagnostics. If you don't capture any frames, the graphics log is discarded.

When you capture a frame for the first time, Visual Studio displays the graphics log (.vsglog) document window. If you close the graphics log window, stop debugging, or close the app, you can’t capture any more frames to that log. To capture more graphics information, you have to run the app under Graphics Diagnostics again to start a new graphics log.

Graphics Diagnostics Capture Options

You can configure capture to collect call stacks for all graphics events or a limited subset, disable the capture HUD, and enable or disable capture compatibility mode.

To configure Graphics Diagnostics capture options

On the menu bar, choose Tools, Options. The Options dialog box appears.
In the options category list on the left, choose Graphics Diagnostics, and then configure the Graphics Diagnostics options that you want.
- Collect call stacks during capture (makes capture slower)
  Check this box to collect call stacks. By default, call stacks are collected, and for draw, dispatch, present, and perf markers is selected. To capture call stacks for all events, select for everything. To not collect call stacks, uncheck Collect call stacks during capture (makes capture slower).
- Disable in-game HUD during capture
  Check this box to disable the HUD overlay that an app running under graphics diagnostics usually displays. Uncheck it to display the HUD overlay.
- Capture in compatibility mode
  Check this box to capture graphics information in compatibility mode. Capturing in compatibility mode is the default. Under compatibility mode, Direct3D won't report that the GPU supports any additional features beyond those defined in the base feature level. This prevents the app being captured from using hardware-specific extensions of the GPU its captured on and ensures that the graphics log can be played back using any GPU that supports the same or higher feature level. Uncheck this box to disable compatibility mode; logs captured with compatibility mode disabled will fail to play back on any GPU that doesn't support the same additional features that were used by the app during capture.

Capturing graphics information remotely

Graphics information can be captured from an app that's running on the local machine, or on a remote machine or device. Remote capture is supported for Windows 8.1 machines and Windows RT 8.1 devices. To capture graphics information from an app that's running remotely, configure your project for remote debugging and then run your app under Graphics Diagnostics as described earlier. The app runs on the remote machine, and the captured graphics information is recorded on your development machine.

How you configure your project for remote debugging depends on the kind of app you're developing and the programming language you're using. For information about how to configure remote debugging for a Windows Store app, see Run Windows Store apps on a remote machine from Visual Studio. For information about how to configure remote debugging for a Windows desktop app, see Set Up Remote Debugging for a Visual Studio Project.

Later, you can use a remote machine or device to play back graphics information, regardless of where the information was captured from. For more information, see How to: Change the Graphics Diagnostics Playback Machine.

Capturing graphics information from the command line

Graphics information can be captured from an app by using a command-line tool. This tool, DXCap.exe, can quickly capture and play back graphics information without using Visual Studio or programmatic capture. In particular, you can use DXCap.exe for automation, or in a test environment. For more information about DXCap.exe, see Command-Line Capture Tool