Configurator Library

Overview

The library is fully described in the Overview. However, to summarise it is a system to manage your own custom configuration values, core allegro values you might use in a game (such as graphcis mode, colour depth, fps, sound options). It is easy to read and write/update existing and new values (there is an auto update option so no explicit saving is required). There is also an 'AllegroStart' function that takes some of the core allegro values you specify and starts up allegro. It tries all permutations you specify (e.g. colour depth, graphics mode, fallback graphics mode, windowing options, etc). If 'AllegroStart' is called again it will re-initialise the system. This will allow (for example) the system to restart after key changes are made in a game configuration menu.

XML File

The allegro system variables and custom variables are fully described in the XML. Example1 contains code that shows how easy it is to use.

This is the core of a config file:

<?xml version="1.0" encoding="UTF-8"?> <config> <system /> <graphics /> <window /> <sound /> <custom /> <custom /> </config>

There is one master element 'config' that contains one each of the core allegro elements 'system', 'graphics', 'window', 'sound' and zero or more 'custom' elements.

There are defaults for all core allegro elements so if none are present (or indeed if the actual element does not exist, the system will create them on saving. However the element names must at least exist when reading the config file.

Elements and Attributes

Full details appear below for all attributes, however a short and concise version is contained in the sample config.xml file that is in the tests\config directory. It's probably best to open up the config.xml file and map the table below to what you see:

Element: system

AttributeDefaultTypeValid EntriesDescription
fps 60 int 1 to 1000 FPS for a game (not used by Configurator class, only Animation and Framework classes). If using Animation system, this and animation share the same value. This overrides animation
debugon 0 boolean 0,1 Not used by the config or animation but can be used as a check in game on wheter to log stuff, for example
autowritemain 0 boolean 0,1 On destructing the configuration object, if 1 will write all data for core allegro elements to the config file
autowritecustom 0 boolean 0,1 On destructing the configuration object, if 1 will write all data for custom elements to the config file
enablejoystick
enablemouse
enablekeyboard
enablesound
enablemidi
1 boolean 0,1 These 5 attributes state which option (e.g. init_keyboard()) is to be called on startup. Timer is exlcuded because it is assumed it will always be enabled. If not, and using the Configuration to start allegro, modify the code.
matchrefreshrate 0 boolean 0,1 Signify that on Allegro initialisation, a change to the refresh rate should be attempted. This may improve smoothness and avoid doing too much/too little in a FPS loop.

Element: graphics

AttributeDefaultTypeValid EntriesDescription
vsync 0 boolean 0,1 Whether vsync is to be enabled if applicable (e.g. if using double buffering). Only used by the Framework class, not the configurator or animation classes.
graphicsmode 0 int 0 (double)
1 (dirty rectangle)
2 (video paged)
3 (triple)
Only used by the Framework class. How the system should be used and tried. If the Configurator is used it will try alternates until successful or it gives up, i.e. if triple fails paged is tried, if paged or dirty fails, double is tried. double fails, the fallback mode and fallback bitmap depth is tried for all permutations until
depthpreferred 32 int 32,24,16, 15,8 bpp required. failure will result in depthfallback tried
depthfallback 16 int 32,24,16, 15,8,0 Fallback mode used if the depthpreferred fails. 0 means no fallback mode allowed
capbmptype 0 boolean 0,1 Signify that if the drawing buffer is not the same as animations/graphics then the animations/graphics should use the same type, e.g. because VRAM->MEMORY blitting can be extremely slow, if the buffer is a memory bitmap but graphics drawn to it are video, performance can be hit. Setting this flag to 0 will indicate that any type specified should be ignored and to use that of the drawing buffer. This is used by the Framework for loading animations and graphics.

Element: window

AttributeDefaultTypeValid EntriesDescription
autodetect any string any, fullscreen, windowed How the window should be created. All these entries use the GFX_AUTODETECT_xxx mode. Any will simply use GFX_AUTODETECT. If another mode is required, see the next attribute. The system will try different valid permutations of this and colour depth in the event of a failure.
specified not set int OS specific If this attribute is specified then 'autodetect' is not used and this is called instead. So only use this entry if not using autodetect as it will override it. This is an integer that corresponds to the modes available (i.e. that the GFX_AUTODETECT_xxx and all OS specific modes are defined as)
width
height
800
600
integer >0 The width/height required

Element: window

AttributeDefaultTypeValid EntriesDescription
maxvoicearray 32 integer 1 to 255 The number of voices to allocate to the sound system
samplevolume 150 int 0 to 255 The starting volume required for sounds/voices
musicvolume 128 int 0 to 255 The starting volume required for any music

Element: custom

AttributeDefaultTypeDescription
name not set string The name of the custom variable. This is how you read/write custom variables as the name is the key. Using dodgy characters may error. So stick to no spaces or punctuation, etc. Error if not set
valuestring
valueint
valuefloat
""
-1
-1.0
string
int
float
One and one only of any of these must be there. If none, the an error is raised. If more than one then precedence (randomly selected for no apparent reason) is int, float, string

Methods

Method/DataDetails
Configuration(string xmlfile) Create a Configuration object and read all values from XML. The 'xmlfile' can be the name of a XML file or the actual XML as a string. See usage below.
~Configuration()When the destructor is called (i.e. destroyed) and any of the autowrite attributes are set, will write the values back to the xml file. If not set then will use the filename 'config.xml'
FileNameName of the config file being read/written. Only set this if you wish to write to a new config file other than the one read or if XML file was not read (using the second constructor). This is simply a std::string (e.g. NewFile="myfile.xml")
GetCustom(string,int)
GetCustom(string,float)
GetCustom(string,string)
Retrieve a value read initially from the XML file. First parameter is the name (i.e. the 'name' attribute in the custom element), the second is the default if not found. This can be a string, int or a float. Note on some compilers you may have to explicitly suffix the int/float (e.g. float g=GetCustom("gravity",-9.8F).
SetCustom(string,int)
SetCustom(string,float)
SetCustom(string,int)
This sets a custom variable. If it already exists it will be overwritten, if not a new one is created (and stored to XML if saved). First parameter is the name (refer to GetCustom() ), the second is the value to write (refer to GetCustom() )
FlushCustom(string)Write all custom variables to the XML file. Parameter is the filename to write to. If omitted will use that which was read. If none was read then the default of 'config.xml' will be used. If 'autowritecustom' attribute is set then this will be called automatically for you on destruction of the configuration object.
FlushMain(string)Write all core allegro variables to the XML. Parameter and usage as FlushCustom()
AllegroStart() Using all core allegro attributes specified, will set up Allegro and leave in a graphics mode. Returns 0 if failed and not in a graphics mode, 1 for successful but not all primary attributes specified were set (e.g. a fallback depth was used), 2 for fully successful. Refer to the Allegro core data below (specifically CapsActualSystem). Note the warning in the section 'Usage' regarding graphics mode changes).
The system will try to initialise the system to pause when you switch out of the application. This should work for most systems and nothing else is required, however full-screen mode in Windows will fail. If pause mode fails (e.g. fullscreen Windows) then AMNESIA mode is set. This mode pauses the program but will lose the contents of the screen. In a game loop this won't matter as your code (or the Framework if using it) will redraw immediately. This mode should work on fullscreen Windows. However if that fails then the fallback of BACKAMNESIA is called. This does not pause your program and blanks your screen! hopefully in a game loop this should be fine, though obviously it may do daft things like have a very large timer value if you are using a FPS based timer. If you wish to cater for this mode then you will have to call 'set_display_callback' to pause the game and redraw on resume.
LogEntry(string,bool, string)This is a static (i.e. can be called without creating a Configuration object and from anywhere in code). Simply writes a string (parameter 1) to the file (parameter 3). Parameter 2 determines of the file will be wiped first. Defaults are false (do not wipe) and 'config.log'
GlobalErrorStringstatic level string. Used for logging your errors if you wish. It is used by the Configuration to log errors at key points so you can test for them, i.e. failure in XML file, no root 'config' element in XML file, no allegro core elements found.

Allegro Core Data

Whereas the custom values are modified via Get/Set functions, the core allegro values are accessed directly via structures made visible by the configuration object, e.g. myConfiguration->CapsGraphics.WindowMode="fullscreen". If the 'structure' column is blank it means it is the same as the previous one. bool values are 0 and 1 for false/true. XML attribute is the value in the XML attribute section that this value equates to.
StructureElementDefaultDescriptionXML attribute
CapsSystemint fps60frames per second indicatorfps
bool DebugEnabled0Debugging is enabled for tracing faults/logging detailsdebugon
bool UseMouse1Enable mouse on Allegro initialisationenablemouse
bool UseKeyboard1Enable keyboard on Allegro initialisationenablekeyboard
bool UseSound1Enable samples on Allegro initialisationenablesound
bool UseMidi1Enable MIDI on Allegro initialisationenablemidi
bool AutoWriteMain0Save all Allegro core attributes (i.e. these) to disk on destruction of the Configuration objectautowritemain
bool AutoWriteCustom0As AutoWriteMain but for all custom created attributesautowritecustom
CapsGraphicsScrWidth800Screen width requiredwidth
ScrHeight600Screen height requiredheight
int RenderMode0How to start graphics (triple buffering, paged, dirty rectangle, double - 3,2,1,0graphicsmode
bool VSync0Use vsyncvsync
int Depth32Colour depth requireddepthpreferred
int DepthFallback16Colour depth required if main fails. 0 means no fallbackdepthfallback
string WindowModeanyHow to create the main window. 'fullscreen', 'window','any'. Use WindowFallback if auto mode not requiredautodetect
int WindowFallback0Graphics mode to set if this value is >0. Overrides WindowMode and equates to the numeric values associated with each graphics mode.specified
CapsSoundSampleVolume150Initial volume for sound effectssamplevolume
MusicVolume128Initial volume for music effectsmusicvolume
MaxSounds32Maximum number of voices to allocate for sound effectsmaxvoicearray

This structure is populated after initialisation and contains the actual settings selected by the system. Use these in your game.

CapsActualSystemUseSoundWhether sound system is ok. Use this in your game to determine whether to play sounds.
UseMidiAs UseSound but for Midi
DepthUsedActual Colour depth used (either of preferred or fallback)
GraphicsRenderModeActual render mode used (triple, paging, double buffering)

Usage

Initialising and Loading

In your source code you need to include the main header file and use the AXL namespace:

#include "axl_config.h"; using namespace AXL_Projects;

There is one class, Configuration. All constructors create a set of base values. Normally you will create a configuration by passing in the name of an XML file, e.g.

Configuration* myConfiguration; myConfiguration=new Configuration("config.xml");

If you wish, you can supply XML data instead of a filename.

To query an existing custom value you would use the var=GetCustom(name, default) method. This is overloaded, which simply means depending on the type of your return variable and the default value it will return the correct value, e.g.

int lastlevel=myConfiguration->GetCustom("lastlevel" , 1); float g=myConfiguration->GetCustom("gravity", -9.8F); string author=myConfiguration->GetCustom("author", "unknown author");
Note: some compilers may not interpret a float/int properly so you might have to tell it, e.g. -9.8F in the example above.

To update and existing custom value or to write a new one (if it doesn't exist), simply use the SetCustom(name, value). Again it knows the type, so simply pass in a string, an int or a float, e.g.

myConfiguration->SetCustom("lastlevel" , lastlevel); myConfiguration->SetCustom("gravity", g); myConfiguration->SetCustom("author", author); myConfiguration->SetCustom("a_brand_new_item", 99);

Setting the core allegro attributes is done via the pre-defined structs mentioned above, e.g.

myConfiguration->CapsSystem.maxvoices=64;

Graphics Mode Change

As you can see adding user definable options menus is as simple as setting autowrite to 1, setting a value when an option is selected, calling the AllegroStart() method and then forgetting about it. See the examples for more code.

If you change graphics modes (e.g. set_gfx_mode() ), for example from a menu option to allow the user to change resolution, etc, then you should delete all animations and reload. This can be done by simply calling 'delete anim' where anim is your animation library, and re-initialising it. If you are using the Framework, it will try to do it for you if you call the Framework method RestartSystem(). This is because if video or system bitmaps are being used they will/might become invalid and/or corrupted. Memory bitmaps should be ok though any change to colour depth/conversion may affect them.

XML as data

Instead of passing in the name of a XML file to the constructor you can specify XML as a string instead. This is useful if you are reading the XML from a source other than a file (e.g. a dat file) or you do not wish the user to modify values. Remember that all attributes need to be quoted. The easiest way to do this is to simply copy the XML data from the sample config.xml files. For example:

std::string config = "" "<config>" " <system fps=\"60\" autowritemain=\"0\" autowritecustom=\"0\" " " enablejoystick=\"0\" enablekeyboard=\"1\" enablemouse=\"1\" enablesound=\"1\" " " />" " <window width=\"640\" height=\"480\" autodetect=\"windowed\" />" " <custom name=\"message\" valuestring=\"Hi Mam\" />" "</config>"; MyConfig=new Configuration(config);

Examples

These are found in the tests\config directory (.\example1 and .\example2). VS2005 and Dev-C++ projects have already been created. If not using either of these two IDe's then follow the installation section, i.e. include tinyXML library file (or tinyXML source files), the main.cpp in the example directory and axl_config.cpp. Additionally, example 2 requires axl_animations.cpp.

Internals

This is not an exhaustive list of what and how the configurator works, for that you need to read the code. This provides a list of what the Constructor/AllegroStart methods do so that you know what happens within allegro.