Re: [AD] docs: play_audio_stream clarification

[Elias Pschernig <elias@xxxxxxxxxx>]

On Tue, 2004-02-10 at 04:26, Ben Davis wrote:
> If you guys would like the proper terminology, I believe it is "sample frame" 
> for an entity comprising both (or all) channels, and the individual values 
> are "sample points". This is according to an 
> official-but-not-proofread-looking document I got from wotsit.org for the 
> .wav file format.
> 

Ok, so we should change the beginning of the text as well. Allegro
counts "sample frames", consisting of "sample points", left channel
first.

And I think, to make this docs entry really good, we also should add:

"The formula to calculate the size of the buffer in bytes is: bytes =
len * bits / 8 * (stereo ? 2 : 1);"

New patch attached.

-- 
Elias Pschernig <elias@xxxxxxxxxx>

Index: docs/src/allegro._tx
===================================================================
RCS file: /cvsroot/alleg/allegro/docs/src/allegro._tx,v
retrieving revision 1.210
diff -u -r1.210 allegro._tx
--- docs/src/allegro._tx	19 Jan 2004 17:30:55 -0000	1.210
+++ docs/src/allegro._tx	10 Feb 2004 13:17:36 -0000
@@ -6633,20 +6633,23 @@
 @@AUDIOSTREAM *@play_audio_stream(int len, bits, stereo, freq, vol, pan);
 @xref install_sound, get_audio_stream_buffer, stop_audio_stream
 @eref exstream
-   This function creates a new audio stream and starts it playing. The 
-   length is the size of each transfer buffer (in samples), which should 
-   normally (but doesn't have to) be a power of two 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-&gtvoice as a
-   parameter. The sample data is always in unsigned format, with stereo
-   waveforms consisting of alternating left/right samples, left sample
-   first.
+
+   This function creates a new audio stream and starts playing it. The
+   length is the size of each transfer buffer (in sample-frames), which
+   should normally (but doesn't have to) be a power of two 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-&gtvoice as a parameter. The sample
+   data is always in unsigned format. Stereo waveforms contain two
+   sample-points per frame, first left, then right channel. The formula
+   two get the size of the buffers in bytes would be:
+   <textblock>bytes = len * (bits / 8) * (stereo ? 2 : 1)<endblock>
 
 @@void @stop_audio_stream(AUDIOSTREAM *stream);
 @xref play_audio_stream