<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
<html><head><title>
Allegro Manual: Audio stream 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="Audio stream routines">Audio stream routines</a></h1>
<ul>
<li><a href="#free_audio_stream_buffer">free_audio_stream_buffer</a> — Tells the audio stream player new data can be played.
<li><a href="#get_audio_stream_buffer">get_audio_stream_buffer</a> — Tells you if you need to fill the audiostream or not.
<li><a href="#play_audio_stream">play_audio_stream</a> — Creates a new audio stream and starts playing it.
<li><a href="#stop_audio_stream">stop_audio_stream</a> — Destroys an audio stream when it is no longer required.
</ul>
<p>
The audio stream functions are for playing digital sounds that are too big
to fit in a regular SAMPLE structure, either because they are huge files
that you want to load in pieces as the data is required, or because you are
doing something clever like generating the waveform on the fly.
<p>
You can think of an AUDIOSTREAM structure as a wrapper around two audio
buffers. The first thing you do is fill both buffers with sound data and let
Allegro play them. Once the first buffer has been played, the second starts,
and Allegro lets you know you have to fill the other one (i.e. graphics
double buffering applied to sounds too big to fit into memory).
<p>
The implementation of the sound buffers uses normal SAMPLE structures, so you
can use all the voice_*() functions to modify the audio streams. Read chapter
"Digital sample routines", section "Voice control" for a list of additional
functions you can use. Read chapter "Structures and types defined by Allegro"
for the internals of the AUDIOSTREAM structure.
<p><br>
<div class="al-api"><b><a class="autotype" href="alleg001.html#AUDIOSTREAM" title="Stores an audiostream.">AUDIOSTREAM</a> *<a name="play_audio_stream">play_audio_stream</a>(int len, int bits, int stereo,
int freq, int vol, int pan);</b></div><br>
This function creates a new audio stream and starts playing it. The
length is the size of each transfer buffer in sample frames (not bytes),
where a sample frame is a single sample value for mono data or a pair of
interleaved sample values (left first) for stereo data. The length should
normally be (but doesn't have to be) a power of 2 somewhere around 1k in
size. Larger buffers are more efficient and require fewer updates, but
result in more latency between you providing the data and it actually
being played.
<p>
The <tt>`bits'</tt> parameter must be 8 or 16. <tt>`freq'</tt> is the sample rate of the
data in Hertz. The <tt>`vol'</tt> and <tt>`pan'</tt> values use the same 0-255 ranges as the
regular sample playing functions. The <tt>`stereo'</tt> parameter should be set to
1 for stereo streams, or 0 otherwise.
<p>
If you want to adjust the pitch, volume, or panning of a stream once it is
playing, you can use the regular voice_*() functions with stream->voice
as a parameter. The format of the sample data is described in the SAMPLE
entry of the "Structures and types defined by Allegro" chapter. The formula
to get the size of the buffers in bytes could be:
<blockquote class="code"><pre>
bytes = length * (bits / 8) * (stereo ? 2 : 1)</pre></blockquote>
Example:
<blockquote class="code"><pre>
/* Create a 22KHz 8bit mono audio stream. */
stream = <a href="#play_audio_stream" class="autotype" title="Creates a new audio stream and starts playing it.">play_audio_stream</a>(1024, 8, FALSE, 22050, 255, 128);
if (!stream)
abort_on_error("Error creating audio stream!\n");</pre></blockquote>
<p><b>Return value:</b>
This function returns a pointer to the audio stream or NULL if it could
not be created.
<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="#get_audio_stream_buffer" title="Tells you if you need to fill the audiostream or not.">get_audio_stream_buffer</a>,
<a class="xref" href="#stop_audio_stream" title="Destroys an audio stream when it is no longer required.">stop_audio_stream</a>,
<a class="xref" href="alleg001.html#AUDIOSTREAM" title="Stores an audiostream.">AUDIOSTREAM</a>,
<a class="xref" href="alleg026.html#Voice control" title="">Voice control</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="stop_audio_stream">stop_audio_stream</a>(<a class="autotype" href="alleg001.html#AUDIOSTREAM" title="Stores an audiostream.">AUDIOSTREAM</a> *stream);</b></div><br>
Destroys an audio stream when it is no longer required.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#play_audio_stream" title="Creates a new audio stream and starts playing it.">play_audio_stream</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="get_audio_stream_buffer">get_audio_stream_buffer</a>(<a class="autotype" href="alleg001.html#AUDIOSTREAM" title="Stores an audiostream.">AUDIOSTREAM</a> *stream);</b></div><br>
You must call this function at regular intervals while an audio stream is
playing, to provide the next buffer of sample data (the smaller the
stream buffer size, the more often it must be called). This function should
not be called from a timer handler. Example:
<blockquote class="code"><pre>
void *mem_chunk;
...
while (TRUE) {
...
mem_chunk = <a href="#get_audio_stream_buffer" class="autotype" title="Tells you if you need to fill the audiostream or not.">get_audio_stream_buffer</a>(buffer);
if (mem_chunk != NULL) {
/* Refill the stream buffer. */
}
}</pre></blockquote>
<p><b>Return value:</b>
If it returns NULL, the stream is still playing the previous lot of data,
so you don't need to do anything. If it returns a value, that is the
location of the next buffer to be played, and you should load the
appropriate number of samples (however many you specified when creating the
stream) to that address, for example using an fread() from a disk file.
After filling the buffer with data, call free_audio_stream_buffer() to
indicate that the new data is now valid.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#play_audio_stream" title="Creates a new audio stream and starts playing it.">play_audio_stream</a>,
<a class="xref" href="#free_audio_stream_buffer" title="Tells the audio stream player new data can be played.">free_audio_stream_buffer</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="free_audio_stream_buffer">free_audio_stream_buffer</a>(<a class="autotype" href="alleg001.html#AUDIOSTREAM" title="Stores an audiostream.">AUDIOSTREAM</a> *stream);</b></div><br>
Call this function after get_audio_stream_buffer() returns a non-NULL
address, to indicate that you have loaded a new block of samples to that
location and the data is now ready to be played. Example:
<blockquote class="code"><pre>
mem_chunk = <a href="#get_audio_stream_buffer" class="autotype" title="Tells you if you need to fill the audiostream or not.">get_audio_stream_buffer</a>(buffer);
if (mem_chunk != NULL) {
/* Refill the stream buffer. */
...
<a href="#free_audio_stream_buffer" class="autotype" title="Tells the audio stream player new data can be played.">free_audio_stream_buffer</a>(buffer);
}</pre></blockquote>
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#get_audio_stream_buffer" title="Tells you if you need to fill the audiostream or not.">get_audio_stream_buffer</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>
<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
>
801
