(I originally posted this on my MSDN blog.)
There are a couple of posts on the excellent Pandemonium game development blog (which sadly seems to have not been updated recently) that talk about the importance of making your game engine easily configurable and and diagnosable. That’s important for any application, of course, but it’s particularly critical for graphics engine where things happen in real-time and a lot of what you see on the screen is not easily interpreted to root causes. Diagnostic and configuration tools help you figure out what’s going on with your engine.
For GenesisEngine, I knew I wanted to have two debugging features:
- The ability to easily view the current configuration options and change them at runtime.
- The ability to view statistics and diagnostic information that would help me understand what the app is doing.
As I noted before, XNA doesn’t give you much help out of the box when it comes to building a UI with buttons, checkboxes, textboxes, and all those other things that we take for granted in standard Windows apps. Development tools are important but I didn’t want to spend a lot of time building them. Because I’m ok with my app being Windows-only right now, it made sense to try to use a Windows-based presentation system, like, say WPF.
The problem was that the XNA and WPF systems are very, very different and there wasn’t a whole lot of material that explained how to glue them together in one app. Fortunately, the answer is pretty simple even if it was a little hard to find so I’ll share it here to help out anyone else who may be wondering the same thing.
To be clear, my approach here is to display WPF windows from an XNA application. Embedding an XNA surface inside a WPF application is a whole different subject! And actually this has nothing to do with XNA: the approach found below will work for any kind of application where you want to control the main app thread yourself and run WPF on a secondary thread.
In order for WPF to work correctly, it needs a few things:
- A separate STA thread
- A thread dispatcher object for that thread
- A message pump
Here’s my WindowManager that makes those things happen:
public class WindowManager : IWindowManager, IDisposable
{
IContainer _container;
IScreenCustodian _settingsCustodian;
IScreenCustodian _statisticsCustodian;
Dispatcher _windowDispatcher;
public WindowManager(IContainer container)
{
_container = container;
StartUIThread();
_windowDispatcher.Invoke((Action)(() =>
{
// We pull these out of the container here instead of doing normal
// constructor injection because we need them to be created on this thread.
_settingsCustodian =
_container.GetInstance<IScreenCustodian>();
_statisticsCustodian =
_container.GetInstance<IScreenCustodian>();
}));
}
public void ShowAllWindows()
{
_windowDispatcher.Invoke((Action)(() =>
{
_settingsCustodian.ShowInactive();
_statisticsCustodian.ShowInactive();
}));
}
void StartUIThread()
{
var dispatcherCreatedEvent = new ManualResetEvent(false);
var thread = new Thread(() =>
{
_windowDispatcher = Dispatcher.CurrentDispatcher;
dispatcherCreatedEvent.Set();
Dispatcher.Run();
});
thread.SetApartmentState(ApartmentState.STA);
thread.IsBackground = true;
thread.Start();
dispatcherCreatedEvent.WaitOne();
}
public void Dispose()
{
if (_windowDispatcher != null)
{
_windowDispatcher.InvokeShutdown();
}
}
}
There are a few notable things here. First, all of the WPF-related objects need to be created on the WPF thread. I’m pulling them all out of my IoC container which means that they have to be pulled from the container on the WPF thread, not on the main app thread, which means that my WindowManager has to retrieve them from the container itself rather than having them injected. Side node: I may be over-relying on the container again here but I have a very simple UI system at the moment so I haven’t run into major problems.
Second, when the WindowManager creates the UI thread it sets it to use the STA threading model which WPF requires. It also makes it a background thread so that it won’t keep the application alive if the main thread quits. That’s appropriate for GenesisEngine but maybe not for other apps. The Event object is used to verify that the UI thread is indeed created and running before we continue.
Third, we call Dispatcher.Run to start the message pump on the UI thread. If this isn’t done then WPF won’t work.
Fourth, all interaction between the main app thread and the WPF elements has to go through Dispatch.Invoke to marshal the calls onto the UI thread. You can see that in the ShowAllWindows method.
Lastly, the WindowManager is disposable so that it can cleanly shut down the dispatcher’s message pump when appropriate. Actually, I suspect I still have an issue with clean shutdown somewhere because occasionally the MSpec runner will complain about mysterious errors when cleaning up my unit tests but I haven’t yet invested a lot of time in chasing down the root cause.
This code seems to work pretty well to create and display WPF windows for my XNA app. I’m not doing a whole lot with them yet; the statistics window updates itself once per second and shows a few interesting numbers but the settings window isn’t hooked up to anything yet. I’ll make more use of them shortly but the infrastructure appears to be working.
SaintGimp 