A Step-by-Step Overview

I mentioned in previous chapters that when I started into graphics programming, you had to do everything yourself. When graphics libraries such as OpenGL were released, it helped a lot. However, if you ever attempt to write an OpenGL program without LlamaWorks2D, you'll quickly discover one thing: there are lots of ways to get a blank screen. It's very easy to spend many frustrated hours trying to figure out why you're not seeing anything but an empty screen. Been there, done that, got the t-shirt.

The great thing about LlamaWorks2D is that it's incredibly easy to use. I designed it to make game programming as simple as possible. When you're starting out, you can ignore almost everything about the engine and you'll still get a decent result. It is written so that it provides a reasonable default value for virtually everything. Therefore, you can often avoid specifying information that the engine needs because anything you don't specify uses the default value. And when you use the default values, you should still see something reasonable on the screen.

To write a LlamaWorks2D program you must create a project in Dev-C++, configure it appropriately, and then start writing your game code. In your game code, you've got to create a software object called a game class. The game class requires some important information, but LlamaWorks2D provides straightforward ways of specifying it. Typically, an OpenGL or DirectX program requires that you write hundreds of lines of code before you can even get a working, but empty, window on the screen. With LlamaWorks2D, you can do that in fewer than 20 lines of code. Let's see how.

Phase 1: Create a Dev-C++ Project

It's time to create the project that will become your first LlamaWorks2D program. Here's how it's done.

Create a Project File and Add a .Cpp File to It.

1.	In your My Documents folder, create a folder called Dev-c++ projects.
2.	In the Dev-C++ Projects folder, create a folder called Simplegame.
3.	Insert the CD that comes with this book. Navigate to the folder <d>:\Source\Chapter04\Prog_04_01, where <d> is the letter of your CD-ROM drive. In that folder, you'll find a file called Prog_04_01.cpp. Copy it to the SimpleGame folder you created in step 2.
4.	Start Dev-C++ if it is not already running. From the File menu, select New and then Project.
5.	In the New Project dialog box, click on the Windows Application icon.
6.	Enter the name simplegame in the Name edit box. Make sure that the C++ Project radio button is selected. Click OK.
7.	In the dialog box that appears, navigate to the SimpleGame folder you created in step 2. Click Save.
8.	Right-click the main.cpp tab at the top of the edit window. In the menu that appears, choose Close, and then select No in the dialog box.
9.	Right-click the name SimpleGame in the Project pane that is along the left side of the Dev-C++ window. Choose Add to Project.
10.	In the dialog box that appears, find the SimpleGame folder that you created in Step 2. When you do, select the file Prog_04_01.cpp. Now click the Open button. This adds the file to the project.

That's all it takes to create the project.

Phase 2: Configure the Dev-C++ Project

The next task is to configure your project so that you can use it with LlamaWorks2D and OpenGL. When you installed Dev-C++ and OpenGL in chapter 2, you hopefully configured Dev-C++ to use OpenGL in all of your programs. Check to ensure that's done with the following instructions.

Ensure that Dev-C++ is Ready to Use OpenGL.

1.	From the Dev-C++ Tools menu, select Compiler Options.
2.	Ensure that there is a check in the check box that's labeled "Add these commands to the linker command line". If the check isn't there, add it now.
3.	In the edit box associated with the "Add these commands to the linker command line" check box, add the following command if it is not there already: <d>:\Dev-Cpp\lib\libopengl32.a Replace the <d> in this command with the letter of the drive where you installed Dev-C++. This is usually the C drive. If that's the case on your computer, the command should read C:\Dev-Cpp\lib\libopengl32.a
4.	Clear the check from the box labeled "Use fast but imperfect dependency generation". Click OK.

You're now ready to use OpenGL.

You also have to configure your project to use LlamaWorks2D. In the Introduction, the instructions had you install LlamaWorks2D into a folder in your Dev-C++ program directory. If you did not do that, please do it now using the instructions from the Introduction in the section called "Installing LlamaWorks2D." Once that's done, you can configure your project to use LlamaWorks2D.

Warning

Setting Dev-C++ to always link to the OpenGL library makes things much easier for the purposes of this book. However, if you want to use Dev-C++ to develop programs that do not use OpenGL, you must uncheck the box you checked in Step 2 and remove the command you inserted in Step 3.

Put LlamaWorks2D Into Your Program.

1.	Use Windows Explorer to copy the LlamaWorks2D files into the SimpleGame folder. If you followed the instructions in the Introduction, it will be in your Dev-Cpp folder, which is probably on your C drive. The whole path will be <d>:\Dev-Cpp\LlamaWorks2D\Source, where <d> is the letter of the drive where your Dev-Cpp folder resides.
2.	After you copy all the LlamaWorks2D files into the SimpleGame folder, right-click the project name in the Project pane. Select Add folder from the menu that appears. In the resulting dialog box, type llamaworks2d and than click OK.
3.	Right-click the LlamaWorks2D folder in the Project pane, and choose Add to Project from the context menu. In the dialog box that appears, navigate to the SimpleGame folder. Select all of the LlamaWorks2D files that you copied in Step 1. Click Open.
4.	Right-click the project name (SimpleGame) in the Project pane and select Project Options from the context menu.
5.	In the Project Options dialog box, click the Directories tab. On the Directories page, click the Include Directories tab. In the lower, single-line edit box, type the path to your LlamaWorks2D\Source directory. Most likely, the path will be C:\Dev-Cpp\LlamaWorks2D\Source. Click the Add button and then click OK.

