Google

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

  • [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 "sp". 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.

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

    • dga_mouse = x
      X only: disable to work around a bug in some X servers' DGA modes, concerning the mouse. Default is on; enable the workaround by setting the variable to "0".

    • dga_centre = x
      X only: instructs the DGA driver to centre the Allegro screen if the actual screen resolution is higher than Allegro's. Default is on; disable this feature by setting the variable to "0".

    • dga_clear = x
      X only: instructs the DGA driver to clear visible video memory on startup. Default is on; disable this feature by setting the variable to "0".

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

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

    • 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 screen 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)

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

    • 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 yes if you have a two button mouse, no otherwise.

    • mouse_device = x
      Linux only: specifies the name of the mouse device file (eg. /dev/mouse).

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

    • digi_card = x
      Sets the driver to use for playing digital samples.

    • midi_card = x
      Sets the driver to use for MIDI music.

    • digi_input_card = x
      Sets the driver to use for digital sample input.

    • midi_input_card = x
      Sets the driver to use for MIDI data input.

    • digi_voices = x
      Specifies the minimum number of voices to reserve for use by the digital sound driver. How many are possible depends on the driver.

    • midi_voices = x
      Specifies the minimum number of voices to reserve for use by the MIDI sound driver. How many are possible depends on the driver.

    • digi_volume = x
      Sets the volume for digital sample playback, from 0 to 255.

    • midi_volume = x
      Sets the volume for midi music playback, from 0 to 255.

    • quality = x
      Controls the sound quality vs. performance tradeoff for the sample mixing code. This can be set to any of the values:
            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

    • flip_pan = x
      Toggling this between 0 and 1 reverses the left/right panning of samples, which might be needed because some SB cards (including mine :-) get the stereo image the wrong way round.

    • sound_freq = x
      DOS, Unix and BeOS: sets the sample frequency. With the SB driver, possible rates are 11906 (any), 16129 (any), 22727 (SB 2.0 and above), and 45454 (only on SB 2.0 or SB16, not the stereo SB Pro driver). On the ESS Audiodrive, possible rates are 11363, 17046, 22729, or 44194. On the Ensoniq Soundscape, possible rates are 11025, 16000, 22050, or 48000. On the Windows Sound System, possible rates are 11025, 22050, 44100, or 48000. Don't worry if you set some other number by mistake: Allegro will automatically round it to the closest supported frequency.

    • sound_bits = x
      Unix and BeOS: sets the preferred number of bits (8 or 16).

    • sound_stereo = x
      Unix and BeOS: selects mono or stereo output (0 or 1).

    • sound_port = x
      DOS only: sets the soundcard port address (this is usually 220).

    • sound_dma = x
      DOS only: sets the soundcard DMA channel (this is usually 1).

    • sound_irq = x
      DOS only: sets the soundcard IRQ number (this is usually 7).

    • fm_port = x
      DOS only: sets the port address of the OPL synth (this is usually 388).

    • mpu_port = x
      DOS only: sets the port address of the MPU-401 MIDI interface (this is usually 330).

    • mpu_irq = x
      DOS only: sets the IRQ for the MPU-401 (this is usually the same as sound_irq).

    • ibk_file = x
      DOS only: specifies the name of a .IBK file which will be used to replace the standard Adlib patch set.

    • ibk_drum_file = x
      DOS only: specifies the name of a .IBK file which will be used to replace the standard set of Adlib percussion patches.

    • oss_driver = x
      Unix only: sets the OSS device driver name. Usually /dev/dsp or /dev/audio, but could be a particular device (e.g. /dev/dsp2).

    • oss_numfrags = x
      oss_fragsize = x
      Unix only: sets number of OSS driver fragments (buffers) and size of each buffer in samples. Buffers are filled with data in the interrupts where interval between subsequent interrupts is not less than 10 ms. If hardware can play all information from buffers faster than 10 ms, then there will be clicks, when hardware have played all data and library has not prepared new data yet. On the other hand, if it takes too long for device driver to play data from all buffers, then there will be delays between action which triggers sound and sound itself.

    • oss_midi_driver = x
      Unix only: sets the OSS MIDI device name. Usually /dev/sequencer.

    • oss_mixer_driver = x
      Unix only: sets the OSS mixer device name. Usually /dev/mixer.

    • esd_server = x
      Unix only: where to find the ESD (Enlightened Sound Daemon) server.

    • alsa_card = x
      alsa_pcmdevice = x
      Unix only: paramaters for the ALSA sound driver system.

    • alsa_numfrags = x
      Unix only: number of ALSA driver fragments (buffers).

    • alsa_fragsize = x
      Unix only: size of each ALSA fragment, in samples.

    • alsa_rawmidi_card = x
      Unix only: ALSA card to use for midi output.

    • alsa_rawmidi_device = x
      Unix only: ALSA rawmidi device to use for output.

    • be_midi_quality = x
      BeOS only: system MIDI synthesizer instruments quality. 0 uses low quality 8-bit 11 kHz samples, 1 uses 16-bit 22 kHz samples.

    • be_midi_freq = x
      BeOS only: MIDI sample mixing frequency in Hz. Can be 11025, 22050 or 44100.

    • be_midi_interpolation = x
      BeOS only: specifies the MIDI samples interpolation method. 0 doesn't interpolate, it's fast but has the worst quality; 1 does a fast interpolation with better performances, but it's a bit slower than the previous method; 2 does a linear interpolation between samples, it is the slowest method but gives the best performances.

    • be_midi_reverb = x
      BeOS only: reverberation intensity, from 0 to 5. 0 disables it, 5 is the strongest one.

    • patches = x
      Specifies where to find the sample set for the DIGMID driver. This can either be a Gravis style directory containing a collection of .pat files and a default.cfg index, or an Allegro datafile produced by the pat2dat utility. If this variable is not set, Allegro will look either for a default.cfg or patches.dat file in the same directory as the program, the directory pointed to by the ALLEGRO environment variable, and the standard GUS directory pointed to by the ULTRASND environment variable.

  • [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 only: specifies the name of the joystick device to be used. First device found is used by default.

    • throttle_axis = x
      Linux only: sets which 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.