A portable C++ GUI library designed for games using Allegro, HGE, OpenGL, OpenLayer and/or SDL.
Getting started
From Guichan
To get started with Guichan you need to download the Guichan source package in the downloads section. As there are numerous problems with providing pre built binaries for a C++ library, such as binary incompatibility between compilers and different versions of the same compiler, only the source of Guichan is provided since Guichan 0.7.0.
Contents |
The structure of the source package
The Guichan core source is found under the directories include and src. Source for back ends are found in sub directories of include/guichan and src, where the sub directories are named after the name of the back end. Examples are found in the examples directory. Contribs, or contributions by end users to Guichan, are found in the contrib directory. Contribs are helpful source not a part of the core library because they either require an extra dependency or because the code implements a very specific non generic task.
guichan-x-x-x (root directory) +-> include +-> guichan +-> allegro
| |
| +-> contrib
| |
| +-> hge
| |
| +-> opengl
| |
| +-> openlayer
| |
| +-> sdl
|
+-> examples
|
+-> src +-> allegro
|
+-> contrib
|
+-> hge
|
+-> opengl
|
+-> openlayer
|
+-> sdl
Supported back ends
Guichan supports usage with the following back ends:
With OpenGL no image loading or input handling is supported due to the fact that OpenGL lacks functions for image loading and input handling. To be able to use the OpenGL back end another back end must be used which takes care of image loading and input handling. At the moment is SDL the only back end that has an implemented image loader that can be used with OpenGL.
Adding the Guichan source to a project
The easiest way of using Guichan is to simply add the Guichan source to an existing project source. By doing so no libraries need to be built. To add the Guichan source just copy the needed source and header files to a project and compile the source files as the other project source files are compiled.
The Guichan source needed depends on the dependencies of the project using Guichan. The core source of Guichan must be added. The core source is the headers and source files in the include/guichan/, the src/ directory, the include/guichan/widgets directory and the src/widgets directory in the source package (source and header files other directories and subdirectories are not a part of the core source).
To use Guichan with a back end, such as Allegro or SDL, source for that back end must be added. Source for each supported back end reside in a subdirectories of src/ and include/guichan/. In the case of Allegro the source in the allegro subdirectory of the include/guichan/ and src/ directories must be added. In the case of SDL the source in the sdl subdirectory of the include/guichan/ and src/ directories must be added. Source for usage with HGE, OpenGL and OpenLayer have similar subdirectories.
For convenience the core source has a header include/guichan.hpp which includes all classes in the core source. All back ends have a similar header. In the case of Allegro the header is include/guichan/allegro.hpp. In the case of SDL the header is include/guichan/sdl.hpp.
If you're using the OpenLayer back end, you can't make a shared library (DLL) from the guichan_openlayer sources, due to the fact that OpenLayer uses global variables internally. So the best way to use guichan with OpenLayer back end is to either put all guichan and guichan_openlayer sources into your project, or create a static library which is linked to your executable. There are two things to know as well: It doesn't work with OpenLayer 2.0, you have to use a reasonable recent snapshot from SVN (2007/04 for example). You should also not use OpenLayer with GlyphKeeper, but the internal text renderer instead.
include/guichan.hpp include/guichan/*.hpp include/guichan/widgets/*.hpp src/*.cpp src/widgets/*.cpp
The core source
include/guichan/allegro.hpp include/guichan/allegro/*.hpp src/allegro/*.cpp
The Allegro back end source
include/guichan/hge.hpp include/guichan/hge/*.hpp src/hge/*.cpp
The HGE back end source
include/guichan/opengl.hpp include/guichan/opengl/*.hpp src/opengl/*.cpp
The OpenGL back end source
include/guichan/openlayer.hpp include/guichan/openlayer/*.hpp src/openlayer/*.cpp
The OpenLayer back end source
include/guichan/sdl.hpp include/guichan/sdl/*.hpp src/sdl/*.cpp
The SDL back end source
Compiling Guichan libraries
A more complicated way of using Guichan (or at least when it comes to Windows) is to compile Guichan as libraries. How this is done varies depending on what operating system is used and what compiler is used.
Windows
MSVC 8
Todo!
Dev-Cpp
In the source of Guichan there exists Dev-Cpp project files for the core library, the Allegro back end, the OpenGL back end and the SDL back end. The easiest way to compile Guichan libraries with Dev-Cpp is to use those project files. They however assume Dev-Cpp is installed in C:\Dev-Cpp.
The following header and source files from the source package are needed to compile the Guichan core library with Dev-Cpp:
include/guichan.hpp include/guichan/*.hpp include/guichan/widgets/*.hpp src/*.cpp src/widgets/*.cpp
The following options are needed to compile the Guichan core library with Dev-Cpp:
Project Options
General -> Type -> Win32DLL
Parameters -> Compiler -> DGUICHAN_BUILD=1
-> C++ Compiler -> DGUICHAN_BUILD=1
-> Linker -> --no-export-all-symbols --add-stdcall-alias -Wl,--enable-runtime-pseudo-reloc --enable-auto-import
Directories -> Include Directories -> include
The following header and source files from the source package are needed to compile the Allegro back end library with Dev-Cpp:
include/guichan/allegro.hpp include/guichan/allegro/*.hpp src/allegro/*.cpp
The following options are needed to compile the Allegro back end library with Dev-Cpp:
Project Options
General -> Type -> Win32DLL
Parameters -> Compiler -> DGUICHAN_EXTENSION_BUILD=1
C++ Compiler -> DGUICHAN_EXTENSION_BUILD=1
Linker -> --no-export-all-symbols --add-stdcall-alias -Wl,--enable-runtime-pseudo-reloc --enable-auto-import -lalleg PATH_TO_GUICHAN_CORE_LIBRARY/libguichan.a
Directories -> Include Directories -> include
PATH_TO_GUICHAN_CORE_LIBRARY should be replaced with the path to the compiled Guichan core library.
The following header and source files from the source package are needed to compile the OpenGL back end library with Dev-Cpp:
include/opengl/opengl.hpp include/guichan/opengl/*.hpp src/opengl/*.cpp
Project Options
General -> Type -> Win32DLL
Parameters -> Compiler -> DGUICHAN_EXTENSION_BUILD=1
C++ Compiler -> DGUICHAN_EXTENSION_BUILD=1
Linker -> --no-export-all-symbols --add-stdcall-alias -Wl,--enable-runtime-pseudo-reloc --enable-auto-import PATH_TO_GUICHAN_CORE_LIBRARY/libguichan.a -lopengl32
Directories -> Include Directories -> include
PATH_TO_GUICHAN_CORE_LIBRARY should be replaced with the path to the compiled Guichan core library.
The following header and source files from the source package are needed to compile the SDL back end library with Dev-Cpp:
include/sdl/sdl.hpp include/guichan/sdl/*.hpp src/sdl/*.cpp
Project Options
General -> Type -> Win32DLL
Parameters -> Compiler -> DGUICHAN_EXTENSION_BUILD=1
C++ Compiler -> DGUICHAN_EXTENSION_BUILD=1
Linker -> --no-export-all-symbols --add-stdcall-alias -Wl,--enable-runtime-pseudo-reloc --enable-auto-import PATH_TO_GUICHAN_CORE_LIBRARY/libguichan.a -lmingw32 -lSDL_image -lSDLmain -lSDL -mwindows
Directories -> Include Directories -> include
PATH_TO_GUICHAN_CORE_LIBRARY should be replaced with the path to the compiled Guichan core library.
MinGW
When compiling Guichan extension llibraries with MinGW the define GUICHAN_DLL_IMPORT has to be define in order for MinGW to see all classes exported from the Guichan core DLL.
Unix
To compile Guichan libraries in Unix is quite easy. The source package of Guichan contains configure and make scripts built with autotools to make the process automatic.
To compile Guichan libraries simply call:
$ tar xvzf guichan-x.y.z-src.tar.gz $ cd guichan-x.y.z $ ./configure $ make $ su Password: # make install
To disable compiling of a certain back end libraries simply pass a --disable-backend flag to the configure script. For instance, to disable compiling of an Allegro back end library pass --disable--allegro to the configure script.
To verify that the compiled libraries work you can enter the examples directory and compile the examples.
# exit (log out from root) $ cd examples $ make -f Makefile.examples sdl (for SDL examples) $ make -f Makefile.examples allegro (for Allegro examples) $ make -f Makefile.examples opengl (for SDL+OpenGL examples)
MacOS X
Compiling Guichan libraries with MacOS X has been reported to be a difficult task (non of the developers have access to a MaxOS X system so this cannot be confirmed). Because of that it's at the moment not recommended to compile libraries with MacOS X. Instead it's recommended to add the Guichan source to the project using Guichan if MacOS X is to be used.
Using Guichan libraries
Windows
MSVC 8
Todo!
Dev-Cpp
The following project options are needed to use Guichan core library and the Guichan Allegro back end library with Dev-Cpp:
Project Options -> Parameters -> Linker -> -lguichan_allegro -lguichan -lalleg
The following project options are needed to use Guichan core library and the Guichan OpenGL back end library with Dev-Cpp:
Project Options -> Parameters -> Linker -> -lguichan_opengl -lguichan -lmingw32 -lopengl32 -mwindows
The following project options are needed to use Guichan core library, the Guichan OpenGL back end library and the Guichan SDL back end library with Dev-Cpp:
Project Options -> Parameters -> Linker -> -lguichan_opengl -lguichan_sdl -lguichan -lmingw32 -lSDL_image -lSDLmain -lSDL -lopengl32 -mwindows
The following project options are needed to use Guichan core library and the Guichan SDL back end library with Dev-Cpp:
Project Options -> Parameters -> Linker -> -lguichan_sdl -lguichan -lmingw32 -lSDL_image -lSDLmain -lSDL -mwindows
MinGW
When using Guichan libraries with MinGW the define GUICHAN_DLL_IMPORT has to be define in order for MinGW to see all classes exported from the DLLs.
Unix
To use compiled Guichan libraries in Unix is also quite easy. The core Guichan library must always be linked with, which other Guichan libraries which needs to be linked with varies depending on the dependencies of the project using Guichan.
The default compiled libraries are:
guichan guichan_allegro guichan_opengl guichan_sdl
Here is an example of compiling a project using SDL and Guichan.
g++ sdlhelloworld.cpp -o sdlhelloworld -lguichan_sdl -lguichan -lSDL_image `sdl-config --libs --cflags`
Note that as always with GCC do the order of libraries passed for linkage matter. The library with no dependency of other linked libraries should be linked last, the library with the most dependency of other libraries passed should be linked first. In the above example has the SDL_image library a dependency of SDL and is therefore linked before SDL. The guichan_sdl library has a dependency of all other linked libraries - guichan, SDL and SDL_image - and is therefore linked first.
MacOS X
Todo!
