← Back to branch summary

~ubuntu-branches/ubuntu/vivid/sflphone/vivid

« back to all changes in this revision

Viewing changes to daemon/libs/pjproject-2.0.1/pjmedia/include/pjmedia/jbuf.h

  • Committer: Package Import Robot
  • Author(s): Mark Purcell
  • Date: 2013-06-30 11:40:56 UTC
  • mfrom: (4.1.18 saucy-proposed)
  • Revision ID: package-import@ubuntu.com-20130630114056-0np50jkyqo6vnmii
Tags: 1.2.3-2
* changeset_r92d62cfc54732bbbcfff2b1d36c096b120b981a5.diff 
  - fixes automatic endian detection 
* Update Vcs: fixes vcs-field-not-canonical

Show diffs side-by-side

added added

removed removed

Lines of Context:
daemon/libs/pjproject-2.0.1/pjmedia/include/pjmedia/jbuf.h
 
1
/* $Id: jbuf.h 3841 2011-10-24 09:28:13Z ming $ */
 
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
/*
 
21
 * Based on implementation kindly contributed by Switchlab, Ltd.
 
22
 */
 
23
#ifndef __PJMEDIA_JBUF_H__
 
24
#define __PJMEDIA_JBUF_H__
 
25
 
 
26
 
 
27
/**
 
28
 * @file jbuf.h
 
29
 * @brief Adaptive jitter buffer implementation.
 
30
 */
 
31
#include <pjmedia/types.h>
 
32
 
 
33
/**
 
34
 * @defgroup PJMED_JBUF Adaptive jitter buffer
 
35
 * @ingroup PJMEDIA_FRAME_OP
 
36
 * @brief Adaptive de-jitter buffering implementation
 
37
 * @{
 
38
 *
 
39
 * This section describes PJMEDIA's implementation of de-jitter buffer.
 
40
 * The de-jitter buffer may be set to operate in adaptive mode or fixed
 
41
 * delay mode.
 
42
 */
 
43
 
 
44
 
 
45
PJ_BEGIN_DECL
 
46
 
 
47
 
 
48
/**
 
49
 * Types of frame returned by the jitter buffer.
 
50
 */
 
51
typedef enum pjmedia_jb_frame_type
 
52
{
 
53
    PJMEDIA_JB_MISSING_FRAME       = 0, /**< No frame because it's missing  */
 
54
    PJMEDIA_JB_NORMAL_FRAME        = 1, /**< Normal frame is being returned */
 
55
    PJMEDIA_JB_ZERO_PREFETCH_FRAME = 2, /**< Zero frame is being returned
 
56
                                             because JB is bufferring.      */
 
57
    PJMEDIA_JB_ZERO_EMPTY_FRAME    = 3  /**< Zero frame is being returned
 
58
                                             because JB is empty.           */
 
59
} pjmedia_jb_frame_type;
 
60
 
 
61
 
 
62
/**
 
63
 * Enumeration of jitter buffer discard algorithm. The jitter buffer
 
64
 * continuously calculates the jitter level to get the optimum latency at
 
65
 * any time and in order to adjust the latency, the jitter buffer may need
 
66
 * to discard some frames.
 
67
 */
 
68
typedef enum pjmedia_jb_discard_algo
 
69
{
 
70
    /**
 
71
     * Jitter buffer should not discard any frame, except when the jitter
 
72
     * buffer is full and a new frame arrives, one frame will be discarded
 
73
     * to make space for the new frame.
 
74
     */
 
75
    PJMEDIA_JB_DISCARD_NONE        = 0,
 
76
 
 
77
    /**
 
78
     * Only discard one frame in at least 200ms when the latency is considered
 
79
     * much higher than it should be. When the jitter buffer is full and a new
 
80
     * frame arrives, one frame will be discarded to make space for the new
 
81
     * frame.
 
82
     */
 
83
    PJMEDIA_JB_DISCARD_STATIC,
 
84
 
 
85
    /**
 
86
     * The discard rate is dynamically calculated based on actual parameters
 
87
     * such as jitter level and latency. When the jitter buffer is full and
 
88
     * a new frame arrives, one frame will be discarded to make space for the
 
89
     * new frame.
 
90
     */
 
91
    PJMEDIA_JB_DISCARD_PROGRESSIVE
 
92
 
 
93
} pjmedia_jb_discard_algo;
 
94
 
 
95
 
 
96
/**
 
97
 * This structure describes jitter buffer state.
 
98
 */
 
