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
| Attribute | Default | Type | Valid Entries | Description |
|---|---|---|---|---|
| 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
| Attribute | Default | Type | Valid Entries | Description |
|---|---|---|---|---|
| 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
| Attribute | Default | Type | Valid Entries | Description |
|---|---|---|---|---|
| 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
| Attribute | Default | Type | Valid Entries | Description |
|---|---|---|---|---|
| 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
| Attribute | Default | Type | Description |
|---|---|---|---|
| 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/Data | Details |
|---|---|
| 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' |
| FileName | Name 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' |
| GlobalErrorString | static 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
| Structure | Element | Default | Description | XML attribute |
|---|---|---|---|---|
| CapsSystem | int fps | 60 | frames per second indicator | fps |
| bool DebugEnabled | 0 | Debugging is enabled for tracing faults/logging details | debugon | |
| bool UseMouse | 1 | Enable mouse on Allegro initialisation | enablemouse | |
| bool UseKeyboard | 1 | Enable keyboard on Allegro initialisation | enablekeyboard | |
| bool UseSound | 1 | Enable samples on Allegro initialisation | enablesound | |
| bool UseMidi | 1 | Enable MIDI on Allegro initialisation | enablemidi | |
| bool AutoWriteMain | 0 | Save all Allegro core attributes (i.e. these) to disk on destruction of the Configuration object | autowritemain | |
| bool AutoWriteCustom | 0 | As AutoWriteMain but for all custom created attributes | autowritecustom | |
| CapsGraphics | ScrWidth | 800 | Screen width required | width |
| ScrHeight | 600 | Screen height required | height | |
| int RenderMode | 0 | How to start graphics (triple buffering, paged, dirty rectangle, double - 3,2,1,0 | graphicsmode | |
| bool VSync | 0 | Use vsync | vsync | |
| int Depth | 32 | Colour depth required | depthpreferred | |
| int DepthFallback | 16 | Colour depth required if main fails. 0 means no fallback | depthfallback | |
| string WindowMode | any | How to create the main window. 'fullscreen', 'window','any'. Use WindowFallback if auto mode not required | autodetect | |
| int WindowFallback | 0 | Graphics mode to set if this value is >0. Overrides WindowMode and equates to the numeric values associated with each graphics mode. | specified | |
| CapsSound | SampleVolume | 150 | Initial volume for sound effects | samplevolume |
| MusicVolume | 128 | Initial volume for music effects | musicvolume | |
| MaxSounds | 32 | Maximum number of voices to allocate for sound effects | maxvoicearray |
This structure is populated after initialisation and contains the actual settings selected by the system. Use these in your game.
| CapsActualSystem | UseSound | Whether sound system is ok. Use this in your game to determine whether to play sounds. | ||
| UseMidi | As UseSound but for Midi | |||
| DepthUsed | Actual Colour depth used (either of preferred or fallback) | |||
| GraphicsRenderMode | Actual 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;
- If you have AutoWriteMain set to true then on destroying the myConfiguration object (e.g. 'delete myConfiguration') all the core allegro values will be written to the XML file automatically
- If you have AutoWriteCustom set to true then on destroying the myConfiguration object all the custom values will be written to the XML file automatically
- AutoWriteCustom/AutoWriteMain are not linked, so either can be on or off
- If the values are to be saved at a specific point in code (whether autowritemain/autowritecustom is true or false), use myConfiguration->FlushMain() or myConfiguration->FlushCustom()
- FlushMain/FlushCustom can be passed in a filename as the only parameter to save the details to a different XML file. If omitted then the file passed in via the constructor is used. If none were supplied then the public class variable myConfiguration->ConfigFile is used (see description in the details above)
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.- The first test (example 1) reads an XML configuration file, initialises Allegro and updates some custom values in the XML file
- The second test (example 2) is the same as the Animation example 1. The animation example 1 shows some animation effects. This example modifies the example 1 to use the configuration module to set up and initialise allegro. Read this example after you have read the Animation help and done example 1
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.- The constructor passing in the config xml file loads up the XMl file and sets all the internal data
- The AllegroStart method installs the keyboard, timer, joystick, sound, midi, mouse (only the ones you specify in the XML), sets the colour depth and graphics mode (it will use the fallback colour depth and alternative fullscreen/windowed if unavailable). All the data that can change (e.g. colour depth, graphics mode, etc) are stored in the CapsActualSystem to allow you to easily check whether what you got was what was specified.