← Back to branch summary

~ubuntu-branches/ubuntu/trusty/sflphone/trusty

« back to all changes in this revision

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

  • Committer: Package Import Robot
  • Author(s): Mark Purcell
  • Date: 2014-01-28 18:23:36 UTC
  • mfrom: (4.3.4 sid)
  • Revision ID: package-import@ubuntu.com-20140128182336-jrsv0k9u6cawc068
Tags: 1.3.0-1
http://bugs.debian.org/735846
http://bugs.debian.org/727164
http://bugs.debian.org/718178
http://bugs.debian.org/736583
http://bugs.debian.org/722040
http://bugs.debian.org/736746
* New upstream release 
  - Fixes "New Upstream Release" (Closes: #735846)
  - Fixes "Ringtone does not stop" (Closes: #727164)
  - Fixes "[sflphone-kde] crash on startup" (Closes: #718178)
  - Fixes "sflphone GUI crashes when call is hung up" (Closes: #736583)
* Build-Depends: ensure GnuTLS 2.6
  - libucommon-dev (>= 6.0.7-1.1), libccrtp-dev (>= 2.0.6-3)
  - Fixes "FTBFS Build-Depends libgnutls{26,28}-dev" (Closes: #722040)
* Fix "boost 1.49 is going away" unversioned Build-Depends: (Closes: #736746)
* Add Build-Depends: libsndfile-dev, nepomuk-core-dev

Show diffs side-by-side

added added

removed removed

Lines of Context:
daemon/libs/pjproject-2.0.1/pjmedia/include/pjmedia/vid_codec.h
1
 
/* $Id: vid_codec.h 3956 2012-02-21 08:31:26Z 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_VID_CODEC_H__
21
 
#define __PJMEDIA_VID_CODEC_H__
22
 
 
23
 
 
24
 
/**
25
 
 * @file vid_codec.h
26
 
 * @brief Video codec framework.
27
 
 */
28
 
 
29
 
#include <pjmedia/codec.h>
30
 
#include <pjmedia/event.h>
31
 
#include <pjmedia/format.h>
32
 
#include <pjmedia/types.h>
33
 
#include <pj/list.h>
34
 
#include <pj/pool.h>
35
 
 
36
 
PJ_BEGIN_DECL
37
 
 
38
 
/**
39
 
 * @defgroup PJMEDIA_VID_CODEC Video Codecs
40
 
 * @ingroup PJMEDIA_CODEC
41
 
 * @{
42
 
 */
43
 
 
44
 
#define PJMEDIA_VID_CODEC_MAX_DEC_FMT_CNT    8
45
 
#define PJMEDIA_VID_CODEC_MAX_FPS_CNT        16
46
 
 
47
 
/**
48
 
 * This enumeration specifies the packetization property of video encoding
49
 
 * process. The value is bitmask, and smaller value will have higher priority
50
 
 * to be used.
51
 
 */
52
 
typedef enum pjmedia_vid_packing
53
 
{
54
 
    /**
55
 
     * This specifies that the packetization is unknown, or if nothing
56
 
     * is supported.
57
 
     */
58
 
    PJMEDIA_VID_PACKING_UNKNOWN,
59
 
 
60
 
    /**
61
 
     * This specifies that the result of video encoding process will be
62
 
     * segmented into packets, which is suitable for RTP transmission.
63
 
     * The maximum size of the packets is set in \a enc_mtu field of
64
 
     * pjmedia_vid_codec_param.
65
 
     */
66
 
    PJMEDIA_VID_PACKING_PACKETS = 1,
67
 
 
68
 
    /**
69
 
     * This specifies that video encoding function will produce a whole
70
 
     * or full frame from the source frame. This is normally used for
71
 
     * encoding video for offline storage such as to an AVI file. The
72
 
     * maximum size of the packets is set in \a enc_mtu field of
73
 
     * pjmedia_vid_codec_param.
74
 
     */
75
 
    PJMEDIA_VID_PACKING_WHOLE = 2
76
 
 
77
 
} pjmedia_vid_packing;
78
 
 
79
 
 
80
 
/**
81
 
 * Enumeration of video frame info flag for the bit_info field in the
82
 
 * pjmedia_frame.
83
 
 */
84
 
typedef enum pjmedia_vid_frm_bit_info
85
 
{
86
 
    /**
87
 
     * The video frame is keyframe.
88
 
     */
89
 
    PJMEDIA_VID_FRM_KEYFRAME    = 1
90
 
 
91
 
} pjmedia_vid_frm_bit_info;
92
 
 
93
 
 
94
 
/**
95
 
 * Encoding option.
96
 
 */
97
 
typedef struct pjmedia_vid_encode_opt
98
 
{
99
 
    /**
100
 
     * Flag to force the encoder to generate keyframe for the specified input
101
 
     * frame. When this flag is set, application can verify the result by
102
 
     * examining PJMEDIA_VID_FRM_KEYFRAME flag in the bit_info field of the
103
 
     * output frame.
104
 
     */
105
 
    pj_bool_t force_keyframe;
106
 
 
107
 
} pjmedia_vid_encode_opt;
108
 
 
109
 
 
110
 
/**
111
 
 * Identification used to search for codec factory that supports specific
112
 
 * codec specification.
113
 
 */
114
 
typedef struct pjmedia_vid_codec_info
115
 
{
116
 
    pjmedia_format_id   fmt_id;         /**< Encoded format ID              */
117
 
    unsigned            pt;             /**< Payload type                   */
118
 
    pj_str_t            encoding_name;  /**< Encoding name                  */
119
 
    pj_str_t            encoding_desc;  /**< Encoding desc                  */
120
 
    unsigned            clock_rate;     /**< Clock rate                     */
121
 
    pjmedia_dir         dir;            /**< Direction                      */
122
 
    unsigned            dec_fmt_id_cnt; /**< # of supported encoding source
123
 
                                             format IDs                     */
124
 
    pjmedia_format_id   dec_fmt_id[PJMEDIA_VID_CODEC_MAX_DEC_FMT_CNT];
125
 
                                        /**< Supported encoding source
126
 
                                             format IDs                     */
127
 
    unsigned            packings;       /**< Supported or requested packings,
128
 
                                             strategies, bitmask from
129
 
                                             pjmedia_vid_packing            */
130
 
    unsigned            fps_cnt;        /**< # of supported frame-rates, can be
131
 
                                             zero (support any frame-rate)  */
132
 
    pjmedia_ratio       fps[PJMEDIA_VID_CODEC_MAX_FPS_CNT];
133
 
                                        /**< Supported frame-rates          */
134
 
 
135
 
} pjmedia_vid_codec_info;
136
 
 
137
 
 
138
 
/**
139
 
 * Detailed codec attributes used in configuring a codec and in querying
140
 
 * the capability of codec factories. Default attributes of any codecs could
141
 
 * be queried using #pjmedia_vid_codec_mgr_get_default_param() and modified
142
 
 * using #pjmedia_vid_codec_mgr_set_default_param().
143
 
 *
144
 
 * Please note that codec parameter also contains SDP specific setting,
145
 
 * #dec_fmtp and #enc_fmtp, which may need to be set appropriately based on
146
 
 * the effective setting. See each codec documentation for more detail.
147
 
 */
148
 
typedef struct pjmedia_vid_codec_param
149
 
{
150
 
    pjmedia_dir         dir;            /**< Direction                      */
151
 
    pjmedia_vid_packing packing;        /**< Packetization strategy.        */
152
 
 
153
 
    pjmedia_format      enc_fmt;        /**< Encoded format                 */
154
 
    pjmedia_codec_fmtp  enc_fmtp;       /**< Encoder fmtp params            */
155
 
    unsigned            enc_mtu;        /**< MTU or max payload size setting*/
156
 
 
157
 
    pjmedia_format      dec_fmt;        /**< Decoded format                 */
158
 
    pjmedia_codec_fmtp  dec_fmtp;       /**< Decoder fmtp params            */
159
 
 
160
 
    pj_bool_t           ignore_fmtp;    /**< Ignore fmtp params. If set to
161
 
                                             PJ_TRUE, the codec will apply
162
 
                                             format settings specified in
163
 
                                             enc_fmt and dec_fmt only.      */
164
 
 
165
 
} pjmedia_vid_codec_param;
166
 
 
167
 
 
168
 
/**
169
 
 * Duplicate video codec parameter.
170
 
 *
171
 
 * @param pool      The pool.
172
 
 * @param src       The video codec parameter to be duplicated.
173
 
 *
174
 
 * @return          Duplicated codec parameter.
175
 
 */
176
 
PJ_DECL(pjmedia_vid_codec_param*) pjmedia_vid_codec_param_clone(
177
 
                                        pj_pool_t *pool,
178
 
                                        const pjmedia_vid_codec_param *src);
179
 
 
180
 
/**
181
 
 * Forward declaration for video codec.
182
 
 */
183
 
typedef struct pjmedia_vid_codec pjmedia_vid_codec;
184
 
 
185
 
 
186
 
/**
187
 
 * This structure describes codec operations. Each codec MUST implement
188
 
 * all of these functions.
189
 
 */
190
 
typedef struct pjmedia_vid_codec_op
191
 
{
192
 
    /**
193
 
     * See #pjmedia_vid_codec_init().
194
 
     */
195
 
    pj_status_t (*init)(pjmedia_vid_codec *codec,
196
 
                        pj_pool_t *pool );
197
 
 
198
 
    /**
199
 
     * See #pjmedia_vid_codec_open().
200
 
     */
201
 
    pj_status_t (*open)(pjmedia_vid_codec *codec,
202
 
                        pjmedia_vid_codec_param *param );
203
 
 
204
 
    /**
205
 
     * See #pjmedia_vid_codec_close().
206
 
     */
207
 
    pj_status_t (*close)(pjmedia_vid_codec *codec);
208
 
 
209
 
    /**
210
 
     * See #pjmedia_vid_codec_modify().
211
 
     */
212
 
    pj_status_t (*modify)(pjmedia_vid_codec *codec,
213
 
                          const pjmedia_vid_codec_param *param);
214
 
 
215
 
    /**
216
 
     * See #pjmedia_vid_codec_get_param().
217
 
     */
218
 
    pj_status_t (*get_param)(pjmedia_vid_codec *codec,
219
 
                             pjmedia_vid_codec_param *param);
220
 
 
221
 
    /**
222
 
     * See #pjmedia_vid_codec_encode_begin().
223
 
     */
224
 
    pj_status_t (*encode_begin)(pjmedia_vid_codec *codec,
225
 
                                const pjmedia_vid_encode_opt *opt,
226
 
                                const pjmedia_frame *input,
227
 
                                unsigned out_size,
228
 
                                pjmedia_frame *output,
229
 
                                pj_bool_t *has_more);
230
 
 
231
 
    /**
232
 
     * See #pjmedia_vid_codec_encode_more()
233
 
     */
234
 
    pj_status_t (*encode_more)(pjmedia_vid_codec *codec,
235
 
                               unsigned out_size,
236
 
                               pjmedia_frame *output,
237
 
                               pj_bool_t *has_more);
238
 
 
239
 
 
240
 
    /*
241
 
     * See #pjmedia_vid_codec_decode().
242
 
     */
243
 
    pj_status_t (*decode)(pjmedia_vid_codec *codec,
244
 
                          pj_size_t count,
245
 
                          pjmedia_frame packets[],
246
 
                          unsigned out_size,
247
 
                          pjmedia_frame *output);
248
 
 
249
 
    /**
250
 
     * See #pjmedia_vid_codec_recover()
251
 
     */
252
 
    pj_status_t (*recover)(pjmedia_vid_codec *codec,
253
 
                           unsigned out_size,
254
 
                           pjmedia_frame *output);
255
 
 
256
 
} pjmedia_vid_codec_op;
257
 
 
258
 
 
259
 
 
260
 
/*
261
 
 * Forward declaration for pjmedia_vid_codec_factory.
262
 
 */
263
 
typedef struct pjmedia_vid_codec_factory pjmedia_vid_codec_factory;
264
 
 
265
 
 
266
 
/**
267
 
 * This structure describes a video codec instance. Codec implementers
268
 
 * should use #pjmedia_vid_codec_init() to initialize this structure with
269
 
 * default values.
270
 
 */
271
 
struct pjmedia_vid_codec
272
 
{
273
 
    /** Entries to put this codec instance in codec factory's list. */
274
 
    PJ_DECL_LIST_MEMBER(struct pjmedia_vid_codec);
275
 
 
276
 
    /** Codec's private data. */
277
 
    void                        *codec_data;
278
 
 
279
 
    /** Codec factory where this codec was allocated. */
280
 
    pjmedia_vid_codec_factory   *factory;
281
 
 
282
 
    /** Operations to codec. */
283
 
    pjmedia_vid_codec_op        *op;
284
 
};
285
 
 
286
 
 
287
 
 
288
 
/**
289
 
 * This structure describes operations that must be supported by codec
290
 
 * factories.
291
 
 */
292
 
typedef struct pjmedia_vid_codec_factory_op
293
 
{
294
 
    /**
295
 
     * Check whether the factory can create codec with the specified
296
 
     * codec info.
297
 
     *
298
 
     * @param factory   The codec factory.
299
 
     * @param info      The codec info.
300
 
     *
301
 
     * @return          PJ_SUCCESS if this factory is able to create an
302
 
     *                  instance of codec with the specified info.
303
 
     */
304
 
    pj_status_t (*test_alloc)(pjmedia_vid_codec_factory *factory,
305
 
                              const pjmedia_vid_codec_info *info );
306
 
 
307
 
    /**
308
 
     * Create default attributes for the specified codec ID. This function
309
 
     * can be called by application to get the capability of the codec.
310
 
     *
311
 
     * @param factory   The codec factory.
312
 
     * @param info      The codec info.
313
 
     * @param attr      The attribute to be initialized.
314
 
     *
315
 
     * @return          PJ_SUCCESS if success.
316
 
     */
317
 
    pj_status_t (*default_attr)(pjmedia_vid_codec_factory *factory,
318
 
                                const pjmedia_vid_codec_info *info,
319
 
                                pjmedia_vid_codec_param *attr );
320
 
 
321
 
    /**
322
 
     * Enumerate supported codecs that can be created using this factory.
323
 
     *
324
 
     *  @param factory  The codec factory.
325
 
     *  @param count    On input, specifies the number of elements in
326
 
     *                  the array. On output, the value will be set to
327
 
     *                  the number of elements that have been initialized
328
 
     *                  by this function.
329
 
     *  @param info     The codec info array, which contents will be
330
 
     *                  initialized upon return.
331
 
     *
332
 
     *  @return         PJ_SUCCESS on success.
333
 
     */
334
 
    pj_status_t (*enum_info)(pjmedia_vid_codec_factory *factory,
335
 
                             unsigned *count,
336
 
                             pjmedia_vid_codec_info codecs[]);
337
 
 
338
 
    /**
339
 
     * Create one instance of the codec with the specified codec info.
340
 
     *
341
 
     * @param factory   The codec factory.
342
 
     * @param info      The codec info.
343
 
     * @param p_codec   Pointer to receive the codec instance.
344
 
     *
345
 
     * @return          PJ_SUCCESS on success.
346
 
     */
347
 
    pj_status_t (*alloc_codec)(pjmedia_vid_codec_factory *factory,
348
 
                               const pjmedia_vid_codec_info *info,
349
 
                               pjmedia_vid_codec **p_codec);
350
 
 
351
 
    /**
352
 
     * This function is called by codec manager to return a particular
353
 
     * instance of codec back to the codec factory.
354
 
     *
355
 
     * @param factory   The codec factory.
356
 
     * @param codec     The codec instance to be returned.
357
 
     *
358
 
     * @return          PJ_SUCCESS on success.
359
 
     */
360
 
    pj_status_t (*dealloc_codec)(pjmedia_vid_codec_factory *factory,
361
 
                                 pjmedia_vid_codec *codec );
362
 
 
363
 
} pjmedia_vid_codec_factory_op;
364
 
 
365
 
 
366
 
 
367
 
/**
368
 
 * Codec factory describes a module that is able to create codec with specific
369
 
 * capabilities. These capabilities can be queried by codec manager to create
370
 
 * instances of codec.
371
 
 */
372
 
struct pjmedia_vid_codec_factory
373
 
{
374
 
    /** Entries to put this structure in the codec manager list. */
375
 
    PJ_DECL_LIST_MEMBER(struct pjmedia_vid_codec_factory);
376
 
 
377
 
    /** The factory's private data. */
378
 
    void                     *factory_data;
379
 
 
380
 
    /** Operations to the factory. */
381
 
    pjmedia_vid_codec_factory_op *op;
382
 
 
383
 
};
384
 
 
385
 
 
386
 
/**
387
 
 * Opaque declaration for codec manager.
388
 
 */
389
 
typedef struct pjmedia_vid_codec_mgr pjmedia_vid_codec_mgr;
390
 
 
391
 
/**
392
 
 * Declare maximum codecs
393
 
 */
394
 
#define PJMEDIA_VID_CODEC_MGR_MAX_CODECS            32
395
 
 
396
 
 
397
 
/**
398
 
 * Initialize codec manager. If there is no the default video codec manager,
399
 
 * this function will automatically set the default video codec manager to
400
 
 * the new codec manager instance. Normally this function is called by pjmedia
401
 
 * endpoint's initialization code.
402
 
 *
403
 
 * @param pool      The pool instance.
404
 
 * @param mgr       The pointer to the new codec manager instance.
405
 
 *
406
 
 * @return          PJ_SUCCESS on success.
407
 
 */
408
 
PJ_DECL(pj_status_t) pjmedia_vid_codec_mgr_create(pj_pool_t *pool,
409
 
                                                  pjmedia_vid_codec_mgr **mgr);
410
 
 
411
 
 
412
 
/**
413
 
 * Destroy codec manager. Normally this function is called by pjmedia
414
 
 * endpoint's deinitialization code.
415
 
 *
416
 
 * @param mgr       Codec manager instance.  If NULL, it is the default codec
417
 
 *                  manager instance will be destroyed.
418
 
 *
419
 
 * @return          PJ_SUCCESS on success.
420
 
 */
421
 
PJ_DECL(pj_status_t) pjmedia_vid_codec_mgr_destroy(pjmedia_vid_codec_mgr *mgr);
422
 
 
423
 
 
424
 
/**
425
 
 * Get the default codec manager instance.
426
 
 *
427
 
 * @return          The default codec manager instance or NULL if none.
428
 
 */
429
 
PJ_DECL(pjmedia_vid_codec_mgr*) pjmedia_vid_codec_mgr_instance(void);
430
 
 
431
 
 
432
 
/**
433
 
 * Set the default codec manager instance.
434
 
 *
435
 
 * @param mgr       The codec manager instance.
436
 
 */
437
 
PJ_DECL(void) pjmedia_vid_codec_mgr_set_instance(pjmedia_vid_codec_mgr* mgr);
438
 
 
439
 
 
440
 
/**
441
 
 * Register codec factory to codec manager. This will also register
442
 
 * all supported codecs in the factory to the codec manager.
443
 
 *
444
 
 * @param mgr       The codec manager instance. If NULL, the default codec
445
 
 *                  manager instance will be used.
446
 
 * @param factory   The codec factory to be registered.
447
 
 *
448
 
 * @return          PJ_SUCCESS on success.
449
 
 */
450
 
PJ_DECL(pj_status_t)
451
 
pjmedia_vid_codec_mgr_register_factory( pjmedia_vid_codec_mgr *mgr,
452
 
                                        pjmedia_vid_codec_factory *factory);
453
 
 
454
 
/**
455
 
 * Unregister codec factory from the codec manager. This will also
456
 
 * remove all the codecs registered by the codec factory from the
457
 
 * codec manager's list of supported codecs.
458
 
 *
459
 
 * @param mgr       The codec manager instance. If NULL, the default codec
460
 
 *                  manager instance will be used.
461
 
 * @param factory   The codec factory to be unregistered.
462
 
 *
463
 
 * @return          PJ_SUCCESS on success.
464
 
 */
465
 
PJ_DECL(pj_status_t)
466
 
pjmedia_vid_codec_mgr_unregister_factory( pjmedia_vid_codec_mgr *mgr,
467
 
                                          pjmedia_vid_codec_factory *factory);
468
 
 
469
 
/**
470
 
 * Enumerate all supported codecs that have been registered to the
471
 
 * codec manager by codec factories.
472
 
 *
473
 
 * @param mgr       The codec manager instance. If NULL, the default codec
474
 
 *                  manager instance will be used.
475
 
 * @param count     On input, specifies the number of elements in
476
 
 *                  the array. On output, the value will be set to
477
 
 *                  the number of elements that have been initialized
478
 
 *                  by this function.
479
 
 * @param info      The codec info array, which contents will be
480
 
 *                  initialized upon return.
481
 
 * @param prio      Optional pointer to receive array of codec priorities.
482
 
 *
483
 
 * @return          PJ_SUCCESS on success.
484
 
 */
485
 
PJ_DECL(pj_status_t)
486
 
pjmedia_vid_codec_mgr_enum_codecs(pjmedia_vid_codec_mgr *mgr,
487
 
                                  unsigned *count,
488
 
                                  pjmedia_vid_codec_info info[],
489
 
                                  unsigned *prio);
490
 
 
491
 
 
492
 
/**
493
 
 * Get codec info for the specified payload type. The payload type must be
494
 
 * static or locally defined in #pjmedia_video_pt.
495
 
 *
496
 
 * @param mgr       The codec manager instance. If NULL, the default codec
497
 
 *                  manager instance will be used.
498
 
 * @param pt        The payload type/number.
499
 
 * @param info      Pointer to receive codec info.
500
 
 *
501
 
 * @return          PJ_SUCCESS on success.
502
 
 */
503
 
PJ_DECL(pj_status_t)
504
 
pjmedia_vid_codec_mgr_get_codec_info( pjmedia_vid_codec_mgr *mgr,
505
 
                                      unsigned pt,
506
 
                                      const pjmedia_vid_codec_info **info);
507
 
 
508
 
 
509
 
/**
510
 
 * Get codec info for the specified format ID.
511
 
 *
512
 
 * @param mgr       The codec manager instance. If NULL, the default codec
513
 
 *                  manager instance will be used.
514
 
 * @param fmt_id    Format ID. See #pjmedia_format_id
515
 
 * @param info      Pointer to receive codec info.
516
 
 *
517
 
 * @return          PJ_SUCCESS on success.
518
 
 */
519
 
PJ_DECL(pj_status_t)
520
 
pjmedia_vid_codec_mgr_get_codec_info2(pjmedia_vid_codec_mgr *mgr,
521
 
                                      pjmedia_format_id fmt_id,
522
 
                                      const pjmedia_vid_codec_info **info);
523
 
 
524
 
 
525
 
/**
526
 
 * Convert codec info struct into a unique codec identifier.
527
 
 * A codec identifier looks something like "H263/90000".
528
 
 *
529
 
 * @param info      The codec info
530
 
 * @param id        Buffer to put the codec info string.
531
 
 * @param max_len   The length of the buffer.
532
 
 *
533
 
 * @return          The null terminated codec info string, or NULL if
534
 
 *                  the buffer is not long enough.
535
 
 */
536
 
PJ_DECL(char*) pjmedia_vid_codec_info_to_id(const pjmedia_vid_codec_info *info,
537
 
                                            char *id, unsigned max_len );
538
 
 
539
 
 
540
 
/**
541
 
 * Find codecs by the unique codec identifier. This function will find
542
 
 * all codecs that match the codec identifier prefix. For example, if
543
 
 * "H26" is specified, then it will find "H263/90000", "H264/90000",
544
 
 * and so on, up to the maximum count specified in the argument.
545
 
 *
546
 
 * @param mgr       The codec manager instance. If NULL, the default codec
547
 
 *                  manager instance will be used.
548
 
 * @param codec_id  The full codec ID or codec ID prefix. If an empty
549
 
 *                  string is given, it will match all codecs.
550
 
 * @param count     Maximum number of codecs to find. On return, it
551
 
 *                  contains the actual number of codecs found.
552
 
 * @param p_info    Array of pointer to codec info to be filled. This
553
 
 *                  argument may be NULL, which in this case, only
554
 
 *                  codec count will be returned.
555
 
 * @param prio      Optional array of codec priorities.
556
 
 *
557
 
 * @return          PJ_SUCCESS if at least one codec info is found.
558
 
 */
559
 
PJ_DECL(pj_status_t)
560
 
pjmedia_vid_codec_mgr_find_codecs_by_id(pjmedia_vid_codec_mgr *mgr,
561
 
                                        const pj_str_t *codec_id,
562
 
                                        unsigned *count,
563
 
                                        const pjmedia_vid_codec_info *p_info[],
564
 
                                        unsigned prio[]);
565
 
 
566
 
 
567
 
/**
568
 
 * Set codec priority. The codec priority determines the order of
569
 
 * the codec in the SDP created by the endpoint. If more than one codecs
570
 
 * are found with the same codec_id prefix, then the function sets the
571
 
 * priorities of all those codecs.
572
 
 *
573
 
 * @param mgr       The codec manager instance. If NULL, the default codec
574
 
 *                  manager instance will be used.
575
 
 * @param codec_id  The full codec ID or codec ID prefix. If an empty
576
 
 *                  string is given, it will match all codecs.
577
 
 * @param prio      Priority to be set. The priority can have any value
578
 
 *                  between 1 to 255. When the priority is set to zero,
579
 
 *                  the codec will be disabled.
580
 
 *
581
 
 * @return          PJ_SUCCESS if at least one codec info is found.
582
 
 */
583
 
PJ_DECL(pj_status_t)
584
 
pjmedia_vid_codec_mgr_set_codec_priority(pjmedia_vid_codec_mgr *mgr,
585
 
                                         const pj_str_t *codec_id,
586
 
                                         pj_uint8_t prio);
587
 
 
588
 
 
589
 
/**
590
 
 * Get default codec param for the specified codec info.
591
 
 *
592
 
 * @param mgr       The codec manager instance. If NULL, the default codec
593
 
 *                  manager instance will be used.
594
 
 * @param info      The codec info, which default parameter's is being
595
 
 *                  queried.
596
 
 * @param param     On return, will be filled with the default codec
597
 
 *                  parameter.
598
 
 *
599
 
 * @return          PJ_SUCCESS on success.
600
 
 */
601
 
PJ_DECL(pj_status_t)
602
 
pjmedia_vid_codec_mgr_get_default_param(pjmedia_vid_codec_mgr *mgr,
603
 
                                        const pjmedia_vid_codec_info *info,
604
 
                                        pjmedia_vid_codec_param *param);
605
 
 
606
 
 
607
 
/**
608
 
 * Set default codec param for the specified codec info.
609
 
 *
610
 
 * @param mgr       The codec manager instance. If NULL, the default codec
611
 
 *                  manager instance will be used.
612
 
 * @param pool      The pool instance.
613
 
 * @param info      The codec info, which default parameter's is being
614
 
 *                  updated.
615
 
 * @param param     The new default codec parameter. Set to NULL to reset
616
 
 *                  codec parameter to library default settings.
617
 
 *
618
 
 * @return          PJ_SUCCESS on success.
619
 
 */
620
 
PJ_DECL(pj_status_t)
621
 
pjmedia_vid_codec_mgr_set_default_param(pjmedia_vid_codec_mgr *mgr,
622
 
                                        const pjmedia_vid_codec_info *info,
623
 
                                        const pjmedia_vid_codec_param *param);
624
 
 
625
 
 
626
 
/**
627
 
 * Request the codec manager to allocate one instance of codec with the
628
 
 * specified codec info. The codec will enumerate all codec factories
629
 
 * until it finds factory that is able to create the specified codec.
630
 
 *
631
 
 * @param mgr       The codec manager instance. If NULL, the default codec
632
 
 *                  manager instance will be used.
633
 
 * @param info      The information about the codec to be created.
634
 
 * @param p_codec   Pointer to receive the codec instance.
635
 
 *
636
 
 * @return          PJ_SUCCESS on success.
637
 
 */
638
 
PJ_DECL(pj_status_t)
639
 
pjmedia_vid_codec_mgr_alloc_codec( pjmedia_vid_codec_mgr *mgr,
640
 
                                   const pjmedia_vid_codec_info *info,
641
 
                                   pjmedia_vid_codec **p_codec);
642
 
 
643
 
/**
644
 
 * Deallocate the specified codec instance. The codec manager will return
645
 
 * the instance of the codec back to its factory.
646
 
 *
647
 
 * @param mgr       The codec manager instance. If NULL, the default codec
648
 
 *                  manager instance will be used.
649
 
 * @param codec     The codec instance.
650
 
 *
651
 
 * @return          PJ_SUCESS on success.
652
 
 */
653
 
PJ_DECL(pj_status_t) pjmedia_vid_codec_mgr_dealloc_codec(
654
 
                                                pjmedia_vid_codec_mgr *mgr,
655
 
                                                pjmedia_vid_codec *codec);
656
 
 
657
 
 
658
 
 
659
 
/**
660
 
 * Initialize codec using the specified attribute.
661
 
 *
662
 
 * @param codec     The codec instance.
663
 
 * @param pool      Pool to use when the codec needs to allocate
664
 
 *                  some memory.
665
 
 *
666
 
 * @return          PJ_SUCCESS on success.
667
 
 */
668
 
PJ_INLINE(pj_status_t) pjmedia_vid_codec_init( pjmedia_vid_codec *codec,
669
 
                                               pj_pool_t *pool )
670
 
{
671
 
    return (*codec->op->init)(codec, pool);
672
 
}
673
 
 
674
 
 
675
 
/**
676
 
 * Open the codec and initialize with the specified parameter.
677
 
 * Upon successful initialization, the codec may modify the parameter
678
 
 * and fills in the unspecified values (such as size or frame rate of
679
 
 * the encoder format, as it may need to be negotiated with remote
680
 
 * preferences via SDP fmtp).
681
 
 *
682
 
 * @param codec     The codec instance.
683
 
 * @param param     Codec initialization parameter.
684
 
 *
685
 
 * @return          PJ_SUCCESS on success.
686
 
 */
687
 
PJ_INLINE(pj_status_t) pjmedia_vid_codec_open(pjmedia_vid_codec *codec,
688
 
                                              pjmedia_vid_codec_param *param)
689
 
{
690
 
    return (*codec->op->open)(codec, param);
691
 
}
692
 
 
693
 
 
694
 
/**
695
 
 * Close and shutdown codec, releasing all resources allocated by
696
 
 * this codec, if any.
697
 
 *
698
 
 * @param codec     The codec instance.
699
 
 *
700
 
 * @return          PJ_SUCCESS on success.
701
 
 */
702
 
PJ_INLINE(pj_status_t) pjmedia_vid_codec_close( pjmedia_vid_codec *codec )
703
 
{
704
 
    return (*codec->op->close)(codec);
705
 
}
706
 
 
707
 
 
708
 
/**
709
 
 * Modify the codec parameter after the codec is open.
710
 
 * Note that not all codec parameters can be modified during run-time.
711
 
 * When the parameter cannot be changed, this function will return
712
 
 * non-PJ_SUCCESS, and the original parameters will not be changed.
713
 
 *
714
 
 * @param codec The codec instance.
715
 
 * @param param The new codec parameter.
716
 
 *
717
 
 * @return              PJ_SUCCESS on success.
718
 
 */
719
 
PJ_INLINE(pj_status_t)
720
 
pjmedia_vid_codec_modify(pjmedia_vid_codec *codec,
721
 
                         const pjmedia_vid_codec_param *param)
722
 
{
723
 
    return (*codec->op->modify)(codec, param);
724
 
}
725
 
 
726
 
 
727
 
/**
728
 
 * Get the codec parameter after the codec is opened.
729
 
 *
730
 
 * @param codec The codec instance.
731
 
 * @param param The codec parameter.
732
 
 *
733
 
 * @return              PJ_SUCCESS on success.
734
 
 */
735
 
PJ_INLINE(pj_status_t)
736
 
pjmedia_vid_codec_get_param(pjmedia_vid_codec *codec,
737
 
                            pjmedia_vid_codec_param *param)
738
 
{
739
 
    return (*codec->op->get_param)(codec, param);
740
 
}
741
 
 
742
 
/**
743
 
 * Encode the specified input frame. The input MUST contain only one picture
744
 
 * with the appropriate format as specified when opening the codec. Depending
745
 
 * on the packing or packetization set in the \a packing param, the process
746
 
 * may produce multiple encoded packets or payloads to represent the picture.
747
 
 * This is true for example for PJMEDIA_VID_PACKING_PACKETS packing. In this
748
 
 * case, the \a has_more field will be set to PJ_TRUE, and application should
749
 
 * call pjmedia_vid_codec_encode_more() to get the remaining results from the
750
 
 * codec.
751
 
 *
752
 
 * @param codec         The codec instance.
753
 
 * @param opt           Optional encoding options.
754
 
 * @param input         The input frame.
755
 
 * @param out_size      The length of buffer in the output frame. This
756
 
 *                      should be at least the same as the configured
757
 
 *                      encoding MTU of the codec.
758
 
 * @param output        The output frame.
759
 
 * @param has_more      PJ_TRUE if more payloads are available; application
760
 
 *                      should then call pjmedia_vid_codec_encode_more()
761
 
 *                      to retrieve the remaining results.
762
 
 *
763
 
 * @return              PJ_SUCCESS on success;
764
 
 */
765
 
PJ_INLINE(pj_status_t)
766
 
pjmedia_vid_codec_encode_begin( pjmedia_vid_codec *codec,
767
 
                                const pjmedia_vid_encode_opt *opt,
768
 
                                const pjmedia_frame *input,
769
 
                                unsigned out_size,
770
 
                                pjmedia_frame *output,
771
 
                                pj_bool_t *has_more)
772
 
{
773
 
    return (*codec->op->encode_begin)(codec, opt, input, out_size, output,
774
 
                                      has_more);
775
 
}
776
 
 
777
 
/**
778
 
 * Retrieve more encoded packets/payloads from the codec. Application
779
 
 * should call this function repeatedly until \a has_more flag is set
780
 
 * to PJ_FALSE.
781
 
 *
782
 
 * @param codec         The codec instance.
783
 
 * @param out_size      The length of buffer in the output frame. This
784
 
 *                      should be at least the same as as the configured
785
 
 *                      encoding MTU of the codec.
786
 
 * @param output        The output frame.
787
 
 * @param has_more      PJ_TRUE if more payloads are available, which in
788
 
 *                      this case application should call \a encode_more()
789
 
 *                      to retrieve them.
790
 
 *
791
 
 * @return              PJ_SUCCESS on success;
792
 
 */
793
 
PJ_INLINE(pj_status_t)
794
 
pjmedia_vid_codec_encode_more( pjmedia_vid_codec *codec,
795
 
                               unsigned out_size,
796
 
                               pjmedia_frame *output,
797
 
                               pj_bool_t *has_more)
798
 
{
799
 
    return (*codec->op->encode_more)(codec, out_size, output, has_more);
800
 
}
801
 
 
802
 
/**
803
 
 * Decode the input packets into one picture. If the packing is set to
804
 
 * PJMEDIA_VID_PACKING_PACKETS when opening the codec, the codec is set
805
 
 * to decode multiple encoded packets into one picture. These encoded
806
 
 * packets are typically retrieved from the jitter buffer. If the packing
807
 
 * is set to PJMEDIA_VID_PACKING_WHOLE, then this decode function can only
808
 
 * accept one frame as the input.
809
 
 *
810
 
 * Note that the decoded picture format may different to the configured
811
 
 * setting (i.e. the format specified in the #pjmedia_vid_codec_param when
812
 
 * opening the codec), in this case the PJMEDIA_EVENT_FMT_CHANGED event will
813
 
 * be emitted by the codec to notify the event. The codec parameter will
814
 
 * also be updated, and application can query the format by using
815
 
 * pjmedia_vid_codec_get_param().
816
 
 *
817
 
 * @param codec         The codec instance.
818
 
 * @param pkt_count     Number of packets in the input.
819
 
 * @param packets       Array of input packets, each containing an encoded
820
 
 *                      frame.
821
 
 * @param out_size      The length of buffer in the output frame.
822
 
 * @param output        The output frame.
823
 
 *
824
 
 * @return              PJ_SUCCESS on success;
825
 
 */
826
 
PJ_INLINE(pj_status_t) pjmedia_vid_codec_decode(pjmedia_vid_codec *codec,
827
 
                                                pj_size_t pkt_count,
828
 
                                                pjmedia_frame packets[],
829
 
                                                unsigned out_size,
830
 
                                                pjmedia_frame *output)
831
 
{
832
 
    return (*codec->op->decode)(codec, pkt_count, packets, out_size, output);
833
 
}
834
 
 
835
 
/**
836
 
 * Recover a missing frame.
837
 
 *
838
 
 * @param codec         The codec instance.
839
 
 * @param out_size      The length of buffer in the output frame.
840
 
 * @param output        The output frame where generated signal
841
 
 *                      will be placed.
842
 
 *
843
 
 * @return              PJ_SUCCESS on success;
844
 
 */
845
 
PJ_INLINE(pj_status_t) pjmedia_vid_codec_recover(pjmedia_vid_codec *codec,
846
 
                                                 unsigned out_size,
847
 
                                                 pjmedia_frame *output)
848
 
{
849
 
    if (codec->op && codec->op->recover)
850
 
        return (*codec->op->recover)(codec, out_size, output);
851
 
    else
852
 
        return PJ_ENOTSUP;
853
 
}
854
 
 
855
 
 
856
 
/**
857
 
 * @}
858
 
 */
859
 
 
860
 
/**
861
 
 * @defgroup PJMEDIA_CODEC_VID_CODECS Supported video codecs
862
 
 * @ingroup PJMEDIA_VID_CODEC
863
 
 */
864
 
 
865
 
 
866
 
 
867
 
 
868
 
PJ_END_DECL
869
 
 
870
 
 
871
 
#endif  /* __PJMEDIA_VID_CODEC_H__ */