Changeset 19
- Timestamp:
- 08/19/02 22:24:04 (6 years ago)
- Files:
-
- 1 modified
Legend:
- Unmodified
- Added
- Removed
-
pa_proposals/trunk/015-ImproveCallbackTimestampInfo.html
r17 r19 18 18 <P><A href="index.html">Enhancement Proposals Index</A>, 19 19 <A href="http://www.portaudio.com/">PortAudio Home Page</A></P> 20 <P>Updated: August 9, 2002 </P>20 <P>Updated: August 20, 2002 </P> 21 21 22 22 <H4>Status</H4> … … 27 27 28 28 <P> 29 The information provided by the outTime callback parameter and Pa_StreamTime() function does 30 not provide sufficient information to perform some syncronisation tasks. One example is that of syncronising 29 The timing information provided by the outTime callback parameter and Pa_StreamTime() function is not sufficient to perform some syncronisation tasks. One example is that of syncronising 31 30 PortAudio generated audio with another timebase, such as syncronisation pulses in a timestamped 32 MIDI event stream. 31 MIDI event stream. Furthermore, the behavior of the outTime callback parameters is not 32 defined in the presence of buffer underflows and overflows and it is difficult to conceive of a single behavioral definition for outTime which could fulfill all possible requirements. 33 33 </P> 34 34 … … 36 36 37 37 <P> 38 Remove the Pa_StreamTime(), as its functionality can be implemented using the features added by the 39 remainder of this proposal. 40 </P> 41 42 <P> 43 Add a function to retrieve a stream's time base expressed in seconds. 44 It is unspecified what this timebase is relative to. 38 Redefine Pa_GetStreamTime() (formerly Pa_StreamTime()) to have completely different behavior. The new behavior is to return the current time in seconds according to the clock used to generate buffer timestamps for the associated stream. The clock runs continuously while the stream is open, i.e. between calls to Pa_OpenStream() and Pa_CloseStream(). The clock's origin (the time at which it was zero) is unspecified. 45 39 </P> 46 40 47 41 <PRE> 48 typedef double PaTime; 42 typedef double PaTime; /* time expressed in seconds */ 49 43 50 PaTime Pa_GetStreamTimeBase( PaStream *stream ); 44 /* 45 Return the current time according to the clock used 46 to generate buffer timestamps for stream. 47 */ 48 PaTime Pa_GetStreamTime( PaStream *stream ); 51 49 </PRE> 50 52 51 53 52 <P> … … 57 56 the time at which the first sample of the output buffer will exit the DAC (outputBufferDACTime), 58 57 and the time at which the callback was initiated (currentTime). These times are all expressed 59 in seconds relative to the stream's time base returned by Pa_GetStreamTimeBase().58 in seconds based on the stream-specific clock returned by Pa_GetStreamTime(). 60 59 </P> 61 60 … … 76 75 77 76 <P> 78 The possibility of retaining Pa_StreamTime() for clients which simply need to display the current stream time was discussed. It was suggested that the functionality currently provided by Pa_StreamTime() could be implemented using the new timestamp parameters, and that doing so would be more robust. One reason is because it is difficult to define a single useful behavior of Pa_StreamTime() in the presence of buffer overruns and underruns.77 Various alternate names were considered for the function named Pa_GetStreamTime() in this proposal - primarily because GetStreamTime() collides with the old StreamTime() function which had a completely different behavior. However a better name could not be found. 79 78 </P> 80 79 81 80 <P> 82 Originally it was planned to have a global PortAudio timebase returned by a function named Pa_GetTime(). However, different host APIs on the same platform may dictate that their timebases are relative to different time sources (timeGetTime() vs. QueryPerformanceCounter() on windows for example.) Trying to syncronise multiple independent time bases is a problematic task (due to potential clock drift), so it was concluded that a safer approach would be to provide separate time bases for each stream.81 The possibility of retaining the original form of Pa_StreamTime() for clients which simply need to display the elapsed stream playback time was discussed. This proposal was rejected as the functionality currently provided by Pa_StreamTime() can be implemented using the new timestamp parameters. Such a solution can potentially be more robust than implementing the functionality in PortAudio because it is difficult to define a single useful behavior of the old Pa_StreamTime() function in the presence of buffer overruns and underruns. 83 82 </P> 83 84 <P> 85 Originally it was planned to have a global PortAudio timebase returned by a function named Pa_GetTime(). However, different host APIs on the same platform may dictate that their timebases are relative to different time sources (timeGetTime() vs. QueryPerformanceCounter() on windows for example.) Trying to syncronise multiple independent time bases is a problematic task (due to potential clock drift), so it was concluded that a safer approach would be to allow each stream to have its own time base. 86 </P> 87 88 <P> 89 Various options for specifying the stream clock's origin and lifetime (times when it is running) have been considered, including only allowing the clock to run between StreamStart() and StreamStop(). The current solution provides clients who whish to use the clock with access to the clock even while the stream is not running - this may be useful for applications that timestamp events using the stream's clock, or display time-based information even when the stream is stopped. 90 </P> 91 84 92 85 93 <H4>Impact Analysis</H4>
