<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
<html><head><title>
Allegro Manual: Sound init routines
</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta http-equiv="Content-Style-Type" content="text/css">
<link rel="stylesheet" title="Default" type="text/css" href="allegro.css"></head><body bgcolor=white text=black link="#0000ee" alink="#ff0000" vlink="#551a8b">
<h1><a name="Sound init routines">Sound init routines</a></h1>
<ul>
<li><a href="#detect_digi_driver">detect_digi_driver</a> — Detects whether the specified digital sound device is available.
<li><a href="#detect_midi_driver">detect_midi_driver</a> — Detects whether the specified MIDI sound device is available.
<li><a href="#get_hardware_volume">get_hardware_volume</a> — Retrieves the hardware sound output volume.
<li><a href="#get_volume">get_volume</a> — Retrieves the global sound output volume.
<li><a href="#install_sound">install_sound</a> — Initialises the sound module.
<li><a href="#remove_sound">remove_sound</a> — Cleans up after you are finished with the sound routines.
<li><a href="#reserve_voices">reserve_voices</a> — Reserve a number of voices for the digital and MIDI drivers.
<li><a href="#set_hardware_volume">set_hardware_volume</a> — Alters the hardware sound output volume.
<li><a href="#set_volume">set_volume</a> — Alters the global sound output volume.
<li><a href="#set_volume_per_voice">set_volume_per_voice</a> — Sets the volume of a voice.
</ul>
<p>
Allegro allows you to use the sound hardware in two ways: automatic, or
manual. Usually you should try the automatic version first. This means
calling install_sound() with the autodetection parameters and using the rest
of the sound functions to play samples or music. In this situation, Allegro
will handle the sound devices and mix the samples and/or music the best way
it can.
<p>
However, sound hardware has a limitation on the number of samples it may
play all at the same time (from now on, called hardware voices). When you
exceed this limit, Allegro will cut off one of the samples being played and
reproduce the new one. Depending on the type of sounds you are playing, how
many of them you need at the same time and their nature (e.g: vital audio
feedback to the user or useless "ping" when some shrapnel hits a rock in the
scenery) you will want to specify more carefully how hardware voices are
reserved and which samples have priority over others.
<p>
The hardware voice reservation phase has to be done before the call to
install_sound(), since it directly affects how Allegro talks to the sound
drivers.
<p><br>
<div class="al-api"><b>int <a name="detect_digi_driver">detect_digi_driver</a>(int driver_id);</b></div><br>
Detects whether the specified digital sound device is available. This
function must be called _before_ install_sound().
<p><b>Return value:</b>
Returns the maximum number of voices that the driver can provide, or zero
if the hardware is not present.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#install_sound" title="Initialises the sound module.">install_sound</a>,
<a class="xref" href="#reserve_voices" title="Reserve a number of voices for the digital and MIDI drivers.">reserve_voices</a>,
<a class="xref" href="alleg036.html#DIGI_*/DOS" title="Supported DOS digital sound drivers.">DIGI_*/DOS</a>,
<a class="xref" href="alleg037.html#DIGI_*/Windows" title="Supported Windows digital sound drivers.">DIGI_*/Windows</a>,
<a class="xref" href="alleg038.html#DIGI_*/Unix" title="Supported Unix digital sound drivers.">DIGI_*/Unix</a>,
<a class="xref" href="alleg039.html#DIGI_*/BeOS" title="Supported BeOS digital sound drivers.">DIGI_*/BeOS</a>,
<a class="xref" href="alleg040.html#DIGI_*/QNX" title="Supported QNX digital sound drivers.">DIGI_*/QNX</a>,
<a class="xref" href="alleg041.html#DIGI_*/MacOSX" title="Supported MacOSX digital sound drivers.">DIGI_*/MacOSX</a>.</blockquote>
<div class="al-api"><b>int <a name="detect_midi_driver">detect_midi_driver</a>(int driver_id);</b></div><br>
Detects whether the specified MIDI sound device is available. This function
must be called _before_ install_sound().
<p><b>Return value:</b>
Returns the maximum number of voices that the driver can provide, or zero
if the hardware is not present.
<p>
There are two special-case return values that you should watch out for:
if this function returns -1 it is a note-stealing driver (eg. DIGMID) that
shares voices with the current digital sound driver, and if it returns
0xFFFF it is an external device like an MPU-401 where there is no way to
determine how many voices are available.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#install_sound" title="Initialises the sound module.">install_sound</a>,
<a class="xref" href="#reserve_voices" title="Reserve a number of voices for the digital and MIDI drivers.">reserve_voices</a>,
<a class="xref" href="alleg036.html#MIDI_*/DOS" title="Supported DOS MIDI sound drivers.">MIDI_*/DOS</a>,
<a class="xref" href="alleg037.html#MIDI_*/Windows" title="Supported Windows MIDI sound drivers.">MIDI_*/Windows</a>,
<a class="xref" href="alleg038.html#MIDI_*/Unix" title="Supported Unix MIDI sound drivers.">MIDI_*/Unix</a>,
<a class="xref" href="alleg039.html#MIDI_*/BeOS" title="Supported BeOS MIDI sound drivers.">MIDI_*/BeOS</a>,
<a class="xref" href="alleg040.html#MIDI_*/QNX" title="Supported QNX MIDI sound drivers.">MIDI_*/QNX</a>,
<a class="xref" href="alleg041.html#MIDI_*/MacOSX" title="Supported MacOSX MIDI sound drivers.">MIDI_*/MacOSX</a>.</blockquote>
<div class="al-api"><b>void <a name="reserve_voices">reserve_voices</a>(int digi_voices, int midi_voices);</b></div><br>
Call this function to specify the number of voices that are to be used by
the digital and MIDI sound drivers respectively. This must be done
_before_ calling install_sound(). If you reserve too many voices,
subsequent calls to install_sound() will fail. How many voices are
available depends on the driver, and in some cases you will actually get
more than you reserve (eg. the FM synth drivers will always provide 9
voices on an OPL2 and 18 on an OPL3, and the SB digital driver will round
the number of voices up to the nearest power of two). Pass negative
values to restore the default settings. You should be aware that the
sound quality is usually inversely related to how many voices you use, so
don't reserve any more than you really need.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#set_volume_per_voice" title="Sets the volume of a voice.">set_volume_per_voice</a>,
<a class="xref" href="#install_sound" title="Initialises the sound module.">install_sound</a>,
<a class="xref" href="#detect_digi_driver" title="Detects whether the specified digital sound device is available.">detect_digi_driver</a>,
<a class="xref" href="#detect_midi_driver" title="Detects whether the specified MIDI sound device is available.">detect_midi_driver</a>,
<a class="xref" href="alleg025.html#get_mixer_voices" title="Returns the number of voices allocated to the mixer.">get_mixer_voices</a>.</blockquote>
<div class="al-api"><b>void <a name="set_volume_per_voice">set_volume_per_voice</a>(int scale);</b></div><br>
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.
<p>
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.
<p>
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.
<p>
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.
<p>
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:
<blockquote class="text"><pre>
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)
</pre></blockquote>
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.
<p>
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().
<p>
To restore volume per voice to its default behaviour, pass 1.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#reserve_voices" title="Reserve a number of voices for the digital and MIDI drivers.">reserve_voices</a>,
<a class="xref" href="#set_volume" title="Alters the global sound output volume.">set_volume</a>,
<a class="xref" href="#install_sound" title="Initialises the sound module.">install_sound</a>,
<a class="xref" href="#detect_digi_driver" title="Detects whether the specified digital sound device is available.">detect_digi_driver</a>,
<a class="xref" href="#detect_midi_driver" title="Detects whether the specified MIDI sound device is available.">detect_midi_driver</a>.</blockquote>
<div class="al-api"><b>int <a name="install_sound">install_sound</a>(int digi, int midi, const char *cfg_path);</b></div><br>
Initialises the sound module. You should normally pass DIGI_AUTODETECT
and MIDI_AUTODETECT as the driver parameters to this function, in which
case Allegro will read hardware settings from the current configuration
file. This allows the user to select different values with the setup
utility: see the config section for details. Alternatively, see the
platform specific documentation for a list of the available drivers. The
cfg_path parameter is only present for compatibility with previous
versions of Allegro, and has no effect on anything.
<p><b>Return value:</b>
Returns zero if the sound is successfully installed, and -1 on failure.
If it fails it will store a description of the problem in allegro_error.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#remove_sound" title="Cleans up after you are finished with the sound routines.">remove_sound</a>,
<a class="xref" href="#reserve_voices" title="Reserve a number of voices for the digital and MIDI drivers.">reserve_voices</a>,
<a class="xref" href="#detect_digi_driver" title="Detects whether the specified digital sound device is available.">detect_digi_driver</a>,
<a class="xref" href="#detect_midi_driver" title="Detects whether the specified MIDI sound device is available.">detect_midi_driver</a>,
<a class="xref" href="#set_volume" title="Alters the global sound output volume.">set_volume</a>,
<a class="xref" href="alleg026.html#play_sample" title="Plays a sample.">play_sample</a>,
<a class="xref" href="alleg026.html#Voice control" title="">Voice control</a>,
<a class="xref" href="alleg027.html#play_midi" title="Starts playing the specified MIDI file.">play_midi</a>,
<a class="xref" href="alleg028.html#play_audio_stream" title="Creates a new audio stream and starts playing it.">play_audio_stream</a>,
<a class="xref" href="alleg029.html#install_sound_input" title="Initialises the sound recorder module.">install_sound_input</a>,
<a class="xref" href="alleg000.html#allegro_error" title="Stores the last Allegro error message.">allegro_error</a>,
<a class="xref" href="alleg003.html#Standard config variables" title="">Standard config variables</a>,
<a class="xref" href="alleg025.html#set_mixer_quality" title="Sets the resampling quality of the mixer.">set_mixer_quality</a>,
<a class="xref" href="alleg036.html#DIGI_*/DOS" title="Supported DOS digital sound drivers.">DIGI_*/DOS</a>,
<a class="xref" href="alleg037.html#DIGI_*/Windows" title="Supported Windows digital sound drivers.">DIGI_*/Windows</a>,
<a class="xref" href="alleg038.html#DIGI_*/Unix" title="Supported Unix digital sound drivers.">DIGI_*/Unix</a>,
<a class="xref" href="alleg039.html#DIGI_*/BeOS" title="Supported BeOS digital sound drivers.">DIGI_*/BeOS</a>,
<a class="xref" href="alleg040.html#DIGI_*/QNX" title="Supported QNX digital sound drivers.">DIGI_*/QNX</a>,
<a class="xref" href="alleg041.html#DIGI_*/MacOSX" title="Supported MacOSX digital sound drivers.">DIGI_*/MacOSX</a>,
<a class="xref" href="alleg036.html#MIDI_*/DOS" title="Supported DOS MIDI sound drivers.">MIDI_*/DOS</a>,
<a class="xref" href="alleg037.html#MIDI_*/Windows" title="Supported Windows MIDI sound drivers.">MIDI_*/Windows</a>,
<a class="xref" href="alleg038.html#MIDI_*/Unix" title="Supported Unix MIDI sound drivers.">MIDI_*/Unix</a>,
<a class="xref" href="alleg039.html#MIDI_*/BeOS" title="Supported BeOS MIDI sound drivers.">MIDI_*/BeOS</a>,
<a class="xref" href="alleg040.html#MIDI_*/QNX" title="Supported QNX MIDI sound drivers.">MIDI_*/QNX</a>,
<a class="xref" href="alleg041.html#MIDI_*/MacOSX" title="Supported MacOSX MIDI sound drivers.">MIDI_*/MacOSX</a>.</blockquote>
<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#exmidi" title="Playing MIDI music.">exmidi</a>,
<a class="eref" href="alleg045.html#exsample" title="Playing digital samples.">exsample</a>,
<a class="eref" href="alleg045.html#exsprite" title="Datafiles access and sprite animation.">exsprite</a>,
<a class="eref" href="alleg045.html#exstream" title="Playing audio streams.">exstream</a>.</blockquote>
<div class="al-api"><b>void <a name="remove_sound">remove_sound</a>();</b></div><br>
Cleans up after you are finished with the sound routines. You don't
normally need to call this, because allegro_exit() will do it for you.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#install_sound" title="Initialises the sound module.">install_sound</a>,
<a class="xref" href="alleg000.html#allegro_exit" title="Closes down the Allegro system.">allegro_exit</a>.</blockquote>
<div class="al-api"><b>void <a name="set_volume">set_volume</a>(int digi_volume, int midi_volume);</b></div><br>
Alters the global sound output volume. Specify volumes for both digital
samples and MIDI playback, as integers from 0 to 255, or pass a negative
value to leave one of the settings unchanged. Values bigger than 255 will
be reduced to 255. This routine will not alter the volume of the hardware
mixer if it exists (i.e. only your application will be affected).
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#install_sound" title="Initialises the sound module.">install_sound</a>,
<a class="xref" href="#set_hardware_volume" title="Alters the hardware sound output volume.">set_hardware_volume</a>.</blockquote>
<div class="al-api"><b>void <a name="set_hardware_volume">set_hardware_volume</a>(int digi_volume, int midi_volume);</b></div><br>
Alters the hardware sound output volume. Specify volumes for both digital
samples and MIDI playback, as integers from 0 to 255, or pass a negative
value to leave one of the settings unchanged. Values bigger than 255 will
be reduced to 255. This routine will use the hardware mixer to control the
volume if it exists (i.e. the volume of all the applications on your
machine will be affected), otherwise do nothing.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#install_sound" title="Initialises the sound module.">install_sound</a>,
<a class="xref" href="#set_volume" title="Alters the global sound output volume.">set_volume</a>.</blockquote>
<div class="al-api"><b>void <a name="get_volume">get_volume</a>(int *digi_volume, int *midi_volume);</b></div><br>
Retrieves the global sound output volume, both for digital samples and MIDI
playback, as integers from 0 to 255. Parameters digi_volume and midi_volume
must be valid pointers to int, or NULL if not interested in specific value.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#set_volume" title="Alters the global sound output volume.">set_volume</a>,
<a class="xref" href="#get_hardware_volume" title="Retrieves the hardware sound output volume.">get_hardware_volume</a>.</blockquote>
<div class="al-api"><b>void <a name="get_hardware_volume">get_hardware_volume</a>(int *digi_volume, int *midi_volume);</b></div><br>
Retrieves the hardware sound output volume, both for digital samples and MIDI
playback, as integers from 0 to 255, or -1 if the information is not
available. Parameters digi_volume and midi_volume must be valid pointers to
int, or NULL if not interested in specific value.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#set_hardware_volume" title="Alters the hardware sound output volume.">set_hardware_volume</a>,
<a class="xref" href="#get_volume" title="Retrieves the global sound output volume.">get_volume</a>.</blockquote>
<hr><div class="al-back-to-contents"><a href="allegro.html">Back to contents</a></div>
</body>
</html>
distrib
>
Arklinux
>
devel
>
x86_64
>
media
>
main
>
by-pkgid
>
c13bc007afe382f898b3b1cfcaf62e82
>
files
>
797
