This document describes how to port your game from an old ClanLib version to a new one.
Upgrading from 0.5.4 to 0.6.0
=============================
1. Signals have been made consistent all over ClanLib
-----------------------------------------------------
In a few cases you need to add a parenthesis to a signal.
Example:
CL_Timer timer;
// ClanLib 0.5.x:
sig_timer.connect(...)
// ClanLib 0.6.0:
sig_timer().connect(...)
The affected signals are as follows:
CL_Timer::sig_timer
CL_Input::sig_button_press
CL_Input::sig_button_release
CL_Input::sig_mouse_move
CL_Mouse::sig_move
CL_Mouse::sig_button_press
CL_Mouse::sig_button_release
2. Input signals were changed in clanGUI
----------------------------------------
CL_Component::sig_key_up(CL_Component *comp, CL_InputDevice *device, const CL_Key &key)
CL_Component::sig_key_down(CL_Component *comp, CL_InputDevice *device, const CL_Key &key)
CL_Component::sig_mouse_move(CL_Component *comp, int x, int y);
were changed to:
CL_Component::sig_key_up(const CL_Key &key)
CL_Component::sig_key_down(const CL_Key &key)
CL_Component::sig_mouse_move(int x, int y);
Also, the following signals were added:
CL_Component::sig_input_up(CL_InputDevice *device, const CL_Key &key)
CL_Component::sig_input_down(CL_InputDevice *device, const CL_Key &key)
sig_key_up/down used to include both mouse and keyboard events, but now sig_key_up/down is
ONLY keyboard, and the newly added sig_input_up/down is ANY inputdevice (mouse, keyboard,
joystick, etc). So, if you want the old behaviour, hook into the sig_input instead of sig_key signals.
Remember, you can always use CL_InputDevice::get_type() to check which inputdevice the
sig_input_up/down got its event from (returns CL_InputDevice::type_mouse, type_joystick,
type_keyboard).
Upgrading from 0.5.2 to 0.5.3
=============================
1. Default videomode has been set to windowed, and not fullscreen as previously.
To override default, you specify fullscreen-mode like this:
CL_Display::set_videomode(640, 480, 16, true);
or, window-mode:
CL_Display::set_videomode(640, 480, 16, false);
Upgrading from 0.5.1 to 0.5.2
=============================
1. Resource pathhandling is changed
-----------------------------------
Now all resources are loaded with path from the location of the resource file, and
not the location of the executable as before.
So, for example, if you have this structure:
data/
data/images/
data/images/surface.tga
data/images.scr
Previously, the images.scr would look like this:
surface = data/images/surface.tga (type = surface);
Now, it must be changed into:
surface = images/surface.tga (type = surface);
without the first data/, as the resourcefile itself is in the data directory.
2. Signal connection API changed
--------------------------------
Earlier you had to use CL_CreateSlot when connecting to a signal:
CL_Slot slot = sig_something.connect(CL_CreateSlot(this, &MyApp::on_signal));
It has been modified to this shorter method instead:
CL_Slot slot = sig_something.connect(this, &MyApp::on_signal);
Just remove CL_CreateSlot from your code, and you're set.
Also, we added a handy CL_SlotContainer. If you find it awkward storing all those
CL_Slot objects, you can do use this instead:
CL_SlotContainer slots; // Put this where you earlier stored your CL_Slot objects. Don't make it local!
...
slots.connect(sig_something, this, &MyApp::on_signal);
slots.connect(sig_something2, this, &MyApp::on_signal2);
slots.connect(sig_something_else, this, &MyApp::on_signal_else);
3. GUI Themeing
---------------
If you have created your own StyleManager, you need to remove the
CL_ComponentOptions &options
from the
void CL_StyleManager::connect_styles(..) function.
For example:
void CL_StyleManager_OpenGL::connect_styles(
const std::string &type,
CL_Component *owner)
Also, remove the ComponentOptions from all the components. Check
the GUIGL example for more specific details.
-------------------------------------------------------------------------------
Upgrading from 0.5.0 to 0.5.1
=============================
1. CL_Input::sig_mouse_move
---------------------------
This signal was moved into the CL_Mouse class, and is now called
CL_Mouse::sig_move(int x, int y);
2. ClanGUI
----------
Sorry, but this module is so rapidly changing these days, so
its no use updating this document regarding that.
-------------------------------------------------------------------------------
Upgrading from 0.4.x to 0.5.0
=============================
1. Multithreaded on Windows
2. Separated modules (Sound, Display, Network & Application)
3. Init/Deinit modules
4. Debug console
5. Datafile invocation
6. Event Chains
7. Input/OutputSource
8. Resources
9. Network
1. Multithreaded on Windows
---------------------------
ClanLib now uses multithreaded libraries on Windows, and you need to upgrade your
libraries (zlib, libpng etc) - see http://clanlib.org/download/foreign-win32.html
and download the needed libraries there.
Also, you need to change your own application to use multithreaded libraries:
1. Select Project->Settings...
2. Select the 'C/C++' tab, and then Category 'Code Generation'
3a. For Release version, change the 'Use run-time library' to Multithreaded.
3b. For Debug version, change the 'Use run-time library' to Debug Multithreaded.
2. Separated modules (Sound, Display, Network & Application)
------------------------------------------------------------
Sound, Display, Network, Application was separated from clanCore, and you need to do
some changes to the initialization and library including in your game.
ClanApplication
---------------
ClanCore was separated from the CL_ClanApplication initializing, and therefore you need
to link with both clanCore and clanApp if you want to use the "standard" way of
initializing ClanLib (the easy way).
Windows:
Add clanApp.lib (release) or clanAppd.lib (debug) to your project settings.
Linux:
Add -lclanApp to your Makefile.
You also need to add this: #include <ClanLib/application.h>
If you want to initialize ClanLib yourself (for example if you want to use ClanNetwork
without anything else from ClanLib), you do not link with ClanApplication,
and do a manual initialization.
ClanDisplay
-----------
ClanDisplay was separated from ClanCore, and therefore you need to link with both clanCore
and clanDisplay.
Windows:
Add clanDisplay.lib (release) or clanDisplayd.lib (debug) to your project settings.
Linux:
Add -lclanDisplay to your Makefile.
Codewise, you need to replace
CL_SetupCore::init_display();
CL_SetupCore::deinit_display();
with
CL_SetupDisplay::init();
CL_SetupDisplay::deinit();
You also need to add this: #include <ClanLib/display.h>
ClanSound
---------
ClanSound was separated from ClanCore, and therefore you need to link with both clanCore
and clanSound IF you want to use sound in your game.
Windows:
Add clanSound.lib (release) or clanSoundd.lib (debug) to your project settings.
Linux:
Add -lclanSound to your Makefile.
Codewise, you need to replace
CL_SetupCore::init_sound();
CL_SetupCore::deinit_sound();
with
CL_SetupSound::init();
CL_SetupSound::deinit();
You also need to add this: #include <ClanLib/sound.h>
ClanNetwork
-----------
ClanNetwork was separated from ClanCore, and therefore you need to link with both clanCore
and clanNetwork IF you want to use network in your game.
Windows:
Add clanNetwork.lib (release) or clanNetworkd.lib (debug) to your project settings.
Linux:
Add -lclanNetwork to your Makefile.
Codewise, you need to replace
CL_SetupCore::init_network();
CL_SetupCore::deinit_network();
with
CL_SetupNetwork::init();
CL_SetupNetwork::deinit();
You also need to add this: #include <ClanLib/network.h>
3. Init/Deinit modules
----------------------
The CL_ClanApplication no longer uses the init_modules() and deinit_modules()
functions. Move the initialization into your main() instead, and remove these
functions. Or, add functions calling init_modules() and deinit_modules() from
your main().
4. Debug console
----------------
The debug window under Windows is no longer enabled by default. If you want a
console window (for std::cout and printf), add this code:
(at the beginning of CL_Application::main for example)
CL_ConsoleWindow console("My console");
console.redirect_stdio();
5. Datafile invocation
----------------------
Datafile support is no longer enabled by default. To support the feature with
"app -datafile ..." add something like the following code to your main():
(You can of course improve this to use filenames from the command line as well)
... CL_SetupCore::init();
... CL_SetupGL::init();
if (argv[1] == "-datafile") {
CL_DatafileCompiler::write("my_file.scr", "my_file.dat");
return;
}
... CL_SetupCore::init_display();
... CL_Display::set_videomode(640, 480, 16 false);
Lines starting with ... are just to show where you could put the code.
6. Event Chains
---------------
Event chains has been removed, and replaced with a signal-system.
So, if any of your classes inherit the following classes, read on to find out
how to upgrade your app to the signal system:
CL_Event_ButtonRelease
CL_Event_ButtonPress
CL_Event_WindowResize
CL_Event_MouseMove
CL_Event_MouseEnter
CL_Event_MouseExit
1. Remove these inherited classes from your classes.
2. Replace the lines:
CL_Input::chain_button_press.push_back( this );
...
CL_Input::chain_button_press.remove( this );
with
CL_Slot slot; // Put this is a non-local location (like your class-header)
...
slot = CL_Input::sig_button_press.connect(CL_CreateSlot(this, &MyClass::on_button_press));
This just shows the buttonpress event, the others are similar. Refer to the
reference for correct API.
7. Input/OutputSource
---------------------
This change is represented in all CL_InputSource* and CL_OutputSource* classes.
The read_bool() function was renamed to read_bool8().
The write_bool() function was renamed to write_bool8().
8. Resources
------------
The resource API has changed a little bit.
First, the construction of the CL_ResourceManager is uses a standard constructor instead
of the previous ::create() method.
Replace
CL_ResourceManager *resource = CL_ResourceManager::create(...);
with
CL_ResourceManager *resource = new CL_ResourceManager(...);
or
CL_ResourceManager resource(...);
Second, if you use custom resources, go read the new Documentation/Overview about
resources. It is now much easier to create custom resources, but it uses a different method
than earlier.
Third, the classes CL_Res_Integer, CL_Res_Boolean and CL_Res_String was replaced with
CL_Integer, CL_Boolean and CL_String.
Instead of previously doing:
int my_integer = CL_Res_Integer::load("resource_name", resource_manager);
you now do:
int my_integer = CL_Integer("resource_name", resource_manager);
9. Network
----------
CL_NetGame was renamed to CL_NetSession, as it is now possible to use ClanNetwork
in other than games; ClanNetwork is no longer dependent on the rest of ClanLib.
Various other stuff was altered in ClanNetwork, but the specifics we cannot recall.
If you have any additions, please send mail to the mailing-lists.
