Debugging XNA graphics problems

Originally posted to Shawn Hargreaves Blog on MSDN, Wednesday, January 31, 2007

XNA Game Studio Express has good support for debugging C# code, but is not so helpful when it comes to diagnosing problems with your graphics rendering calls. Fortunately, the native DirectX SDK includes some tools that can be invaluable when your gorgeous graphics just ain't rendering right.

The first step is to install the latest DirectX SDK. This is not needed to develop XNA games (the end user runtime is enough for that) but you need it to get the debugging tools.

Now look in the Microsoft DirectX SDK / DirectX Utilities folder in your Start menu. In here you will find such gems as PIX for Windows and the DirectX Control Panel. I'm not going to talk about PIX here, other than to observe that it is just like totally awesome, dude, and you should definitely try it.

Inside the DirectX Control Panel is an exciting option labeled "Use Debug Version of Direct3D". There are also a bunch of scary looking checkboxes in the Debugging section, which I usually leave turned off because I have no idea what they do.

When you switch to the debug version of Direct3D, three things will happen:

1: Games will run slower. Usually only a little bit slower, but enough that you will want to switch back to the retail bits before doing any optimization work or playing other games. I leave my D3D in debug mode all the time while I am developing, though.

2: Your game may stop working entirely. This is because the regular release mode D3D runtime doesn't bother doing a lot of parameter validation, so it will often let things through even through they are technically wrong. Depending on your graphics card and driver, the wrong data might actually happen to work, so your game will seem fine, but then it will fall over when the debug runtime starts doing more careful validation. It is always a good idea to fix such problems, because even if you happen to be lucky on your particular machine, the wrong data is unlikely to work reliably on different computers even with the release runtime.

3: Direct3D will start printing out warnings and errors. You can control how chatty it gets using the Debug Output Level slider. I normally leave mine on the default (second of the five tick marks) because the higher settings include way too much information that I don't care about.

Now comes the bad news. Direct3D is printing native debug output, but C# Express only supports managed debugging, so there is no way to get these messages back into the XNA GSE IDE. Fortunately, there are many standalone applications that can display native OutputDebugString captures. This one seems good, but there are plenty to choose from.

Select the debug runtime, start up a capture utility, then run your game and see what it says. The output is often interesting and sometimes invaluable, as it can tell you exactly why a call is failing where the managed debugger might only see an InvalidOperationException that doesn't tell you what you did wrong.

Of course, this only works on Windows. For debugging Xbox graphics you have to rely on less scientific techniques, such as tea leaves, entrails, or a visit to the local palm reader...

Blog index   -   Back to my homepage