Debugging - one of the more infuriating aspects of software engineering. Also, one of the areas that far too few people know a lot about.

Quote:Debugging is twice as hard as writing the code in the first place. Therefore, if you write the code as cleverly as possible, you are, by definition, not smart enough to debug it.
- Brian W. Kernighan

I have this dream that people posting on various forums (not just this site) would make great posts where they detail the problem they've got, an isolated code fragment (not just a copy of the entire source file) and some of the debug spew that describes the error in question. It's definitely wishful thinking - it'll probably never happen[sad]

Because debugging is both difficult and essential, there are lots of tools to help you (do a Google search and see). Learning how to use them effectively is difficult, but it is a valuable skill nonetheless. I'm going to use this journal entry to describe, as simply as I can, how to set up Direct3D debugging.


The DirectX SDK (any version) has two very powerful debugging features: The Reference Rasterizer (Specify D3DDEVTYPE_REF when calling CreateDevice( )) and the Debug Runtimes. I'm going to cover the latter here..

STEP ONE: ACCESS THE DIRECTX CONTROL PANEL
If you have the DirectX SDK correctly installed, you should have an entry for it in your windows control panel:


(click to enlarge)

Launching it, you'll get a fairly familiar control-panel style window. From the tabs along the top, select "Direct3D", and you should see something like:


(click to enlarge)

STEP TWO: CHOOSING THE RIGHT SETTINGS
The key to it all is knowing which settings you want, and when to use them. Trial-and-error is good here, you'll find that some information just isn't of any use in some scenarios.

With reference to the previous image...

On the top-right is the selector for "Debug" or "Retail". You, as a developer will want to write your code against the "Debug" runtime, but when testing it (especially for performance) you'll want to work with the "Retail" runtime. You only get a "Debug" runtime installed with the SDK, so it almost certainly won't be there for any end-users that use your software.

On the top-left is a slider for "Debug Output Level" - this, obviously, only affects the debug runtime. Experimentation is needed with this - setting it all the way to "more" as in the screenshot can generate too much information in some cases.

The last interesting part is the "Debugging" group just below the runtime selection on the right. Allowing "Maximum Validation" is a good idea, and will produce better results; by default leaving the other 4 entries "off" is acceptable. When you encounter specific problems (such as memory leaks) then you should use them.

STEP THREE: SETTING UP DEBUGGING IN YOUR CODE
There are two things that you should do within your code to help out with debugging. For the record, I use Microsoft Visual C++ 7.0 (aka .Net 2002). The other .Net releases should be similar enough, but anything else and you're on your own for now.

The first thing is to make sure that your debug build is linking to the debug library: d3dx9d.lib (note the 'd' at the end of the name)


(click to enlarge)

Its a simple case of adding d3dx9d.lib to your "Additional Dependencies" field in the project settings. You should also have d3dx9.lib specified as a dependency for your "Release" build.

You can also do this as part of your source code if you prefer:


The second thing you can do - which is completely optional - is give Direct3D a hint that you want it to spit out a bit more information. If you define the D3D_DEBUG_INFO symbol before including d3dx9.h it will generate a bit of extra information at runtime. For the most part it's just extra information on the current setup (such as incorrect default renderstates), so may or may not be of much use to you.


STEP FOUR: GETTING YOUR DEBUG INFORMATION
You're now ready to go, so give your application a compile and execute [smile] You might notice that it runs somewhat slower than usual - this is simply because the debug runtime is doing a lot more work (and possibly outputting a lot of information) than the normal retail runtime.

In Visual Studio.Net there is a "Output" window as part of the IDE - it is here that you need to look to see your output. You can either keep it open whilst your application is running (only useful if you're running in windowed mode!) or look at it after you terminate your program. It should look something like this:


(click to enlarge)

The output shown is of a clean run of some code I'm currently working on, there aren't any "proper" errors in it. You might see that D3D9 Helper complains about a few things, but in this instance they're just default values that aren't set (note: never rely on default renderstates/values!)



(click to enlarge)

The above image is a better example - showing an unfortunately common output involving DirectX specific memory leaks. As we should all know - memory leaks == BAD, so a debug output like that shown above demands action [smile]

IN CONCLUSION
To keep things simple, I'll stop here. You should now have the main points regarding getting debug information. If people are interested, I'll carry this on sometime to go over interpretting common debug output and using it to pinpoint the exact pieces of code that it's complaining about [smile]

Hopefully the above is of some use, if you didn't already know about it before.

Now, I'm hoping there are two outcomes here:

1. You start using this (if you dont already) and learn to solve your own problems.

2. You start using this, and when asking online for help, you use it to help us help you by posing more complete and intelligent questions.

Option number 2 makes me happy, remember that [wink]

Till next time...
Jack