Beginning CSharp Game Programming (2005) [eng]

130Chapter 6 Setting Up a Framework

The next function renders the scene. It makes sure that there actually is a Direct3D device created, and if so, it clears the screen to blue and tells the device that it’s going to start drawing a scene. (As I’ve said previously, I’ll get into the graphics stuff in detail in Chapter 7.) Then the function ends the scene drawing and tells the device to present the scene to the viewer; this is just fancy-talk for saying it’s going to show what was actually rendered onto the monitor (or whatever device the user is using to view the game).

Next is the Run function, which is called when someone wants the game to run:

public void Run()

{

while (Created) { FrameMove(); Render();

Application.DoEvents();

}

}

This is just a simple loop that keeps looping while the form is “created.” Created is a Boolean property of the form that stays true when the form is valid, and turns false when the form is closed. For each loop, the function performs the game logic, renders the scene, and tells your application to handle all the events.

n o t e

The Application class is a static class that represents your application and provides useful functions, such as telling the program to handle events or to immediately shut down.

Windows Event Handlers

Every form has built-in event handlers for handling basic windows events, such as key presses and repainting the scene. Incidentally, the framework has functions to handle these events, also.

You should note that you don’t need to add these basic events to any event delegates any- where—Windows automatically knows to call these events when actions occur.

n o t e

The Form class has the event-handling functions built-in already, but they usually do nothing by default, which is why you must create your own and specify them as overrides. On occasion, however, they will perform extra functions, so you must remember to call the base versions on your own if you want to use the extra functionality. Look at the OnKeyPress example a bit further on to see what I’m talking about.

protected override void OnPaint(PaintEventArgs e)

{

this.Render();

}

The OnPaint event occurs whenever the program needs to be repainted, such as when a window is on top of your form and is then moved off, and so on. The framework simply tells the renderer to re-render the scene.

Next you have the key press event:

protected override void OnKeyPress(KeyPressEventArgs e)

{

base.OnKeyPress(e);

if ((int)e.KeyChar == (int)System.Windows.Forms.Keys.Escape) { this.Close();

}

}

The first thing this function does is call the base keypress function, Form.OnKeyPress. This is because the Form.OnKeyPress function actually does some useful processing for you. For example, if you have any GUI components on the screen, then pressing Tab should cause the window focus to go to the next GUI component. The Form.OnKeyPress function handles that for you, and I doubt you want to re-implement that functionality on your own.

Then Form.OnKeyPress checks to see if you pressed Escape, and if so, the form is told to close.

n o t e

This is going to change later on. It’s a bad idea to have a game close automatically when you press Escape inside of it.

The Entry Point

The final part of the framework is the entry point:

static void Main()

{

using (MainClass mainClass = new MainClass()) { if (!mainClass.InitializeGraphics()) {

MessageBox.Show(“Error while initializing Direct3D”); return;

}

mainClass.Show();

mainClass.Run();

}

}

132Chapter 6 Setting Up a Framework

This simply creates a new MainClass object (your window) and tries to initialize it. If it can’t be initialized, then an error message appears onscreen and the application exits.

n o t e

This example uses the using keyword in a way that you haven’t seen before. The code creates a using-block, in which the variable mainClass is valid. As soon as the block ends, C# immediately destructs the mainClass variable instead of waiting for the garbage collector to get around to it later on.

If the window was created successfully, then the Main function tells the window to show itself, and then calls the Run function. When you load this project up and run it, you should get what you see in Figure 6.3.

Figure 6.3 The framework window in action; it’s blank because nothing is being rendered yet!

Pressing Escape will cause the program to exit.

If you’re using SharpDevelop, load Demo 6.1 and hit F5. If you’re using Visual C#, then you need to do a bit more work to use this framework; I’ll go over it in the next section.

Visual C#

Visual C# is a very popular C# IDE made by Microsoft; it can be found in the Visual Studio package or as a product on its own. It’s a lot more complex than SharpDevelop, but that’s to be expected, as SharpDevelop is free, and VC# costs lots of money.

The framework from Demo 6.1 works perfectly well in Visual C#. You don’t even need to make any code changes. That’s the great thing about .NET and C#—they’re all completely

standardized, so the code will work across any compiler. With C++, you don’t really have that luxury because it’s implemented in 500 different ways across 500 different compilers. C# really makes your life so much easier.

To create a new project in Visual C#, open the File menu and select New Project. VC#’s project wizard should pop up and give you a bunch of options. You want to create an empty C# project, like Figure 6.4 shows.

