<HTML>
<HEAD>
<TITLE>ClanLib Game SDK: Getting started with ClanLib</TITLE>
<STYLE TYPE="text/css"><!--
HTML BODY
{
font-family: verdana, helvetica, sans-serif;
font-size: 14px;
border-style: solid;
}
H1 { font-size: 22px; }
H2 { font-size: 18px; }
H3 { font-size: 16px; }
H4 { font-size: 14px; }
P { font-size: 14px; }
LI { font-size: 14px; }
--></STYLE>
</HEAD>
<body bgcolor=white text=black>
<center>
<table width=70%>
<tr>
<td>
<center><table><tr><td>
<img
SRC="Images/clanlib_logo_small.gif"
alt="ClanLib logo"><br>
</td></tr></table></center>
<h1>Getting started with ClanLib</h1>
<h2>Abstract</h2>
<p>This document shows how to write a very basic ClanLib appliation, using
the CL_ClanApplication interface. It explains why a global instance of this
class is needed and how to initialize the different subsystems/components in
ClanLib (using the CL_System and CL_Settings classes). Finally it explains how
to trace errors and handle exceptions in ClanLib.</p>
<h2>The CL_ClanApplication Interface</h2>
<p>Welcome to the ClanLib overview documentation. We will start at the first
steps needed to use ClanLib: initialization of the library and the
application. Most libraries does this by requiring an application to call
some kind of init function before the library is used, and a deinit function
at the end of the application. Eg.:</p>
<ul><pre><font face="Arial,Courier New,Courier">void main()
{
library_init();
// run game
library_deinit();
}
</font></pre></ul>
<p>However, ClanLib doesn't use this strategy for one important reason:
ClanLib runs on a lot of platforms. Some of these platforms do not use the
traditional main() initialization method. Windows is an example where
WinMain() is used instead. Often ClanLib need to use the parameters to these
alternative main() functions, and thus requires a very platform dependent
initialization.</p>
<p>We have solved the problem by making ClanLib itself incapsulate the real
main() function, and then call the ClanLib application when it is done with
its initialization. The resulting main() "function" in ClanLib looks like
this:</p>
<ul><pre><font face="Arial,Courier New,Courier">
#include <ClanLib/core.h>
#include <ClanLib/application.h>
class MyClanLibApplication : public CL_ClanApplication
{
public:
virtual char *get_title() { return "MyApplication"; }
virtual int main(int argc, char **argv)
{
CL_SetupCore::init();
// Insert game code here
CL_SetupCore::deinit();
return 1;
}
} app;
</font></pre></ul>
<p>There has to be <i>one</i> single instance of this class - otherwise
ClanLib isn't able to locate the class, and thus cannot invoke the main
function.</p>
<p>This can somewhat be compared to the Applet class in Java, and CWinApp in
Microsoft's Foundation Classes (MFC).</p>
<h2>Initializing components</h2>
<p>ClanLib is a large library and thus can be used for several purposes.
Because of this, ClanLib doesn't initialize its components before asked to.
This is done through the <a href="../Reference/html/CL_SetupCore.html">CL_SetupCore</a> class: </p>
<ul><pre><font face="Arial,Courier New,Courier">class CL_SetupCore
{
static void init();
static void deinit();
};
</font></pre></ul>
<p>Each library in ClanLib has such a class. The clanGL library has
<a href="../Reference/html/CL_SetupGL.html">CL_SetupGL</a>, clanGUI has
<a href="../Reference/html/CL_SetupGUI.html">CL_SetupGUI</a>, and so on. Since each of these
libraries requires some initialization and shutdown code, the CL_SetupXXX
classes always contain at least two functions, called init() and deinit().
You <i>must</i> call those before using the respective components in your
program, and call the deinit-function when the program ends.</p>
<p>If you need to use the display and sound parts of ClanLib, but not the
network, you could do something like this:</p>
<ul><pre><font face="Arial,Courier New,Courier">
#include <ClanLib/core.h>
#include <ClanLib/display.h>
#include <ClanLib/sound.h>
virtual int main(int argc, char** argv)
{
CL_SetupCore::init();
CL_SetupDisplay::init();
CL_SetupSound::init();
// run game.
CL_SetupCore::deinit();
CL_SetupDisplay::deinit();
CL_SetupSound::deinit();
return 1;
}
</font></pre></ul>
<h2>Creating a simple Makefile for Linux</h2>
<p>Read the file INSTALL.linux in the ClanLib root directory for
specifix details on how to use ClanLib under Linux.</p>
<h2>Creating a ClanLib project in Visual C++</h2>
<p>Read the file INSTALL.win32 in the ClanLib root directory for
specific details on how to use ClanLib with Microsoft Visual C++ 6.0.</p>
<h2>Creating a ClanLib project in Borland C++</h2>
<p>Read the file INSTALL.borland in the ClanLib root directory for
specific details on how to use ClanLib with Borland C++.</p>
</TD>
</TR>
</TABLE>
<BR>
<BR>
<FONT COLOR="#a0a0a0">Questions or comments, write to the <a href="mailto:clanlib-user.x.dtu.dk">ClanLib mailing list</a>.</FONT>
</CENTER>
</BODY>
</HTML>
