Configuration routines
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. MacOS X also checks in the Contents/Resources directory of the
application bundle, if any, before doing the checks above.
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 also extend the paths
searched for allegro resources with set_allegro_resource_path().
You can store whatever custom information you like in the config file, along
with the standard variables that are used by Allegro (see below). Allegro
comes with a setup directory where you can find configuration programs. The
standalone setup program is likely to be of interest to final users. It
allows any user to create an `allegro.cfg' file without the need to touch a
text editor and enter values by hand. It also provides a few basic tests like
sound playing for soundcard testing. You are welcome to include the setup
program with your game, either as is or with modified graphics to fit better
your game.
Standard config variables
Allegro uses these standard variables from the configuration file:
-
[system]
Section containing general purpose variables:
-
system = x
Specifies which system driver to use. This is currently only useful on
Linux, for choosing between the XWindows ("XWIN") or console ("LNXC")
modes.
-
keyboard = x
Specifies which keyboard layout to use. The parameter is the name of a
keyboard mapping file produced by the keyconf utility, and can either be
a fully qualified file path or a basename like `us' or `uk'. If the
latter, Allegro will look first for a separate config file with that name
(eg. `uk.cfg') and then for an object with that name in the `keyboard.dat'
file (eg. `UK_CFG'). The config file or `keyboard.dat' file can be stored
in the same directory as the program, or in the location pointed to by
the ALLEGRO environment variable. Look in the `keyboard.dat' file to see
what mappings are currently available.
-
language = x
Specifies which language file to use for error messages and other bits of
system text. The parameter is the name of a translation file, and can
either be a fully qualified file path or a basename like `en' or `es'. If
the latter, Allegro will look first for a separate config file with a
name in the form `entext.cfg', and then for an object with that name in
the `language.dat' file (eg. `ENTEXT_CFG'). The config file or
`language.dat' file can be stored in the same directory as the program, or
in the location pointed to by the ALLEGRO environment variable.
Look in the `language.dat' file to see which mappings are currently
available. If there is none for your language, you can create it using the
English one as model, and even send it to the Allegro development team to
include it in future releases.
-
disable_screensaver = x
Specifies whether to disable the screensaver: 0 to never disable it, 1 to
disable it in fullscreen mode only and 2 to always disable it. Default is 1.
-
menu_opening_delay = x
Sets how long the menus take to auto-open. The time is given in
milliseconds (default is `300'). Specifying `-1' will disable the
auto-opening feature.
-
XInitThreads = x
If this is set to 0, the X11 port will not call XInitThreads. This can have
slight performance advantages and was required on some broken X11 servers,
but it makes Allegro incompatible with other X11 libraries like Mesa.
-
[graphics]
Section containing graphics configuration information, using the
variables:
-
gfx_card = x
Specifies which graphics driver to use when the program requests
GFX_AUTODETECT. Multiple possible drivers can be suggested with extra
lines in the form `gfx_card1 = x', `gfx_card2 = x', etc, or you can
specify different drivers for each mode and color depth with variables in
the form `gfx_card_24bpp = x', `gfx_card_640x480x16 = x', etc.
-
gfx_cardw = x
Specifies which graphics driver to use when the program requests
GFX_AUTODETECT_WINDOWED. This variable functions exactly like
gfx_card in all other respects. If it is not set, Allegro will look
for the gfx_card variable.
-
disable_vsync = x
Specifies whether to disable synchronization with the vertical blank when
page-flipping (yes or no). Disabling synchronization may increase the
frame rate on slow systems, at the expense of introducing flicker on fast
systems.
-
vbeaf_driver = x
DOS and Linux only: specifies where to look for the VBE/AF driver
(vbeaf.drv). If this variable is not set, Allegro will look in the same
directory as the program, and then fall back on the standard locations
(`c:\' for DOS, `/usr/local/lib', `/usr/lib', `/lib', and `/' for Linux, or
the directory specified with the VBEAF_PATH environment variable).
-
framebuffer = x
Linux only: specifies what device file to use for the fbcon driver. If
this variable is not set, Allegro checks the FRAMEBUFFER environment
variable, and then defaults to `/dev/fb0'.
-
force_centering = x
Unix/X11 only: specifies whether to force window centering in fullscreen
mode when the XWFS driver is used (yes or no). Enabling this setting may
cause some artifacts to appear on KDE desktops.
-
disable_direct_updating = x
Windows only: specifies whether to disable direct updating when the
GFX_DIRECTX_WIN driver is used in color conversion mode (yes or no).
Direct updating can cause artifacts to be left on the desktop when the
window is moved or minimized; disabling it results in a significant
performance loss.
-
[mouse]
Section containing mouse configuration information, using the variables:
-
mouse = x
Mouse driver type. Available DOS drivers are:
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)
EV - Event interfaces (EVDEV)
-
num_buttons = x
Sets the number of mouse buttons viewed by Allegro. You don't normally
need to set this variable because Allegro will autodetect it. You can only
use it to restrict the set of actual mouse buttons to zero or positive
values, negative values will be ignored.
-
emulate_three = x
Sets whether to emulate a third mouse button by detecting chords of the
left and right buttons (yes or no). Defaults to no.
-
mouse_device = x
Linux only: specifies the name of the mouse device file (eg.
`/dev/mouse').
-
ev_absolute = x
Linux only: specifies the mode for the default EV input:
0 - relative mode: pointer position changes if the input moves,
1 - absolute mode: pointer position is the input position.
If unspecified, the mode is relative.
If the device supports several tools (such as a graphic tablet), the
default input is the mouse. If the device has only one tool (e.g. a
normal mouse) the default input is this tool. All additionnal tools
work in absolute mode.
-
ev_min_x = x
ev_max_x = x
ev_min_y = x
ev_max_y = x
ev_min_z = x
ev_max_z = x
Linux only: for absolute EV inputs, minimum and maximum value. By default
this information is autodetected. If you want to use only part of a
tablet, you need to set the entries for X and Y axis by hand.
-
ev_abs_to_rel_x = x
ev_abs_to_rel_y = x
ev_abs_to_rel_z = x
Linux only: scaling factor for tablet mouse speed. Defaults to 1.
This is used only when the input sends absolute events (tablet, joystick,
etc.) and the cursor should behave like a mouse.
If you are using a mouse on a tablet, you need to set these entries
for X and Y axis (try numbers between 1 and 40).
-
mouse_accel_factor = x
Windows only: specifies the mouse acceleration factor. Defaults to 1.
Set it to 0 in order to disable mouse acceleration. 2 accelerates twice
as much as 1.
-
[sound]
Section containing sound configuration information, using the variables:
-
[midimap]
If you are using the SB MIDI output or MPU-401 drivers with an external
synthesiser that is not General MIDI compatible, you can use the midimap
section of the config file to specify a patch mapping table for
converting GM patch numbers into whatever bank and program change
messages will select the appropriate sound on your synth. This is a real
piece of self-indulgence. I have a Yamaha TG500, which has some great
sounds but no GM patch set, and I just had to make it work somehow...
This section consists of a set of lines in the form:
-
p<n> = bank0 bank1 prog pitch
With this statement, n is the GM program change number (1-128), bank0 and
bank1 are the two bank change messages to send to your synth (on
controllers #0 and #32), prog is the program change message to send to
your synth, and pitch is the number of semitones to shift everything that
is played with that sound. Setting the bank change numbers to -1 will
prevent them from being sent.
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.
-
[joystick]
Section containing joystick configuration information, using the
variables:
-
joytype = x
Specifies which joystick driver to use when the program requests
JOY_TYPE_AUTODETECT.
-
joystick_device = x
BeOS and Linux only: specifies the name of the joystick device to be used
(as reported in the system joystick preferences under BeOS). The first
device found is used by default. If you want to specify the device for
each joystick, use variables of the form joystick_device_n, where n is
the joystick number.
-
throttle_axis = x
Linux only: sets the axis number the throttle is located at. This
variable will be used for every detected joystick. If you want to specify
the axis number for each joystick individually, use variables of the form
throttle_axis_n, where n is the joystick number.