Figure 6.4 The Visual C# project wizard

Next copy over the two .cs files from Demo 6.1 into the Demo 6.2 directory, and add them into the project manually.

You’re not done yet, unfortunately. C# projects can’t compile unless they know about all of the references needed for the project. In this case, you’re going to need to import the System and DirectX DLLs into your project. To do this, click on Project, Add Reference. A dialog box will appear, allowing you to make your project reference certain DLLs that you need. For this particular framework, you’re going to need to import the System.dll, System.Drawing.dll, System.Windows.Forms.dll, Microsoft.DirectX, and Microsoft.DirectX.Direct3D modules. (See Figure 6.5.) Appendix A goes over this process in more detail.

Once you’ve done that, your program knows what modules it needs to compile correctly, and you can hit F7 to compile and F5 to run the program. You’ll get the same output that you saw in Figure 6.3

Visual C#’s D3D Framework

You can use Visual C#’s application wizard to create a different D3D framework, but I’m not going to actually do so for this book. If you’ve ever used it, you’ll know why. The framework produced by Visual C# is incredibly complex and would take several chapters just to explain; I’m going to keep things nice and simple.

mind. The .NET framework was designed with application programmers in mind, so all it includes is a timer system that isn’t very accurate. When is the last time you saw a regular word-processing application require a millisecond-accuracy timer, anyway?

Luckily for you and me, the DirectX team at Microsoft decided to fix this problem and gave us a handy, high-precision timer, with time accuracy that no sane game programmer would ever need. We’re talking about microsecond accuracy here. I’m happy with just milliseconds, though.

n o t e

All Intel-compatible CPUs since the original Pentium have had a performance counter in them, which is what Windows uses to obtain this ultra-high-precision timing.

Microsoft provided a file called DXUtil.cs that contains this timer, but it’s kind of hidden away in the SDK. You can find it if you go into the Samples\C#\Common directory inside wherever you installed the DirectX 9 SDK.

Here’s an example of how to use the timer:

float time = DXUtil.Timer( DirectXTimer.GetAbsoluteTime );

The DXUtil class is static, and the Timer function returns a given time, depending on what values pass into it. The values are all part of an enumeration called DirectXTimer. The valid values are listed in Table 6.1.

Table 6.1 Timer Function Options

So there’s a fair amount of available options. You’ll notice that the time is represented as a float; that’s actually pretty handy. The unit of the float is the second, meaning that 1.0 represents one full second, and 0.001 represents one millisecond, and so on. The reason this is handy is that most of the time, you represent speeds and other assorted time-based

136Chapter 6 Setting Up a Framework

values in games as “units per second.” For example, a rocket may move 10 feet per second, so to get the amount of feet it moved for any given timer result, you just multiply the timer result by 10.

The DirectX timer keeps track of two different times, the absolute time and the application time. The absolute time usually represents how long the Windows operating system has been running since the last reboot (but this isn’t guaranteed), and the application time is modifiable by you.

Let me show you how to play around with the timer a bit:

// get the absolute time:

float t;

t = DXUtil.Timer( DirectXTimer.GetAbsoluteTime );

t = DXUtil.Timer( DirectXTimer.GetApplicationTime );

After those two calls, t was around 68,000 seconds for both calls, differing only by a few milliseconds. That’s around 19 hours, which is, coincidentally, the last time I rebooted.

When you first start your program, the application timer has the same value as the absolute timer, so it’s not really useful. To make it useful, you need to reset it:

DXUtil.Timer( DirectXTimer.Reset );

t = DXUtil.Timer( DirectXTimer.GetApplicationTime );

Now t will hold the number of seconds that have elapsed since the application timer was reset (probably much fewer than zero; on my system I got 0.000000838095332 as the result, meaning that 0.84 microseconds elapsed between those two calls).

You can also stop the timer:

DXUtil.Timer( DirectXTimer.Reset );

DXUtil.Timer( DirectXTimer.Stop );

f = DXUtil.Timer( DirectXTimer.GetApplicationTime );

f = DXUtil.Timer( DirectXTimer.GetApplicationTime );

DXUtil.Timer( DirectXTimer.Start );

f = DXUtil.Timer( DirectXTimer.GetApplicationTime );

The first time f was retrieved on my machine the result was 0.00000139482561 seconds. The very next line performs the call again, and the result is the same: 0.00000139482561 seconds. That means that 1.39 microseconds elapsed from the time the timer was reset to the time the timer was stopped, and, obviously, the timer doesn’t advance when it’s stopped.

