plucky (3) set_volume_per_voice.3alleg4.gz

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)