Sound init routines


int detect_digi_driver(int driver_id);

Detects whether the specified digital sound device is available. Returns the maximum number of voices that the driver can provide, or zero if the hardware is not present. This function must be called _before_ install_sound().
See also: install_sound, reserve_voices, DIGI_*/DOS, DIGI_*/Windows, DIGI_*/Unix, DIGI_*/BeOS, DIGI_*/QNX.
int detect_midi_driver(int driver_id);

Detects whether the specified MIDI sound device is available. Returns the maximum number of voices that the driver can provide, or zero if the hardware is not present. There are two special-case return values that you should watch out for: if this function returns -1 it is a note-stealing driver (eg. DIGMID) that shares voices with the current digital sound driver, and if it returns 0xFFFF it is an external device like an MPU-401 where there is no way to determine how many voices are available. This function must be called _before_ install_sound().
See also: install_sound, reserve_voices, MIDI_*/DOS, MIDI_*/Windows, MIDI_*/Unix, MIDI_*/BeOS, MIDI_*/QNX.
void reserve_voices(int digi_voices, int midi_voices);

Call this function to specify the number of voices that are to be used by the digital and MIDI sound drivers respectively. This must be done _before_ calling install_sound(). If you reserve too many voices, subsequent calls to install_sound() will fail. How many voices are available depends on the driver, and in some cases you will actually get more than you reserve (eg. the FM synth drivers will always provide 9 voices on an OPL2 and 18 on an OPL3, and the SB digital driver will round the number of voices up to the nearest power of two). Pass negative values to restore the default settings. You should be aware that the sound quality is usually inversely related to how many voices you use, so don't reserve any more than you really need.
See also: set_volume_per_voice, install_sound, detect_digi_driver, detect_midi_driver.
void set_volume_per_voice(int scale);

By default, when you reserve more voices for the digital sound driver, Allegro will reduce the volume of each voice to compensate. This is done to avoid too much distortion. The default volume per voice is such that, if you reserve n voices, you can play up to n/2 normalised samples with centre panning without risking distortion. The exception is when you have fewer than 8 voices, where the volume remains the same as for 8 voices.

If the resultant output is either too loud or too quiet, this function can be used to adjust the volume of each voice. You should first check that your speakers are at a reasonable volume, Allegro's global volume is at maximum (see set_volume() below), and any other mixers such as the Windows Volume Control are set reasonably.

Once you are sure that Allegro's output level is unsuitable for your application, use this function to adjust it. This must be done _before_ calling install_sound(). Note that this function is currently only relevant for drivers that use the Allegro mixer (which is most of them).

If you pass 0 to this function, each centred sample will play at the maximum volume possible without distortion, as will all samples played through a mono driver. Samples at the extreme left and right will distort if played at full volume. If you wish to play panned samples at full volume without distortion, you should pass 1 to this function. Note: this is different from the function's behaviour in WIPs 3.9.34, 3.9.35 and 3.9.36. If you used this function under one of these WIPs, you will have to increase your parameter by one to get the same volume.

Each time you increase the parameter by one, the volume of each voice will halve. For example, if you pass 4, you can play up to 16 centred samples at maximum volume without distortion.

Here are the default values, dependent on the number of voices: 

     1-8 voices - set_volume_per_voice(2)
      16 voices - set_volume_per_voice(3)
      32 voices - set_volume_per_voice(4)
      64 voices - set_volume_per_voice(5)
Of course this function does not override the volume you specify with play_sample() or voice_set_volume(). It simply alters the overall output of the program. If you play samples at lower volumes, or if they are not normalised, then you can play more of them without distortion.

Warning: Allegro uses a clipping table to clip the waveform. The table is big enough to accommodate a total output of up to 4 times the maximum possible without distortion. If your output goes above this limit, the wave will 'wrap around' (peaks become troughs and vice versa), thus distorting much more. You should be careful that this does not happen.

It is recommended that you hard-code the parameter into your program, rather than offering it to the user. The user can alter the volume with the configuration file instead, or you can provide for this with set_volume().

To restore volume per voice to its default behaviour, pass -1.

See also: reserve_voices, set_volume, install_sound, detect_digi_driver, detect_midi_driver.
int install_sound(int digi, int midi, const char *cfg_path);

Initialises the sound module. You should normally pass DIGI_AUTODETECT and MIDI_AUTODETECT as the driver parameters to this function, in which case Allegro will read hardware settings from the current configuration file. This allows the user to select different values with the setup utility: see the config section for details. Alternatively, see the platform specific documentation for a list of the available drivers. The cfg_path parameter is only present for compatibility with previous versions of Allegro, and has no effect on anything. Returns zero if the sound is successfully installed, and -1 on failure. If it fails it will store a description of the problem in allegro_error.
See also: remove_sound, reserve_voices, detect_digi_driver, detect_midi_driver, set_volume, play_sample, Voice control, play_midi, play_audio_stream, install_sound_input, allegro_error, Standard config variables, DIGI_*/DOS, DIGI_*/Windows, DIGI_*/Unix, DIGI_*/BeOS, DIGI_*/QNX, MIDI_*/DOS, MIDI_*/Windows, MIDI_*/Unix, MIDI_*/BeOS, MIDI_*/QNX.
void remove_sound();

Cleans up after you are finished with the sound routines. You don't normally need to call this, because allegro_exit() will do it for you.
See also: install_sound, allegro_exit.
void set_volume(int digi_volume, int midi_volume);

Alters the global sound output volume. Specify volumes for both digital samples and MIDI playback, as integers from 0 to 255, or pass a negative value to leave one of the settings unchanged. If possible this routine will use a hardware mixer to control the volume, otherwise it will tell the sample and MIDI players to simulate a mixer in software.
See also: install_sound.
Back to contents