1 /* $Id$ */ 2 /* 3 * Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com) 4 * Copyright (C) 2003-2008 Benny Prijono <benny@prijono.org> 5 * 6 * This program is free software; you can redistribute it and/or modify 7 * it under the terms of the GNU General Public License as published by 8 * the Free Software Foundation; either version 2 of the License, or 9 * (at your option) any later version. 10 * 11 * This program is distributed in the hope that it will be useful, 12 * but WITHOUT ANY WARRANTY; without even the implied warranty of 13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 14 * GNU General Public License for more details. 15 * 16 * You should have received a copy of the GNU General Public License 17 * along with this program; if not, write to the Free Software 18 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 19 */ 20 #ifndef __PJMEDIA_CLOCK_H__ 21 #define __PJMEDIA_CLOCK_H__ 22 23 /** 24 * @file clock.h 25 * @brief Media clock. 26 */ 27 #include <pjmedia/types.h> 28 29 30 /** 31 * @defgroup PJMEDIA_PORT_CLOCK Clock/Timing 32 * @ingroup PJMEDIA_PORT 33 * @brief Various types of classes that provide timing. 34 * @{ 35 36 The media clock/timing extends the media port concept that is explained 37 in @ref PJMEDIA_PORT. When clock is present in the ports 38 interconnection, media will flow automatically (and with correct timing too!) 39 from one media port to another. 40 41 There are few objects in PJMEDIA that are able to provide clock/timing 42 to media ports interconnection: 43 44 - @ref PJMED_SND_PORT\n 45 The sound device makes a good candidate as the clock source, and 46 PJMEDIA @ref PJMED_SND is designed so that it is able to invoke 47 operations according to timing driven by the sound hardware clock 48 (this may sound complicated, but actually it just means that 49 the sound device abstraction provides callbacks to be called when 50 it has/wants media frames).\n 51 See @ref PJMED_SND_PORT for more details. 52 53 - @ref PJMEDIA_MASTER_PORT\n 54 The master port uses @ref PJMEDIA_CLOCK as the clock source. By using 55 @ref PJMEDIA_MASTER_PORT, it is possible to interconnect passive 56 media ports and let the frames flow automatically in timely manner.\n 57 Please see @ref PJMEDIA_MASTER_PORT for more details. 58 59 @} 60 */ 61 62 63 /** 64 * @addtogroup PJMEDIA_CLOCK Clock Generator 65 * @ingroup PJMEDIA_PORT_CLOCK 66 * @brief Interface for generating clock. 67 * @{ 68 * 69 * The clock generator provides the application with media timing, 70 * and it is used by the @ref PJMEDIA_MASTER_PORT for its sound clock. 71 * 72 * The clock generator may be configured to run <b>asynchronously</b> 73 * (the default behavior) or <b>synchronously</b>. When it is run 74 * asynchronously, it will call the application's callback every time 75 * the clock <b>tick</b> expires. When it is run synchronously, 76 * application must continuously polls the clock generator to synchronize 77 * the timing. 78 */ 79 80 PJ_BEGIN_DECL 81 82 /** 83 * Media clock source. 84 */ 85 typedef struct pjmedia_clock_src 86 { 87 pjmedia_type media_type; /**< Media type. */ 88 unsigned clock_rate; /**< Clock rate. */ 89 unsigned ptime_usec; /**< Frame interval (in usec). */ 90 /** 91 * The timestamp field holds an increasing value in samples and its 92 * value is expected to be increased by clock_rate samples per second. 93 */ 94 pj_timestamp timestamp; 95 /** 96 * Timestamp's last update. The last_update field contains a value in 97 * ticks, and it is expected to be increased by pj_get_timestamp_freq() 98 * ticks per second. 99 */ 100 pj_timestamp last_update; 101 } pjmedia_clock_src; 102 103 /** 104 * This is an auxiliary function to initialize the media clock source. 105 * 106 * @param clocksrc The clock source to be initialized. 107 * @param media_type The media type. 108 * @param clock_rate The clock rate. 109 * @param ptime_usec Media frame interval (in usec). 110 * 111 * @return PJ_SUCCESS on success. 112 */ 113 PJ_DECL(pj_status_t) pjmedia_clock_src_init( pjmedia_clock_src *clocksrc, 114 pjmedia_type media_type, 115 unsigned clock_rate, 116 unsigned ptime_usec ); 117 118 /** 119 * This function updates the clock source's timestamp. Application should 120 * use this function instead of updating the timestamp directly since this 121 * function will also update the last_update field of the clock source. 122 * 123 * @param clocksrc The clock source to be updated. 124 * @param timestamp The new timestamp, can be NULL if the current 125 * timestamp does not change (in this case it 126 * will only update the last_update field). 127 * 128 * @return PJ_SUCCESS on success. 129 */ 130 PJ_DECL(pj_status_t) pjmedia_clock_src_update( pjmedia_clock_src *clocksrc, 131 const pj_timestamp *timestamp ); 132 133 /** 134 * This function gets the clock source's current timestamp. Application 135 * should use this function instead of accessing the timestamp directly 136 * since this function will calculate the predicted timestamp for current 137 * time, based on the values of timestamp, last_update, and clock_rate. 138 * 139 * @param clocksrc The clock source. 140 * @param timestamp Argument to receive the current timestamp 141 * 142 * @return PJ_SUCCESS on success. 143 */ 144 PJ_DECL(pj_status_t) 145 pjmedia_clock_src_get_current_timestamp( const pjmedia_clock_src *clocksrc, 146 pj_timestamp *timestamp); 147 148 /** 149 * This function gets the clock source's time in msec. 150 * 151 * @param clocksrc The clock source. 152 * 153 * @return The clock source's time (in msec). 154 */ 155 PJ_DECL(pj_uint32_t) 156 pjmedia_clock_src_get_time_msec( const pjmedia_clock_src *clocksrc ); 157 158 159 /** 160 * Opaque declaration for media clock. 161 */ 162 typedef struct pjmedia_clock pjmedia_clock; 163 164 165 /** 166 * Options when creating the clock. 167 */ 168 enum pjmedia_clock_options 169 { 170 /** 171 * Prevents the clock from running asynchronously. In this case, 172 * application must poll the clock continuously by calling 173 * #pjmedia_clock_wait() in order to synchronize timing. 174 */ 175 PJMEDIA_CLOCK_NO_ASYNC = 1, 176 177 /** 178 * Prevent the clock from setting it's thread to highest priority. 179 */ 180 PJMEDIA_CLOCK_NO_HIGHEST_PRIO = 2 181 }; 182 183 184 typedef struct pjmedia_clock_param 185 { 186 /** 187 * The frame interval, in microseconds. 188 */ 189 unsigned usec_interval; 190 /** 191 * The media clock rate, to determine timestamp 192 * increment for each call. 193 */ 194 unsigned clock_rate; 195 } pjmedia_clock_param; 196 197 /** 198 * Type of media clock callback. 199 * 200 * @param ts Current timestamp, in samples. 201 * @param user_data Application data that is passed when 202 * the clock was created. 203 */ 204 typedef void pjmedia_clock_callback(const pj_timestamp *ts, 205 void *user_data); 206 207 208 209 /** 210 * Create media clock. This creates a media clock object that will run 211 * periodically at an interval that is calculated from the audio parameters. 212 * Once created, application must call #pjmedia_clock_start() to actually 213 * start the clock. 214 * 215 * @see pjmedia_clock_create2() 216 * 217 * @param pool Pool to allocate memory. 218 * @param clock_rate Number of samples per second. 219 * @param channel_count Number of channel. 220 * @param samples_per_frame Number of samples per frame. This argument 221 * along with clock_rate and channel_count, specifies 222 * the interval of each clock run (or clock ticks). 223 * @param options Bitmask of pjmedia_clock_options. 224 * @param cb Callback to be called for each clock tick. 225 * @param user_data User data, which will be passed to the callback. 226 * @param p_clock Pointer to receive the clock instance. 227 * 228 * @return PJ_SUCCESS on success, or the appropriate error 229 * code. 230 */ 231 PJ_DECL(pj_status_t) pjmedia_clock_create( pj_pool_t *pool, 232 unsigned clock_rate, 233 unsigned channel_count, 234 unsigned samples_per_frame, 235 unsigned options, 236 pjmedia_clock_callback *cb, 237 void *user_data, 238 pjmedia_clock **p_clock); 239 240 241 /** 242 * Create media clock. This creates a media clock object that will run 243 * periodically at the specified interval. Once created, application must 244 * call #pjmedia_clock_start() to actually start the clock. 245 * 246 * @param pool Pool to allocate memory. 247 * @param param The clock parameter. 248 * @param options Bitmask of pjmedia_clock_options. 249 * @param cb Callback to be called for each clock tick. 250 * @param user_data User data, which will be passed to the callback. 251 * @param p_clock Pointer to receive the clock instance. 252 * 253 * @return PJ_SUCCESS on success, or the appropriate error 254 * code. 255 */ 256 PJ_DECL(pj_status_t) pjmedia_clock_create2(pj_pool_t *pool, 257 const pjmedia_clock_param *param, 258 unsigned options, 259 pjmedia_clock_callback *cb, 260 void *user_data, 261 pjmedia_clock **p_clock); 262 263 /** 264 * Start the clock. For clock created with asynchronous flag set to TRUE, 265 * this may start a worker thread for the clock (depending on the 266 * backend clock implementation being used). 267 * 268 * @param clock The media clock. 269 * 270 * @return PJ_SUCCES on success. 271 */ 272 PJ_DECL(pj_status_t) pjmedia_clock_start(pjmedia_clock *clock); 273 274 275 /** 276 * Stop the clock. 277 * 278 * @param clock The media clock. 279 * 280 * @return PJ_SUCCES on success. 281 */ 282 PJ_DECL(pj_status_t) pjmedia_clock_stop(pjmedia_clock *clock); 283 284 285 /** 286 * Modify the clock's parameter. 287 * 288 * @param clock The media clock. 289 * @param param The clock's new parameter. 290 * @return PJ_SUCCES on success. 291 */ 292 PJ_DECL(pj_status_t) pjmedia_clock_modify(pjmedia_clock *clock, 293 const pjmedia_clock_param *param); 294 295 296 /** 297 * Poll the media clock, and execute the callback when the clock tick has 298 * elapsed. This operation is only valid if the clock is created with async 299 * flag set to FALSE. 300 * 301 * @param clock The media clock. 302 * @param wait If non-zero, then the function will block until 303 * a clock tick elapsed and callback has been called. 304 * @param ts Optional argument to receive the current 305 * timestamp. 306 * 307 * @return Non-zero if clock tick has elapsed, or FALSE if 308 * the function returns before a clock tick has 309 * elapsed. 310 */ 311 PJ_DECL(pj_bool_t) pjmedia_clock_wait(pjmedia_clock *clock, 312 pj_bool_t wait, 313 pj_timestamp *ts); 314 315 316 /** 317 * Destroy the clock. 318 * 319 * @param clock The media clock. 320 * 321 * @return PJ_SUCCES on success. 322 */ 323 PJ_DECL(pj_status_t) pjmedia_clock_destroy(pjmedia_clock *clock); 324 325 326 327 PJ_END_DECL 328 329 /** 330 * @} 331 */ 332 333 334 #endif /* __PJMEDIA_CLOCK_H__ */ 335 336