Various parts of Allegro, such as the sound routines and the load_joystick_data() function, require some configuration information. This data is stored in text files as a collection of "variable=value" lines, along with comments that begin with a '#' character and continue to the end of the line. The configuration file may optionally be divided into sections, which begin with a "[sectionname]" line. Each section has a unique namespace, to prevent variable name conflicts, but any variables that aren't in a section are considered to belong to all the sections simultaneously.
By default the configuration data is read from a file called allegro.cfg, which can be located either in the same directory as the program executable, or the directory pointed to by the ALLEGRO environment variable. Under Unix, it also checks for ~/allegro.cfg, ~/.allegrorc, /etc/allegro.cfg, and /etc/allegrorc, in that order; under BeOS only the last two are also checked. If you don't like this approach, you can specify any filename you like, or use a block of binary configuration data provided by your program (which could for example be loaded from a datafile).
You can store whatever custom information you like in the config file, along with the standard variables that are used by Allegro (see below).
void set_config_file(const char *filename);
Sets the configuration file to be used by all subsequent config
functions. If you don't call this function, Allegro will use the default
allegro.cfg file, looking first in the same directory as your program and
then in the directory pointed to by the ALLEGRO environment variable.
All pointers returned by previous calls to get_config_string() and other related functions are invalidated when you call this function!
void set_config_data(const char *data, int length);
Specifies a block of data to be used by all subsequent config functions,
which you have already loaded from disk (eg. as part of some more
complicated format of your own, or in a grabber datafile). This routine
makes a copy of the information, so you can safely free the data after
calling it.
void override_config_file(const char *filename);
Specifies a file containing config overrides. These settings will be used
in addition to the parameters in the main config file, and where a
variable is present in both files this version will take priority. This
can be used by application programmers to override some of the config
settings from their code, while still leaving the main config file free
for the end user to customise. For example, you could specify a
particular sample frequency and IBK instrument file, but the user could
still use an allegro.cfg file to specify the port settings and irq
numbers.
void override_config_data(const char *data, int length);
Version of override_config_file() which uses a block of data that has
already been read into memory.
void push_config_state();
Pushes the current configuration state (filename, variable values, etc).
onto an internal stack, allowing you to select some other config source
and later restore the current settings by calling pop_config_state().
This function is mostly intended for internal use by other library
functions, for example when you specify a config filename to the
save_joystick_data() function, it pushes the config state before
switching to the file you specified.
void pop_config_state();
Pops a configuration state previously stored by push_config_state(),
replacing the current config source with it.
void flush_config_file();
Writes the current config file to disk if the contents have changed
since it was loaded or since the latest call to the function.
void reload_config_texts(const char *new_language);
Reloads the translated strings returned by get_config_text. This is
useful to switch to another language in your program at runtime. If you
want to modify the [system] language configuration variable yourself, or
you have switched configuration files, you will want to pass NULL to
just reload whatever language is currently selected. Or you can pass a
string containing the two letter code of the language you desire to
switch to, and the function will modify the language variable. After you
call this function, the previously returned pointers of get_config_text
will be invalid.
void hook_config_section(const char *section,
int (*intgetter)(const char *name, int def),
const char *(*stringgetter)(const char *name, const char *def),
void (*stringsetter)(const char *name, const char *value));
Takes control of the specified config file section, so that your hook
functions will be used to manipulate it instead of the normal disk file
access. If both the getter and setter functions are NULL, a currently
present hook will be unhooked. Hooked functions have the highest
priority. If a section is hooked, the hook will always be called, so you
can also hook a '#' section: even override_config_file() cannot override
a hooked section.
int config_is_hooked(const char *section);
Returns TRUE if the specified config section has been hooked.
const char *get_config_string(const char *section,
const char *name, const char *def);
Retrieves a string variable from the current config file. If the named
variable cannot be found, or its entry in the config file is empty, the
value of def is returned. The section name may be set to NULL to read
variables from the root of the file, or used to control which set of
parameters (eg. sound or joystick) you are interested in reading.
int get_config_int(const char *section, const char *name, int def);
Reads an integer variable from the current config file. See the comments
about get_config_string().
int get_config_hex(const char *section, const char *name, int def);
Reads an integer variable from the current config file, in hexadecimal
format. See the comments about get_config_string().
float get_config_float(const char *section, const char *name, float def);
Reads a floating point variable from the current config file. See the
comments about get_config_string().
int get_config_id(const char *section, const char *name, int def);
Reads a 4-letter driver ID variable from the current config file. See the
comments about get_config_string().
char **get_config_argv(const char *section, const char *name, int *argc);
Reads a token list (words separated by spaces) from the current config
file, returning a an argv style argument list, and setting argc to the
number of tokens (unlike argc/argv, this list is zero based). Returns
NULL and sets argc to zero if the variable is not present. The token list
is stored in a temporary buffer that will be clobbered by the next call
to get_config_argv(), so the data should not be expected to persist.
const char *get_config_text(const char *msg);
This function is primarily intended for use by internal library code, but
it may perhaps be helpful to application programmers as well. It uses the
language.dat or XXtext.cfg files (where XX is a language code) to look up
a translated version of the parameter in the currently selected language,
returning a suitable translation if one can be found or a copy of the
parameter if nothing else is available. This is basically the same thing
as calling get_config_string() with [language] as the section, msg as the
variable name, and msg as the default value, but it contains some special
code to handle Unicode format conversions. The msg parameter is always
given in ASCII format, but the returned string will be converted into the
current text encoding, with memory being allocated as required, so you
can assume that this pointer will persist without having to manually
allocate storage space for each string.
void set_config_string(const char *section, const char *name,
const char *val);
Writes a string variable to the current config file, replacing any
existing value it may have, or removes the variable if val is NULL. The
section name may be set to NULL to write the variable to the root of the
file, or used to control which section the variable is inserted into. The
altered file will be cached in memory, and not actually written to disk
until you call allegro_exit(). Note that you can only write to files in
this way, so the function will have no effect if the current config
source was specified with set_config_data() rather than set_config_file().
As a special case, variable or section names that begin with a '#' character are treated specially and will not be read from or written to the disk. Addon packages can use this to store version info or other status information into the config module, from where it can be read with the get_config_string() function.
void set_config_int(const char *section, const char *name, int val);
Writes an integer variable to the current config file. See the comments
about set_config_string().
void set_config_hex(const char *section, const char *name, int val);
Writes an integer variable to the current config file, in hexadecimal
format. See the comments about set_config_string().
void set_config_float(const char *section, const char *name, float val);
Writes a floating point variable to the current config file. See the
comments about set_config_string().
void set_config_id(const char *section, const char *name, int val);
Writes a 4-letter driver ID variable to the current config file. See the
comments about set_config_string().
Allegro uses these standard variables from the configuration file:
MICK - mickey mode driver (normally the best)
I33 - int 0x33 callback driver
POLL - timer polling (for use under NT)
Linux console mouse drivers are:
MS - Microsoft serial mouse
IMS - Microsoft serial mouse with Intellimouse extension
LPS2 - PS2 mouse
LIPS - PS2 mouse with Intellimouse extension
GPMD - GPM repeater data (Mouse Systems protocol)
0 - fast mixing of 8 bit data into 16 bit buffers
1 - true 16 bit mixing (requires a 16 bit stereo soundcard)
2 - interpolated 16 bit mixing
This section consists of a set of lines in the form:
For example, the line:
p36 = 0 34 9 12
specifies that whenever GM program 36 (which happens to be a fretless bass) is selected, Allegro should send a bank change message #0 with a parameter of 0, a bank change message #32 with a parameter of 34, a program change with a parameter of 9, and then should shift everything up by an octave.