Changeset 3664 for pjproject/trunk/pjmedia/include/pjmedia/clock.h

Timestamp:

Jul 19, 2011 3:42:28 AM (13 years ago)

Author:

nanang

Message:

Re #1326: Initial code integration from branch 2.0-dev to trunk as "2.0-pre-alpha-svn".

Location:

pjproject/trunk

Files:

• . (modified) (1 prop)
• pjmedia/include/pjmedia/clock.h (modified) (5 diffs)

pjproject/trunk/pjmedia/include/pjmedia/clock.h

@@ -80 +80 @@
 PJ_BEGIN_DECL
 
+/**
+ * Media clock source.
+ */
+typedef struct pjmedia_clock_src
+{
+    pjmedia_type    media_type;     /**< Media type.                */
+    unsigned        clock_rate;     /**< Clock rate.                */
+    unsigned        ptime_usec;     /**< Frame interval (in usec).  */
+    /**
+     * The timestamp field holds an increasing value in samples and its
+     * value is expected to be increased by clock_rate samples per second.
+     */
+    pj_timestamp    timestamp;
+    /**
+     * Timestamp's last update. The last_update field contains a value in
+     * ticks, and it is expected to be increased by pj_get_timestamp_freq()
+     * ticks per second.
+     */
+    pj_timestamp    last_update;
+} pjmedia_clock_src;
+
+/**
+ * This is an auxiliary function to initialize the media clock source.
+ *
+ * @param clocksrc          The clock source to be initialized.
+ * @param media_type        The media type.
+ * @param clock_rate        The clock rate.
+ * @param ptime_usec        Media frame interval (in usec).
+ *
+ * @return                  PJ_SUCCESS on success.
+ */
+PJ_DECL(pj_status_t) pjmedia_clock_src_init( pjmedia_clock_src *clocksrc,
+                                             pjmedia_type media_type,
+                                             unsigned clock_rate,
+                                             unsigned ptime_usec );
+
+/**
+ * This function updates the clock source's timestamp. Application should
+ * use this function instead of updating the timestamp directly since this
+ * function will also update the last_update field of the clock source.
+ *
+ * @param clocksrc          The clock source to be updated.
+ * @param timestamp         The new timestamp, can be NULL if the current
+ *                          timestamp does not change (in this case it
+ *                          will only update the last_update field).
+ *
+ * @return                  PJ_SUCCESS on success.
+ */
+PJ_DECL(pj_status_t) pjmedia_clock_src_update( pjmedia_clock_src *clocksrc,
+                                               const pj_timestamp *timestamp );
+
+/**
+ * This function gets the clock source's current timestamp. Application
+ * should use this function instead of accessing the timestamp directly
+ * since this function will calculate the predicted timestamp for current
+ * time, based on the values of timestamp, last_update, and clock_rate.
+ *
+ * @param clocksrc          The clock source.
+ * @param timestamp         Argument to receive the current timestamp
+ *
+ * @return                  PJ_SUCCESS on success.
+ */
+PJ_DECL(pj_status_t)
+pjmedia_clock_src_get_current_timestamp( const pjmedia_clock_src *clocksrc,
+                                         pj_timestamp *timestamp);
+
+/**
+ * This function gets the clock source's time in msec.
+ *
+ * @param clocksrc          The clock source.
+ *
+ * @return                  The clock source's time (in msec).
+ */
+PJ_DECL(pj_uint32_t)
+pjmedia_clock_src_get_time_msec( const pjmedia_clock_src *clocksrc );
+
 
 /**
@@ -106 +182 @@
 
 
+typedef struct pjmedia_clock_param
+{
+    /**
+     * The frame interval, in microseconds.
+     */
+    unsigned usec_interval;
+    /**
+     * The media clock rate, to determine timestamp
+     * increment for each call.
+     */
+    unsigned clock_rate;
+} pjmedia_clock_param;
+
 /**
  * Type of media clock callback.
@@ -119 +208 @@
 
 /**
- * Create media clock.
+ * Create media clock. This creates a media clock object that will run
+ * periodically at an interval that is calculated from the audio parameters.
+ * Once created, application must call #pjmedia_clock_start() to actually
+ * start the clock.
+ *
+ * @see pjmedia_clock_create2()
  *
  * @param pool              Pool to allocate memory.
@@ -144 +238 @@
                                            pjmedia_clock **p_clock);
 
+
+/**
+ * Create media clock. This creates a media clock object that will run
+ * periodically at the specified interval. Once created, application must
+ * call #pjmedia_clock_start() to actually start the clock.
+ *
+ * @param pool              Pool to allocate memory.
+ * @param param             The clock parameter.
+ * @param options           Bitmask of pjmedia_clock_options.
+ * @param cb                Callback to be called for each clock tick.
+ * @param user_data         User data, which will be passed to the callback.
+ * @param p_clock           Pointer to receive the clock instance.
+ *
+ * @return                  PJ_SUCCESS on success, or the appropriate error
+ *                          code.
+ */
+PJ_DECL(pj_status_t) pjmedia_clock_create2(pj_pool_t *pool,
+                                           const pjmedia_clock_param *param,
+                                           unsigned options,
+                                           pjmedia_clock_callback *cb,
+                                           void *user_data,
+                                           pjmedia_clock **p_clock);
+
 /**
  * Start the clock. For clock created with asynchronous flag set to TRUE,
@@ -165 +282 @@
 PJ_DECL(pj_status_t) pjmedia_clock_stop(pjmedia_clock *clock);
 
+
+/**
+ * Modify the clock's parameter.
+ *
+ * @param clock             The media clock.
+ * @param param             The clock's new parameter.
+ * @return                  PJ_SUCCES on success.
+ */
+PJ_DECL(pj_status_t) pjmedia_clock_modify(pjmedia_clock *clock,
+                                          const pjmedia_clock_param *param);