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.
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. The bits parameter must be 8 or 16. freq is the sample rate
of the data in Hertz. The vol and pan values use the same 0-255 ranges as
the regular sample playing functions. The stereo parameter should be set
to 1 for stereo streams, or 0 otherwise. 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 sample data
are always in unsigned format.
The formula to get the size of the buffers in bytes could be:
bytes = len * (bits / 8) * (stereo ? 2 : 1)
See also:
install_sound,
get_audio_stream_buffer,
stop_audio_stream.
Examples using this:
exstream.
Destroys an audio stream when it is no longer required.
See also:
play_audio_stream.
Examples using this:
exstream.
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). 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. Note that this function should not be called from
a timer handler...
See also:
play_audio_stream,
free_audio_stream_buffer.
Examples using this:
exstream.
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.
See also:
get_audio_stream_buffer.
Examples using this:
exstream.