From: rossb Date: Thu, 25 Aug 2011 17:44:01 +0000 (+0000) Subject: added stream callback documentation describing real-time constraints including not... X-Git-Tag: pa_stable_v19_20111121_r1788~30 X-Git-Url: https://andrewgundersen.net/repos?a=commitdiff_plain;h=91d6a84b5569c30acf1d9d15a1df0ee4e1edfdb0;p=portaudio 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 --- diff --git a/include/portaudio.h b/include/portaudio.h index 4b6420a..2dcdf8f 100644 --- a/include/portaudio.h +++ b/include/portaudio.h @@ -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