99
typedef struct pjmedia_jb_state
 
100
{
 
101
    /* Setting */
 
102
    unsigned    frame_size;         /**< Individual frame size, in bytes.   */
 
103
    unsigned    min_prefetch;       /**< Minimum allowed prefetch, in frms. */
 
104
    unsigned    max_prefetch;       /**< Maximum allowed prefetch, in frms. */
 
105
 
 
106
    /* Status */
 
107
    unsigned    burst;              /**< Current burst level, in frames     */
 
108
    unsigned    prefetch;           /**< Current prefetch value, in frames  */
 
109
    unsigned    size;               /**< Current buffer size, in frames.    */
 
110
 
 
111
    /* Statistic */
 
112
    unsigned    avg_delay;          /**< Average delay, in ms.              */
 
113
    unsigned    min_delay;          /**< Minimum delay, in ms.              */
 
114
    unsigned    max_delay;          /**< Maximum delay, in ms.              */
 
115
    unsigned    dev_delay;          /**< Standard deviation of delay, in ms.*/
 
116
    unsigned    avg_burst;          /**< Average burst, in frames.          */
 
117
    unsigned    lost;               /**< Number of lost frames.             */
 
118
    unsigned    discard;            /**< Number of discarded frames.        */
 
119
    unsigned    empty;              /**< Number of empty on GET events.     */
 
120
} pjmedia_jb_state;
 
121
 
 
122
 
 
123
/**
 
124
 * The constant PJMEDIA_JB_DEFAULT_INIT_DELAY specifies default jitter
 
125
 * buffer prefetch count during jitter buffer creation.
 
126
 */
 
127
#define PJMEDIA_JB_DEFAULT_INIT_DELAY    15
 
128
 
 
129
/**
 
130
 * Opaque declaration for jitter buffer.
 
131
 */
 
132
typedef struct pjmedia_jbuf pjmedia_jbuf;
 
133
 
 
134
 
 
135
/**
 
136
 * Create an adaptive jitter buffer according to the specification. If
 
137
 * application wants to have a fixed jitter buffer, it may call
 
138
 * #pjmedia_jbuf_set_fixed() after the jitter buffer is created. Also
 
139
 * if application wants to alter the discard algorithm, which the default
 
140
 * PJMEDIA_JB_DISCARD_PROGRESSIVE, it may call #pjmedia_jbuf_set_discard().
 
141
 *
 
142
 * This function may allocate large chunk of memory to keep the frames in
 
143
 * the buffer.
 
144
 *
 
145
 * @param pool          The pool to allocate memory.
 
146
 * @param name          Name to identify the jitter buffer for logging
 
147
 *                      purpose.
 
148
 * @param frame_size    The size of each frame that will be kept in the
 
149
 *                      jitter buffer, in bytes. This should correspond
 
150
 *                      to the minimum frame size supported by the codec.
 
151
 *                      For example, a 10ms frame (80 bytes) would be
 
152
 *                      recommended for G.711 codec.
 
153
 * @param max_count     Maximum number of frames that can be kept in the
 
154
 *                      jitter buffer. This effectively means the maximum
 
155
 *                      delay that may be introduced by this jitter
 
156
 *                      buffer.
 
157
 * @param ptime         Indication of frame duration, used to calculate
 
158
 *                      the interval between jitter recalculation.
 
159
 * @param p_jb          Pointer to receive jitter buffer instance.
 
160
 *
 
161
 * @return              PJ_SUCCESS on success.
 
162
 */
 
163
PJ_DECL(pj_status_t) pjmedia_jbuf_create(pj_pool_t *pool,
 
164
                                         const pj_str_t *name,
 
165
                                         unsigned frame_size,
 
166
                                         unsigned ptime,
 
167
                                         unsigned max_count,
 
168
                                         pjmedia_jbuf **p_jb);
 
169
 
 
170
/**
 
171
 * Set the jitter buffer to fixed delay mode. The default behavior
 
172
 * is to adapt the delay with actual packet delay.
 
173
 *
 
174
 * @param jb            The jitter buffer
 
175
 * @param prefetch      The fixed delay value, in number of frames.
 
176
 *
 
177
 * @return              PJ_SUCCESS on success.
 
178
 */
 
179
PJ_DECL(pj_status_t) pjmedia_jbuf_set_fixed( pjmedia_jbuf *jb,
 
180
                                             unsigned prefetch);
 
