Enhancement Proposals Index, PortAudio Home Page
Updated: December 3, 2002
This proposal is sufficiently well defined to be implemented.
Currently (V18), when a stream is started, host buffers are initially filled with zeros (silence). This is done so that the Stream Callback: a) is called at regular intervals (useful for time syncronisation), b) provides relatively constant and predictable latency from calback to output, and c) avoids a peak in processor load that would occur if all of the buffers were initialised directly one after another. The downside of this strategy is that the startup latency is held constant, whereas some host APIs may be capable of providing significantly lower startup latency if the initial buffers are filled with valid sample data.
Although it is generally considered that the current behavior is the most widely useful for streaming audio applications, some applications (such as those that transiently play short sounds that can be efficiently generated) could benefit from being able to prime the buffers with their own data rather than silence.
Define a flag to be used in the streamFlags parameter to Pa_OpenStream that indicates that the initial output buffer(s) should be primed using the stream callback, instead of the default behavior of priming the buffers with zeros (silence). This flag has no effect for input-only streams.
/** Call the stream callback to fill initial output buffers, rather than the default behavior of priming the buffers with zeros (silence). This flag has no effect for input-only and blocking read/write streams. @see PaStreamFlags */ #define paPrimeOutputBuffersUsingStreamCallback ((PaStreamFlags) 0x00000008)
Define a flag which will be passed to the stream callback via the statusFlags parameter to indicate that some or all of the data generated by the callback will be used to prime the stream.
/** Some of all of the output data will be used to prime the stream, input data may be zero. @see PaStreamCallbackFlags */ #define paPrimingOutput ((PaStreamCallbackFlags) 0x00000010)
If the stream is a full-duplex stream, the calback's input buffer will contain zeros and the paInputUnderflow flag will be set while the stream is being primed.
Although the new inputLatency and outputLatency PaStreamInfo fields are able to report the latency for a standard call to the stream callback, these latency values will not be accurate for priming call(s) to the stream callback. It would be difficult to accurately predict the startup latency when the callback is used to prime the stream, and no mechanism to retrieve this startup latency is being proposed.
It was suggested that it might be possible to avoid adding the paPrimeOutputBuffersUsingStreamCallback flag and simply always call the callback (with the paPrimingOutput flag) to prime the stream. One problem with this approach is that the priming calls may be called in a different thread which could cause problems for some applications.
This proposal adds new functionality and does not effect existing client code.