ClanLib is a cross-platform C++ framework focused primarily on the needs of game developers. Although the API is streamlined for gaming, you could easily use ClanLib to develop a scientific 3D visualization tool or multimedia application (such as the Gecko Multimedia System).

ClanLib has APIs for 2D and 3D graphics, sound, network, I/O, input, and GUI and resource administration. It provides transparent support for OpenGL, so you can use native OpenGL commands while letting ClanLib handle the OS-dependent window management and everything else. ClanLib renders 2D graphics through DirectX or Simple Direct Media Layer (a platform-independent multimedia library). The ClanLib games page lists about 50 well-developed games, including puzzles, strategy, and shooter games in 2D and 3D. For example, Asteroid Arena (see Figure 1) uses ClanLib and OpenGL to one-up the arcade classic.

Figure 1. Screenshot of Asteroid Arena

ClanLib works on Windows, Linux, and MacOS and is supplied in source-only zip or tar files. Windows developers can use Microsoft Visual Studio, Borland C++, or MinGW (Minimalist GNU for Windows) compilers and environments. Third-party support for Ruby and Perl language bindings is also available. Optional extras include a Lua plug-in (the popular lightweight scripting language) and FreeType (a free TrueType font library).

Inside the ClanLib Feature Set

Before digging into the API, take a quick glance at its major features:

• Basic cross-platform runtime (GUI, threading, file I/O, and so forth)
• Template-based C++ signal/slots library (type-safe callbacks/delegates)
• Integrated resource management
• Sound mixer supporting .WAV files, Ogg Vorbis, and anything supported by the MikMod library (MOD, S3M, XM, and so on)
• Document Object Model (DOM) XML parser support
• High-level 2D graphics API supporting OpenGL, DirectX, and SDL as render targets
• Batch rendering engine for best performance when rendering 2D with OpenGL
• 2D collision detection
• 2D sprite animation support
• Highly customizable GUI framework
• Network library with low- to high-level interfaces

The Basic Gaming Model of ClanLib

Now, examine the ClanLib API model from the inside out. I've always found that the best tutorial is a fully explained example program. Specifically, you'll look inside Luke Worth's boxes, an electronic version of the two-player, paper-and-pencil game (see Figure 2). The boxes game consists of a grid of points between which players alternately draw lines. Whoever encloses a square with the final line, scores one point and gets to play another turn. (If you're eager to see the API reference first, by all means do so.)

Figure 2. A Boxes Game in Progress with a Score of Blue 8 and Red 3

I purposely kept the main program as short as possible to better highlight the "game loop:"

 1 #include <iostream>
 2 #include <ClanLib/application.h>
 3 #include <ClanLib/core.h>
 4 #include <ClanLib/display.h>
 5 #include <ClanLib/gl.h>
 6 #include <ClanLib/sound.h>
 7 #include <ClanLib/vorbis.h>
 8
 9 const int boardsize = 6, spacing = 50, border = 20;
10 const int numsquares = int(pow(float(boardsize - 1), 2));
11
12 enum coloursquare { off, blue, red };
13 struct cursor {
14    int x, y;
15    bool vert;
16 };
17
18 class Boxes: public CL_ClanApplication {
19    bool ver[boardsize][boardsize - 1];
20    bool hor[boardsize - 1][boardsize];
21    coloursquare squares[boardsize - 1][boardsize - 1];
22    bool redturn;
23    bool fullup;
24    cursor curs;
25
26    void inputHandler(const CL_InputEvent &i);
27    bool findsquares(void);
28    inline int numaroundsquare(int x, int y);
29    void init();
30    void drawBoard();
31    void endOfGame();
32
33 public:
34    virtual int Boxes::main(int, char **);
35 } app;
36
37 using namespace std;