Your Dev-C++ project is ready. Now let's write a LlamaWorks2D program.

Phase 3: Write a Game Class

To start writing a game with LlamaWorks2D, you must create a game class. Writing a game class is essentially like writing any other C++ class. Game classes have public member functions and private member data. They also require some additional features that typical C++ classes may not have.

I've provided a file, called Prog_04_01.cpp, that contains a minimal game class. It's on the CD in the folder \Source\Chapter04\Prog_04_01. You added it to your project in Phase 1. Listing 4.1 shows its contents.

Listing 4.1. The smallest possible LlamaWorks2D program

 1    #include "LlamaWorks2d.h" 2 3    using namespace llamaworks2d; 4 5    class my_game : public game 6    { 7    public: 8      ATTACH_MESSAGE_MAP; 9    private: 10   }; 11 12 13   CREATE_GAME_OBJECT(my_game); 14 15   START_MESSAGE_MAP(my_game) 16   END_MESSAGE_MAP(my_game) 

The file Prog_04_01.cpp begins by including the file LlamaWorks2D.h. Recall from chapter 2 that #include statements are a way of providing the compiler with the definitions that your program needs to compile. The file LlamaWorks2D.h is a kind of "ultimate include file" in the LlamaWorks2D game engine. All of the files you create for your games must include LlamaWorks2D.h. So you should put the statement you see on line 1 of Listing 4.1 at the beginning of all your C++ source files in your games.

Factoid

Programmers have a couple of different names for files they use with #include statements. They'll refer to them as either include files or header files.

The statement on line 3 must also be present to use the LlamaWorks2D game engine. Back in chapter 3, you saw that namespaces help group types, functions, and so forth into related collections. Everything the LlamaWorks2D game engine provides is in the llamaworks2d namespace. The using statement on line 3 saves you from having to put llamaworks2d:: at the beginning of every variable declaration in your program.

The definition of the game class itself begins on line 5. Notice at the end of the line that there's a colon, followed by the C++ keyword public, followed by the name game. I'll explain exactly what all that means in chapter 6, "Inheritance: Getting a Lot for a Little." For now, just know that it's required in your game class definition.

The statement on line 8 is a special marker called a macro. What it does is copy a whole bunch of C++ source code into your game class for you. The source code this macro inserts is part of the LlamaWorks2D engine. It adds a message map to your game class. A message map is a technique for assigning specific functions to handle player input. Message maps are widely used in all types of programs. (Message maps are presented in more detail in chapter 7, "Game Program Structure.") Every game class must have a message map. It does not matter whether your LlamaWorks2D program actually accepts player input. In fact, the program in Listing 4.1 ignores all player input. Even so, the game class in Listing 4.1 must have the statement shown on line 8 or it will not compile.

In addition to ATTACH_MESSAGE_MAP, LlamaWorks2D also provides you with other macros that insert a lot of source code into your game. This simplifies your life by saving you from having to write large amounts of code yourself. Line 13 of Listing 4.1 uses a macro to create an object from your game class. Recall that classes define what objects contain, but you don't have an object until you declare a variable. The macro on line 13 creates a variable of type my_game.

Warning

If you forget the ATTACH_MESSAGE_MAP; statement in your game class, the compiler outputs an error telling you that the function ProcessInputMessageMap() is not a member of your game class. If you see this error, you know you are missing the ATTACH_MESSAGE_MAP; statement in your game class.

If you change the name of your game class to something other than my_game, you need to put that name within the parentheses of the CREATE_GAME_OBJECT() macro; it has to contain the type name of your game class. In addition, this macro must always appear right after the definition of your game class.

The macros you see on lines 15 and 16 mark the beginning and ending of the game class's message map. As I mentioned, the message map does nothing at this point. However, it must be present for your game to compile.

Warning

If the compiler outputs an error stating that it cannot find the function CreateGameObject(), you did not put the CREATE_GAME_OBJECT() macro in your program. If it tells you that it cannot find the function ProcessInputMessageMap(), you don't have the START_MESSAGE_MAP() macro in your program. Whenever the compiler tells you that it found the beginning of another function before the end of ProcessInputMessageMap(), that means you left out the END_MESSAGE_MAP() macro.

Phase 4: Compile and Run the Program

Now comes the easy part. If you've done everything correctly, all you have to do is press F9 or select Compile & Run from the Dev-C++ Execute menu. Assuming all goes well, you'll see a nice blue window that covers most of your screen. Press Alt+F4 to close it.

That blue window may not seem like much, but it hides a lot that is going behind the scenes. The game engine initialized Windows and OpenGL for you. It sized and positioned to the window, and set its background color. While you gaze into the window's relaxing blueness, the game engine is displaying lots and lots of empty frames per second. It's checking for player input, even though it doesn't do anything with the input. It sits patiently waiting for you to add your unique and dazzling game elements so that it can display them. Not bad for just 16 lines of code.