Structure

On unzipping, the following directory structure will exist (the top level being the directory 'axl_projects'):

Library Files

For each library component you want to use, there is one c++ code file and one header file, located in the root directory, that you need to include in your project: Also, each header file automatically includes the file axl.h. This file contains all the optimisations you might want to apply to the various modules. Refer to the 'Optimising' section of each module (from the main menu) - or just open the file and read it. The optimisations apply to the Animation and Framework modules.

Because each library is self-sufficient you can delete any of the pairs of files you are not interested in. Remember though the Framework requires Animation and Configurator so all files are required if using the Framework. If just using the Framework or the Animation, you will need to remove the references to the Configuration log file in the source code (it will show you the error)

A few external libraries are also required (though included with the download):

Feel free to delete fblend if not required, or update either with newer versions. This release includes version 0.5beta1 of FBlend and version 2.3.4 of tinyXML.

WARNING for Windows Users: The current stable 4.2 (and below) version of allegro has bugs that prevent subbitmaps (i.e. the Animation module uses these if you are using sheet graphics) from being displayed if your parent bitmap is either a system or a video bitmap, and crashes your program if you try to delete a subbitmap (e.g. deleting animation objects that use sheet graphics) that is a system bitmap. Included in the download is an update that fixes these bugs that should be available in the next stable or a future CVS release. Simply use this DLL and all will be well. Also put the gfx.h file in your allegro include directory.

This DLL also includes code changes to allow hardware acceleration of the stretch functions (currently it is only non-stretching functions that use hardware acceleration). However, one bug found is if you stretch video bitmaps (system and memory bitmaps are ok) then you *may* encounter a 'halo' effect round the bitmap where the mask colour is showing. However it is fixed by updating your video driver. This problem was found on a few nvidia cards with older drivers.

