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_FORMAT_H__
21 #define __PJMEDIA_FORMAT_H__
22
23 /**
24 * @file pjmedia/format.h Media format
25 * @brief Media format
26 */
27 #include <pjmedia/types.h>
28
29 /**
30 * @defgroup PJMEDIA_FORMAT Media format
31 * @ingroup PJMEDIA_TYPES
32 * @brief Media format
33 * @{
34 */
35
36 PJ_BEGIN_DECL
37
38 /**
39 * Macro for packing format from a four character code, similar to FOURCC.
40 * This macro is used for building the constants in pjmedia_format_id
41 * enumeration.
42 */
43 #define PJMEDIA_FORMAT_PACK(C1, C2, C3, C4) PJMEDIA_FOURCC(C1, C2, C3, C4)
44
45 /**
46 * This enumeration uniquely identify audio sample and/or video pixel formats.
47 * Some well known formats are listed here. The format ids are built by
48 * combining four character codes, similar to FOURCC. The format id is
49 * extensible, as application may define and use format ids not declared
50 * on this enumeration.
51 *
52 * This format id along with other information will fully describe the media
53 * in #pjmedia_format structure.
54 */
55 typedef enum pjmedia_format_id
56 {
57 /*
58 * Audio formats
59 */
60
61 /** 16bit signed integer linear PCM audio */
62 PJMEDIA_FORMAT_L16 = 0,
63
64 /** Alias for PJMEDIA_FORMAT_L16 */
65 PJMEDIA_FORMAT_PCM = PJMEDIA_FORMAT_L16,
66
67 /** G.711 ALAW */
68 PJMEDIA_FORMAT_PCMA = PJMEDIA_FORMAT_PACK('A', 'L', 'A', 'W'),
69
70 /** Alias for PJMEDIA_FORMAT_PCMA */
71 PJMEDIA_FORMAT_ALAW = PJMEDIA_FORMAT_PCMA,
72
73 /** G.711 ULAW */
74 PJMEDIA_FORMAT_PCMU = PJMEDIA_FORMAT_PACK('u', 'L', 'A', 'W'),
75
76 /** Aliaw for PJMEDIA_FORMAT_PCMU */
77 PJMEDIA_FORMAT_ULAW = PJMEDIA_FORMAT_PCMU,
78
79 /** AMR narrowband */
80 PJMEDIA_FORMAT_AMR = PJMEDIA_FORMAT_PACK(' ', 'A', 'M', 'R'),
81
82 /** ITU G.729 */
83 PJMEDIA_FORMAT_G729 = PJMEDIA_FORMAT_PACK('G', '7', '2', '9'),
84
85 /** Internet Low Bit-Rate Codec (ILBC) */
86 PJMEDIA_FORMAT_ILBC = PJMEDIA_FORMAT_PACK('I', 'L', 'B', 'C'),
87
88
89 /*
90 * Video formats.
91 */
92 /**
93 * 24bit RGB
94 */
95 PJMEDIA_FORMAT_RGB24 = PJMEDIA_FORMAT_PACK('R', 'G', 'B', '3'),
96
97 /**
98 * 32bit RGB with alpha channel
99 */
100 PJMEDIA_FORMAT_RGBA = PJMEDIA_FORMAT_PACK('R', 'G', 'B', 'A'),
101 PJMEDIA_FORMAT_BGRA = PJMEDIA_FORMAT_PACK('B', 'G', 'R', 'A'),
102
103 /**
104 * Alias for PJMEDIA_FORMAT_RGBA
105 */
106 PJMEDIA_FORMAT_RGB32 = PJMEDIA_FORMAT_RGBA,
107
108 /**
109 * Device Independent Bitmap, alias for 24 bit RGB
110 */
111 PJMEDIA_FORMAT_DIB = PJMEDIA_FORMAT_PACK('D', 'I', 'B', ' '),
112
113 /**
114 * This is planar 4:4:4/24bpp RGB format, the data can be treated as
115 * three planes of color components, where the first plane contains
116 * only the G samples, the second plane contains only the B samples,
117 * and the third plane contains only the R samples.
118 */
119 PJMEDIA_FORMAT_GBRP = PJMEDIA_FORMAT_PACK('G', 'B', 'R', 'P'),
120
121 /**
122 * This is a packed 4:4:4/32bpp format, where each pixel is encoded as
123 * four consecutive bytes, arranged in the following sequence: V0, U0,
124 * Y0, A0. Source:
125 * http://msdn.microsoft.com/en-us/library/dd206750%28v=VS.85%29.aspx#ayuv
126 */
127 PJMEDIA_FORMAT_AYUV = PJMEDIA_FORMAT_PACK('A', 'Y', 'U', 'V'),
128
129 /**
130 * This is packed 4:2:2/16bpp YUV format, the data can be treated as
131 * an array of unsigned char values, where the first byte contains
132 * the first Y sample, the second byte contains the first U (Cb) sample,
133 * the third byte contains the second Y sample, and the fourth byte
134 * contains the first V (Cr) sample, and so forth. Source:
135 * http://msdn.microsoft.com/en-us/library/dd206750%28v=VS.85%29.aspx#yuy2
136 */
137 PJMEDIA_FORMAT_YUY2 = PJMEDIA_FORMAT_PACK('Y', 'U', 'Y', '2'),
138
139 /**
140 * This format is the same as the YUY2 format except the byte order is
141 * reversed -- that is, the chroma and luma bytes are flipped. If the
142 * image is addressed as an array of two little-endian WORD values, the
143 * first WORD contains U in the LSBs and Y0 in the MSBs, and the second
144 * WORD contains V in the LSBs and Y1 in the MSBs. Source:
145 * http://msdn.microsoft.com/en-us/library/dd206750%28v=VS.85%29.aspx#uyvy
146 */
147 PJMEDIA_FORMAT_UYVY = PJMEDIA_FORMAT_PACK('U', 'Y', 'V', 'Y'),
148
149 /**
150 * This format is the same as the YUY2 and UYVY format except the byte
151 * order is reversed -- that is, the chroma and luma bytes are flipped.
152 * If the image is addressed as an array of two little-endian WORD values,
153 * the first WORD contains Y0 in the LSBs and V in the MSBs, and the second
154 * WORD contains Y1 in the LSBs and U in the MSBs.
155 */
156 PJMEDIA_FORMAT_YVYU = PJMEDIA_FORMAT_PACK('Y', 'V', 'Y', 'U'),
157
158 /**
159 * This is planar 4:2:0/12bpp YUV format, the data can be treated as
160 * three planes of color components, where the first plane contains
161 * only the Y samples, the second plane contains only the U (Cb) samples,
162 * and the third plane contains only the V (Cr) sample.
163 */
164 PJMEDIA_FORMAT_I420 = PJMEDIA_FORMAT_PACK('I', '4', '2', '0'),
165
166 /**
167 * IYUV is alias for I420.
168 */
169 PJMEDIA_FORMAT_IYUV = PJMEDIA_FORMAT_I420,
170
171 /**
172 * This is planar 4:2:0/12bpp YUV format, similar to I420 or IYUV but
173 * the U (Cb) and V (Cr) planes order is switched, i.e: the second plane
174 * contains the V (Cb) samples and the third plane contains the V (Cr)
175 * samples.
176 */
177 PJMEDIA_FORMAT_YV12 = PJMEDIA_FORMAT_PACK('Y', 'V', '1', '2'),
178
179 /**
180 * This is planar 4:2:0/12bpp YUV format, the data can be treated as
181 * two planes of color components, where the first plane contains
182 * only the Y samples, the second plane contains interleaved
183 * U (Cb) - V (Cr) samples.
184 */
185 PJMEDIA_FORMAT_NV12 = PJMEDIA_FORMAT_PACK('N', 'V', '1', '2'),
186
187 /**
188 * This is planar 4:2:0/12bpp YUV format, the data can be treated as
189 * two planes of color components, where the first plane contains
190 * only the Y samples, the second plane contains interleaved
191 * V (Cr) - U (Cb) samples.
192 */
193 PJMEDIA_FORMAT_NV21 = PJMEDIA_FORMAT_PACK('N', 'V', '2', '1'),
194
195 /**
196 * This is planar 4:2:2/16bpp YUV format, the data can be treated as
197 * three planes of color components, where the first plane contains
198 * only the Y samples, the second plane contains only the U (Cb) samples,
199 * and the third plane contains only the V (Cr) sample.
200 */
201 PJMEDIA_FORMAT_I422 = PJMEDIA_FORMAT_PACK('I', '4', '2', '2'),
202
203 /**
204 * The JPEG version of planar 4:2:0/12bpp YUV format.
205 */
206 PJMEDIA_FORMAT_I420JPEG = PJMEDIA_FORMAT_PACK('J', '4', '2', '0'),
207
208 /**
209 * The JPEG version of planar 4:2:2/16bpp YUV format.
210 */
211 PJMEDIA_FORMAT_I422JPEG = PJMEDIA_FORMAT_PACK('J', '4', '2', '2'),
212
213 /**
214 * Encoded video formats
215 */
216
217 PJMEDIA_FORMAT_H261 = PJMEDIA_FORMAT_PACK('H', '2', '6', '1'),
218 PJMEDIA_FORMAT_H263 = PJMEDIA_FORMAT_PACK('H', '2', '6', '3'),
219 PJMEDIA_FORMAT_H263P = PJMEDIA_FORMAT_PACK('P', '2', '6', '3'),
220 PJMEDIA_FORMAT_H264 = PJMEDIA_FORMAT_PACK('H', '2', '6', '4'),
221
222 PJMEDIA_FORMAT_VP8 = PJMEDIA_FORMAT_PACK('V', 'P', '8', '0'),
223 PJMEDIA_FORMAT_VP9 = PJMEDIA_FORMAT_PACK('V', 'P', '9', '0'),
224
225 PJMEDIA_FORMAT_MJPEG = PJMEDIA_FORMAT_PACK('M', 'J', 'P', 'G'),
226 PJMEDIA_FORMAT_MPEG1VIDEO = PJMEDIA_FORMAT_PACK('M', 'P', '1', 'V'),
227 PJMEDIA_FORMAT_MPEG2VIDEO = PJMEDIA_FORMAT_PACK('M', 'P', '2', 'V'),
228 PJMEDIA_FORMAT_MPEG4 = PJMEDIA_FORMAT_PACK('M', 'P', 'G', '4'),
229
230 PJMEDIA_FORMAT_INVALID = 0xFFFFFFFF
231
232 } pjmedia_format_id;
233
234 /**
235 * This enumeration specifies what type of detail is included in a
236 * #pjmedia_format structure.
237 */
238 typedef enum pjmedia_format_detail_type
239 {
240 /** Format detail is not specified. */
241 PJMEDIA_FORMAT_DETAIL_NONE,
242
243 /** Audio format detail. */
244 PJMEDIA_FORMAT_DETAIL_AUDIO,
245
246 /** Video format detail. */
247 PJMEDIA_FORMAT_DETAIL_VIDEO,
248
249 /** Number of format detail type that has been defined. */
250 PJMEDIA_FORMAT_DETAIL_MAX
251
252 } pjmedia_format_detail_type;
253
254 /**
255 * This structure is put in \a detail field of #pjmedia_format to describe
256 * detail information about an audio media.
257 */
258 typedef struct pjmedia_audio_format_detail
259 {
260 unsigned clock_rate; /**< Audio clock rate in samples or Hz. */
261 unsigned channel_count; /**< Number of channels. */
262 unsigned frame_time_usec;/**< Frame interval, in microseconds. */
263 unsigned bits_per_sample;/**< Number of bits per sample. */
264 pj_uint32_t avg_bps; /**< Average bitrate */
265 pj_uint32_t max_bps; /**< Maximum bitrate */
266 } pjmedia_audio_format_detail;
267
268 /**
269 * This structure is put in \a detail field of #pjmedia_format to describe
270 * detail information about a video media.
271 *
272 * Additional information about a video format can also be retrieved by
273 * calling #pjmedia_get_video_format_info().
274 */
275 typedef struct pjmedia_video_format_detail
276 {
277 pjmedia_rect_size size; /**< Video size (width, height) */
278 pjmedia_ratio fps; /**< Number of frames per second. */
279 pj_uint32_t avg_bps;/**< Average bitrate. */
280 pj_uint32_t max_bps;/**< Maximum bitrate. */
281 } pjmedia_video_format_detail;
282
283 /**
284 * This macro declares the size of the detail section in #pjmedia_format
285 * to be reserved for user defined detail.
286 */
287 #ifndef PJMEDIA_FORMAT_DETAIL_USER_SIZE
288 # define PJMEDIA_FORMAT_DETAIL_USER_SIZE 1
289 #endif
290
291 /**
292 * This structure contains all the information needed to completely describe
293 * a media.
294 */
295 typedef struct pjmedia_format
296 {
297 /**
298 * The format id that specifies the audio sample or video pixel format.
299 * Some well known formats ids are declared in pjmedia_format_id
300 * enumeration.
301 *
302 * @see pjmedia_format_id
303 */
304 pj_uint32_t id;
305
306 /**
307 * The top-most type of the media, as an information.
308 */
309 pjmedia_type type;
310
311 /**
312 * The type of detail structure in the \a detail pointer.
313 */
314 pjmedia_format_detail_type detail_type;
315
316 /**
317 * Detail section to describe the media.
318 */
319 union
320 {
321 /**
322 * Detail section for audio format.
323 */
324 pjmedia_audio_format_detail aud;
325
326 /**
327 * Detail section for video format.
328 */
329 pjmedia_video_format_detail vid;
330
331 /**
332 * Reserved area for user-defined format detail.
333 */
334 char user[PJMEDIA_FORMAT_DETAIL_USER_SIZE];
335 } det;
336
337 } pjmedia_format;
338
339 /**
340 * This enumeration describes video color model. It mostly serves as
341 * information only.
342 */
343 typedef enum pjmedia_color_model
344 {
345 /** The color model is unknown or unspecified. */
346 PJMEDIA_COLOR_MODEL_NONE,
347
348 /** RGB color model. */
349 PJMEDIA_COLOR_MODEL_RGB,
350
351 /** YUV color model. */
352 PJMEDIA_COLOR_MODEL_YUV
353 } pjmedia_color_model;
354
355 /**
356 * This structure holds information to apply a specific video format
357 * against size and buffer information, and get additional information
358 * from it. To do that, application fills up the input fields of this
359 * structure, and give this structure to \a apply_fmt() function
360 * of #pjmedia_video_format_info structure.
361 */
362 typedef struct pjmedia_video_apply_fmt_param
363 {
364 /* input fields: */
365
366 /**
367 * [IN] The image size. This field is mandatory, and has to be set
368 * correctly prior to calling \a apply_fmt() function.
369 */
370 pjmedia_rect_size size;
371
372 /**
373 * [IN] Pointer to the buffer that holds the frame. The \a apply_fmt()
374 * function uses this pointer to calculate the pointer for each video
375 * planes of the media. This field is optional -- however, the
376 * \a apply_fmt() would still fill up the \a planes[] array with the
377 * correct pointer even though the buffer is set to NULL. This could be
378 * useful to calculate the size (in bytes) of each plane.
379 */
380 pj_uint8_t *buffer;
381
382 /* output fields: */
383
384 /**
385 * [OUT] The size (in bytes) required of the buffer to hold the video
386 * frame of the particular frame size (width, height).
387 */
388 pj_size_t framebytes;
389
390 /**
391 * [OUT] Array of strides value (in bytes) for each video plane.
392 */
393 int strides[PJMEDIA_MAX_VIDEO_PLANES];
394
395 /**
396 * [OUT] Array of pointers to each of the video planes. The values are
397 * calculated from the \a buffer field.
398 */
399 pj_uint8_t *planes[PJMEDIA_MAX_VIDEO_PLANES];
400
401 /**
402 * [OUT] Array of video plane sizes.
403 */
404 pj_size_t plane_bytes[PJMEDIA_MAX_VIDEO_PLANES];
405
406 } pjmedia_video_apply_fmt_param;
407
408 /**
409 * This structure holds information to describe a video format. Application
410 * can retrieve this structure by calling #pjmedia_get_video_format_info()
411 * funcion.
412 */
413 typedef struct pjmedia_video_format_info
414 {
415 /**
416 * The unique format ID of the media. Well known format ids are declared
417 * in pjmedia_format_id enumeration.
418 */
419 pj_uint32_t id;
420
421 /**
422 * Null terminated string containing short identification about the
423 * format.
424 */
425 char name[8];
426
427 /**
428 * Information about the color model of this video format.
429 */
430 pjmedia_color_model color_model;
431
432 /**
433 * Number of bits needed to store one pixel of this video format.
434 */
435 pj_uint8_t bpp;
436
437 /**
438 * Number of video planes that this format uses. Value 1 indicates
439 * packed format, while value greater than 1 indicates planar format.
440 */
441 pj_uint8_t plane_cnt;
442
443 /**
444 * Pointer to function to apply this format against size and buffer
445 * information in pjmedia_video_apply_fmt_param argument. Application
446 * uses this function to obtain various information such as the
447 * memory size of a frame buffer, strides value of the image, the
448 * location of the planes, and so on. See pjmedia_video_apply_fmt_param
449 * for additional information.
450 *
451 * @param vfi The video format info.
452 * @param vafp The parameters to investigate.
453 *
454 * @return PJ_SUCCESS if the function has calculated the
455 * information in \a vafp successfully.
456 */
457 pj_status_t (*apply_fmt)(const struct pjmedia_video_format_info *vfi,
458 pjmedia_video_apply_fmt_param *vafp);
459
460 } pjmedia_video_format_info;
461
462
463 /*****************************************************************************
464 * UTILITIES:
465 */
466
467 /**
468 * General utility routine to calculate samples per frame value from clock
469 * rate, ptime (in usec), and channel count. Application should use this
470 * macro whenever possible due to possible overflow in the math calculation.
471 *
472 * @param clock_rate Clock rate.
473 * @param usec_ptime Frame interval, in microsecond.
474 * @param channel_count Number of channels.
475 *
476 * @return The samples per frame value.
477 */
PJMEDIA_SPF(unsigned clock_rate,unsigned usec_ptime,unsigned channel_count)478 PJ_INLINE(unsigned) PJMEDIA_SPF(unsigned clock_rate, unsigned usec_ptime,
479 unsigned channel_count)
480 {
481 #if PJ_HAS_INT64
482 return ((unsigned)((pj_uint64_t)usec_ptime * \
483 clock_rate * channel_count / 1000000));
484 #elif PJ_HAS_FLOATING_POINT
485 return ((unsigned)(1.0*usec_ptime * clock_rate * channel_count / 1000000));
486 #else
487 return ((unsigned)(usec_ptime / 1000L * clock_rate * \
488 channel_count / 1000));
489 #endif
490 }
491
492 /**
493 * Variant of #PJMEDIA_SPF() which takes frame rate instead of ptime.
494 */
PJMEDIA_SPF2(unsigned clock_rate,const pjmedia_ratio * fr,unsigned channel_count)495 PJ_INLINE(unsigned) PJMEDIA_SPF2(unsigned clock_rate, const pjmedia_ratio *fr,
496 unsigned channel_count)
497 {
498 #if PJ_HAS_INT64
499 return ((unsigned)((pj_uint64_t)clock_rate * fr->denum \
500 / fr->num / channel_count));
501 #elif PJ_HAS_FLOATING_POINT
502 return ((unsigned)(1.0* clock_rate * fr->denum / fr->num /channel_count));
503 #else
504 return ((unsigned)(1L * clock_rate * fr->denum / fr->num / channel_count));
505 #endif
506 }
507
508
509 /**
510 * Utility routine to calculate frame size (in bytes) from bitrate and frame
511 * interval values. Application should use this macro whenever possible due
512 * to possible overflow in the math calculation.
513 *
514 * @param bps The bitrate of the stream.
515 * @param usec_ptime Frame interval, in microsecond.
516 *
517 * @return Frame size in bytes.
518 */
PJMEDIA_FSZ(unsigned bps,unsigned usec_ptime)519 PJ_INLINE(unsigned) PJMEDIA_FSZ(unsigned bps, unsigned usec_ptime)
520 {
521 #if PJ_HAS_INT64
522 return ((unsigned)((pj_uint64_t)bps * usec_ptime / PJ_UINT64(8000000)));
523 #elif PJ_HAS_FLOATING_POINT
524 return ((unsigned)(1.0 * bps * usec_ptime / 8000000.0));
525 #else
526 return ((unsigned)(bps / 8L * usec_ptime / 1000000));
527 #endif
528 }
529
530 /**
531 * General utility routine to calculate ptime value from frame rate.
532 * Application should use this macro whenever possible due to possible
533 * overflow in the math calculation.
534 *
535 * @param frame_rate Frame rate
536 *
537 * @return The ptime value (in usec).
538 */
PJMEDIA_PTIME(const pjmedia_ratio * frame_rate)539 PJ_INLINE(unsigned) PJMEDIA_PTIME(const pjmedia_ratio *frame_rate)
540 {
541 #if PJ_HAS_INT64
542 return ((unsigned)((pj_uint64_t)1000000 * \
543 frame_rate->denum / frame_rate->num));
544 #elif PJ_HAS_FLOATING_POINT
545 return ((unsigned)(1000000.0 * frame_rate->denum /
546 frame_rate->num));
547 #else
548 return ((unsigned)((1000L * frame_rate->denum /
549 frame_rate->num) * 1000));
550 #endif
551 }
552
553 /**
554 * Utility to retrieve samples_per_frame value from
555 * pjmedia_audio_format_detail.
556 *
557 * @param pafd Pointer to pjmedia_audio_format_detail
558 * @return Samples per frame
559 */
PJMEDIA_AFD_SPF(const pjmedia_audio_format_detail * pafd)560 PJ_INLINE(unsigned) PJMEDIA_AFD_SPF(const pjmedia_audio_format_detail *pafd)
561 {
562 return PJMEDIA_SPF(pafd->clock_rate, pafd->frame_time_usec,
563 pafd->channel_count);
564 }
565
566 /**
567 * Utility to retrieve average frame size from pjmedia_audio_format_detail.
568 * The average frame size is derived from the average bitrate of the audio
569 * stream.
570 *
571 * @param afd Pointer to pjmedia_audio_format_detail
572 * @return Average frame size.
573 */
PJMEDIA_AFD_AVG_FSZ(const pjmedia_audio_format_detail * afd)574 PJ_INLINE(unsigned) PJMEDIA_AFD_AVG_FSZ(const pjmedia_audio_format_detail *afd)
575 {
576 return PJMEDIA_FSZ(afd->avg_bps, afd->frame_time_usec);
577 }
578
579 /**
580 * Utility to retrieve maximum frame size from pjmedia_audio_format_detail.
581 * The maximum frame size is derived from the maximum bitrate of the audio
582 * stream.
583 *
584 * @param afd Pointer to pjmedia_audio_format_detail
585 * @return Average frame size.
586 */
PJMEDIA_AFD_MAX_FSZ(const pjmedia_audio_format_detail * afd)587 PJ_INLINE(unsigned) PJMEDIA_AFD_MAX_FSZ(const pjmedia_audio_format_detail *afd)
588 {
589 return PJMEDIA_FSZ(afd->max_bps, afd->frame_time_usec);
590 }
591
592
593 /**
594 * Initialize the format as audio format with the specified parameters.
595 *
596 * @param fmt The format to be initialized.
597 * @param fmt_id Format ID. See #pjmedia_format_id
598 * @param clock_rate Audio clock rate.
599 * @param channel_count Number of channels.
600 * @param bits_per_sample Number of bits per sample.
601 * @param frame_time_usec Frame interval, in microsecond.
602 * @param avg_bps Average bitrate.
603 * @param max_bps Maximum bitrate.
604 */
pjmedia_format_init_audio(pjmedia_format * fmt,pj_uint32_t fmt_id,unsigned clock_rate,unsigned channel_count,unsigned bits_per_sample,unsigned frame_time_usec,pj_uint32_t avg_bps,pj_uint32_t max_bps)605 PJ_INLINE(void) pjmedia_format_init_audio(pjmedia_format *fmt,
606 pj_uint32_t fmt_id,
607 unsigned clock_rate,
608 unsigned channel_count,
609 unsigned bits_per_sample,
610 unsigned frame_time_usec,
611 pj_uint32_t avg_bps,
612 pj_uint32_t max_bps)
613 {
614 /* This function is inlined to avoid build problem due to circular
615 * dependency, i.e: this function is part of pjmedia and is needed
616 * by pjmedia-audiodev, while pjmedia depends on pjmedia-audiodev.
617 */
618
619 fmt->id = fmt_id;
620 fmt->type = PJMEDIA_TYPE_AUDIO;
621 fmt->detail_type = PJMEDIA_FORMAT_DETAIL_AUDIO;
622
623 fmt->det.aud.clock_rate = clock_rate;
624 fmt->det.aud.channel_count = channel_count;
625 fmt->det.aud.bits_per_sample = bits_per_sample;
626 fmt->det.aud.frame_time_usec = frame_time_usec;
627 fmt->det.aud.avg_bps = avg_bps;
628 fmt->det.aud.max_bps = max_bps;
629 }
630
631
632 /**
633 * Initialize the format as video format with the specified parameters.
634 * A format manager should have been created, as this function will need
635 * to consult to a format manager in order to fill in detailed
636 * information about the format.
637 *
638 * @param fmt The format to be initialised.
639 * @param fmt_id Format ID. See #pjmedia_format_id
640 * @param width Image width.
641 * @param height Image heigth.
642 * @param fps_num FPS numerator.
643 * @param fps_denum FPS denumerator.
644 * @param avg_bps Average bitrate.
645 * @param max_bps Maximum bitrate.
646 */
647 PJ_DECL(void) pjmedia_format_init_video(pjmedia_format *fmt,
648 pj_uint32_t fmt_id,
649 unsigned width,
650 unsigned height,
651 unsigned fps_num,
652 unsigned fps_denum);
653
654 /**
655 * Copy format to another.
656 *
657 * @param dst The destination format.
658 * @param src The source format.
659 *
660 * @return Pointer to destination format.
661 */
662 PJ_DECL(pjmedia_format*) pjmedia_format_copy(pjmedia_format *dst,
663 const pjmedia_format *src);
664
665 /**
666 * Check if the format contains audio format, and retrieve the audio format
667 * detail in the format.
668 *
669 * @param fmt The format structure.
670 * @param assert_valid If this is set to non-zero, an assertion will be
671 * raised if the detail type is not audio or if the
672 * the detail is NULL.
673 *
674 * @return The instance of audio format detail in the format
675 * structure, or NULL if the format doesn't contain
676 * audio detail.
677 */
678 PJ_DECL(pjmedia_audio_format_detail*)
679 pjmedia_format_get_audio_format_detail(const pjmedia_format *fmt,
680 pj_bool_t assert_valid);
681
682 /**
683 * Check if the format contains video format, and retrieve the video format
684 * detail in the format.
685 *
686 * @param fmt The format structure.
687 * @param assert_valid If this is set to non-zero, an assertion will be
688 * raised if the detail type is not video or if the
689 * the detail is NULL.
690 *
691 * @return The instance of video format detail in the format
692 * structure, or NULL if the format doesn't contain
693 * video detail.
694 */
695 PJ_DECL(pjmedia_video_format_detail*)
696 pjmedia_format_get_video_format_detail(const pjmedia_format *fmt,
697 pj_bool_t assert_valid);
698
699 /*****************************************************************************
700 * FORMAT MANAGEMENT:
701 */
702
703 /**
704 * Opaque data type for video format manager. The video format manager manages
705 * the repository of video formats that the framework recognises. Typically it
706 * is a singleton instance, although application may instantiate more than one
707 * instances of this if required.
708 */
709 typedef struct pjmedia_video_format_mgr pjmedia_video_format_mgr;
710
711
712 /**
713 * Create a new video format manager instance. This will also set the pointer
714 * to the singleton instance if the value is still NULL.
715 *
716 * @param pool The pool to allocate memory.
717 * @param max_fmt Maximum number of formats to accommodate.
718 * @param options Option flags. Must be zero for now.
719 * @param p_mgr Pointer to hold the created instance.
720 *
721 * @return PJ_SUCCESS on success, or the appripriate error value.
722 */
723 PJ_DECL(pj_status_t)
724 pjmedia_video_format_mgr_create(pj_pool_t *pool,
725 unsigned max_fmt,
726 unsigned options,
727 pjmedia_video_format_mgr **p_mgr);
728
729 /**
730 * Get the singleton instance of the video format manager.
731 *
732 * @return The instance.
733 */
734 PJ_DECL(pjmedia_video_format_mgr*) pjmedia_video_format_mgr_instance(void);
735
736 /**
737 * Manually assign a specific video manager instance as the singleton
738 * instance. Normally this is not needed if only one instance is ever
739 * going to be created, as the library automatically assign the singleton
740 * instance.
741 *
742 * @param mgr The instance to be used as the singleton instance.
743 * Application may specify NULL to clear the singleton
744 * singleton instance.
745 */
746 PJ_DECL(void)
747 pjmedia_video_format_mgr_set_instance(pjmedia_video_format_mgr *mgr);
748
749 /**
750 * Retrieve a video format info for the specified format id.
751 *
752 * @param mgr The video format manager. Specify NULL to use
753 * the singleton instance (however, a video format
754 * manager still must have been created prior to
755 * calling this function).
756 * @param id The format id which format info is to be
757 * retrieved.
758 *
759 * @return The video format info.
760 */
761 PJ_DECL(const pjmedia_video_format_info*)
762 pjmedia_get_video_format_info(pjmedia_video_format_mgr *mgr,
763 pj_uint32_t id);
764
765 /**
766 * Register a new video format to the framework. By default, built-in
767 * formats will be registered automatically to the format manager when
768 * it is created (note: built-in formats are ones which format id is
769 * listed in pjmedia_format_id enumeration). This function allows
770 * application to use user defined format id by registering that format
771 * into the framework.
772 *
773 * @param mgr The video format manager. Specify NULL to use
774 * the singleton instance (however, a video format
775 * manager still must have been created prior to
776 * calling this function).
777 * @param vfi The video format info to be registered. This
778 * structure must remain valid until the format
779 * manager is destroyed.
780 *
781 * @return PJ_SUCCESS on success, or the appripriate error value.
782 */
783 PJ_DECL(pj_status_t)
784 pjmedia_register_video_format_info(pjmedia_video_format_mgr *mgr,
785 pjmedia_video_format_info *vfi);
786
787 /**
788 * Destroy a video format manager. If the manager happens to be the singleton
789 * instance, the singleton instance will be set to NULL.
790 *
791 * @param mgr The video format manager. Specify NULL to use
792 * the singleton instance (however, a video format
793 * manager still must have been created prior to
794 * calling this function).
795 */
796 PJ_DECL(void) pjmedia_video_format_mgr_destroy(pjmedia_video_format_mgr *mgr);
797
798 PJ_END_DECL
799
800 /**
801 * @}
802 */
803
804 #endif /* __PJMEDIA_FORMAT_H__ */
805
806