← Back to branch summary

~ubuntu-branches/ubuntu/wily/sflphone/wily

« back to all changes in this revision

Viewing changes to daemon/libs/pjproject-2.2.1/pjmedia/include/pjmedia/clock.h

  • Committer: Package Import Robot
  • Author(s): Jonathan Riddell
  • Date: 2015-01-07 14:51:16 UTC
  • mfrom: (4.3.5 sid)
  • Revision ID: package-import@ubuntu.com-20150107145116-yxnafinf4lrdvrmx
Tags: 1.4.1-0.1ubuntu1
* Merge with Debian, remaining changes:
 - Drop soprano, nepomuk build-dep
* Drop ubuntu patches, now upstream

Show diffs side-by-side

added added

removed removed

Lines of Context:
daemon/libs/pjproject-2.2.1/pjmedia/include/pjmedia/clock.h
 
1
/* $Id: clock.h 3664 2011-07-19 03:42:28Z nanang $ */
 
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