Installation for Windows using MSVC/MinGW/Dev-C++

  • Copy the source\extern\tinyxml_minimum\*.h files to your include directory
  • Copy the source\extern\tinyxml_minimum\*.lib (for msvc, or *.a for mingw/devcpp) files to your lib directory
  • If you wish, instead of using the tinyxml library file you can simply add the four *.cpp files from the extern\tinyxml_minimum directory to your project. These files constitute the whole of tinyxml and allow easier debugging/fault fixing. You can also ignore the above instructions and simply modify your IDE to search the extern directories for lib/include files.

    Installation for Other Systems

    1. FBlend: If you are planning on using fblend for the faster fade routines then you will need to download and install fblend yourself as the library is too big to include here. Otherwise simply do nothing as the animation library works without it
    2. TinyXML: This is a small portable library with no other dependencies. Either include the *.cpp files in your project or compile and pack the *.cpp files into a library file
    3. If using your compiled files then copy the relevant header and library files to your lib/include directories

    Quick Compilation Test

    Configurator

    1. Firstly (if using Windows) run the tests\config\example1.exe demo to see what the library can do
    2. Create your allegro project as normal
    3. To the external library files add tinyxml.a/tinyxml.lib (or drop in the four .cpp files as mentioned above) before the allegro library (alleg.lib/liballeg.a)
    4. To your project add axl_config.cpp from the axl_projects source directory
    5. To your project add the tests\config\example1\main.cpp to your project and compile

    Animation

    1. Firstly (if using Windows) run the tests\animation\example1.exe demo to see what the library can do
    2. Create your allegro project as normal
    3. To the external library files add fblend.lib/fblend.a (if used) and tinyxml.a/tinyxml.lib (or drop in the four .cpp files as mentioned above)
    4. To the external library files add tinyxml.a/tinyxml.lib (or drop in the four .cpp files as mentioned above)
    5. To your project add axl_animation.cpp and configuration.cpp from the axl_projects source directory
    6. To your project add the tests\animation\example1\main.cpp to your project and compile

    Framework

    1. Firstly (if using Windows) run the tests\framework\example1.exe demo. This is just a quick text output showing how the FPS loop handles events
    2. Create your allegro project as normal
    3. To the external library files add tinyxml.a/tinyxml.lib (or drop in the four .cpp files as mentioned above) before the allegro library (alleg.lib/liballeg.a)
    4. To your project add axl_framework.cpp from the axl_projects source directory
    5. To your project add axl_animation.cpp from the axl_projects source directory
    6. To your project add axl_config.cpp from the axl_projects source directory
    7. To your project add the tests\framework\example1\main.cpp to your project and compile

    Combined

    All the libraries work together. To see this a number of examples exist:
    1. Firstly (if using windows) run the tests\animation\example2.exe. This example is exactly the same as the animation example1 except instead of using custom code to startup allegro, the Configurator library is used. The improvement can be seen by no allegro startup code in the main.cpp code and the ability to change settings and the way the display is rendered via the XML. Only the startup (graphics mode selection, installation of devices, etc) is done by Configurator.
    2. Secondly (if using windows) run the tests\animation\example3.exe. This example is the same as the animation example 1 and 2 but builds on example 2 byt doing all of the FPS loops, allowing the system to run using triple, double, paging, etc.
    For the combined tests you need to include the relevant files mentioned above (e.g. tinyXML and the main.cpp from the example directory). For the first combined test (animation\example 2) you need to include the Configurator source file (axl_config.cpp) with the animation source file (axl_animation.cpp). For the second combined example (animation\example 3) you need all the source files (axl_framework.cpp, axl_config.cpp, axl_animation.cpp) plus the main.cpp. Further details on the examples are found in the 'Examples' section of each help topic in the main menu.

    Alternatively Dev-C++ and VS2005 projects have already been set up to do this and are found in the tests directory for all examples. Note: for Dev-C++ users the full path of the .a library files has to be stored in the project file, so on loading the projects for the first time, edit the compiler settings and change the absolute path to wherever it is stored. Also, FBlend is not included by default, to add this, add the .a or .lib file to the project make file. This needs to be included before the Allegro library, otherwise link errors will result.

    Code Templates

    Below are example minimal code templates to get you started. You best approach is to read and use the samples in the test directories.

    Configurator Only

    #include "axl_config.h" using namespace AXL_Projects; using namespace std; int main() { Configuration* myConfig; myConfig=new Configuration("config.xml"); if(Configuration::GlobalErrorString!="") { //some kind of nice exit return 1; } //start allegro and set up everything myConfig.AllegroStart(); //we are now in a graphics mode and have access to everything such as: int lives=1; float g; string author; lives=myConfig->GetCustom("lives",-1); g=myConfig->GetCustom("gravity",-9.8F); author=myConfig->GetCustom("author","george dawes"); myConfig->SetCustom("lives",lives+1); myConfig->SetCustom("badger","badger badger badger"); myConfig->FlushCustom(); //i'd rather not wait until exit to write to file //use some stuff int fps=myConfig->CapsSystem.fps; string windowmode=myConfig->CapsGraphics.WindowMode; //change some settings from an options menu myConfig->CapsGraphics.WindowMode="fullscreen"; //below will write all main and custom settings back to the file //if we have set the flag in the XML to do it, otherwise, //simply call myConfig->FlushCustom() and myConfig->FlushMain() delete myConfig; //shouldn't call exit in a destructor, //just in case the badgers get you allegro_exit(); return 0; } END_OF_MAIN()

    Animation Only

    #include "axl_animations.h" using namespace AXL_Projects; int main() { //whatever you do normally allegro_init(); install_timer(); install_keyboard(); set_color_depth(32); if(set_gfx_mode(GFX_AUTODETECT,640,480,0,0)<0) { //nice failure exit message return 1; }; //animation set up AnimationLibrary* GameLibrary; GameLibrary=new AnimationLibrary(); if(!GameLibrary->LoadAnimations("myfile.xml")) { delete GameLibrary; //nice failure exit message return 1; } //debug code that outputs every graphic to the screen //GameLibrary->draw(); //sample code to get an animation via creating a new object Animation* FuelAnimation=new Animation(GameLibrary,"fuelfull"); draw_sprite(screen, FuelAnimation->ReadOnly_CurrentItem, 0,0); //sample code to get an animation once the object is created fuelAnimation->SetNewAnimation("fuelempty"); //exit code delete FuelAnimation; delete GameLibrary; readkey(); allegro_exit(); return 0; } END_OF_MAIN()

    Combined Configurator and Animation

    #include "axl_animation.h" #include "axl_config.h" using namespace AXL_Projects; using namespace std; int main() { Configuration* myConfig; myConfig=new Configuration("config.xml"); if(Configuration::GlobalErrorString!="") { //some kind of nice exit return 1; } //start allegro and set up everything if(myConfig.AllegroStart()==0) { //some kind of nice exit return 1; } //animation set up. need allegro up and running first so bitmaps are loaded correctly AnimationLibrary* GameLibrary; GameLibrary=new AnimationLibrary(); if(!GameLibrary->LoadAnimations("myfile.xml")) { delete GameLibrary; //nice failure exit message return 1; } //sample code to get an animation via creating a new object Animation* FuelAnimation=new Animation(GameLibrary,"fuelfull"); string author; int lives=3; author=myConfig->GetCustom("author","george dawes"); myConfig->SetCustom("lives",lives+1); myConfig->FlushCustom(); //i'd rather not wait until exit to write to file //use some stuff and change, maybe through a menu int fps=myConfig->CapsSystem.fps; string windowmode=myConfig->CapsGraphics.WindowMode; //draw our sprite draw_sprite(screen, FuelAnimation->ReadOnly_CurrentItem, 0,0); //sample code to get an animation once the object is created fuelAnimation->SetNewAnimation("fuelempty"); //exit code delete myConfig; delete FuelAnimation; delete GameLibrary; readkey(); allegro_exit(); return 0; } END_OF_MAIN()

    Framework using Animation and Configuration

    #include "axl_framework.h" //this opens axl_config.h/axl_animation.h for us using namespace AXL_Projects; //main game variables static Framework* GameFramework; //framework static AnimationLibrary* GameLibrary; //our graphics library static Configuration* GameConfiguration; //our configuration object //if we want to show the FPS, this holds it extern volatile int TimerCurrentFPS; //forward declarations as this sample isn't using a header file //hooks to pass to framework for the various parts of the game bool LogicStartup(); bool DrawingStartup(); bool LogicMenu(); bool DrawingMenu(); bool LogicGame(); bool DrawingGame(); bool LogicGameOver(); bool DrawingGameOver(); bool OverrideLogic1(); bool OverrideDrawing1(); void SetupGame(); void EndGame(); void DoMenu(int speed); int main(void) { //create our framework, load animations, initialise buffers, //on leaving, unless errors, we will be in graphics mode GameFramework=new Framework("config.xml","animations.xml"); if(Configuration::GlobalErrorString!="") { delete GameFramework; allegro_message(Configuration::GlobalErrorString.c_str()); } else { //any initialisation needed before the game starts //usually assign variables to the configurator, animation library, etc. SetupGame(); //can just use NULL if any are not required as they are //arbitrary anyway, they are called by the flag you set. if( !GameFramework->StartGameLoop( LogicStartup,DrawingStartup, LogicMenu,DrawingMenu, LogicGame,DrawingGame, LogicGameOver,DrawingGameOver,true) ) { //destroy everything, clean up memory and bitmaps, stop timers, etc. //exit is text mode delete GameFramework; allegro_message("Failed to run game loop. Check config.log"); } else { //do any clean up we want, e.g. our dynamic variables for Animations, etc EndGame(); //destroy everything, clean up memory and bitmaps, stop timers, etc. //exit is text mode delete GameFramework; } } allegro_exit(); return 0; } END_OF_MAIN(); bool LogicStartup() { //to change the logic/drawing call the change timer function with //the relevant name (these correspond to the functions passed in GameFramework->ChangeTimerType(GAME_MENU); //if we want to set an override, e.g. instead of coding lots of stuff here //or putting in lots of case statements we can temporarily swap the timer type //(sort of like ChangeTimerType but on returning true it returns back to the //original logic/drawing pair //SetAutoGameLoopOverride(OverrideLogic1,OverrideDrawing1); //return true; //return and exit the loop return false; //return normally } bool DrawingStartup() { //DrawingSurface is the SCREEN sized drawing buffer //the system handles the buffering mode (paging, triple, double, etc) //and does all the swapping for you. you still need to clear it if you need to //the system calls each logic/drawing pair at the correct time to maintain FPS clear_to_color(GameFramework->DrawingSurface,makecol(0,0,0)); //return true; //return and exit the loop return false; } //the other functions are to be coded exactly as LogicGStartup bool LogicMenu() { return false; } bool DrawingMenu(){ return false; } bool LogicGame() { return false; } bool DrawingGame(){ return false; } bool LogicGameOver() { return false; } bool DrawingGameOver(){ return false; } //our helper functions void SetupGame() { //we are in a graphics mode, so grab everything needed GameLibrary=GameFramework->GetGraphicsLibrary(); GameConfiguration=GameFramework->GetConfiguration(); //initialise animations, etc. exactly as animation/configuration examples, e.g. //MainAnimation=new Animation(GameLibrary,"ufo"); //CollisionAnimation=new Animation(GameLibrary,"fuel"); //AnimationLibraryFrames* af=GameLibrary->GetAnimation("logo"); //LogoAnimation=new Animation(GameLibrary,af); //LogoAnimationSimple=GameLibrary->GetFirstGraphic("logo"); } void EndGame() { //only delete the stuff we create //the framework deletes the drawing buffers, animation, framework, configuration //delete MainAnimation; //delete CollisionAnimation; //delete LoopAnimation }

    Now select which library part you wish to learn about from the left hand menu, 'Framework', 'Animation', 'Configurator'