Graphics Diagnostics Overview

  • Article

Graphics Diagnostics helps you debug rendering errors in DirectX games and apps.

Visual Studio 2013 requirements

To use Graphics Diagnostics in Visual Studio 2013, you must have one of these editions:

  • Visual Studio 2013 Ultimate

  • Visual Studio 2013 Premium

  • Visual Studio 2013 Professional

  • Visual Studio 2013 Express for Windows

Note

Visual Studio 2013 Express for Windows Desktop does not support Graphics Diagnostics features.

Operating system and SDK requirements

The Windows Software Development Kit (SDK) for Windows 8.1 installs the runtime components that are required by Graphics Diagnostics, and supports development for Windows 8.1 and Windows 8. To use Graphics Diagnostics on Windows 7 and Windows Vista, you must install one of the following SDKs:

  • Windows SDK (version 7.1)

  • DirectX SDK (June 2010)

DirectX version compatibility

Graphics Diagnostics supports apps that use Direct3D 10, Direct3D 10.1, Direct3D 11, Direct3D 11.1, and Direct3D 11.2, and provides limited support for apps that use Direct2D. It does not support apps that use earlier versions of Direct3D, DirectDraw, or other graphics APIs.

Windows 8.1 and Direct3D 11.2

In Windows 8.1, DirectX 11.2 introduces new features that include support for capturing graphics information through its runtime. Windows 8.1 uses the new runtime-based capture—known as robust capture—exclusively for all versions of DirectX that Windows 8.1 supports. Robust capture also supports new features of Direct3D 11.2.

Windows 8 and Windows 7 support

Because previous versions of Windows don't support DirectX 11.2, robust capture is unavailable on those platforms. Instead, apps running on Windows 8 or Windows 7 use the previous, detour-based capture method known as legacy capture. Because there's no need to support it on Windows 8.1, legacy capture is deprecated; however, it's still available to support apps running on Windows 8 or Windows 7.

Limited Direct2D support

Because Direct2D is a user-mode API that’s built on top of Direct3D, you can use Graphics Diagnostics to help debug rendering problems in apps that use Direct2D. However, because only the underlying Direct3D events are recorded instead of the higher-level Direct2D events, Direct2D events won't appear in the Graphics Event List. Also, because the relationship between Direct2D events and the resulting Direct3D events are not always clear, using Graphics Diagnostics to debug rendering problems in apps that use Direct2D is not straight forward. Still, you can use Graphics Diagnostics to get information about low-level rendering problems in apps that use Direct2D.

User Interface Changes in Visual Studio 2013 Update 3

Starting in Visual Studio 2013 Update 3, the Graphics Diagnostics tool windows are hosted in an independent copy of the Visual Studio shell to reduce the number of tool windows competing for limited space in the main Visual Studio IDE. The customized shell that now hosts the Graphics Diagnostics tools, called Visual Studio Graphics Analysis, eliminates menus and options that aren't needed by graphics diagnostics, but otherwise the graphics diagnostics tools and workflows are similar to Graphics Diagnostics in previous versions of Visual Studio.

There are two significant differences:

  1. When you run your app under Graphics Diagnostics, Visual Studio no longer displays a live version of the Graphics Log Document. Instead, Visual Studio provides a new capture interface. Here's what the new capture interface looks like:

    The GPU Usage tool.

    From this interface you can capture single or multiple frames to the graphics log, and view real-time graphs that display the frame-rate of your app, as well as the time in milliseconds that each frame takes to render.

  2. You cannot edit code in the Graphics Analysis shell; if you open code for editing in Graphics Analysis, it will be opened in the main Visual Studio IDE and given focus.

This interface is what you see in Visual Studio. To launch Visual Studio Graphics Analysis, choose one of the frames by following the Frame … link above the image thumbnail, or double-clicking the thumbnail.

Using Graphics Diagnostics to debug rendering problems

Debugging rendering problems in a graphically-rich app is not as straight-forward as starting a debugger and stepping through some code. In each frame, hundreds of thousands of unique pixels are produced, each according to a complex set of state, data, parameters, and code—of these, perhaps only a few pixels will exhibit the problem you are trying to diagnose. To complicate matters even further, the code that generates each pixel is executed on specialized hardware that processes hundreds of pixels in parallel. Traditional debugging tools and techniques—which are difficult to leverage in even lightly-threaded code—are ineffective when faced with so much data.

The Graphics Diagnostics tools in Visual Studio are designed to help you locate rendering problems by starting with the visual artifacts that indicate the problem and then tracing back to the source of the problem by focusing only on relevant shader code, pipeline stages, draw calls, resources, and device state—in the app's own source code.