181
 
 
182
 
 
183
/**
 
184
 * Set the jitter buffer to adaptive mode.
 
185
 *
 
186
 * @param jb            The jitter buffer.
 
187
 * @param prefetch      The initial prefetch value to be applied to the
 
188
 *                      jitter buffer. Setting this to other than 0 will
 
189
 *                      activate prefetch buffering, a jitter buffer feature
 
190
 *                      that each time it gets empty, it won't return a
 
191
 *                      normal frame until its size reaches the number
 
192
 *                      specified here.
 
193
 * @param min_prefetch  The minimum delay that must be applied to each
 
194
 *                      incoming packets, in number of frames.
 
195
 * @param max_prefetch  The maximum allowable value for prefetch delay,
 
196
 *                      in number of frames.
 
197
 *
 
198
 * @return              PJ_SUCCESS on success.
 
199
 */
 
200
PJ_DECL(pj_status_t) pjmedia_jbuf_set_adaptive( pjmedia_jbuf *jb,
 
201
                                                unsigned prefetch,
 
202
                                                unsigned min_prefetch,
 
203
                                                unsigned max_prefetch);
 
204
 
 
205
 
 
206
/**
 
207
 * Set the jitter buffer discard algorithm. The default discard algorithm,
 
208
 * set in jitter buffer creation, is PJMEDIA_JB_DISCARD_PROGRESSIVE.
 
209
 *
 
210
 * @param jb            The jitter buffer.
 
211
 * @param algo          The discard algorithm to be used.
 
212
 *
 
213
 * @return              PJ_SUCCESS on success.
 
214
 */
 
215
PJ_DECL(pj_status_t) pjmedia_jbuf_set_discard(pjmedia_jbuf *jb,
 
216
                                              pjmedia_jb_discard_algo algo);
 
217
 
 
218
 
 
219
/**
 
220
 * Destroy jitter buffer instance.
 
221
 *
 
222
 * @param jb            The jitter buffer.
 
223
 *
 
224
 * @return              PJ_SUCCESS on success.
 
225
 */
 
226
PJ_DECL(pj_status_t) pjmedia_jbuf_destroy(pjmedia_jbuf *jb);
 
227
 
 
228
 
 
229
/**
 
230
 * Restart jitter. This function flushes all packets in the buffer and
 
231
 * reset the internal sequence number.
 
232
 *
 
233
 * @param jb            The jitter buffer.
 
234
 *
 
235
 * @return              PJ_SUCCESS on success.
 
236
 */
 
237
PJ_DECL(pj_status_t) pjmedia_jbuf_reset(pjmedia_jbuf *jb);
 
238
 
 
239
/**
 
240
 * Put a frame to the jitter buffer. If the frame can be accepted (based
 
241
 * on the sequence number), the jitter buffer will copy the frame and put
 
242
 * it in the appropriate position in the buffer.
 
243
 *
 
244
 * Application MUST manage it's own synchronization when multiple threads
 
245
 * are accessing the jitter buffer at the same time.
 
246
 *
 
247
 * @param jb            The jitter buffer.
 
248
 * @param frame         Pointer to frame buffer to be stored in the jitter
 
249
 *                      buffer.
 
250
 * @param size          The frame size.
 
251
 * @param frame_seq     The frame sequence number.
 
252
 */
 
253
PJ_DECL(void) pjmedia_jbuf_put_frame( pjmedia_jbuf *jb,
 
254
                                      const void *frame,
 
255
                                      pj_size_t size,
 
256
                                      int frame_seq);
 
257
 
 
258
/**
 
259
 * Put a frame to the jitter buffer. If the frame can be accepted (based
 
260
 * on the sequence number), the jitter buffer will copy the frame and put
 
261
 * it in the appropriate position in the buffer.
 
262
 *
 
263
 * Application MUST manage it's own synchronization when multiple threads
 
264
 * are accessing the jitter buffer at the same time.
 
265
 *
 
266
 * @param jb            The jitter buffer.
 
267
 * @param frame         Pointer to frame buffer to be stored in the jitter
 
268
 *                      buffer.
 
269
 * @param size          The frame size.
 
270
 * @param bit_info      Bit precise info of the frame, e.g: a frame may not
 
271
 *                      exactly start and end at the octet boundary, so this
 
272
 *                      field may be used for specifying start & end bit offset.
 
273
 * @param frame_seq     The frame sequence number.
 
274
 * @param discarded     Flag whether the frame is discarded by jitter buffer.
 
275
 */
 
