NAME¶
set_volume_per_voice - Sets the volume of a voice. Allegro game programming
library.
SYNOPSIS¶
#include <allegro.h>
void set_volume_per_voice(int scale);
DESCRIPTION¶
By default, Allegro will play a centered sample at half volume on both the left
and right channel. A sample panned to the far right or left will be played at
maximum volume on that channel only. This is done so you can play a single
panned sample without distortion. If you play multiple samples at full volume,
the mixing process can result in clipping, a noticeable form of distortion.
The more samples, the more likely clipping is to occur, and the more clipping,
the worse the output will sound.
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:
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.
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(3alleg4),
set_volume(3alleg4),
install_sound(3alleg4),
detect_digi_driver(3alleg4),
detect_midi_driver(3alleg4)