Changeset 60

Show
Ignore:
Timestamp:
12/03/02 01:32:24 (6 years ago)
Author:
rossbencina
Message:

clarified documentation and marked as ready to implement

Files:
1 modified

Legend:

Unmodified
Added
Removed

  • pa_proposals/trunk/019-NotifyClientWhenAllBuffersHavePlayed.html

    r53 r60  
    1818<P><A href="index.html">Enhancement Proposals Index</A>, 
    1919<A href="http://www.portaudio.com/">PortAudio Home Page</A></P> 
    20 <P>Updated: October 22, 2002 </P> 
     20<P>Updated: December 3, 2002 </P> 
    2121 
    2222<H4>Status</H4> 
    2323 
    24 <P>This proposal is open for discussion.</P> 
     24<P>This proposal is sufficiently well defined to be implemented.</P> 
    2525 
    2626<H4>Background</H4> 
    2727 
    2828<P> 
    29 PortAudio allows clients to terminate a stream by returning non-zero from the stream callback function. When the callback return value is paComplete, PortAudio will finish playing all generated audio data before deactivating the stream. PortAudio does not notify clients when the stream has actually completed playing all audio data. Currently the only methods of discovering whether a stream has actually finished playing is to poll Pa_IsStreamActive() or to wait for a blocking call to Pa_StopStream() to return. Some clients would prefer to receive an asyncronous notification when the stream completes playing. 
     29PortAudio allows clients to terminate a stream by returning non-zero from the stream callback function. When the callback return value is paComplete, PortAudio will finish playing all generated audio data before deactivating the stream. PortAudio does not notify clients when the stream has actually completed playing all audio data. Currently the only methods of discovering whether a stream has actually finished playing is to poll Pa_IsStreamActive() or to wait for a blocking call to Pa_StopStream() to return. Some clients would like to receive an asyncronous notification when the stream completes playing all queued sample data. 
    3030</P> 
    3131 
    … …  
    3737 
    3838<PRE> 
     39/** Functions of type PaStreamFinishedCallback are implemented by PortAudio  
     40 clients. They can be registered with a stream using the Pa_SetStreamFinishedCallback 
     41 function. Once registered they are called when the stream becomes inactive 
     42 (ie once a call to Pa_StopStream() will not block). 
     43 A stream will become inactive after the stream callback returns non-zero, 
     44 or when Pa_StopStream or Pa_AbortStream is called. For a stream providing audio 
     45 output, if the stream callback returns paComplete, or Pa_StopStream is called, 
     46 the stream finished callback will not be called until all generated sample data 
     47 has been played. 
     48  
     49 @param userData The userData parameter supplied to Pa_OpenStream() 
     50 
     51 @see Pa_SetStreamFinishedCallback 
     52*/ 
    3953typedef void PaStreamFinishedCallback( void *userData ); 
    4054 
    41 /** Register a callback function which will be called when a stream finishes 
    42  playing all queued audio data - this condition will arise after the stream  
    43  callback returns non-zero, or when Pa_StopStream or Pa_AbortStream is called.  
    44  If the stream callback returns paComplete, or Pa_StopStream is called, the  
    45  stream finished callback will not be called until all generated sample data  
    46  has been played. In the case of an input-only stream, the callback will be 
    47  called when the stream becomes inactive (ie once a call to Pa_StopStream()  
    48  will not block.) Passing NULL for the streamFinishedCallback parameter  
    49  un-registers a previously registered stream finished callback function. 
    50  Pa_SetStreamFinishedCallback must only be called when the stream is stopped, 
    51  otherwise an error will be returned. 
     55 
     56/** Register a stream finished callback function which will be called when the  
     57 stream becomes inactive. See the description of PaStreamFinishedCallback for  
     58 further details about when the callback will be called. 
     59 
     60 @param stream a pointer to a PaStream that is in the stopped state - if the 
     61 stream is not stopped, the stream's finished callback will remain unchanged  
     62 and an error code will be returned. 
     63 
     64 @param streamFinishedCallback a pointer to a function with the same signature 
     65 as PaStreamFinishedCallback, that will be called when the stream becomes 
     66 inactive. Passing NULL for this parameter will un-register a previously 
     67 registered stream finished callback function. 
     68 
     69 @return on success returns paNoError, otherwise an error code indicating the cause 
     70 of the error. 
     71 
     72 @see PaStreamFinishedCallback 
    5273*/ 
    5374PaError Pa_SetStreamFinishedCallback( PaStream *stream, PaStreamFinishedCallback* streamFinishedCallback );  
    … …  
    5879 
    5980<P> 
    60 The stream finished callback could be passed as a parameter to PaOpenStream,  
     81Instead of providing a Pa_SetStreamFinishedCallback function, the stream  
     82finished callback could be passed as a parameter to PaOpenStream,  
    6183this would make things more complicated for clients who don't need to use 
    62 a stream finished callback. No clear decision has been made on this point yet. 
     84a stream finished callback.  
    6385</P> 
    6486