← Back to branch summary

~noskcaj/ubuntu/saucy/sflphone/merge-1.2.3-2

« back to all changes in this revision

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

  • Committer: Jackson Doak
  • Date: 2013-07-10 21:04:46 UTC
  • mfrom: (20.1.3 sid)
  • Revision ID: noskcaj@ubuntu.com-20130710210446-y8f587vza807icr9
https://launchpad.net/bugs/1196978
Properly merged from upstream.

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__ */