<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
<html><head><title>
Allegro Manual: Digital sample 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="Digital sample routines">Digital sample routines</a></h1>
<ul>
<li><a href="#adjust_sample">adjust_sample</a> — Alters the parameters of a sample while it is playing.
<li><a href="#allocate_voice">allocate_voice</a> — Allocates a sound card voice for a sample.
<li><a href="#create_sample">create_sample</a> — Constructs a new sample structure of the specified type.
<li><a href="#deallocate_voice">deallocate_voice</a> — Frees a sound card voice.
<li><a href="#destroy_sample">destroy_sample</a> — Destroys a sample structure when you are done with it.
<li><a href="#load_sample">load_sample</a> — Loads a sample from a file.
<li><a href="#load_voc">load_voc</a> — Loads a sample from a Creative Labs VOC file.
<li><a href="#load_voc_pf">load_voc_pf</a> — Packfile version of load_voc.
<li><a href="#load_wav">load_wav</a> — Loads a sample from a RIFF WAV file.
<li><a href="#load_wav_pf">load_wav_pf</a> — Packfile version of load_wav.
<li><a href="#lock_sample">lock_sample</a> — Locks all the memory used by a sample.
<li><a href="#play_sample">play_sample</a> — Plays a sample.
<li><a href="#reallocate_voice">reallocate_voice</a> — Switches the sample of an already-allocated voice.
<li><a href="#register_sample_file_type">register_sample_file_type</a> — Registers custom loading/saving sample routines.
<li><a href="#release_voice">release_voice</a> — Releases a sound card voice.
<li><a href="#save_sample">save_sample</a> — Writes a sample into a file.
<li><a href="#stop_sample">stop_sample</a> — Stops a sample from playing.
<li><a href="#voice_check">voice_check</a> — Checks whether a voice is currently allocated.
<li><a href="#voice_get_frequency">voice_get_frequency</a> — Returns the current pitch of the voice.
<li><a href="#voice_get_pan">voice_get_pan</a> — Returns the current pan position.
<li><a href="#voice_get_position">voice_get_position</a> — Returns the current position of a voice.
<li><a href="#voice_get_volume">voice_get_volume</a> — Returns the current volume of the voice.
<li><a href="#voice_ramp_volume">voice_ramp_volume</a> — Starts a volume ramp for a voice.
<li><a href="#voice_set_echo">voice_set_echo</a> — Sets the echo parameters for a voice.
<li><a href="#voice_set_frequency">voice_set_frequency</a> — Sets the pitch of the voice.
<li><a href="#voice_set_pan">voice_set_pan</a> — Sets the pan position.
<li><a href="#voice_set_playmode">voice_set_playmode</a> — Adjusts the loop status of the specified voice.
<li><a href="#voice_set_position">voice_set_position</a> — Sets the position of a voice.
<li><a href="#voice_set_priority">voice_set_priority</a> — Sets the priority of a voice.
<li><a href="#voice_set_tremolo">voice_set_tremolo</a> — Sets the tremolo parameters for a voice.
<li><a href="#voice_set_vibrato">voice_set_vibrato</a> — Sets the vibrato parameters for a voice.
<li><a href="#voice_set_volume">voice_set_volume</a> — Sets the volume of the voice.
<li><a href="#voice_start">voice_start</a> — Activates a voice.
<li><a href="#voice_stop">voice_stop</a> — Stops a voice.
<li><a href="#voice_stop_frequency_sweep">voice_stop_frequency_sweep</a> — Interrupts a frequency sweep operation.
<li><a href="#voice_stop_pan_sweep">voice_stop_pan_sweep</a> — Interrupts a pan sweep operation.
<li><a href="#voice_stop_volumeramp">voice_stop_volumeramp</a> — Interrupts a volume ramp operation.
<li><a href="#voice_sweep_frequency">voice_sweep_frequency</a> — Starts a frequency sweep for a voice.
<li><a href="#voice_sweep_pan">voice_sweep_pan</a> — Starts a pan sweep for a voice.
</ul>
<p><br>
<div class="al-api"><b><a class="autotype" href="alleg001.html#SAMPLE" title="Stores sound data.">SAMPLE</a> *<a name="load_sample">load_sample</a>(const char *filename);</b></div><br>
Loads a sample from a file, supporting both mono and stereo WAV and mono
VOC files, in 8 or 16-bit formats, as well as formats handled by functions
registered using register_sample_file_type(). Example:
<blockquote class="code"><pre>
<a href="alleg001.html#SAMPLE" class="autotype" title="Stores sound data.">SAMPLE</a> *sample = <a href="#load_sample" class="autotype" title="Loads a sample from a file.">load_sample</a>(user_input);
if (!sample)
abort_on_error("Couldn't load sample!");</pre></blockquote>
<p><b>Return value:</b>
Returns a pointer to the SAMPLE or NULL on error. Remember to free this
sample later to avoid memory leaks.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#destroy_sample" title="Destroys a sample structure when you are done with it.">destroy_sample</a>,
<a class="xref" href="#load_voc" title="Loads a sample from a Creative Labs VOC file.">load_voc</a>,
<a class="xref" href="#load_wav" title="Loads a sample from a RIFF WAV file.">load_wav</a>,
<a class="xref" href="#play_sample" title="Plays a sample.">play_sample</a>,
<a class="xref" href="#save_sample" title="Writes a sample into a file.">save_sample</a>,
<a class="xref" href="#register_sample_file_type" title="Registers custom loading/saving sample routines.">register_sample_file_type</a>,
<a class="xref" href="#Voice control" title="">Voice control</a>.</blockquote>
<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#exsample" title="Playing digital samples.">exsample</a>.</blockquote>
<div class="al-api"><b><a class="autotype" href="alleg001.html#SAMPLE" title="Stores sound data.">SAMPLE</a> *<a name="load_wav">load_wav</a>(const char *filename);</b></div><br>
Loads a sample from a RIFF WAV file. Example:
<blockquote class="code"><pre>
<a href="alleg001.html#SAMPLE" class="autotype" title="Stores sound data.">SAMPLE</a> *sample = <a href="#load_wav" class="autotype" title="Loads a sample from a RIFF WAV file.">load_wav</a>("scream.wav");
if (!sample)
abort_on_error("Couldn't scare user!");</pre></blockquote>
<p><b>Return value:</b>
Returns a pointer to the SAMPLE or NULL on error. Remember to free this
sample later to avoid memory leaks.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#load_sample" title="Loads a sample from a file.">load_sample</a>,
<a class="xref" href="#register_sample_file_type" title="Registers custom loading/saving sample routines.">register_sample_file_type</a>.</blockquote>
<div class="al-api"><b><a class="autotype" href="alleg001.html#SAMPLE" title="Stores sound data.">SAMPLE</a> *<a name="load_wav_pf">load_wav_pf</a>(<a class="autotype" href="alleg001.html#PACKFILE" title="Packfile structure, similar to the libc FILE structure.">PACKFILE</a> *f);</b></div><br>
A version of load_wav() which reads from a packfile. Example:
<blockquote class="code"><pre>
<a href="alleg001.html#PACKFILE" class="autotype" title="Packfile structure, similar to the libc FILE structure.">PACKFILE</a> *packfile;
<a href="alleg001.html#SAMPLE" class="autotype" title="Stores sound data.">SAMPLE</a> *sample;
packfile = <a href="alleg030.html#pack_fopen" class="autotype" title="Opens a file according to mode.">pack_fopen</a>("sound.wav", F_READ);
if (!packfile)
abort_on_error("Couldn't open sound.wav");
sample = <a href="#load_wav_pf" class="autotype" title="Packfile version of load_wav.">load_wav_pf</a>(packfile);
if (!sample)
abort_on_error("Error loading sound.wav");</pre></blockquote>
<p><b>Return value:</b>
Returns a pointer to the SAMPLE or NULL on error. Remember to free this
sample later to avoid memory leaks.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#load_wav" title="Loads a sample from a RIFF WAV file.">load_wav</a>.</blockquote>
<div class="al-api"><b><a class="autotype" href="alleg001.html#SAMPLE" title="Stores sound data.">SAMPLE</a> *<a name="load_voc">load_voc</a>(const char *filename);</b></div><br>
Loads a sample from a Creative Labs VOC file. Example:
<blockquote class="code"><pre>
<a href="alleg001.html#SAMPLE" class="autotype" title="Stores sound data.">SAMPLE</a> *sample = <a href="#load_voc" class="autotype" title="Loads a sample from a Creative Labs VOC file.">load_voc</a>("alarm.voc");
if (!sample)
abort_on_error("Couldn't <a href="alleg035.html#alert" class="autotype" title="Displays a popup alert box.">alert</a> user!");</pre></blockquote>
<p><b>Return value:</b>
Returns a pointer to the SAMPLE or NULL on error. Remember to free this
sample later to avoid memory leaks.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#load_sample" title="Loads a sample from a file.">load_sample</a>,
<a class="xref" href="#register_sample_file_type" title="Registers custom loading/saving sample routines.">register_sample_file_type</a>.</blockquote>
<div class="al-api"><b><a class="autotype" href="alleg001.html#SAMPLE" title="Stores sound data.">SAMPLE</a> *<a name="load_voc_pf">load_voc_pf</a>(<a class="autotype" href="alleg001.html#PACKFILE" title="Packfile structure, similar to the libc FILE structure.">PACKFILE</a> *f);</b></div><br>
A version of load_voc() which reads from a packfile. Example:
<blockquote class="code"><pre>
<a href="alleg001.html#PACKFILE" class="autotype" title="Packfile structure, similar to the libc FILE structure.">PACKFILE</a> *packfile;
<a href="alleg001.html#SAMPLE" class="autotype" title="Stores sound data.">SAMPLE</a> *sample;
packfile = <a href="alleg030.html#pack_fopen" class="autotype" title="Opens a file according to mode.">pack_fopen</a>("sound.wav", F_READ);
if (!packfile)
abort_on_error("Couldn't open sound.wav");
sample = <a href="#load_wav_pf" class="autotype" title="Packfile version of load_wav.">load_wav_pf</a>(packfile);
if (!sample)
abort_on_error("Error loading sound.wav");</pre></blockquote>
<p><b>Return value:</b>
Returns a pointer to the SAMPLE or NULL on error. Remember to free this
sample later to avoid memory leaks.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#load_voc" title="Loads a sample from a Creative Labs VOC file.">load_voc</a>.</blockquote>
<div class="al-api"><b>int <a name="save_sample">save_sample</a>(const char *filename, <a class="autotype" href="alleg001.html#SAMPLE" title="Stores sound data.">SAMPLE</a> *spl);</b></div><br>
Writes a sample into a file. The output format is determined from the
filename extension. At present Allegro does not natively support the
writing of any sample formats, so you must register a custom saver routine
with register_sample_file_type(). Example:
<blockquote class="code"><pre>
if (<a href="#save_sample" class="autotype" title="Writes a sample into a file.">save_sample</a>("sound.wav", sample) != 0)
abort_on_error("Couldn't save sample!");</pre></blockquote>
<p><b>Return value:</b>
Returns zero on success, non-zero otherwise.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#load_sample" title="Loads a sample from a file.">load_sample</a>,
<a class="xref" href="#register_sample_file_type" title="Registers custom loading/saving sample routines.">register_sample_file_type</a>.</blockquote>
<div class="al-api"><b><a class="autotype" href="alleg001.html#SAMPLE" title="Stores sound data.">SAMPLE</a> *<a name="create_sample">create_sample</a>(int bits, int stereo, int freq, int len);</b></div><br>
Constructs a new sample structure of the specified type. Read chapter
"Structures and types defined by Allegro" for an internal description of
the SAMPLE structure. The <tt>`bits'</tt> parameter can be 8 or 16, <tt>`stereo'</tt> can be
zero for mono samples and non-zero for stereo samples, <tt>`freq'</tt> is the
frequency in hertz, and <tt>`len'</tt> is the number of samples you want to allocate
for the full sound buffer.
<p><b>Return value:</b>
Returns a pointer to the created sample, or NULL if the sample could not
be created. Remember to free this sample later to avoid memory leaks.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#load_sample" title="Loads a sample from a file.">load_sample</a>,
<a class="xref" href="#destroy_sample" title="Destroys a sample structure when you are done with it.">destroy_sample</a>,
<a class="xref" href="alleg001.html#Structures and types defined by Allegro" title="">Structures and types defined by Allegro</a>.</blockquote>
<div class="al-api"><b>void <a name="destroy_sample">destroy_sample</a>(<a class="autotype" href="alleg001.html#SAMPLE" title="Stores sound data.">SAMPLE</a> *spl);</b></div><br>
Destroys a sample structure when you are done with it. It is safe to call
this even when the sample might be playing, because it checks and will
kill it off if it is active. Use this to avoid memory leaks in your
program.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#load_sample" title="Loads a sample from a file.">load_sample</a>.</blockquote>
<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#exsample" title="Playing digital samples.">exsample</a>.</blockquote>
<div class="al-api"><b>void <a name="lock_sample">lock_sample</a>(<a class="autotype" href="alleg001.html#SAMPLE" title="Stores sound data.">SAMPLE</a> *spl);</b></div><br>
Under DOS, locks all the memory used by a sample. You don't normally need
to call this function because load_sample() and create_sample() do it for
you.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#load_sample" title="Loads a sample from a file.">load_sample</a>,
<a class="xref" href="#create_sample" title="Constructs a new sample structure of the specified type.">create_sample</a>.</blockquote>
<div class="al-api"><b>void <a name="register_sample_file_type">register_sample_file_type</a>(const char *ext,
<a class="autotype" href="alleg001.html#SAMPLE" title="Stores sound data.">SAMPLE</a> *(*load)(const char *filename),
int (*save)(const char *filename, <a class="autotype" href="alleg001.html#SAMPLE" title="Stores sound data.">SAMPLE</a> *spl));</b></div><br>
Informs the load_sample() function of a new sample file type,
providing routines to read and write samples in this format (either
function may be NULL). Example:
<blockquote class="code"><pre>
<a href="alleg001.html#SAMPLE" class="autotype" title="Stores sound data.">SAMPLE</a> *load_mp3(const char *filename)
{
...
}
<a href="#register_sample_file_type" class="autotype" title="Registers custom loading/saving sample routines.">register_sample_file_type</a>("mp3", load_mp3, NULL);</pre></blockquote>
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#load_sample" title="Loads a sample from a file.">load_sample</a>,
<a class="xref" href="#save_sample" title="Writes a sample into a file.">save_sample</a>.</blockquote>
<div class="al-api"><b>int <a name="play_sample">play_sample</a>(const <a class="autotype" href="alleg001.html#SAMPLE" title="Stores sound data.">SAMPLE</a> *spl, int vol, int pan, int freq, int loop);</b></div><br>
Triggers a sample at the specified volume, pan position, and frequency.
The parameters <tt>`vol'</tt> and <tt>`pan'</tt> range from 0 (min/left) to 255 (max/right).
Frequency is relative rather than absolute: 1000 represents the frequency
that the sample was recorded at, 2000 is twice this, etc. If <tt>`loop'</tt> is not
zero, the sample will repeat until you call stop_sample(), and can be
manipulated while it is playing by calling adjust_sample(). Example:
<blockquote class="code"><pre>
/* Scream from the left speaker, twice the freq. */
int sound = <a href="#play_sample" class="autotype" title="Plays a sample.">play_sample</a>(scream, 255, 0, 2000, 0);</pre></blockquote>
<p><b>Return value:</b>
Returns the voice number that was allocated for the sample or negative if
no voices were available.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="alleg024.html#install_sound" title="Initialises the sound module.">install_sound</a>,
<a class="xref" href="#load_sample" title="Loads a sample from a file.">load_sample</a>,
<a class="xref" href="#adjust_sample" title="Alters the parameters of a sample while it is playing.">adjust_sample</a>,
<a class="xref" href="#stop_sample" title="Stops a sample from playing.">stop_sample</a>,
<a class="xref" href="#Voice control" title="">Voice control</a>.</blockquote>
<blockquote class="eref"><em><b>Examples using this:</b></em>
<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>.</blockquote>
<div class="al-api"><b>void <a name="adjust_sample">adjust_sample</a>(const <a class="autotype" href="alleg001.html#SAMPLE" title="Stores sound data.">SAMPLE</a> *spl, int vol, int pan, int freq, int loop);</b></div><br>
Alters the parameters of a sample while it is playing (useful for
manipulating looped sounds). You can alter the volume, pan, and frequency,
and can also clear the loop flag, which will stop the sample when it next
reaches the end of its loop. The values of the parameters are just like
those of play_sample(). If there are several copies of the same sample
playing, this will adjust the first one it comes across. If the sample is
not playing it has no effect.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#play_sample" title="Plays a sample.">play_sample</a>.</blockquote>
<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#exsample" title="Playing digital samples.">exsample</a>.</blockquote>
<div class="al-api"><b>void <a name="stop_sample">stop_sample</a>(const <a class="autotype" href="alleg001.html#SAMPLE" title="Stores sound data.">SAMPLE</a> *spl);</b></div><br>
Stop a sample from playing, which is required if you have set a sample
going in looped mode. If there are several copies of the sample playing,
it will stop them all. You must still destroy the sample using
destroy_sample().
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#play_sample" title="Plays a sample.">play_sample</a>,
<a class="xref" href="#destroy_sample" title="Destroys a sample structure when you are done with it.">destroy_sample</a>.</blockquote>
<br><center><h2><a name="Voice control">Voice control</a></h2></center><p>
If you need more detailed control over how samples are played, you can use
the lower level voice functions rather than just calling play_sample(). This
is rather more work, because you have to explicitly allocate and free the
voices rather than them being automatically released when they finish
playing, but allows far more precise specification of exactly how you want
everything to sound. You may also want to modify a couple of fields from the
SAMPLE structure. Read chapter "Structures and types defined by Allegro" for
its definition.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="alleg024.html#install_sound" title="Initialises the sound module.">install_sound</a>,
<a class="xref" href="#allocate_voice" title="Allocates a sound card voice for a sample.">allocate_voice</a>,
<a class="xref" href="#deallocate_voice" title="Frees a sound card voice.">deallocate_voice</a>,
<a class="xref" href="#reallocate_voice" title="Switches the sample of an already-allocated voice.">reallocate_voice</a>,
<a class="xref" href="#release_voice" title="Releases a sound card voice.">release_voice</a>,
<a class="xref" href="#voice_start" title="Activates a voice.">voice_start</a>,
<a class="xref" href="#voice_set_priority" title="Sets the priority of a voice.">voice_set_priority</a>,
<a class="xref" href="#voice_check" title="Checks whether a voice is currently allocated.">voice_check</a>,
<a class="xref" href="#voice_set_position" title="Sets the position of a voice.">voice_set_position</a>,
<a class="xref" href="#voice_set_playmode" title="Adjusts the loop status of the specified voice.">voice_set_playmode</a>,
<a class="xref" href="#voice_set_volume" title="Sets the volume of the voice.">voice_set_volume</a>,
<a class="xref" href="#voice_set_frequency" title="Sets the pitch of the voice.">voice_set_frequency</a>,
<a class="xref" href="#voice_set_pan" title="Sets the pan position.">voice_set_pan</a>,
<a class="xref" href="alleg001.html#SAMPLE" title="Stores sound data.">SAMPLE</a>.</blockquote>
<div class="al-api"><b>int <a name="allocate_voice">allocate_voice</a>(const <a class="autotype" href="alleg001.html#SAMPLE" title="Stores sound data.">SAMPLE</a> *spl);</b></div><br>
Allocates a sound card voice and prepares it for playing the specified
sample, setting up sensible default parameters (maximum volume, centre
pan, no change of pitch, no looping). When you are finished with the
voice you must free it by calling deallocate_voice() or release_voice().
Allegro can manage up to 256 simultaneous voices, but that limit may be
lower due to hardware reasons.
<p><b>Return value:</b>
Returns the voice number, or -1 if no voices are available.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#Voice control" title="">Voice control</a>,
<a class="xref" href="#deallocate_voice" title="Frees a sound card voice.">deallocate_voice</a>,
<a class="xref" href="#reallocate_voice" title="Switches the sample of an already-allocated voice.">reallocate_voice</a>,
<a class="xref" href="#release_voice" title="Releases a sound card voice.">release_voice</a>,
<a class="xref" href="#load_sample" title="Loads a sample from a file.">load_sample</a>.</blockquote>
<div class="al-api"><b>void <a name="deallocate_voice">deallocate_voice</a>(int voice);</b></div><br>
Frees a sound card voice, stopping it from playing and releasing whatever
resources it is using.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#allocate_voice" title="Allocates a sound card voice for a sample.">allocate_voice</a>,
<a class="xref" href="#voice_stop" title="Stops a voice.">voice_stop</a>.</blockquote>
<div class="al-api"><b>void <a name="reallocate_voice">reallocate_voice</a>(int voice, const <a class="autotype" href="alleg001.html#SAMPLE" title="Stores sound data.">SAMPLE</a> *spl);</b></div><br>
Switches an already-allocated voice to use a different sample. Calling
reallocate_voice(voice, sample) is equivalent to:
<blockquote class="code"><pre>
<a href="#deallocate_voice" class="autotype" title="Frees a sound card voice.">deallocate_voice</a>(voice);
voice = <a href="#allocate_voice" class="autotype" title="Allocates a sound card voice for a sample.">allocate_voice</a>(sample);</pre></blockquote>
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#allocate_voice" title="Allocates a sound card voice for a sample.">allocate_voice</a>,
<a class="xref" href="#deallocate_voice" title="Frees a sound card voice.">deallocate_voice</a>,
<a class="xref" href="#load_sample" title="Loads a sample from a file.">load_sample</a>.</blockquote>
<div class="al-api"><b>void <a name="release_voice">release_voice</a>(int voice);</b></div><br>
Releases a sound card voice, indicating that you are no longer interested
in manipulating it. The sound will continue to play, and any resources
that it is using will automatically be freed when it finishes. This is
essentially the same as deallocate_voice(), but it waits for the sound to
stop playing before taking effect.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#allocate_voice" title="Allocates a sound card voice for a sample.">allocate_voice</a>,
<a class="xref" href="#deallocate_voice" title="Frees a sound card voice.">deallocate_voice</a>.</blockquote>
<div class="al-api"><b>void <a name="voice_start">voice_start</a>(int voice);</b></div><br>
Activates a voice, using whatever parameters have been set for it.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#Voice control" title="">Voice control</a>,
<a class="xref" href="#allocate_voice" title="Allocates a sound card voice for a sample.">allocate_voice</a>,
<a class="xref" href="#voice_stop" title="Stops a voice.">voice_stop</a>,
<a class="xref" href="#release_voice" title="Releases a sound card voice.">release_voice</a>.</blockquote>
<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#exstream" title="Playing audio streams.">exstream</a>.</blockquote>
<div class="al-api"><b>void <a name="voice_stop">voice_stop</a>(int voice);</b></div><br>
Stops a voice, storing the current position and state so that it may
later be resumed by calling voice_start().
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#voice_start" title="Activates a voice.">voice_start</a>,
<a class="xref" href="#deallocate_voice" title="Frees a sound card voice.">deallocate_voice</a>,
<a class="xref" href="#release_voice" title="Releases a sound card voice.">release_voice</a>.</blockquote>
<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#exstream" title="Playing audio streams.">exstream</a>.</blockquote>
<div class="al-api"><b>void <a name="voice_set_priority">voice_set_priority</a>(int voice, int priority);</b></div><br>
Sets the priority of a voice (range 0-255). This is used to decide which
voices should be chopped off, if you attempt to play more than the
sound card driver can handle.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#Voice control" title="">Voice control</a>.</blockquote>
<div class="al-api"><b><a class="autotype" href="alleg001.html#SAMPLE" title="Stores sound data.">SAMPLE</a> *<a name="voice_check">voice_check</a>(int voice);</b></div><br>
Checks whether a voice is currently allocated.
<p><b>Return value:</b>
Returns a pointer to the sample that the voice is using, or NULL if the
voice is inactive (ie. it has been deallocated, or the release_voice()
function has been called and the sample has then finished playing).
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#allocate_voice" title="Allocates a sound card voice for a sample.">allocate_voice</a>,
<a class="xref" href="#voice_start" title="Activates a voice.">voice_start</a>,
<a class="xref" href="#voice_get_position" title="Returns the current position of a voice.">voice_get_position</a>.</blockquote>
<div class="al-api"><b>int <a name="voice_get_position">voice_get_position</a>(int voice);</b></div><br>
Returns the current position of a voice, in sample units, or -1 if it has
finished playing.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#Voice control" title="">Voice control</a>,
<a class="xref" href="#voice_set_position" title="Sets the position of a voice.">voice_set_position</a>.</blockquote>
<div class="al-api"><b>void <a name="voice_set_position">voice_set_position</a>(int voice, int position);</b></div><br>
Sets the position of a voice, in sample units.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#Voice control" title="">Voice control</a>,
<a class="xref" href="#voice_get_position" title="Returns the current position of a voice.">voice_get_position</a>,
<a class="xref" href="#voice_set_playmode" title="Adjusts the loop status of the specified voice.">voice_set_playmode</a>.</blockquote>
<div class="al-api"><b>void <a name="voice_set_playmode">voice_set_playmode</a>(int voice, int playmode);</b></div><br>
Adjusts the loop status of the specified voice. This can be done while
the voice is playing, so you can start a sample in looped mode (having
set the loop start and end positions to the appropriate values), and then
clear the loop flag when you want to end the sound, which will cause it
to continue past the loop end, play the subsequent part of the sample,
and finish in the normal way. The mode parameter is a bitfield containing
the following values:
<ul><li>
PLAYMODE_PLAY<br>
Plays the sample a single time. This is the default if you don't set
the loop flag.
<li>
PLAYMODE_LOOP<br>
Loops repeatedly through the sample, jumping back to the loop start
position upon reaching the loop end.
<li>
PLAYMODE_FORWARD<br>
Plays the sample from beginning to end. This is the default if you
don't set the backward flag.
<li>
PLAYMODE_BACKWARD<br>
Reverses the direction of the sample. If you combine this with the
loop flag, the sample jumps to the loop end position upon reaching the
loop start (ie. you do not need to reverse the loop start and end
values when you play the sample in reverse).
<li>
PLAYMODE_BIDIR<br>
When used in combination with the loop flag, causes the sample to
change direction each time it reaches one of the loop points, so it
alternates between playing forwards and in reverse.
</ul>
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#Voice control" title="">Voice control</a>.</blockquote>
<div class="al-api"><b>int <a name="voice_get_volume">voice_get_volume</a>(int voice);</b></div><br>
Returns the current volume of the voice, range 0-255. Otherwise it
returns -1 if that cannot be determined (because it has finished or
been preempted by a different sound).
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#Voice control" title="">Voice control</a>,
<a class="xref" href="#voice_set_volume" title="Sets the volume of the voice.">voice_set_volume</a>.</blockquote>
<div class="al-api"><b>void <a name="voice_set_volume">voice_set_volume</a>(int voice, int volume);</b></div><br>
Sets the volume of the voice, range 0-255.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#Voice control" title="">Voice control</a>,
<a class="xref" href="#voice_get_volume" title="Returns the current volume of the voice.">voice_get_volume</a>,
<a class="xref" href="#voice_ramp_volume" title="Starts a volume ramp for a voice.">voice_ramp_volume</a>.</blockquote>
<div class="al-api"><b>void <a name="voice_ramp_volume">voice_ramp_volume</a>(int voice, int time, int endvol);</b></div><br>
Starts a volume ramp (crescendo or diminuendo) from the current volume to
the specified ending volume, lasting for time milliseconds. The volume is
a value in the range 0-255.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#Voice control" title="">Voice control</a>,
<a class="xref" href="#voice_set_volume" title="Sets the volume of the voice.">voice_set_volume</a>.</blockquote>
<div class="al-api"><b>void <a name="voice_stop_volumeramp">voice_stop_volumeramp</a>(int voice);</b></div><br>
Interrupts a volume ramp operation.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#voice_ramp_volume" title="Starts a volume ramp for a voice.">voice_ramp_volume</a>.</blockquote>
<div class="al-api"><b>int <a name="voice_get_frequency">voice_get_frequency</a>(int voice);</b></div><br>
Returns the current pitch of the voice, in Hz.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#Voice control" title="">Voice control</a>,
<a class="xref" href="#voice_set_frequency" title="Sets the pitch of the voice.">voice_set_frequency</a>.</blockquote>
<div class="al-api"><b>void <a name="voice_set_frequency">voice_set_frequency</a>(int voice, int frequency);</b></div><br>
Sets the pitch of the voice, in Hz.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#Voice control" title="">Voice control</a>,
<a class="xref" href="#voice_get_frequency" title="Returns the current pitch of the voice.">voice_get_frequency</a>,
<a class="xref" href="#voice_sweep_frequency" title="Starts a frequency sweep for a voice.">voice_sweep_frequency</a>.</blockquote>
<div class="al-api"><b>void <a name="voice_sweep_frequency">voice_sweep_frequency</a>(int voice, int time, int endfreq);</b></div><br>
Starts a frequency sweep (glissando) from the current pitch to the
specified ending pitch, lasting for time milliseconds.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#Voice control" title="">Voice control</a>,
<a class="xref" href="#voice_set_frequency" title="Sets the pitch of the voice.">voice_set_frequency</a>.</blockquote>
<div class="al-api"><b>void <a name="voice_stop_frequency_sweep">voice_stop_frequency_sweep</a>(int voice);</b></div><br>
Interrupts a frequency sweep operation.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#voice_sweep_frequency" title="Starts a frequency sweep for a voice.">voice_sweep_frequency</a>.</blockquote>
<div class="al-api"><b>int <a name="voice_get_pan">voice_get_pan</a>(int voice);</b></div><br>
Returns the current pan position, from 0 (left) to 255 (right).
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#Voice control" title="">Voice control</a>,
<a class="xref" href="#voice_set_pan" title="Sets the pan position.">voice_set_pan</a>.</blockquote>
<div class="al-api"><b>void <a name="voice_set_pan">voice_set_pan</a>(int voice, int pan);</b></div><br>
Sets the pan position, ranging from 0 (left) to 255 (right).
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#Voice control" title="">Voice control</a>,
<a class="xref" href="#voice_get_pan" title="Returns the current pan position.">voice_get_pan</a>,
<a class="xref" href="#voice_sweep_pan" title="Starts a pan sweep for a voice.">voice_sweep_pan</a>.</blockquote>
<div class="al-api"><b>void <a name="voice_sweep_pan">voice_sweep_pan</a>(int voice, int time, int endpan);</b></div><br>
Starts a pan sweep (left <-> right movement) from the current position to
the specified ending position, lasting for time milliseconds.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#Voice control" title="">Voice control</a>,
<a class="xref" href="#voice_set_pan" title="Sets the pan position.">voice_set_pan</a>.</blockquote>
<div class="al-api"><b>void <a name="voice_stop_pan_sweep">voice_stop_pan_sweep</a>(int voice);</b></div><br>
Interrupts a pan sweep operation.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#voice_sweep_pan" title="Starts a pan sweep for a voice.">voice_sweep_pan</a>.</blockquote>
<div class="al-api"><b>void <a name="voice_set_echo">voice_set_echo</a>(int voice, int strength, int delay);</b></div><br>
Sets the echo parameters for a voice (not currently implemented).
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#Voice control" title="">Voice control</a>.</blockquote>
<div class="al-api"><b>void <a name="voice_set_tremolo">voice_set_tremolo</a>(int voice, int rate, int depth);</b></div><br>
Sets the tremolo parameters for a voice (not currently implemented).
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#Voice control" title="">Voice control</a>.</blockquote>
<div class="al-api"><b>void <a name="voice_set_vibrato">voice_set_vibrato</a>(int voice, int rate, int depth);</b></div><br>
Sets the vibrato parameters for a voice (not currently implemented).
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#Voice control" title="">Voice control</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
>
799
