| 1 |
<xml> |
| 2 |
<head> |
| 3 |
<title>Getting started with ClanLib</title> |
| 4 |
<eyecolor>yellow</eyecolor> |
| 5 |
</head> |
| 6 |
<body> |
| 7 |
|
| 8 |
<p>This document shows how to write a very basic ClanLib application, using |
| 9 |
the CL_ClanApplication interface. It explains why a global instance of this |
| 10 |
class is needed and how to initialize the different subsystems/components in |
| 11 |
ClanLib. Finally it explains how to trace errors and handle exceptions in ClanLib.</p> |
| 12 |
|
| 13 |
<h3>The CL_ClanApplication Interface</h3> |
| 14 |
|
| 15 |
<p>We will start at the first steps needed to use ClanLib: initialization of |
| 16 |
the library and the application. Most libraries do this by requiring an application |
| 17 |
to call some kind of init function before the library is used, and a deinit function |
| 18 |
at the end of the application. Eg.:</p> |
| 19 |
|
| 20 |
<code> |
| 21 |
void main() |
| 22 |
{ |
| 23 |
library_init(); |
| 24 |
// run game |
| 25 |
library_deinit(); |
| 26 |
} |
| 27 |
</code> |
| 28 |
|
| 29 |
<p>However, ClanLib doesn't use this strategy for one important reason: |
| 30 |
ClanLib runs on a lot of platforms. Some of these platforms do not use the |
| 31 |
traditional main() initialization method. Windows is an example where |
| 32 |
WinMain() is used instead. Often ClanLib need to use the parameters to these |
| 33 |
alternative main() functions, and thus requires a very platform dependent |
| 34 |
initialization.</p> |
| 35 |
|
| 36 |
<p>We have solved the problem by making ClanLib itself encapsulate the real |
| 37 |
main() function, and then call the ClanLib application when it is done with |
| 38 |
its initialization. The resulting main() "function" in ClanLib looks like |
| 39 |
this:</p> |
| 40 |
|
| 41 |
<code> |
| 42 |
|
| 43 |
#include <ClanLib/core.h> |
| 44 |
#include <ClanLib/application.h> |
| 45 |
|
| 46 |
class MyClanLibApplication : public CL_ClanApplication |
| 47 |
{ |
| 48 |
public: |
| 49 |
virtual int main(int argc, char **argv) |
| 50 |
{ |
| 51 |
CL_SetupCore setup_init; |
| 52 |
|
| 53 |
// Insert game code here |
| 54 |
|
| 55 |
return 0; |
| 56 |
} |
| 57 |
} app; |
| 58 |
</code> |
| 59 |
|
| 60 |
<p>There has to be <i>one</i> single instance of this class - otherwise |
| 61 |
ClanLib isn't able to locate the class, and thus cannot invoke the main |
| 62 |
function.</p> |
| 63 |
|
| 64 |
<p>This can somewhat be compared to the Applet class in Java, and CWinApp in |
| 65 |
Microsoft's Foundation Classes (MFC).</p> |
| 66 |
|
| 67 |
<h3>Initializing components</h3> |
| 68 |
|
| 69 |
<p>ClanLib is a large library and thus can be used for several purposes. |
| 70 |
Because of this, ClanLib doesn't initialize its components before asked to. |
| 71 |
This is done through the <codelink>CL_SetupCore</codelink> class. </p> |
| 72 |
|
| 73 |
<p>Each library in ClanLib has such a class. The clanGL library has |
| 74 |
<codelink>CL_SetupGL</codelink>, clanGUI has |
| 75 |
<codelink>CL_SetupGUI</codelink>, and so on. |
| 76 |
You <i>must</i> create these classes before using the respective components in your |
| 77 |
program. Make sure they don't go out of scope until your program is ending.</p> |
| 78 |
|
| 79 |
<p>If you need to use the display and sound parts of ClanLib, but not the |
| 80 |
network, you could do something like this:</p> |
| 81 |
|
| 82 |
<code> |
| 83 |
|
| 84 |
#include <ClanLib/core.h> |
| 85 |
#include <ClanLib/display.h> |
| 86 |
#include <ClanLib/gl.h> |
| 87 |
#include <ClanLib/sound.h> |
| 88 |
|
| 89 |
class MyClanLibApplication : public CL_ClanApplication |
| 90 |
{ |
| 91 |
public: |
| 92 |
virtual int main(int argc, char** argv) |
| 93 |
{ |
| 94 |
CL_SetupCore setup_core; |
| 95 |
CL_SetupDisplay setup_display; |
| 96 |
CL_SetupGL setup_gl; |
| 97 |
CL_SetupSound setup_sound; |
| 98 |
|
| 99 |
// run game. |
| 100 |
|
| 101 |
return 0; |
| 102 |
} |
| 103 |
} app; |
| 104 |
</code> |
| 105 |
|
| 106 |
<h3>Creating a simple Makefile for Linux</h3> |
| 107 |
|
| 108 |
<p>Read the file INSTALL.linux in the ClanLib root directory for |
| 109 |
specifix details on how to use ClanLib under Linux.</p> |
| 110 |
|
| 111 |
<h3>Creating a ClanLib project in Visual C++</h3> |
| 112 |
|
| 113 |
<p>Read the file INSTALL.win32 in the ClanLib root directory for |
| 114 |
specific details on how to use ClanLib with Microsoft Visual C++.</p> |
| 115 |
|
| 116 |
<h3>Creating a ClanLib project in Borland C++</h3> |
| 117 |
|
| 118 |
<p>Read the file INSTALL.borland in the ClanLib root directory for |
| 119 |
specific details on how to use ClanLib with Borland C++.</p> |
| 120 |
|
| 121 |
</body> |
| 122 |
</xml> |