The DirectX 9 SDK now ships with the DirectX Sample Application Framework. With the sample framework, optimized DirectX initialization and management code are delivered free at the click of a button. I’m enthusiastic about the sample framework because developers will be able to begin work on DirectX games and simulations without re-engineering support code. But before we tour the sample framework, let’s take a look at the pain we can expect to avoid.
The Bad Old Days
In the past, many of the available example programs set up only the most basic DirectX 3D graphics requirements. Using Delphi and the wrapper units available from project Jedi for example, the following unmanaged code executes basic DirectX setup functions:
// wrapper unit from project Jedi, available from Borland code central uses D3D9;
var Direct3D9: IDirect3D9; Direct3DDevice8: IDirect3DDevice9;
procedure TfrmMain.FormCreate(Sender: TObject); var DisplayMode: TD3DDisplayMode; D3DPresent_Parameters: TD3DPresent_Parameters; begin Direct3D9 := Direct3DCreate9(D3D_SDK_VERSION); Direct3D9.GetAdapterDisplayMode(D3DADAPTER_DEFAULT, DisplayMode);
FillChar(D3DPresent_Parameters, SizeOf(TD3DPresent_Parameters), 0); with D3DPresent_Parameters do begin Windowed := True; hDeviceWindow := Handle; SwapEffect := D3DSWAPEFFECT_DISCARD; BackBufferFormat := DisplayMode.Format; end;
Direct3D9.CreateDevice(D3DADAPTER_DEFAULT, D3DDEVTYPE_HAL, Handle, D3DCREATE_SOFTWARE_VERTEXPROCESSING, D3DPresent_Parameters, Direct3DDevice8); end;
procedure TfrmMain.FormPaint(Sender: TObject); begin Direct3DDevice8.Clear(0, nil, D3DCLEAR_TARGET, D3DCOLOR_XRGB(0, 0, 255), 0, 0);
Direct3DDevice8.BeginScene; // assemble your scene here on the back buffer Direct3DDevice8.EndScene;
// swap your back buffer to the visible screen Direct3DDevice8.Present(nil, nil, 0, nil); end;
procedure TfrmMain.FormResize(Sender: TObject); begin FormPaint(Self); end;
What do you get with this example? A blue screen, which of course Microsoft used to supply automatically at nominal cost. What doesn’t this do? Besides the fact the example has no other visual content, the example does not:
- Handle device changes.
- Have an optimal message loop.
- Support text controls, edit boxes, or drop downs or any other basic UI that work in DirectX.
- Support switching between full and windowed screens
- Contain exception handling.
Fortunately you get all of the above for free using the DirectX Sample Application Framework that ships with the DirectX 9 SDK.
The Direct X Sample Application Framework
Your first step will be to install the latest DirectX 9 SDK from the msdn.microsoft.com DirectX download area. The download is about 220 Meg. After installing the SDK, run the DirectX Sample Browser from the SDK menu. Once you open the Sample Browser, you will probably spend the next couple hours exploring the very cool examples. When you get back, we can finish the article.
The DirectX Sample Browser
To create a new C# sample application, first find the entry labeled “EmptyProject”. To locate the entry quickly, select the “Managed” and “Samples” checkboxes on the left. Then click the “Install Project” link to bring up the Install dialog. Note: You may have a Visual Studio plug-in for DirectX projects but this only works for some versions.
Installing the Empty Project
In the Install dialog give your project a name and change the location if you’re not happy with the default Visual Studio Projects location. When you click “Install”, the project is created for you. Note that your prebuilt project includes a hefty amount of infrastructure code. Also notice that references for DirectX assemblies are added automatically to support 3D graphics and other graphic utility functions.
Checking out the new DirectX project
In the “Common” folder, you’ll find a number of support classes:
- The Framework class is defined in dxmut.cs. This class welds familiar Windows mechanics to the DirectX display details, including an implementation of a custom message loop. Graphics applications are typically organized around a “rendering loop”, the section of code that continually repaints the screen. A custom message loop avoids the use of less optimal paint or idle events for DirectX rendering.
- Your application automatically implements IFrameworkCallback and IDeviceCreation interfaces. IFrameworkCallback defines OnFrameRender to animate the scene and OnFrameMove for pre-rendering calculations. Both interfaces are called by the Framework class and are defined in dxmutdata.cs.
- Central to DirectX is the notion of direct access to the best capabilities of your hardware. The Enumerate class defined in Dxmutenum.cs discovers what graphics cards are available and the capabilities of each.
- Before the advent of the Sample Framework, if you wanted user input controls that worked in a DirectX environment, you had to write your own. DxmutGui.cs defines a working set of edit boxes, radio buttons, standard buttons, drop down, sliders and dialogs that are structured similar to the familiar Windows controls, but are actually rendered along with your 3D scene.
New Sample Application Running
All told, the DirectX Sample Application Framework delivers more than 16,000 lines of robust support code. This free functionality translates to code you don’t need to re-engineer and write just to get started game and simulation programming.