1 /* $Id$ */
2 /*
3 * Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com)
4 * Copyright (C) 2003-2008 Benny Prijono <benny@prijono.org>
5 *
6 * This program is free software; you can redistribute it and/or modify
7 * it under the terms of the GNU General Public License as published by
8 * the Free Software Foundation; either version 2 of the License, or
9 * (at your option) any later version.
10 *
11 * This program is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 * GNU General Public License for more details.
15 *
16 * You should have received a copy of the GNU General Public License
17 * along with this program; if not, write to the Free Software
18 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
19 */
20 #ifndef __PJMEDIA_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/34", where "H263" is the
528 * codec name and "34" is the (default) payload type.
529 *
530 * @param info The codec info
531 * @param id Buffer to put the codec info string.
532 * @param max_len The length of the buffer.
533 *
534 * @return The null terminated codec info string, or NULL if
535 * the buffer is not long enough.
536 */
537 PJ_DECL(char*) pjmedia_vid_codec_info_to_id(const pjmedia_vid_codec_info *info,
538 char *id, unsigned max_len );
539
540
541 /**
542 * Find codecs by the unique codec identifier. This function will find
543 * all codecs that match the codec identifier prefix. For example, if
544 * "H26" is specified, then it will find "H263", "H264", and so on,
545 * up to the maximum count specified in the argument.
546 *
547 * @param mgr The codec manager instance. If NULL, the default codec
548 * manager instance will be used.
549 * @param codec_id The full codec ID or codec ID prefix. If an empty
550 * string is given, it will match all codecs.
551 * @param count Maximum number of codecs to find. On return, it
552 * contains the actual number of codecs found.
553 * @param p_info Array of pointer to codec info to be filled. This
554 * argument may be NULL, which in this case, only
555 * codec count will be returned.
556 * @param prio Optional array of codec priorities.
557 *
558 * @return PJ_SUCCESS if at least one codec info is found.
559 */
560 PJ_DECL(pj_status_t)
561 pjmedia_vid_codec_mgr_find_codecs_by_id(pjmedia_vid_codec_mgr *mgr,
562 const pj_str_t *codec_id,
563 unsigned *count,
564 const pjmedia_vid_codec_info *p_info[],
565 unsigned prio[]);
566
567
568 /**
569 * Set codec priority. The codec priority determines the order of
570 * the codec in the SDP created by the endpoint. If more than one codecs
571 * are found with the same codec_id prefix, then the function sets the
572 * priorities of all those codecs.
573 *
574 * @param mgr The codec manager instance. If NULL, the default codec
575 * manager instance will be used.
576 * @param codec_id The full codec ID or codec ID prefix. If an empty
577 * string is given, it will match all codecs.
578 * @param prio Priority to be set. The priority can have any value
579 * between 1 to 255. When the priority is set to zero,
580 * the codec will be disabled.
581 *
582 * @return PJ_SUCCESS if at least one codec info is found.
583 */
584 PJ_DECL(pj_status_t)
585 pjmedia_vid_codec_mgr_set_codec_priority(pjmedia_vid_codec_mgr *mgr,
586 const pj_str_t *codec_id,
587 pj_uint8_t prio);
588
589
590 /**
591 * Get default codec param for the specified codec info.
592 *
593 * @param mgr The codec manager instance. If NULL, the default codec
594 * manager instance will be used.
595 * @param info The codec info, which default parameter's is being
596 * queried.
597 * @param param On return, will be filled with the default codec
598 * parameter.
599 *
600 * @return PJ_SUCCESS on success.
601 */
602 PJ_DECL(pj_status_t)
603 pjmedia_vid_codec_mgr_get_default_param(pjmedia_vid_codec_mgr *mgr,
604 const pjmedia_vid_codec_info *info,
605 pjmedia_vid_codec_param *param);
606
607
608 /**
609 * Set default codec param for the specified codec info.
610 *
611 * @param mgr The codec manager instance. If NULL, the default codec
612 * manager instance will be used.
613 * @param pool The pool instance.
614 * @param info The codec info, which default parameter's is being
615 * updated.
616 * @param param The new default codec parameter. Set to NULL to reset
617 * codec parameter to library default settings.
618 *
619 * @return PJ_SUCCESS on success.
620 */
621 PJ_DECL(pj_status_t)
622 pjmedia_vid_codec_mgr_set_default_param(pjmedia_vid_codec_mgr *mgr,
623 const pjmedia_vid_codec_info *info,
624 const pjmedia_vid_codec_param *param);
625
626
627 /**
628 * Request the codec manager to allocate one instance of codec with the
629 * specified codec info. The codec will enumerate all codec factories
630 * until it finds factory that is able to create the specified codec.
631 *
632 * @param mgr The codec manager instance. If NULL, the default codec
633 * manager instance will be used.
634 * @param info The information about the codec to be created.
635 * @param p_codec Pointer to receive the codec instance.
636 *
637 * @return PJ_SUCCESS on success.
638 */
639 PJ_DECL(pj_status_t)
640 pjmedia_vid_codec_mgr_alloc_codec( pjmedia_vid_codec_mgr *mgr,
641 const pjmedia_vid_codec_info *info,
642 pjmedia_vid_codec **p_codec);
643
644 /**
645 * Deallocate the specified codec instance. The codec manager will return
646 * the instance of the codec back to its factory.
647 *
648 * @param mgr The codec manager instance. If NULL, the default codec
649 * manager instance will be used.
650 * @param codec The codec instance.
651 *
652 * @return PJ_SUCESS on success.
653 */
654 PJ_DECL(pj_status_t) pjmedia_vid_codec_mgr_dealloc_codec(
655 pjmedia_vid_codec_mgr *mgr,
656 pjmedia_vid_codec *codec);
657
658
659
660 /**
661 * Initialize codec using the specified attribute.
662 *
663 * @param codec The codec instance.
664 * @param pool Pool to use when the codec needs to allocate
665 * some memory.
666 *
667 * @return PJ_SUCCESS on success.
668 */
pjmedia_vid_codec_init(pjmedia_vid_codec * codec,pj_pool_t * pool)669 PJ_INLINE(pj_status_t) pjmedia_vid_codec_init( pjmedia_vid_codec *codec,
670 pj_pool_t *pool )
671 {
672 return (*codec->op->init)(codec, pool);
673 }
674
675
676 /**
677 * Open the codec and initialize with the specified parameter.
678 * Upon successful initialization, the codec may modify the parameter
679 * and fills in the unspecified values (such as size or frame rate of
680 * the encoder format, as it may need to be negotiated with remote
681 * preferences via SDP fmtp).
682 *
683 * @param codec The codec instance.
684 * @param param Codec initialization parameter.
685 *
686 * @return PJ_SUCCESS on success.
687 */
pjmedia_vid_codec_open(pjmedia_vid_codec * codec,pjmedia_vid_codec_param * param)688 PJ_INLINE(pj_status_t) pjmedia_vid_codec_open(pjmedia_vid_codec *codec,
689 pjmedia_vid_codec_param *param)
690 {
691 return (*codec->op->open)(codec, param);
692 }
693
694
695 /**
696 * Close and shutdown codec, releasing all resources allocated by
697 * this codec, if any.
698 *
699 * @param codec The codec instance.
700 *
701 * @return PJ_SUCCESS on success.
702 */
pjmedia_vid_codec_close(pjmedia_vid_codec * codec)703 PJ_INLINE(pj_status_t) pjmedia_vid_codec_close( pjmedia_vid_codec *codec )
704 {
705 return (*codec->op->close)(codec);
706 }
707
708
709 /**
710 * Modify the codec parameter after the codec is open.
711 * Note that not all codec parameters can be modified during run-time.
712 * When the parameter cannot be changed, this function will return
713 * non-PJ_SUCCESS, and the original parameters will not be changed.
714 *
715 * @param codec The codec instance.
716 * @param param The new codec parameter.
717 *
718 * @return PJ_SUCCESS on success.
719 */
720 PJ_INLINE(pj_status_t)
pjmedia_vid_codec_modify(pjmedia_vid_codec * codec,const pjmedia_vid_codec_param * param)721 pjmedia_vid_codec_modify(pjmedia_vid_codec *codec,
722 const pjmedia_vid_codec_param *param)
723 {
724 return (*codec->op->modify)(codec, param);
725 }
726
727
728 /**
729 * Get the codec parameter after the codec is opened.
730 *
731 * @param codec The codec instance.
732 * @param param The codec parameter.
733 *
734 * @return PJ_SUCCESS on success.
735 */
736 PJ_INLINE(pj_status_t)
pjmedia_vid_codec_get_param(pjmedia_vid_codec * codec,pjmedia_vid_codec_param * param)737 pjmedia_vid_codec_get_param(pjmedia_vid_codec *codec,
738 pjmedia_vid_codec_param *param)
739 {
740 return (*codec->op->get_param)(codec, param);
741 }
742
743 /**
744 * Encode the specified input frame. The input MUST contain only one picture
745 * with the appropriate format as specified when opening the codec. Depending
746 * on the packing or packetization set in the \a packing param, the process
747 * may produce multiple encoded packets or payloads to represent the picture.
748 * This is true for example for PJMEDIA_VID_PACKING_PACKETS packing. In this
749 * case, the \a has_more field will be set to PJ_TRUE, and application should
750 * call pjmedia_vid_codec_encode_more() to get the remaining results from the
751 * codec.
752 *
753 * @param codec The codec instance.
754 * @param opt Optional encoding options.
755 * @param input The input frame.
756 * @param out_size The length of buffer in the output frame. This
757 * should be at least the same as the configured
758 * encoding MTU of the codec.
759 * @param output The output frame.
760 * @param has_more PJ_TRUE if more payloads are available; application
761 * should then call pjmedia_vid_codec_encode_more()
762 * to retrieve the remaining results.
763 *
764 * @return PJ_SUCCESS on success;
765 */
766 PJ_INLINE(pj_status_t)
pjmedia_vid_codec_encode_begin(pjmedia_vid_codec * codec,const pjmedia_vid_encode_opt * opt,const pjmedia_frame * input,unsigned out_size,pjmedia_frame * output,pj_bool_t * has_more)767 pjmedia_vid_codec_encode_begin( pjmedia_vid_codec *codec,
768 const pjmedia_vid_encode_opt *opt,
769 const pjmedia_frame *input,
770 unsigned out_size,
771 pjmedia_frame *output,
772 pj_bool_t *has_more)
773 {
774 return (*codec->op->encode_begin)(codec, opt, input, out_size, output,
775 has_more);
776 }
777
778 /**
779 * Retrieve more encoded packets/payloads from the codec. Application
780 * should call this function repeatedly until \a has_more flag is set
781 * to PJ_FALSE.
782 *
783 * @param codec The codec instance.
784 * @param out_size The length of buffer in the output frame. This
785 * should be at least the same as as the configured
786 * encoding MTU of the codec.
787 * @param output The output frame.
788 * @param has_more PJ_TRUE if more payloads are available, which in
789 * this case application should call \a encode_more()
790 * to retrieve them.
791 *
792 * @return PJ_SUCCESS on success;
793 */
794 PJ_INLINE(pj_status_t)
pjmedia_vid_codec_encode_more(pjmedia_vid_codec * codec,unsigned out_size,pjmedia_frame * output,pj_bool_t * has_more)795 pjmedia_vid_codec_encode_more( pjmedia_vid_codec *codec,
796 unsigned out_size,
797 pjmedia_frame *output,
798 pj_bool_t *has_more)
799 {
800 return (*codec->op->encode_more)(codec, out_size, output, has_more);
801 }
802
803 /**
804 * Decode the input packets into one picture. If the packing is set to
805 * PJMEDIA_VID_PACKING_PACKETS when opening the codec, the codec is set
806 * to decode multiple encoded packets into one picture. These encoded
807 * packets are typically retrieved from the jitter buffer. If the packing
808 * is set to PJMEDIA_VID_PACKING_WHOLE, then this decode function can only
809 * accept one frame as the input.
810 *
811 * Note that the decoded picture format may different to the configured
812 * setting (i.e. the format specified in the #pjmedia_vid_codec_param when
813 * opening the codec), in this case the PJMEDIA_EVENT_FMT_CHANGED event will
814 * be emitted by the codec to notify the event. The codec parameter will
815 * also be updated, and application can query the format by using
816 * pjmedia_vid_codec_get_param().
817 *
818 * @param codec The codec instance.
819 * @param pkt_count Number of packets in the input.
820 * @param packets Array of input packets, each containing an encoded
821 * frame.
822 * @param out_size The length of buffer in the output frame.
823 * @param output The output frame.
824 *
825 * @return PJ_SUCCESS on success;
826 */
pjmedia_vid_codec_decode(pjmedia_vid_codec * codec,pj_size_t pkt_count,pjmedia_frame packets[],unsigned out_size,pjmedia_frame * output)827 PJ_INLINE(pj_status_t) pjmedia_vid_codec_decode(pjmedia_vid_codec *codec,
828 pj_size_t pkt_count,
829 pjmedia_frame packets[],
830 unsigned out_size,
831 pjmedia_frame *output)
832 {
833 return (*codec->op->decode)(codec, pkt_count, packets, out_size, output);
834 }
835
836 /**
837 * Recover a missing frame.
838 *
839 * @param codec The codec instance.
840 * @param out_size The length of buffer in the output frame.
841 * @param output The output frame where generated signal
842 * will be placed.
843 *
844 * @return PJ_SUCCESS on success;
845 */
pjmedia_vid_codec_recover(pjmedia_vid_codec * codec,unsigned out_size,pjmedia_frame * output)846 PJ_INLINE(pj_status_t) pjmedia_vid_codec_recover(pjmedia_vid_codec *codec,
847 unsigned out_size,
848 pjmedia_frame *output)
849 {
850 if (codec->op && codec->op->recover)
851 return (*codec->op->recover)(codec, out_size, output);
852 else
853 return PJ_ENOTSUP;
854 }
855
856
857 /**
858 * @}
859 */
860
861 /**
862 * @defgroup PJMEDIA_CODEC_VID_CODECS Supported video codecs
863 * @ingroup PJMEDIA_VID_CODEC
864 */
865
866
867
868
869 PJ_END_DECL
870
871
872 #endif /* __PJMEDIA_VID_CODEC_H__ */
873