Debug Info

Introduction

The Control Panel

Managed DirectX

D3DX

Introduction

The debug version of DirectX (you did install the Debug version, right?) is an invaluable tool. Often finding the cause of a bug is as easy as viewing the Debug output generated by the Debug libraries. Both errors and warnings are output and paying close attention to them will help you make a solid, well performing application.

The output of the debug libraries is sent to the same place as anything passed to the OutputDebugString Win32 function. If you use Microsoft Visual C++, there is a debug window as part of the IDE. When you run an app from within the IDE, the debug window is shown at the bottom of the IDE window. If you do not have MSVC++ or want/need to run your app outside of the IDE, then you can download DebugView from SysInternals. It's completely free and very handy to have around.

The Control Panel

If you've installed the Debug version of DirectX then it will have added an icon to your control panel. Run the application and you will see a window with 1 tab for each major component of DirectX. On these tabs are various controls that will assist you in debugging your DirectX applications.

Select the Direct3D tab. There are a number of things presented here, but we're mostly interested in 2 of them: Debug Output Level and Debug/Retail D3D Runtime.

Debug Output Level, as you would probably guess, regulates how verbose the messages it sends are. Set it to the lowest level and very few messages will be sent. Set it to the highest level and you will be swimming in output (hence the term "Debug Spew", which is often used to refer to this debug output). Setting it somewhere in the middle is a good default.

Debug/Retail D3D Runtime chooses whether applications will use the Retail or Debug libraries when they run. This allows you to switch to the more optimized Retail libraries for profiling or gaming, while being able to quickly switch back to Debug for development.

Managed DirectX

If you are using Managed DirectX there is one thing you need to do in addition to the steps listed above. Go to the project settings and under Debugging, set Enable Unmanaged Debugging to true. Without this the Debug output will not be visible.

D3DX

All of this works well for the standard DirectX DLLs since they're dynamically linked, but what about D3DX? In the Lib directory of the SDK you will see 3 different versions of the D3DX9 library. There is a retail library, a debug library, and a debug library that actually uses a DLL. I've never really understood the point of that last one, so we'll focus on the first two.

When you link with the debug version of D3DX, you get the same benefits of debug output as with the standard DirectX libraries. Typically you'll want to link with the debug library in your debug builds, and the retail library in your retail builds. Since I use the #pragma comment mechanism to link libraries, all it takes is a little #ifdef magic and you're done. Here's the code snippet:

#ifdef _DEBUG
  #pragma comment(lib,"d3dx9d.lib")
#else
  #pragma comment(lib,"d3dx9.lib")
#endif
Back