After the timer was started again on my machine, f was filled in with 0.00000391111143, or 3.9 microseconds. This goes to show you that the time between resetting and stopping the timer added to the time between starting it up again and retrieving its value is a total of 3.9 microseconds. The amount of time spent retrieving the value while the timer was stopped isn’t counted at all.

Finally, the timer makes it easy to retrieve the elapsed time between calls:

DXUtil.Timer( DirectXTimer.GetElapsedTime );

f = DXUtil.Timer( DirectXTimer.GetElapsedTime );

The first call is to simply reset the elapsed time counter, so I don’t bother getting the value. The next call gives me how much time has elapsed since the last time I got the elapsed time value. In my case, it is simply 0.000000838095332 seconds, or 0.84 microseconds.

Problems with the Timer

I don’t like the DirectX application timer for one reason: it’s static, meaning that there’s only one timer. It isn’t very useful to have only one high-resolution timer in your entire program, because there are probably a lot of things that need timing, not just one thing. So I went ahead and did the reasonable thing: I created my very own expandable timer class, which you can find along with the Advanced Framework inside the Demo 6.3 directory in the file Timer.cs. This timer class is built on top of the existing DirectX timer, but it allows you to create many different timers, all running on different clocks. Most of the code is pretty straightforward and is built on top of the existing DirectX timer code, so I’m just going to show you the AdvancedFramework.Timer class outline and how to use it, instead of wasting precious time documenting silly timer code.

Here’s the class outline:

public class Timer

{

public static float Now() public Timer()

public void Reset()

public void Reset( float p_time )

public float Time() public float Elapsed()

public void Pause() public void Unpause()

}

The Now function is simply a wrapper around the absolute time function inside the DirectX timer. It’s a static function, so you don’t need any actual timers to call it:

float f = AdvancedFramework.Timer.Now();

138 Chapter 6 Setting Up a Framework

There are two Reset functions, allowing you to reset the timer to 0 or to whatever time you want:

AdvancedFramework.Timer t = new AdvancedFramework.Timer();

t.Reset( 60.0f ); // to 60 seconds

Then you can use the timer to get the amount of time passed since it was last reset:

or to get the amount of time elapsed since the last call to Elapsed:

And, of course, you can pause and unpause the timer:

// time does not advance for this timer anymore

This timer is a heck of a lot easier to use than the DirectX timer.

Changes to the Framework

As I said earlier, the Advanced framework is built on top of the SharpDevelop framework, with lots of minor changes that make it easier to use, cleaner to look at, and more gamerelated.

Namespaces

Here is an example of how the new framework makes things cleaner: the Microsoft. DirectX.Direct3D namespace is no longer implicitly used via the using command. That can make things somewhat confusing. All major DirectX components have classes they call

Devices, such as a DirectSound.Device and a DirectInput.Device. Therefore, it’s a bad idea to have code like this:

So the Advanced Framework uses namespace aliasing to create three new namespaces:

using Direct3D = Microsoft.DirectX.Direct3D;

using DirectSound = Microsoft.DirectX.DirectSound;

using DirectInput = Microsoft.DirectX.DirectInput;

Now you can just say Direct3D.Device or DirectSound.Device, and your program will be much more readable.

The Game Class

The Advanced Framework calls its main class Game. This isn’t really an important change (the old framework called it MainClass), as you’re probably going to end up changing it anyway, but I felt that MainClass sounded silly.

Along with the name change, I’ve added a bunch of static variables near the top of the framework so that you can change them easily if you need to:

static string gametitle = “Advanced Framework”;

static int screenwidth = 640;

static int screenheight = 480;

If you recall, these values were kind of hidden away inside the MainClass constructor in the first framework, so you had to hunt that function down if you wanted to change them.

Also added are some other statics:

A game timer is defined that will keep track of the current game time for you, and a paused variable is defined that determines whether the game is paused or not. Lastly, there are five devices defined: the graphics device; the sound device; and three input devices representing a keyboard, a mouse, and any other game input device (usually a joystick or a gamepad) that may be used.

Function Changes

The old framework just initialized the Direct3D system using an InitializeGraphics function. This new framework takes it one step further and adds two functions: InitializeSound and InitializeInput. You get a free cookie if you can guess what those do. I’m not going to post their code here, as you wouldn’t understand it now, anyway—I’m going to postpone that until Chapters 8 and 9.

The old FrameMove function has changed its name; it is now called ProcessFrame. I think that sounds better and more descriptive of what it actually does.