276
PJ_DECL(void) pjmedia_jbuf_put_frame2( pjmedia_jbuf *jb,
 
277
                                       const void *frame,
 
278
                                       pj_size_t size,
 
279
                                       pj_uint32_t bit_info,
 
280
                                       int frame_seq,
 
281
                                       pj_bool_t *discarded);
 
282
 
 
283
/**
 
284
 * Put a frame to the jitter buffer. If the frame can be accepted (based
 
285
 * on the sequence number), the jitter buffer will copy the frame and put
 
286
 * it in the appropriate position in the buffer.
 
287
 *
 
288
 * Application MUST manage it's own synchronization when multiple threads
 
289
 * are accessing the jitter buffer at the same time.
 
290
 *
 
291
 * @param jb            The jitter buffer.
 
292
 * @param frame         Pointer to frame buffer to be stored in the jitter
 
293
 *                      buffer.
 
294
 * @param size          The frame size.
 
295
 * @param bit_info      Bit precise info of the frame, e.g: a frame may not
 
296
 *                      exactly start and end at the octet boundary, so this
 
297
 *                      field may be used for specifying start & end bit offset.
 
298
 * @param frame_seq     The frame sequence number.
 
299
 * @param frame_ts      The frame timestamp.
 
300
 * @param discarded     Flag whether the frame is discarded by jitter buffer.
 
301
 */
 
302
PJ_DECL(void) pjmedia_jbuf_put_frame3( pjmedia_jbuf *jb,
 
303
                                       const void *frame,
 
304
                                       pj_size_t size,
 
305
                                       pj_uint32_t bit_info,
 
306
                                       int frame_seq,
 
307
                                       pj_uint32_t frame_ts,
 
308
                                       pj_bool_t *discarded);
 
309
/**
 
310
 * Get a frame from the jitter buffer. The jitter buffer will return the
 
311
 * oldest frame from it's buffer, when it is available.
 
312
 *
 
313
 * Application MUST manage it's own synchronization when multiple threads
 
314
 * are accessing the jitter buffer at the same time.
 
315
 *
 
316
 * @param jb            The jitter buffer.
 
317
 * @param frame         Buffer to receive the payload from the jitter buffer.
 
318
 *                      Application MUST make sure that the buffer has
 
319
 *                      appropriate size (i.e. not less than the frame size,
 
320
 *                      as specified when the jitter buffer was created).
 
321
 *                      The jitter buffer only copied a frame to this
 
322
 *                      buffer when the frame type returned by this function
 
323
 *                      is PJMEDIA_JB_NORMAL_FRAME.
 
324
 * @param p_frm_type    Pointer to receive frame type. If jitter buffer is
 
325
 *                      currently empty or bufferring, the frame type will
 
326
 *                      be set to PJMEDIA_JB_ZERO_FRAME, and no frame will
 
327
 *                      be copied. If the jitter buffer detects that frame is
 
328
 *                      missing with current sequence number, the frame type
 
329
 *                      will be set to PJMEDIA_JB_MISSING_FRAME, and no
 
330
 *                      frame will be copied. If there is a frame, the jitter
 
331
 *                      buffer will copy the frame to the buffer, and frame
 
332
 *                      type will be set to PJMEDIA_JB_NORMAL_FRAME.
 
333
 */
 
334
PJ_DECL(void) pjmedia_jbuf_get_frame( pjmedia_jbuf *jb,
 
335
                                      void *frame,
 
336
                                      char *p_frm_type);
 
337
 
 
338
/**
 
339
 * Get a frame from the jitter buffer. The jitter buffer will return the
 
340
 * oldest frame from it's buffer, when it is available.
 
341
 *
 
342
 * @param jb            The jitter buffer.
 
343
 * @param frame         Buffer to receive the payload from the jitter buffer.
 
344
 *                      @see pjmedia_jbuf_get_frame().
 
345
 * @param size          Pointer to receive frame size.
 
346
 * @param p_frm_type    Pointer to receive frame type.
 
347
 *                      @see pjmedia_jbuf_get_frame().
 
348
 * @param bit_info      Bit precise info of the frame, e.g: a frame may not
 
349
 *                      exactly start and end at the octet boundary, so this
 
350
 *                      field may be used for specifying start & end bit offset.
 
351
 */
 