Here are some of the kinds of rendering problems that Visual Studio can help you solve.

  • Device state
    Correct configuration of the graphics device is important because it determines how the graphics pipeline interprets the data associated with each draw call, and how draw call outputs are merged. For example, if the device state specifies the clockwise vertex winding order, then any model that specifies vertices in a counter-clockwise order will not be rendered correctly. Device state problems can be difficult to diagnose because the root of the problem in the source code is often far removed from the affected objects. By using Graphics Diagnostics, you can view the current device state at any time during rendering.

  • Uninitialized or incorrect constant buffers and parameters
    Graphics apps use constant buffers and parameters to pass additional data to a draw call or set of draw calls. For example, the data might specify different locations or appearances for different objects. When that data is not initialized or contains incorrect values, the corresponding object is rendered incorrectly, or perhaps not at all. This kind of problem can be difficult to diagnose because it's not always clear whether the problem is in the data or the shader code that consumes it. It can also be difficult to determine which shaders, constant buffers, and parameters correspond to the error. You can use Graphics Diagnostics to determine which shaders, constant buffers, and parameters apply to each draw call, and view their contents.

  • Shader bugs
    Making a mistake in app code is almost inevitable, whether the code is C++ or High Level Shader Language (HLSL). However, debugging HLSL code has traditionally been more difficult because it hasn't had the rich debugging support that C++ and other languages enjoy. Graphics Diagnostics brings traditional code debugging tools to HLSL so that you can step through code, set breakpoints, and examine the contents of variables, parameters, and constant buffers.

How Graphics Diagnostics works

To use Graphics Diagnostics, you first record information about how an app uses the Direct3D API as it runs, and then later examine the recorded behavior. For the specified frames, the information that’s recorded includes API calls—such as those that clear the screen, draw geometry, dispatch compute shaders, or change the state of the graphics device—together with their arguments, and copies of buffers and objects that are referenced indirectly. Additionally, API calls related to setup and initialization are recorded before any frames are rendered. The information that’s recorded is written to a graphics log (.vsglog) file.

You recreate the rendering behavior that’s recorded in the graphics log by playing back the graphics events on your development machine, or on a remote machine or device. The playback machine can be the same machine or device where the graphics log was originally captured, or a different one. For most playback features, the graphics hardware of the playback machine is used to play back graphics events, but when the HLSL debugger is used, the shader code is always played back by using an emulated GPU on the CPU. Using an emulated GPU makes it possible to step through the shader code, inspect variables, and use other common debugging features regardless of whether the graphics hardware in the playback machine supports hardware debugging.

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. 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 is embedded in the graphics log during capture.)

Note

Because certain APIs might not be available in previous versions of Windows or DirectX, you can't play back graphics logs that captured these API calls on a playback machine that doesn't support them.

Graphics logs

A graphics log contains one or more frames that were captured from a running DirectX graphics application. Because a graphics log is self-contained, these frames can be recreated at a later time and without external information or references. This means that you can share graphics logs with other developers, examine problems on different machines, and examine old graphics logs even when the models and textures have been changed in development. You can also load multiple graphics log (.vsglog) files at the same time to compare data and rendering results.

To open a graphics log (vsglog) file

  1. In Visual Studio, on the menu bar, choose File, Open, File. The Open File dialog box appears.

  2. Specify a graphics log (.vsglog) file to open, and then choose the Open button.

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.

The Graphics toolbar

The Graphics toolbar provides quick access to Graphics Diagnostics commands and tool windows.

The Graphics toolbar in graphics diagnostics mode

The Start Diagnostics button runs the app under Graphics Diagnostics. When an app is running under Graphics Diagnostics, the Capture the next rendered frame button is enabled, and you can use the other buttons to view the different tool windows. For more information about how to run your app under Graphics Diagnostics and capture graphics information, see Capturing Graphics Information.

Graphics Diagnostics tool windows

The following illustration shows a typical layout of the tool windows that are used to inspect and debug captured frames. Each window exposes a different category of information about the captured frame that's being inspected, and even about individual pixels in the frame.

All of the graphics debugger windows

DirectX control panel

The DirectX control panel is a component of DirectX that you can use to change the way that DirectX behaves—for example, you can enable the debug version of the DirectX runtime components, select the kind of debug messages that are reported, and disallow certain graphics hardware capabilities from being used to emulate less-capable hardware. This level of control over DirectX can help you debug and test your DirectX app. You can access the DirectX control panel from Visual Studio.

To open the DirectX control panel

  • On the menu bar, choose Debug, Graphics, DirectX Control Panel.

See Also

Concepts

HLSL Debugger