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)