set_volume_per_voice(3)

NAME
set_volume_per_voice

SYNOPSIS
#include <allegro.h>

void set_volume_per_voice(int scale);

DESCRIPTION
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(3), set_volume(3), install_sound(3), detect_digi_driver(3), detect_midi_driver(3)