Report some cleanup and documentation improvements done on JACK1 timing functions.

git-svn-id: http://subversion.jackaudio.org/jack/jack2/trunk/jackmp@3602 0c269be4-1314-0410-8aa9-9f06e86f4224

ChangeLog

@@ -28,6 +28,8 @@ Paul Davis
 2009-07-16 Stephane Letz  <letz@grame.fr>
 
 	* Rename JackDriver::Init method to JackDriver::Initialize (to avoid confusion with JackThread::Init method).
+	* Update Solaris boomer driver.
+	* Report some cleanup and documentation improvements done on JACK1 timing functions.
 
 2009-07-11 Stephane Letz  <letz@grame.fr>
 

common/JackAPI.cpp

@@ -1465,14 +1465,8 @@ EXPORT jack_nframes_t jack_last_frame_time(const jack_client_t* ext_client)
 #ifdef __CLIENTDEBUG__
     JackLibGlobals::CheckContext();
 #endif
-    JackTimer timer;
     JackEngineControl* control = GetEngineControl();
-    if (control) {
-        control->ReadFrameTime(&timer);
-        return timer.CurFrame();
-    } else {
-        return 0;
-    }
+    return (control) ? control->fFrameTimer.ReadCurrentState()->CurFrame() : 0;
 }
 
 EXPORT float jack_cpu_load(jack_client_t* ext_client)

common/jack/jack.h

@@ -984,47 +984,57 @@ jack_port_t * jack_port_by_id (jack_client_t *client,
 /**
  * @defgroup TimeFunctions Handling time
  * @{
- */                                                          
+ *
+ * JACK time is in units of 'frames', according to the current sample rate.
+ * The absolute value of frame times is meaningless, frame times have meaning
+ * only relative to each other.
+ */
 
 /**
- * @return the time in frames that has passed since the JACK server
- * began the current process cycle.
+ * @return the estimated time in frames that has passed since the JACK
+ * server began the current process cycle.
  */
 jack_nframes_t jack_frames_since_cycle_start (const jack_client_t *);
 
 /**
- * @return an estimate of the current time in frames.  This is a
- * running counter, no significance should be attached to its value,
- * but it can be compared to a previously returned value.
+ * @return the estimated current time in frames.
+ * This function is intended for use in other threads (not the process
+ * callback).  The return value can be compared with the value of
+ * jack_last_frame_time to relate time in other threads to JACK time.
  */
 jack_nframes_t jack_frame_time (const jack_client_t *);
 
 /**
- * @return the frame_time after the last processing of the graph
- * this is only to be used from the process callback. 
- *
- * This function can be used to put timestamps generated by 
- * jack_frame_time() in correlation to the current process cycle.
+ * @return the precise time at the start of the current process cycle.
+ * This function may only be used from the process callback, and can
+ * be used to interpret timestamps generated by jack_frame_time() in
+ * other threads with respect to the current process cycle.
+ * 
+ * This is the only jack time function that returns exact time:
+ * when used during the process callback it always returns the same
+ * value (until the next process callback, where it will return
+ * that value + nframes, etc).  The return value is guaranteed to be
+ * monotonic and linear in this fashion unless an xrun occurs.
+ * If an xrun occurs, clients must check this value again, as time
+ * may have advanced in a non-linear way (e.g. cycles may have been skipped).
  */
 jack_nframes_t jack_last_frame_time (const jack_client_t *client);
 
 /**
- * @return estimated time in microseconds of the specified frame time
+ * @return the estimated time in microseconds of the specified frame time
  */
 jack_time_t jack_frames_to_time(const jack_client_t *client, jack_nframes_t);
 
 /**
- * @return estimated time in frames for the specified system time.
+ * @return the estimated time in frames for the specified system time.
  */
 jack_nframes_t jack_time_to_frames(const jack_client_t *client, jack_time_t);
 
 /**
  * @return return JACK's current system time in microseconds,
- *         using JACK clock source. 
+ *         using the JACK clock source. 
  * 
  * The value returned is guaranteed to be monotonic, but not linear.
- *
- * This function is a client version of @function jack_get_microseconds().
  */
 jack_time_t jack_get_time();