Re: [AD] docs: play_audio_stream clarification

[Elias Pschernig <elias@xxxxxxxxxx>]

On Tue, 2004-02-10 at 19:58, Ben Davis wrote:
> 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>
> -----

I like this version, it makes completely clear to everyone what the
length means. Most important to me is to not have the reader guessing
what is meant, like it was before.

-- 
Elias Pschernig <elias@xxxxxxxxxx>