Structure

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

docs : this documentation
source : the AXL source code and associated libraries
tests : samples for all the libraries
tutorial : a complete game tutorial

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:

Animation: axl_animations.cpp/axl_animations.h
Configurator: axl_config.cpp/axl_config.h
Framework: axl_framework.cpp/axl_framework.h

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):

tinyXML: is a sourceforge library written in ANSI compatible C and is a library for handling XML files. It is required by the library
FBlend: Used by the animation library only. This is another sourceforge library but specific to Allegro and allows much faster blended bitmap drawing than the built in blender functions (for transparency, additive, subtractive drawing). Although not required, if present it will be compiled in and speeds up execution of the fade routines.

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

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
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
If using your compiled files then copy the relevant header and library files to your lib/include directories

Quick Compilation Test

Configurator

Firstly (if using Windows) run the tests\config\example1.exe demo to see what the library can do
Create your allegro project as normal
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)
To your project add axl_config.cpp from the axl_projects source directory
To your project add the tests\config\example1\main.cpp to your project and compile

Animation

Firstly (if using Windows) run the tests\animation\example1.exe demo to see what the library can do
Create your allegro project as normal
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)
To the external library files add tinyxml.a/tinyxml.lib (or drop in the four .cpp files as mentioned above)
To your project add axl_animation.cpp and configuration.cpp from the axl_projects source directory
To your project add the tests\animation\example1\main.cpp to your project and compile

Framework

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
Create your allegro project as normal
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)
To your project add axl_framework.cpp from the axl_projects source directory
To your project add axl_animation.cpp from the axl_projects source directory
To your project add axl_config.cpp from the axl_projects source directory
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:

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.
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.

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'