Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
set_volume_per_voice(3)		Allegro	manual	       set_volume_per_voice(3)

       set_volume_per_voice  -	Sets  the volume of a voice. Allegro game pro-
       gramming	library.

       #include	<allegro.h>

       void set_volume_per_voice(int scale);

       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 clip-
       ping,  a	 noticeable  form  of  distortion.  The	more samples, the more
       likely clipping is to occur, and	the more clipping, the worse the  out-
       put will	sound.

       If  clipping  is	a problem - or if the output is	too quiet - this func-
       tion 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 dis-
       tort 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 nor-
       malised samples with centre panning without risking distortion. The ex-
       ception	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  out-
       put  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

       To restore volume per voice to its default behaviour, pass 1.

       reserve_voices(3),	set_volume(3),	    install_sound(3),	   de-
       tect_digi_driver(3), detect_midi_driver(3)

Allegro				 version 4.4.3	       set_volume_per_voice(3)


Want to link to this manual page? Use this URL:

home | help