Re: [AD] docs: play_audio_stream clarification

[Ben Davis <bnd25@xxxxxxxxxx>]

A few points:

- I think it would be advisable to explain the terms; not everyone will have 
heard of a sample frame or a sample point.

- I don't like the hyphenation. Just call them "sample points" and "sample 
frames".

- Are all the brackets necessary?

- There's a rogue "two" near the end :)

So here's my revision (sorry, I'm too lazy to do a proper patch for it):

-----
This function creates a new audio stream and starts playing it. The length is 
the size of each transfer buffer in sample frames, where a sample frame is a 
single sample point (i.e. value) for mono data or a pair of sample points for 
stereo data. The length should normally be (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 are always in unsigned format. For stereo waveforms, the samples are 
interleaved, left first.

The formula to get the size of the buffers in bytes would be:
<textblock>bytes = len * (bits / 8) * (stereo ? 2 : 1)<endblock>
-----

Ben

On Tuesday 10 February 2004 1:23 pm, Elias Pschernig wrote:
> 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.