diff options
Diffstat (limited to 'pjmedia/include/pjmedia/clock.h')
| -rw-r--r-- | pjmedia/include/pjmedia/clock.h | 129 |
1 files changed, 128 insertions, 1 deletions
diff --git a/pjmedia/include/pjmedia/clock.h b/pjmedia/include/pjmedia/clock.h index d7dc26e3..dd33a108 100644 --- a/pjmedia/include/pjmedia/clock.h +++ b/pjmedia/include/pjmedia/clock.h @@ -79,6 +79,82 @@ 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 ); + /** * Opaque declaration for media clock. @@ -105,6 +181,19 @@ enum pjmedia_clock_options }; +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. * @@ -118,7 +207,12 @@ typedef void pjmedia_clock_callback(const pj_timestamp *ts, /** - * 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. * @param clock_rate Number of samples per second. @@ -143,6 +237,29 @@ PJ_DECL(pj_status_t) pjmedia_clock_create( pj_pool_t *pool, void *user_data, 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, * this may start a worker thread for the clock (depending on the @@ -165,6 +282,16 @@ PJ_DECL(pj_status_t) pjmedia_clock_start(pjmedia_clock *clock); 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); + /** * Poll the media clock, and execute the callback when the clock tick has |