Debugging DirectX Applications

This section covers the following topics pertaining to debugging C and C++ applications.

Debug vs. Retail DLLs
Removing or Adding Debug DLLs
Other Resources

Debug vs. Retail DLLs

The Microsoft DirectX software development kit (SDK) installation program provides the option of installing either debug or retail builds of the DirectX dynamic-link libraries (DLLs).

When you develop software in C++, it is best to install the debug versions of the DLLs. This option installs both debug and retail DLLs on your system (the retail version installs only the retail DLLs). The debug DLLs have additional code that validates internal data structures and outputs debug error messages, using the OutputDebugString function while your program is executing. When an error occurs, the debug output gives you a more detailed description of the problem. The debug DLLs run more slowly than the retail DLLs but are much more useful for debugging an application. Be sure to ship the retail version with your application.

If you have the debug SDK installed, you can use the DirectX Control Panel utility to switch between the debug and retail builds of most components. To enable this feature, select the Debug option when you install the SDK.

To see the debug messages, configure your system so that debug output appears in a window or on a remote computer. A development environment such as Microsoft Visual Studio .NET enables you to do this. Consult the environment documentation for setup instructions.

To ensure that the debugger can find the relevant symbolic information when using debug builds, locate the symbol files as follows:

Operating system	Debugger	.pdb file location	.dbg file location
Microsoft Windows 98	Microsoft Visual C++	Same directory as binary	Same directory as binary
Windows 2000	Visual Studio .NET	Same directory as binary	%SystemRoot%\Symbols\<binary extension>\
Microsoft Windows NT, Windows 2000	Visual C++	Same directory as binary	%SystemRoot%\Symbols\<binary extension>\
Windows NT, Windows 2000	NTSD/KD	%SystemRoot%\Symbols\<binary extension>\	%SystemRoot%\Symbols\<binary extension>\
Windows XP	Visual Studio .NET	Same directory as binary	%SystemRoot%\Symbols\<binary extension>\

Note When debugging with the Visual C++ development system on Windows NT or Windows 2000, do not use the Splitsym development tool. Splitsym copies private symbolic information from the <binary>.dbg file into the symbol directory under the binary extension—for example, %SystemRoot%\Symbols\Dll\—and deletes the original file from the binary directory. Visual C++ relies on finding a private symbolic information (<binary>.dbg) file in the same directory as the binary. Therefore, for debug builds, you must copy the private symbolic information and not delete it. This is an issue only when using Visual C++ with Windows NT or Windows 2000. Consult Visual C++ documentation and Windows 2000 Driver Development Kit (DDK) documentation for more debugging information.

Removing or Adding Debug DLLs

If you installed the retail runtime and would like to change to the debug runtime, run Dxsetup.exe, which is located in the (SDK root)\Redist\DirectX9\ folder.

If you have the debug runtime and would like to revert to the retail runtime, run Undxxpdebug.exe, which is located in the Windows System folder. You can also run this by selecting Run from the Start menu and typing undxxpdebug in the box.

Note If you are using Windows 98, Windows Millennium Edition (Windows Me) or Windows 2000, you will need to uninstall the DirectX SDK in order to remove the debug version of the runtime.

Other Resources

To find C++ memory corruption problems, consider using a memory corruption/leak tool like Compuware's BoundsChecker .

Microsoft maintains a database of "knowledge base" articles on MSDN. Go to msdn.microsoft.com and search for Knowledge Base Articles. Then search for the topic you need.

The AppVerifier tool monitors an application for things like heap corruption, locks usage, invalid handles, and thread stack size checking. To find the tool, search for Testing Applications with AppVerifier on the MSDN Library .