40
41 int Boxes::main(int, char **)
42 {
43    int winsize = spacing * (boardsize - 1) + border * 2;
44    try {
45       Boxes::init();
46       while (!CL_Keyboard::get_keycode(CL_KEY_ESCAPE)) {
47          Boxes::drawBoard();
48          if (fullup) break;
49          CL_System::keep_alive(20);
50    }
51    Boxes::endOfGame();
52
53    CL_SetupVorbis::deinit();
54    CL_SetupSound::deinit();
55    CL_SetupGL::deinit();
56    CL_SetupDisplay::deinit();
57    CL_SetupCore::deinit();
58    }
59    catch (CL_Error err) {
60       std::cout << "Exception caught: "
                   << err.message.c_str()
                   << std::endl;
61    }
62
63 return 0;
64 }

The first thing to notice about this application is that the main() function (see line #41) is not a top-level function but rather is embedded in an object derived from CL_ClanApplication. This serves to encapsulate a lot of the inevitable platform dependencies that might surround a traditional ::main() implementation (such as having to use WinMain() in Win32 apps).

Also, note that virtually all the executable code (lines 43-58) are enclosed in a try{}/catch{} exception handler. ClanLib will throw exceptions if needed and you can restart a game, and the like. Basically, all program logic resides in init(), drawBoard(), endOfGame(), and inputHandler(). If the board has no more moves (fullup==true), you exit the game loop (in line 48). CL_System::keep_alive() updates all input and system events (like closing the window or moving it), and if given an argument, it will wait that many milliseconds before proceeding. This frees up CPU cycles in the vein of the old::Yield() from Win16 API or sleep() in Linux.

66 void Boxes::init()
67 {
68    CL_SetupCore::init();
69    CL_SetupDisplay::init();
70    CL_SetupGL::init();
71    CL_SetupSound::init();
72    CL_SetupVorbis::init();
73
74    CL_DisplayWindow window("Boxes", winsize, winsize);
75    CL_SoundOutput output(44100);    //44Khz sampling selected
76
77    CL_Surface *cursimg = new CL_Surface("cursor.tga");
78    cursimg->set_alignment(origin_center);
79    CL_Surface *redpict = new CL_Surface("handtransp.tga");
80    redpict->set_alignment(origin_center);
81    redpict->set_scale(float(spacing)/float(redpict->get_width()),
82       float(spacing)/float(redpict->get_height()));
83    CL_Surface *bluepict = new CL_Surface("circlehandtransp.tga");
84    bluepict->set_alignment(origin_center);
85    bluepict->set_scale(float(spacing) /
                float(bluepict->get_width()),
86              float(spacing) / float(bluepict->get_height()));
87

The init() method does mostly what you would expect from game setup: initializes needed subsystems of ClanLib for graphics and sound (lines 68-72) and then constructs a window to be used for all display graphics (line 75).

CL_Surface (lines 77-87) is a 2D bitmap class used for cursors, the blue-filled square, and the red-filled square (in other words, indicating that red won this square).

TGA files are bitmap file formats from the now obscure AT&T Targa Graphics Adapter (TGA). ClanLib has an integrated copy of PNG library, so it can read and write most popular bitmap file formats.

Next, you must initialize the board to an empty state (lines 87-103) and perform similar housekeeping for other game counters.

 89
 90    redturn = true;
 91    curs.vert = false;
 92    fullup = false;
 93    curs.x = curs.y = 1;
 94
 95    srand(CL_System::get_time());    // Seed random number
                                        // generator
 96
 97    for (int x = 0; x < boardsize - 1; x++) {
 98    for (int y = 0; y < boardsize; y++)
 99    hor[x][y] = ver[y][x] = false;
100
101    for (int y = 0; y < boardsize - 1; y++)
102    squares[x][y] = off;
103
104

An interesting aspect of ClanLib is that it eschews the traditional callback model used in many frameworks for the "signals and slots" model. This has been popularized by the Boost C++ library and implemented in QT (among other frameworks). Signals represent callbacks with multiple targets, and are also called publishers or events in similar systems. Signals are connected to some set of slots, which are callback receivers (also called event targets or subscribers), which are called when the signal is "emitted." Signals have the great advantage of being typesafe and they avoid the inevitable cast-a-thon seen in traditional frameworks.

Signals and slots are managed, in that signals and slots (or, more properly, objects that occur as part of the slots) track all connections and are capable of automatically disconnecting signal/slot connections when either is destroyed. This enables the user to make signal/slot connections without expending great effort to manage the lifetimes of those connections with regard to the lifetimes of all objects involved. In line 105, you just want to trap all the keypress ("down") events and insure your own inputHandler() is used (see lines 168-216).

105    CL_Slot keypress =
          CL_Keyboard::sig_key_down().connect(this,
          &Boxes::inputHandler);

Now, you are ready to initialize the musical portion of the program. First, you load up a CL_SoundBuffer with a waveform ("binary") music file and then prepare a session handle so it's ready to play. Next, you apply a fade filter to asynchronously bring the music from zero to 60 percent volume over the course of five seconds (lines 108-112).

106    CL_SoundBuffer *music = new CL_SoundBuffer("linemusic.ogg");
107    CL_SoundBuffer_Session session = music->prepare();
108    CL_FadeFilter *fade = new CL_FadeFilter(0.0f);
109    session.add_filter(fade);
110    session.set_looping(true);
111    session.play();
112    fade->fade_to_volume(0.6f, 5000);
113 }

The drawBoard() method draws the dotted grid pattern where line segments lie, the tomato red and cornflower blue squares that each player has won, and last but not least the simulated cursor. The most important line of code here is line 165. CL_Display::flip() swaps the front buffer and back buffers. The back buffer is where you draw all your graphics during the frame, and the front buffer is what displays on the screen.

115 void Boxes::drawBoard()
116 {
117    CL_Display::clear(redturn ? CL_Color::red : CL_Color::blue);
118    CL_Display::fill_rect(CL_Rect(border/2, border/2,
119                          winsize - border/2, winsize - border/2),
                             CL_Color::black);
120
121    // Draw squares
122    for (int x = 0; x < boardsize - 1; x++)
123       for (int y = 0; y < boardsize - 1; y++) {
124          if (squares[x][y] == red) {
125             CL_Display::fill_rect(CL_Rect(x * spacing + border,
                   y * spacing + border, x * spacing + border +
                   spacing,
127                y * spacing + border + spacing),
                      CL_Gradient(CL_Color::red,
128                CL_Color::red, CL_Color::tomato, CL_Color::tomato));
129          redpict->draw(x * spacing + border + spacing / 2,
130                        y * spacing + border + spacing / 2);
131       }
132       else if (squares[x][y] == blue) {
133          CL_Display::fill_rect(CL_Rect(x * spacing + border,
134                                        y * spacing + border,
                                           x * spacing + border +
                                           spacing,
135                                        y * spacing + border +
                                           spacing),
                                           CL_Gradient(CL_Color::blue,
136          CL_Color::blue, CL_Color::cornflowerblue,
             CL_Color::cornflowerblue));
137       bluepict->draw(x * spacing + border + spacing / 2,
                         y * spacing + border + spacing / 2);
139       }
140    }
141
142    // Draw lines
143    for (int x = 0; x < boardsize; x++) {
144    for (int y = 0; y < boardsize - 1; y++) {
145       if (ver[x][y]) CL_Display::draw_line(x * spacing + border,
146                                            y * spacing + border,
                                               x * spacing + border,
147                                            y * spacing + border
                                               + spacing,
                                               CL_Color::yellow);
148       if (hor[y][x]) CL_Display::draw_line(y * spacing + border,
149                                            x * spacing + border,
                                               y * spacing + border
                                               + spacing,
                                               x * spacing + border,
                                               CL_Color::yellow);
151       }
152    }
153
154    // Draw grid
155    for (int x = 0; x < boardsize; x++)
156       for (int y = 0; y < boardsize; y++)
157          CL_Display::draw_rect(CL_Rect(x * spacing + border,
158                                        y * spacing + border,
                                           x * spacing + border + 2,
159                                        y * spacing + border + 2),
                                           CL_Color::white);
160
161    //Draw cursor
162    if (curs.vert) cursimg->draw((curs.x - 1) * spacing + border,
          int((curs.y - 0.5) * spacing + border));
163    else cursimg->draw(int((curs.x - 0.5) * spacing + border),
          (curs.y - 1) * spacing + border);
164
165   CL_Display::flip();
166 }

You installed the inputHandler() to watch the key down signal back on line 105. This function handles the cumbersome details of turning keystrokes into game moves, the most significant being SPACE or ENTER to signify a selection by the current player (lines 200-210). Then, you check to see whether you completed a "square" and return control to the same player if you've done so.

168 void Boxes::inputHandler(const CL_InputEvent &i)
169 {
170    if (redturn) {
171       switch(i.id) {
172       case CL_KEY_LEFT:
173       case CL_KEY_G:
174          if (curs.x > 1) curs.x--;
175          break;
176       case CL_KEY_RIGHT:
177       case CL_KEY_J:
178          if (curs.x < boardsize) curs.x++;
179          break;
180       case CL_KEY_UP:
181       case CL_KEY_Y:
182          if (!curs.vert && curs.y > 1) {
183             curs.y--;
184             curs.vert = !curs.vert;
185          }
186          else if (curs.vert) curs.vert = false;
187          break;
188       case CL_KEY_DOWN:
189       case CL_KEY_H:
190          if (curs.vert && curs.y < boardsize) {
191             curs.y++;
192             curs.vert = !curs.vert;
193          }
194          else if (!curs.vert) curs.vert = true;
195          break;
196       }
197       if (curs.x == boardsize && !curs.vert) curs.x--;
198       if (curs.y == boardsize && curs.vert)
             curs.vert = false;
199
200       if (i.id == CL_KEY_SPACE || i.id == CL_KEY_ENTER) {
201          if (curs.vert) {
202             if (!ver[curs.x-1][curs.y-1]) {
203                ver[curs.x-1][curs.y-1] = true;
204                if (!findsquares()) redturn = !redturn;
205             }
206          }
207          else {
208             if (!hor[curs.x-1][curs.y-1]) {
209                hor[curs.x-1][curs.y-1] = true;
210                if (!findsquares()) redturn = !redturn;
211             }
212          }
213       }
214    }
215 }

Lastly, the endOfGame() method computes the final score. Remember that the game is not over until the board is full (see line 48) or someone resigns by hitting the ESC key (see line 46). Last of all, you fade out the volume to 0 percent over the course of one second.

217 void Boxes::endOfGame()
218 {
219    // Count scores
220       int redscore, bluescore;
221       redscore = bluescore = 0;
222       for (int x = 0; x < boardsize - 1; x++)
223          for (int y = 0; y < boardsize - 1; y++) {
224             if (squares[x][y] == red) redscore++;
225             else if (squares[x][y] == blue) bluescore++;
226          }
227
228       cout << "Red: " << redscore
               << "\nBlue: " << bluescore
              << endl;
229       if (bluescore != redscore)
230          cout << (bluescore > redscore ? "Blue" : "Red")
                  << " player wins\n";
231       else cout << "It was a tie\n";
232
233       if (fullup) {
234          fade->fade_to_volume(0.0f, 1000);
235          CL_System::sleep(1000);
236       }
237 }

Stay Tuned!

Be sure to come back next week for the fifth and final installment of Cross-Platform Game Development for C++ Developers.

About the Author

Victor Volkman has been writing for C/C++ Users Journal and other programming journals since the late 1980s. He is a graduate of Michigan Tech and a faculty advisor board member for Washtenaw Community College CIS department. Volkman is the editor of numerous books, including C/C++ Treasure Chest and is the owner of Loving Healing Press. He can help you in your quest for open source tools and libraries; just drop an e-mail to sysop@HAL9K.com.