Allegro allows you to use the sound hardware in two ways: automatic, or manual. Usually you should try the automatic version first. This means calling install_sound() with the autodetection parameters and using the rest of the sound functions to play samples or music. In this situation, Allegro will handle the sound devices and mix the samples and/or music the best way it can.
However, sound hardware has a limitation on the number of samples it may play all at the same time (from now on, called hardware voices). When you exceed this limit, Allegro will cut off one of the samples being played and reproduce the new one. Depending on the type of sounds you are playing, how many of them you need at the same time and their nature (e.g: vital audio feedback to the user or useless "ping" when some shrapnel hits a rock in the scenery) you will want to specify more carefully how hardware voices are reserved and which samples have priority over others.
The hardware voice reservation phase has to be done before the call to install_sound(), since it directly affects how Allegro talks to the sound drivers.
Return value: Returns the maximum number of voices that the driver can provide, or zero if the hardware is not present.
See also: install_sound, reserve_voices, DIGI_*/DOS, DIGI_*/Windows, DIGI_*/Unix, DIGI_*/BeOS, DIGI_*/QNX, DIGI_*/MacOSX.
Return value: 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.
See also: install_sound, reserve_voices, MIDI_*/DOS, MIDI_*/Windows, MIDI_*/Unix, MIDI_*/BeOS, MIDI_*/QNX, MIDI_*/MacOSX.
See also: set_volume_per_voice, install_sound, detect_digi_driver, detect_midi_driver, get_mixer_voices.
If clipping is a problem - or if the output is 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.
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.
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.
Note: The default behaviour has changed as of Allegro 4.1.15. If you would like the behaviour of earlier versions of Allegro, pass -1 to this function. Allegro will choose a value dependent on the number of voices, so 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. Here are the values, dependent on the number of voices:
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.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)
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.
Return value: 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, set_mixer_quality, DIGI_*/DOS, DIGI_*/Windows, DIGI_*/Unix, DIGI_*/BeOS, DIGI_*/QNX, DIGI_*/MacOSX, MIDI_*/DOS, MIDI_*/Windows, MIDI_*/Unix, MIDI_*/BeOS, MIDI_*/QNX, MIDI_*/MacOSX.
Examples using this: exmidi, exsample, exsprite, exstream.
See also: install_sound, allegro_exit.
See also: install_sound, set_hardware_volume.
See also: install_sound, set_volume.
See also: set_volume, get_hardware_volume.
See also: set_hardware_volume, get_volume.