| 30 | | |
| 31 | | |
| 32 | | <H4>Stream Finished Callback</H4> |
| 33 | | |
| 34 | | <P> |
| 35 | | PortAudio allows clients to terminate a stream by returning non-zero from the |
| 36 | | stream callback function. However, PortAudio cannot notify clients when the stream has |
| 37 | | actually completed playing all audio data. Currently the only methods of discovering |
| 38 | | whether a stream has actually finished playing is to poll Pa_IsStreamActive() |
| 39 | | or to wait for a blocking call to Pa_StopStream() to return. Some clients would |
| 40 | | prefer to receive an asyncronous notification when the stream completes playing: |
| 41 | | </P> |
| 42 | | |
| 43 | | <PRE> |
| 44 | | typedef void PaStreamFinishedCallback( void *userData ); |
| 45 | | |
| 46 | | /* register a callback function which will be called when a stream enters |
| 47 | | the Callback Finished state in response to the audio callback returning |
| 48 | | non-zero*/ |
| 49 | | |
| 50 | | PaError Pa_SetStreamFinishedCallback( PaStream *stream, PaStreamFinishedCallback* streamFinishedCallback ); |
| 51 | | </PRE> |
| 52 | | |
| 53 | | |
| 54 | | <H4>Version querying functions</H4> |
| 55 | | |
| 56 | | <P> |
| 57 | | Some clients could benefit from being able to determine which version of |
| 58 | | PortAudio is in use. This could be achieved using the following version |
| 59 | | querying functions: |
| 60 | | </P> |
| 61 | | |
| 62 | | <PRE> |
| 63 | | /* return the release number of the currently running build of PortAudio, eg 1900 */ |
| 64 | | int Pa_GetVersion(); |
| 65 | | |
| 66 | | /* return a textual description of the current PortAudio build, eg "PortAudio V19-devel 13 October 2002" */ |
| 67 | | const char* Pa_GetVersionText(); |
| 68 | | </PRE> |
| 81 | | <H4>Pa_OpenStream() Flag to Prime Initial Buffers Using the Stream Callback</H4> |
| 82 | | |
| 83 | | <P> |
| 84 | | Currently, when a stream is started, host buffers are initially filled with zeros (silence). This is done so that the Stream Callback: a) is called regularly (useful for time syncronisation), b) provides relatively constant latency from calback to output, and c) avoids a peak in processor load while a number of buffers are filled one after another. The downside of this strategy is that the startup latency is held constant, whereas some host APIs may be able to provide significantly lower startup latency if the initial buffers are filled with valid sample data. |
| 85 | | </P> |
| 86 | | |
| 87 | | <P> |
| 88 | | Although it is generally held that the above behavior is the most widely useful for streaming audio applications, a flag could be provided to Pa_OpenStream() to indicate that the buffers should initially be primed using the callback: |
| 89 | | </P> |
| 90 | | |
| 91 | | <PRE> |
| 92 | | paPrimeBuffersUsingCallback |
| 93 | | </PRE> |
| 94 | | |
