Audio play_qeue() documentation

[Frank B]

The documentation https://www.pjrc.com/teensy/gui/?info=AudioPlayQueue for play_qeue is not OK.
https://github.com/PaulStoffregen/Au..._queue.cpp#L31

It does not mention available(), and getBuffer() does not return null.

Then, a short example, probably pesudocode should be given:

if (queue1.available()) {   
  audio_buffer = queue1.getBuffer();
  ..fill buffer here..
  queue1.playBuffer(); 
  ...
}

I leave the pullrequest to others with better English skills.

 

[defragster]

Looking at this I see:

getBuffer();
Returns a pointer to an array of 128 int16. This buffer is within the audio library memory pool, providing the most efficient way to input data to the audio system. The buffer is likely to be populated by previously used data, so the entire 128 words should be written before calling playBuffer(). Only a single buffer should be requested at a time. This function may return NULL if no memory is available.

Versus the linked code.

Indeed getBuffer() will not return NULL, it will not return at all until a buffer can be allocated and then returned for use.

As Frank's code demonstrates a call to the undocumented available() would be advised to prevent getBuffer() from giving an indeterminate wait when not desired.

Perhaps:

getBuffer();
Returns a pointer to an array of 128 int16. This buffer is within the audio library memory pool, providing the most efficient way to input data to the audio system. The buffer is likely to be populated by previously used data, so the entire 128 words should be written before calling playBuffer(). Only a single buffer should be requested at a time. This function will not return until a free memory block is available. Calling available() first will return true if a buffer is allocated or false otherwise

and add:

available();
A single 'userblock' is maintained for this object. If one is already allocated this function will return true, if one is not already allocated a single attempt to acquire one will be made and will return true if that succeeds, otherwise false will be returned

 

[defragster]

Frank reviewed the suggested text - just opened this issue: github.com/PaulStoffregen/Audio/issues/264