<?xml version="1.0"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<title>Porting from ClanLib 1.0 - ClanLib SDK</title>
<link rel="stylesheet" media="screen" type="text/css" href="clanlib.css"/>
<link rel="icon" href="gfx/favicon.png" type="image/png"/>
</head>
<body>
<div id="content">
<h1><a href="."><img src="gfx/clanlib.png" alt="ClanLib SDK" /></a></h1>
<h2>
<img src="gfx/overview.png"/>Porting from ClanLib 1.0
</h2>
<p>If you are familiar with, or have a project using the ClanLib 1.0 API, here are some guidelines to help you port over the code to ClanLib 2. It is not a complete guide, but it should get you started. If you discover some new issues that you think would fit into this document, please write a post on the forum and we'll try to get it updated. Notice that porting GUI from ClanLib 1.0 to 2.0 is completely out of the scope of this overview, and won't be covered.</p>
<h3>Code Design</h3>
<p>If your old code creates objects as follows:</p>
<pre>
CL_Sprite *mysprite = new CL_Sprite(...);
...
delete mysprite;
</pre>
<p>consider using ClanLibs handle objects instead:</p>
<pre>
CL_Sprite mysprite(...);
..or..
CL_Sprite mysprite;
mysprite = CL_Sprite(...);
</pre>
<p>This will help prevent objects not being destroyed when exceptions are thrown, and you won't have to delete pointers manually.</p>
<p>Most ClanLib's objects use shared pointers for the implementation:</p>
<pre>
CL_Sprite mysprite(...);
CL_Sprite mysprite2 = mysprite;
</pre>
<p>Now, mysprite and mysprite2 both relate to the same object. The overhead is only setting up a new shared pointer.
If you do require a real copy of the object, a few clanLib objects support the "clone" function:</p>
<pre>
CL_Sprite mysprite3(gc); // note CL_Sprite mysprite3; will not work, it requires a gc!
mysprite3.clone(mysprite2);
</pre>
<h3>Graphic Contexts</h3>
<p>Since ClanLib 2.0 directly supports multiple windows all graphic functions require a CL_GraphicContext to operate on. This is obtained from the display window.</p>
<pre>
CL_GraphicContext gc = window.get_gc();
..
mysprite.draw(gc, 100, 200);
</pre>
<p>This usually means that you should pass the graphic context to every drawing function. Note, passing by reference is faster than passing by object.</p>
<pre>
void Player::draw(CL_GraphicContext &gc)
{
mysprite.draw(gc, 100, 200);
}
</pre>
<h3>CL_ClanApplication</h3>
<p>ClanLib 1.0:</p>
<pre>
class Application : public CL_ClanApplication
{
public:
virtual int main(int argc, char **argv);
}
</pre>
<p>ClanLib 2.0:</p>
<pre>
class Application
{
void int main(const std::vector<CL_String> &args)
{
...
}
};
class Program
{
public:
static int main(const std::vector<CL_String> &args)
{
CL_SetupCore setup_core;
Application app;
return app.start(args);
}
};
CL_ClanApplication app(&Program::main);
</pre>
<p>You don't have to use 2 classes like above, but it enforces CL_SetupCore is always called first before any other clanlib objects, and the destruction order is correct.</p>
<h3>Target Setup</h3>
<p>ClanLib 1.0</p>
<pre>
CL_SetupCore::init();
CL_SetupDisplay::init();
..
CL_SetupCore::deinit();
CL_SetupDisplay::deinit();
</pre>
<p>ClanLib 2.0:</p>
<pre>
CL_SetupCore setup_core;
CL_SetupDisplay setup_display;
</pre>
<p>Core must be initialized before Display. Display must be initialized before GL (or other display targets).</p>
<p>If you want to support multiple target targets, you can do the following:</p>
<pre>
CL_SetupGL target_gl2;
CL_SetupGL1 target_gl1;
CL_SetupGDI target_gdi;
CL_SetupSDL target_sdl;
target_gdi.set_current();
</pre>
<h3>Exceptions</h3>
<p>ClanLib 1.0:</p>
<pre>
catch (CL_Error err)
{
std::cout << err.message.c_str() << std::endl;
}
</pre>
<p>ClanLib 2.0:</p>
<pre>
catch(CL_Exception &exception)
{
CL_ConsoleWindow console("Console", 80, 160);
CL_Console::write_line(exception.message);
console.display_close_message();
}
</pre>
<p>See the Basic2D example to display the call stack when an exception occurs.</p>
<h3>Window Creation</h3>
<p>Fullscreen mode on ClanLib 2.0 does not change the screen resolution, unlike ClanLib 1.0. It will only maximize to the current desktop resolution.</p>
<p>If your ClanLib 1.0 window size is fixed (eg 800x600), the following option is ideal in most situations:</p>
<pre>
CL_DisplayWindowDescription desc;
desc.set_title("mygame");
desc.set_size(CL_Size(800,600), true);
if(fullscreen)
{
desc.set_fullscreen(true);
desc.set_decorations(false);
}
else
{
desc.set_allow_resize(true);
}
main_window = CL_DisplayWindow(desc);
</pre>
<p>You can also scale the output to match the current resolution:</p>
<pre>
CL_GraphicContext gc = main_window.get_gc();
CL_Mat4f matrix = CL_Mat4f::scale( (float) gc.get_width() / 800.0f, (float) gc.get_height() / 600.0f, 1.0f);
gc.set_modelview(matrix);
</pre>
<h3>Clear, Keep Alive and Flip!</h3>
<p>ClanLib 1.0:</p>
<pre>
CL_Display::clear(CL_Color(0, 0, 0));
CL_System::keep_alive();
CL_Display::flip(x);
</pre>
<p>ClanLib 2.0:</p>
<pre>
gc.clear(CL_Colorf(0.0f, 0.0f, 0.0f));
CL_KeepAlive::process();
window.flip(x);
</pre>
<h3>Surfaces</h3>
<p>CL_Surface class no longer exist, but you find a close match in CL_Image. You also need to change resources:</p>
<p>ClanLib 1.0:</p>
<pre>
<surface name = "logo" file = "misc/logo.png"/>
</pre>
<p>ClanLib 2.0:</p>
<pre>
<image name = "logo"><image-file file = "misc/logo.png"/></image>
</pre>
<h3>Keyboard</h3>
<p>ClanLib 1.0:</p>
<pre>
CL_Keyboard::get_keycode(key);
</pre>
<p>ClanLib 2.0:</p>
<pre>
CL_InputDevice keyboard = window->get_ic().get_keyboard();
...
keyboard.get_keycode(key);
</pre>
<h3>File I/O</h3>
<p>ClanLib 1.0:</p>
<pre>
CL_InputSource_File input_file(options_file);
CL_OutputSource_File output_file(options_file);
input_file.tell();
input_file.size();
input_file.read_string();
</pre>
<p>ClanLib 2.0:</p>
<pre>
CL_File input_file(options_file);
CL_File output_file(options_file, CL_File::create_always, CL_File::access_write);
input_file.get_position();
input_file.get_size();
input_file.read_string_a();
</pre>
<h3>Resource Loading From ZipArchive</h3>
<p>ClanLib 1.0:</p>
<pre>
CL_Zip_Archive zip(skin);
CL_ResourceManager gfx("menu_skins.xml", &zip, false);
</pre>
<p>ClanLib 2.0:</p>
<pre>
CL_VirtualFileSystem vfs(skin, true);
CL_VirtualDirectory vd(vfs, "./");
CL_ResourceManager gfx("menu_skins.xml", vd);
</pre>
</div>
</body>
</html>
