me/portaudio
Watch
1
0
Fork
You've already forked portaudio
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

added stream callback documentation describing real-time constraints including not calling non-real-time code, and that it should be safe to consume 70% or more of available CPU time in the callback. resolves #96

Browse source
This commit is contained in:
rossb 2011-08-25 17:44:01 +00:00
commit 91d6a84b55
1 changed files with 23 additions and 1 deletions
Download patch file Download diff file Expand all files Collapse all files

24
include/portaudio.h
View file

@ -711,6 +711,28 @@ typedef enum PaStreamCallbackResult
Functions of type PaStreamCallback are implemented by PortAudio clients.
They consume, process or generate audio in response to requests from an
active PortAudio stream.
When a stream is running, PortAudio calls the stream callback periodically.
The callback function is responsible for processing buffers of audio samples
passed via the input and output parameters.
The PortAudio stream callback runs at very high or real-time priority.
It is required to consistently meet its time deadlines. Do not allocate
memory, access the file system, call library functions or call other functions
from the stream callback that may block or take an unpredictable amount of
time to complete.
In order for a stream to maintain glitch-free operation the callback
must consume and return audio data faster than it is recorded and/or
played. PortAudio anticipates that each callback invocation may execute for
a duration approaching the duration of frameCount audio frames at the stream
sample rate. It is reasonable to expect to be able to utilise 70% or more of
the available CPU time in the PortAudio callback. However, due to buffer size
adaption and other factors, not all host APIs are able to guarantee audio
stability under heavy CPU load with arbitrary fixed callback buffer sizes.
When high callback CPU utilisation is required the most robust behavior
can be achieved by using paFramesPerBufferUnspecified as the
Pa_OpenStream() framesPerBuffer parameter.
@param input and @param output are either arrays of interleaved samples or;
if non-interleaved samples were requested using the paNonInterleaved sample
@ -737,7 +759,7 @@ typedef enum PaStreamCallbackResult
@return
The stream callback should return one of the values in the
PaStreamCallbackResult enumeration. To ensure that the callback continues
::PaStreamCallbackResult enumeration. To ensure that the callback continues
to be called, it should return paContinue (0). Either paComplete or paAbort
can be returned to finish stream processing, after either of these values is
returned the callback will not be called again. If paAbort is returned the