Debian Codegraph @

Documentation/Overview/getting_started.xml

raw
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>