352
PJ_DECL(void) pjmedia_jbuf_get_frame2(pjmedia_jbuf *jb,
 
353
                                      void *frame,
 
354
                                      pj_size_t *size,
 
355
                                      char *p_frm_type,
 
356
                                      pj_uint32_t *bit_info);
 
357
 
 
358
 
 
359
/**
 
360
 * Get a frame from the jitter buffer. The jitter buffer will return the
 
361
 * oldest frame from it's buffer, when it is available.
 
362
 *
 
363
 * @param jb            The jitter buffer.
 
364
 * @param frame         Buffer to receive the payload from the jitter buffer.
 
365
 *                      @see pjmedia_jbuf_get_frame().
 
366
 * @param size          Pointer to receive frame size.
 
367
 * @param p_frm_type    Pointer to receive frame type.
 
368
 *                      @see pjmedia_jbuf_get_frame().
 
369
 * @param bit_info      Bit precise info of the frame, e.g: a frame may not
 
370
 *                      exactly start and end at the octet boundary, so this
 
371
 *                      field may be used for specifying start & end bit offset.
 
372
 * @param ts            Frame timestamp.
 
373
 * @param seq           Frame sequence number.
 
374
 */
 
375
PJ_DECL(void) pjmedia_jbuf_get_frame3(pjmedia_jbuf *jb,
 
376
                                      void *frame,
 
377
                                      pj_size_t *size,
 
378
                                      char *p_frm_type,
 
379
                                      pj_uint32_t *bit_info,
 
380
                                      pj_uint32_t *ts,
 
381
                                      int *seq);
 
382
 
 
383
 
 
384
/**
 
385
 * Peek a frame from the jitter buffer. The jitter buffer state will not be
 
386
 * modified.
 
387
 *
 
388
 * @param jb            The jitter buffer.
 
389
 * @param offset        Offset from the oldest frame to be peeked.
 
390
 * @param frame         Buffer to receive the payload from the jitter buffer.
 
391
 *                      @see pjmedia_jbuf_get_frame().
 
392
 * @param size          Pointer to receive frame size.
 
393
 * @param p_frm_type    Pointer to receive frame type.
 
394
 *                      @see pjmedia_jbuf_get_frame().
 
395
 * @param bit_info      Bit precise info of the frame, e.g: a frame may not
 
396
 *                      exactly start and end at the octet boundary, so this
 
397
 *                      field may be used for specifying start & end bit offset.
 
398
 * @param ts            Frame timestamp.
 
399
 * @param seq           Frame sequence number.
 
400
 */
 
401
PJ_DECL(void) pjmedia_jbuf_peek_frame(pjmedia_jbuf *jb,
 
402
                                      unsigned offset,
 
403
                                      const void **frame,
 
404
                                      pj_size_t *size,
 
405
                                      char *p_frm_type,
 
406
                                      pj_uint32_t *bit_info,
 
407
                                      pj_uint32_t *ts,
 
408
                                      int *seq);
 
409
 
 
410
 
 
411
/**
 
412
 * Remove frames from the jitter buffer.
 
413
 *
 
414
 * @param jb            The jitter buffer.
 
415
 * @param frame_cnt     Number of frames to be removed.
 
416
 *
 
417
 * @return              The number of frame successfully removed.
 
418
 */
 
419
PJ_DECL(unsigned) pjmedia_jbuf_remove_frame(pjmedia_jbuf *jb,
 
420
                                            unsigned frame_cnt);
 
421
 
 
422
/**
 
423
 * Check if the jitter buffer is full.
 
424
 *
 
425
 * @param jb            The jitter buffer.
 
426
 *
 
427
 * @return              PJ_TRUE if it is full.
 
428
 */
 
429
PJ_DECL(pj_bool_t) pjmedia_jbuf_is_full(const pjmedia_jbuf *jb);
 
430
 
 
431
 
 
432
/**
 
433
 * Get jitter buffer current state/settings.
 
434
 *
 
435
 * @param jb            The jitter buffer.
 
436
 * @param state         Buffer to receive jitter buffer state.
 
437
 *
 
438
 * @return              PJ_SUCCESS on success.
 
439
 */
 
440
PJ_DECL(pj_status_t) pjmedia_jbuf_get_state( const pjmedia_jbuf *jb,
 
441
                                             pjmedia_jb_state *state );
 
442
 
 
443
 
 
444
 
 
445
PJ_END_DECL
 
446
 
 
447
/**
 
448
 * @}
 
449
 */
 
450
 
 
451
#endif  /* __PJMEDIA_JBUF_H__ */