← 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/format.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/format.h
 
1
/* $Id: format.h 4158 2012-06-06 09:56:14Z 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_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:2/16bpp YUV format, the data can be treated as
 
181
     * three planes of color components, where the first plane contains
 
182
     * only the Y samples, the second plane contains only the U (Cb) samples,
 
183
     * and the third plane contains only the V (Cr) sample.
 
184
     */
 
185
    PJMEDIA_FORMAT_I422     = PJMEDIA_FORMAT_PACK('I', '4', '2', '2'),
 
186
 
 
187
    /**
 
188
     * The JPEG version of planar 4:2:0/12bpp YUV format.
 
189
     */
 
190
    PJMEDIA_FORMAT_I420JPEG = PJMEDIA_FORMAT_PACK('J', '4', '2', '0'),
 
191
 
 
192
    /**
 
193
     * The JPEG version of planar 4:2:2/16bpp YUV format.
 
194
     */
 
195
    PJMEDIA_FORMAT_I422JPEG = PJMEDIA_FORMAT_PACK('J', '4', '2', '2'),
 
196
 
 
197
    /**
 
198
     * Encoded video formats
 
199
     */
 
200
 
 
201
    PJMEDIA_FORMAT_H261     = PJMEDIA_FORMAT_PACK('H', '2', '6', '1'),
 
202
    PJMEDIA_FORMAT_H263     = PJMEDIA_FORMAT_PACK('H', '2', '6', '3'),
 
203
    PJMEDIA_FORMAT_H263P    = PJMEDIA_FORMAT_PACK('P', '2', '6', '3'),
 
204
    PJMEDIA_FORMAT_H264     = PJMEDIA_FORMAT_PACK('H', '2', '6', '4'),
 
205
 
 
206
    PJMEDIA_FORMAT_MJPEG    = PJMEDIA_FORMAT_PACK('M', 'J', 'P', 'G'),
 
207
    PJMEDIA_FORMAT_MPEG1VIDEO = PJMEDIA_FORMAT_PACK('M', 'P', '1', 'V'),
 
208
    PJMEDIA_FORMAT_MPEG2VIDEO = PJMEDIA_FORMAT_PACK('M', 'P', '2', 'V'),
 
209
    PJMEDIA_FORMAT_MPEG4    = PJMEDIA_FORMAT_PACK('M', 'P', 'G', '4'),
 
210
 
 
211
} pjmedia_format_id;
 
212
 
 
213
/**
 
214
 * This enumeration specifies what type of detail is included in a
 
215
 * #pjmedia_format structure.
 
216
 */
 
217
typedef enum pjmedia_format_detail_type
 
218
{
 
219
    /** Format detail is not specified. */
 
220
    PJMEDIA_FORMAT_DETAIL_NONE,
 
221
 
 
222
    /** Audio format detail. */
 
223
    PJMEDIA_FORMAT_DETAIL_AUDIO,
 
224
 
 
225
    /** Video format detail. */
 
226
    PJMEDIA_FORMAT_DETAIL_VIDEO,
 
227
 
 
228
    /** Number of format detail type that has been defined. */
 
229
    PJMEDIA_FORMAT_DETAIL_MAX
 
230
 
 
231
} pjmedia_format_detail_type;
 
232
 
 
233
/**
 
234
 * This structure is put in \a detail field of #pjmedia_format to describe
 
235
 * detail information about an audio media.
 
236
 */
 
237
typedef struct pjmedia_audio_format_detail
 
238
{
 
239
    unsigned    clock_rate;     /**< Audio clock rate in samples or Hz. */
 
240
    unsigned    channel_count;  /**< Number of channels.                */
 
241
    unsigned    frame_time_usec;/**< Frame interval, in microseconds.   */
 
242
    unsigned    bits_per_sample;/**< Number of bits per sample.         */
 
243
    pj_uint32_t avg_bps;        /**< Average bitrate                    */
 
244
    pj_uint32_t max_bps;        /**< Maximum bitrate                    */
 
245
} pjmedia_audio_format_detail;
 
246
 
 
247
/**
 
248
 * This structure is put in \a detail field of #pjmedia_format to describe
 
249
 * detail information about a video media.
 
250
 *
 
251
 * Additional information about a video format can also be retrieved by
 
252
 * calling #pjmedia_get_video_format_info().
 
253
 */
 
254
typedef struct pjmedia_video_format_detail
 
255
{
 
256
    pjmedia_rect_size   size;   /**< Video size (width, height)         */
 
257
    pjmedia_ratio       fps;    /**< Number of frames per second.       */
 
258
    pj_uint32_t         avg_bps;/**< Average bitrate.                   */
 
259
    pj_uint32_t         max_bps;/**< Maximum bitrate.                   */
 
260
} pjmedia_video_format_detail;
 
261
 
 
262
/**
 
263
 * This macro declares the size of the detail section in #pjmedia_format
 
264
 * to be reserved for user defined detail.
 
265
 */
 
266
#ifndef PJMEDIA_FORMAT_DETAIL_USER_SIZE
 
267
#   define PJMEDIA_FORMAT_DETAIL_USER_SIZE              1
 
268
#endif
 
269
 
 
270
/**
 
271
 * This structure contains all the information needed to completely describe
 
272
 * a media.
 
273
 */
 
274
typedef struct pjmedia_format
 
275
{
 
276
    /**
 
277
     * The format id that specifies the audio sample or video pixel format.
 
278
     * Some well known formats ids are declared in pjmedia_format_id
 
279
     * enumeration.
 
280
     *
 
281
     * @see pjmedia_format_id
 
282
     */
 
283
    pj_uint32_t                  id;
 
284
 
 
285
    /**
 
286
     * The top-most type of the media, as an information.
 
287
     */
 
288
    pjmedia_type                 type;
 
289
 
 
290
    /**
 
291
     * The type of detail structure in the \a detail pointer.
 
292
     */
 
293
    pjmedia_format_detail_type   detail_type;
 
294
 
 
295
    /**
 
296
     * Detail section to describe the media.
 
297
     */
 
298
    union
 
299
    {
 
300
        /**
 
301
         * Detail section for audio format.
 
302
         */
 
303
        pjmedia_audio_format_detail     aud;
 
304
 
 
305
        /**
 
306
         * Detail section for video format.
 
307
         */
 
308
        pjmedia_video_format_detail     vid;
 
309
 
 
310
        /**
 
311
         * Reserved area for user-defined format detail.
 
312
         */
 
313
        char                            user[PJMEDIA_FORMAT_DETAIL_USER_SIZE];
 
314
    } det;
 
315
 
 
316
} pjmedia_format;
 
317
 
 
318
/**
 
319
 * This enumeration describes video color model. It mostly serves as
 
320
 * information only.
 
321
 */
 
322
typedef enum pjmedia_color_model
 
323
{
 
324
    /** The color model is unknown or unspecified. */
 
325
    PJMEDIA_COLOR_MODEL_NONE,
 
326
 
 
327
    /** RGB color model. */
 
328
    PJMEDIA_COLOR_MODEL_RGB,
 
329
 
 
330
    /** YUV color model. */
 
331
    PJMEDIA_COLOR_MODEL_YUV
 
332
} pjmedia_color_model;
 
333
 
 
334
/**
 
335
 * This structure holds information to apply a specific video format
 
336
 * against size and buffer information, and get additional information
 
337
 * from it. To do that, application fills up the input fields of this
 
338
 * structure, and give this structure to \a apply_fmt() function
 
339
 * of #pjmedia_video_format_info structure.
 
340
 */
 
341
typedef struct pjmedia_video_apply_fmt_param
 
342
{
 
343
    /* input fields: */
 
344
 
 
345
    /**
 
346
     * [IN] The image size. This field is mandatory, and has to be set
 
347
     * correctly prior to calling \a apply_fmt() function.
 
348
     */
 
349
    pjmedia_rect_size    size;
 
350
 
 
351
    /**
 
352
     * [IN] Pointer to the buffer that holds the frame. The \a apply_fmt()
 
353
     * function uses this pointer to calculate the pointer for each video
 
354
     * planes of the media. This field is optional -- however, the
 
355
     * \a apply_fmt() would still fill up the \a planes[] array with the
 
356
     * correct pointer even though the buffer is set to NULL. This could be
 
357
     * useful to calculate the size (in bytes) of each plane.
 
358
     */
 
359
    pj_uint8_t          *buffer;
 
360
 
 
361
    /* output fields: */
 
362
 
 
363
    /**
 
364
     * [OUT] The size (in bytes) required of the buffer to hold the video
 
365
     * frame of the particular frame size (width, height).
 
366
     */
 
367
    pj_size_t            framebytes;
 
368
 
 
369
    /**
 
370
     * [OUT] Array of strides value (in bytes) for each video plane.
 
371
     */
 
372
    int                  strides[PJMEDIA_MAX_VIDEO_PLANES];
 
373
 
 
374
    /**
 
375
     * [OUT] Array of pointers to each of the video planes. The values are
 
376
     * calculated from the \a buffer field.
 
377
     */
 
378
    pj_uint8_t          *planes[PJMEDIA_MAX_VIDEO_PLANES];
 
379
 
 
380
    /**
 
381
     * [OUT] Array of video plane sizes.
 
382
     */
 
383
    pj_size_t            plane_bytes[PJMEDIA_MAX_VIDEO_PLANES];
 
384
 
 
385
} pjmedia_video_apply_fmt_param;
 
386
 
 
387
/**
 
388
 * This structure holds information to describe a video format. Application
 
389
 * can retrieve this structure by calling #pjmedia_get_video_format_info()
 
390
 * funcion.
 
391
 */
 
392
typedef struct pjmedia_video_format_info
 
393
{
 
394
    /**
 
395
     * The unique format ID of the media. Well known format ids are declared
 
396
     * in pjmedia_format_id enumeration.
 
397
     */
 
398
    pj_uint32_t         id;
 
399
 
 
400
    /**
 
401
     * Null terminated string containing short identification about the
 
402
     * format.
 
403
     */
 
404
    char                name[8];
 
405
 
 
406
    /**
 
407
     * Information about the color model of this video format.
 
408
     */
 
409
    pjmedia_color_model color_model;
 
410
 
 
411
    /**
 
412
     * Number of bits needed to store one pixel of this video format.
 
413
     */
 
414
    pj_uint8_t          bpp;
 
415
 
 
416
    /**
 
417
     * Number of video planes that this format uses. Value 1 indicates
 
418
     * packed format, while value greater than 1 indicates planar format.
 
419
     */
 
420
    pj_uint8_t          plane_cnt;
 
421
 
 
422
    /**
 
423
     * Pointer to function to apply this format against size and buffer
 
424
     * information in pjmedia_video_apply_fmt_param argument. Application
 
425
     * uses this function to obtain various information such as the
 
426
     * memory size of a frame buffer, strides value of the image, the
 
427
     * location of the planes, and so on. See pjmedia_video_apply_fmt_param
 
428
     * for additional information.
 
429
     *
 
430
     * @param vfi       The video format info.
 
431
     * @param vafp      The parameters to investigate.
 
432
     *
 
433
     * @return          PJ_SUCCESS if the function has calculated the
 
434
     *                  information in \a vafp successfully.
 
435
     */
 
436
    pj_status_t (*apply_fmt)(const struct pjmedia_video_format_info *vfi,
 
437
                             pjmedia_video_apply_fmt_param *vafp);
 
438
 
 
439
} pjmedia_video_format_info;
 
440
 
 
441
 
 
442
/*****************************************************************************
 
443
 * UTILITIES:
 
444
 */
 
445
 
 
446
/**
 
447
 * General utility routine to calculate samples per frame value from clock
 
448
 * rate, ptime (in usec), and channel count. Application should use this
 
449
 * macro whenever possible due to possible overflow in the math calculation.
 
450
 *
 
451
 * @param clock_rate            Clock rate.
 
452
 * @param usec_ptime            Frame interval, in microsecond.
 
453
 * @param channel_count         Number of channels.
 
454
 *
 
455
 * @return                      The samples per frame value.
 
456
 */
 
457
PJ_INLINE(unsigned) PJMEDIA_SPF(unsigned clock_rate, unsigned usec_ptime,
 
458
                                unsigned channel_count)
 
459
{
 
460
#if PJ_HAS_INT64
 
461
    return ((unsigned)((pj_uint64_t)usec_ptime * \
 
462
                       clock_rate * channel_count / 1000000));
 
463
#elif PJ_HAS_FLOATING_POINT
 
464
    return ((unsigned)(1.0*usec_ptime * clock_rate * channel_count / 1000000));
 
465
#else
 
466
    return ((unsigned)(usec_ptime / 1000L * clock_rate * \
 
467
                       channel_count / 1000));
 
468
#endif
 
469
}
 
470
 
 
471
/**
 
472
 * Variant of #PJMEDIA_SPF() which takes frame rate instead of ptime.
 
473
 */
 
474
PJ_INLINE(unsigned) PJMEDIA_SPF2(unsigned clock_rate, const pjmedia_ratio *fr,
 
475
                                 unsigned channel_count)
 
476
{
 
477
#if PJ_HAS_INT64
 
478
    return ((unsigned)((pj_uint64_t)clock_rate * fr->denum \
 
479
                       / fr->num / channel_count));
 
480
#elif PJ_HAS_FLOATING_POINT
 
481
    return ((unsigned)(1.0* clock_rate * fr->denum / fr->num /channel_count));
 
482
#else
 
483
    return ((unsigned)(1L * clock_rate * fr->denum / fr->num / channel_count));
 
484
#endif
 
485
}
 
486
 
 
487
 
 
488
/**
 
489
 * Utility routine to calculate frame size (in bytes) from bitrate and frame
 
490
 * interval values. Application should use this macro whenever possible due
 
491
 * to possible overflow in the math calculation.
 
492
 *
 
493
 * @param bps                   The bitrate of the stream.
 
494
 * @param usec_ptime            Frame interval, in microsecond.
 
495
 *
 
496
 * @return                      Frame size in bytes.
 
497
 */
 
498
PJ_INLINE(unsigned) PJMEDIA_FSZ(unsigned bps, unsigned usec_ptime)
 
499
{
 
500
#if PJ_HAS_INT64
 
501
    return ((unsigned)((pj_uint64_t)bps * usec_ptime / PJ_UINT64(8000000)));
 
502
#elif PJ_HAS_FLOATING_POINT
 
503
    return ((unsigned)(1.0 * bps * usec_ptime / 8000000.0));
 
504
#else
 
505
    return ((unsigned)(bps / 8L * usec_ptime / 1000000));
 
506
#endif
 
507
}
 
508
 
 
509
/**
 
510
 * General utility routine to calculate ptime value from frame rate.
 
511
 * Application should use this macro whenever possible due to possible
 
512
 * overflow in the math calculation.
 
513
 *
 
514
 * @param frame_rate            Frame rate
 
515
 *
 
516
 * @return                      The ptime value (in usec).
 
517
 */
 
518
PJ_INLINE(unsigned) PJMEDIA_PTIME(const pjmedia_ratio *frame_rate)
 
519
{
 
520
#if PJ_HAS_INT64
 
521
    return ((unsigned)((pj_uint64_t)1000000 * \
 
522
                       frame_rate->denum / frame_rate->num));
 
523
#elif PJ_HAS_FLOATING_POINT
 
524
    return ((unsigned)(1000000.0 * frame_rate->denum / \
 
525
                       frame_rate->num));
 
526
#else
 
527
    return ((unsigned)((1000L * frame_rate->denum / \
 
528
                       frame_rate->num) * 1000);
 
529
#endif
 
530
}
 
531
 
 
532
/**
 
533
 * Utility to retrieve samples_per_frame value from
 
534
 * pjmedia_audio_format_detail.
 
535
 *
 
536
 * @param pafd          Pointer to pjmedia_audio_format_detail
 
537
 * @return              Samples per frame
 
538
 */
 
539
PJ_INLINE(unsigned) PJMEDIA_AFD_SPF(const pjmedia_audio_format_detail *pafd)
 
540
{
 
541
    return PJMEDIA_SPF(pafd->clock_rate, pafd->frame_time_usec,
 
542
                       pafd->channel_count);
 
543
}
 
544
 
 
545
/**
 
546
 * Utility to retrieve average frame size from pjmedia_audio_format_detail.
 
547
 * The average frame size is derived from the average bitrate of the audio
 
548
 * stream.
 
549
 *
 
550
 * @param afd           Pointer to pjmedia_audio_format_detail
 
551
 * @return              Average frame size.
 
552
 */
 
553
PJ_INLINE(unsigned) PJMEDIA_AFD_AVG_FSZ(const pjmedia_audio_format_detail *afd)
 
554
{
 
555
    return PJMEDIA_FSZ(afd->avg_bps, afd->frame_time_usec);
 
556
}
 
557
 
 
558
/**
 
559
 * Utility to retrieve maximum frame size from pjmedia_audio_format_detail.
 
560
 * The maximum frame size is derived from the maximum bitrate of the audio
 
561
 * stream.
 
562
 *
 
563
 * @param afd           Pointer to pjmedia_audio_format_detail
 
564
 * @return              Average frame size.
 
565
 */
 
566
PJ_INLINE(unsigned) PJMEDIA_AFD_MAX_FSZ(const pjmedia_audio_format_detail *afd)
 
567
{
 
568
    return PJMEDIA_FSZ(afd->max_bps, afd->frame_time_usec);
 
569
}
 
570
 
 
571
 
 
572
/**
 
573
 * Initialize the format as audio format with the specified parameters.
 
574
 *
 
575
 * @param fmt                   The format to be initialized.
 
576
 * @param fmt_id                Format ID. See #pjmedia_format_id
 
577
 * @param clock_rate            Audio clock rate.
 
578
 * @param channel_count         Number of channels.
 
579
 * @param bits_per_sample       Number of bits per sample.
 
580
 * @param frame_time_usec       Frame interval, in microsecond.
 
581
 * @param avg_bps               Average bitrate.
 
582
 * @param max_bps               Maximum bitrate.
 
583
 */
 
584
PJ_DECL(void) pjmedia_format_init_audio(pjmedia_format *fmt,
 
585
                                        pj_uint32_t fmt_id,
 
586
                                        unsigned clock_rate,
 
587
                                        unsigned channel_count,
 
588
                                        unsigned bits_per_sample,
 
589
                                        unsigned frame_time_usec,
 
590
                                        pj_uint32_t avg_bps,
 
591
                                        pj_uint32_t max_bps);
 
592
 
 
593
/**
 
594
 * Initialize the format as video format with the specified parameters.
 
595
 * A format manager should have been created, as this function will need
 
596
 * to consult to a format manager in order to fill in detailed
 
597
 * information about the format.
 
598
 *
 
599
 * @param fmt           The format to be initialised.
 
600
 * @param fmt_id        Format ID. See #pjmedia_format_id
 
601
 * @param width         Image width.
 
602
 * @param height        Image heigth.
 
603
 * @param fps_num       FPS numerator.
 
604
 * @param fps_denum     FPS denumerator.
 
605
 * @param avg_bps       Average bitrate.
 
606
 * @param max_bps       Maximum bitrate.
 
607
 */
 
608
PJ_DECL(void) pjmedia_format_init_video(pjmedia_format *fmt,
 
609
                                        pj_uint32_t fmt_id,
 
610
                                        unsigned width,
 
611
                                        unsigned height,
 
612
                                        unsigned fps_num,
 
613
                                        unsigned fps_denum);
 
614
 
 
615
/**
 
616
 * Copy format to another.
 
617
 *
 
618
 * @param dst           The destination format.
 
619
 * @param src           The source format.
 
620
 *
 
621
 * @return              Pointer to destination format.
 
622
 */
 
623
PJ_DECL(pjmedia_format*) pjmedia_format_copy(pjmedia_format *dst,
 
624
                                             const pjmedia_format *src);
 
625
 
 
626
/**
 
627
 * Check if the format contains audio format, and retrieve the audio format
 
628
 * detail in the format.
 
629
 *
 
630
 * @param fmt           The format structure.
 
631
 * @param assert_valid  If this is set to non-zero, an assertion will be
 
632
 *                      raised if the detail type is not audio or if the
 
633
 *                      the detail is NULL.
 
634
 *
 
635
 * @return              The instance of audio format detail in the format
 
636
 *                      structure, or NULL if the format doesn't contain
 
637
 *                      audio detail.
 
638
 */
 
639
PJ_DECL(pjmedia_audio_format_detail*)
 
640
pjmedia_format_get_audio_format_detail(const pjmedia_format *fmt,
 
641
                                       pj_bool_t assert_valid);
 
642
 
 
643
/**
 
644
 * Check if the format contains video format, and retrieve the video format
 
645
 * detail in the format.
 
646
 *
 
647
 * @param fmt           The format structure.
 
648
 * @param assert_valid  If this is set to non-zero, an assertion will be
 
649
 *                      raised if the detail type is not video or if the
 
650
 *                      the detail is NULL.
 
651
 *
 
652
 * @return              The instance of video format detail in the format
 
653
 *                      structure, or NULL if the format doesn't contain
 
654
 *                      video detail.
 
655
 */
 
656
PJ_DECL(pjmedia_video_format_detail*)
 
657
pjmedia_format_get_video_format_detail(const pjmedia_format *fmt,
 
658
                                       pj_bool_t assert_valid);
 
659
 
 
660
/*****************************************************************************
 
661
 * FORMAT MANAGEMENT:
 
662
 */
 
663
 
 
664
/**
 
665
 * Opaque data type for video format manager. The video format manager manages
 
666
 * the repository of video formats that the framework recognises. Typically it
 
667
 * is a singleton instance, although application may instantiate more than one
 
668
 * instances of this if required.
 
669
 */
 
670
typedef struct pjmedia_video_format_mgr pjmedia_video_format_mgr;
 
671
 
 
672
 
 
673
/**
 
674
 * Create a new video format manager instance. This will also set the pointer
 
675
 * to the singleton instance if the value is still NULL.
 
676
 *
 
677
 * @param pool          The pool to allocate memory.
 
678
 * @param max_fmt       Maximum number of formats to accommodate.
 
679
 * @param options       Option flags. Must be zero for now.
 
680
 * @param p_mgr         Pointer to hold the created instance.
 
681
 *
 
682
 * @return              PJ_SUCCESS on success, or the appripriate error value.
 
683
 */
 
684
PJ_DECL(pj_status_t)
 
685
pjmedia_video_format_mgr_create(pj_pool_t *pool,
 
686
                                unsigned max_fmt,
 
687
                                unsigned options,
 
688
                                pjmedia_video_format_mgr **p_mgr);
 
689
 
 
690
/**
 
691
 * Get the singleton instance of the video format manager.
 
692
 *
 
693
 * @return              The instance.
 
694
 */
 
695
PJ_DECL(pjmedia_video_format_mgr*) pjmedia_video_format_mgr_instance(void);
 
696
 
 
697
/**
 
698
 * Manually assign a specific video manager instance as the singleton
 
699
 * instance. Normally this is not needed if only one instance is ever
 
700
 * going to be created, as the library automatically assign the singleton
 
701
 * instance.
 
702
 *
 
703
 * @param mgr           The instance to be used as the singleton instance.
 
704
 *                      Application may specify NULL to clear the singleton
 
705
 *                      singleton instance.
 
706
 */
 
707
PJ_DECL(void)
 
708
pjmedia_video_format_mgr_set_instance(pjmedia_video_format_mgr *mgr);
 
709
 
 
710
/**
 
711
 * Retrieve a video format info for the specified format id.
 
712
 *
 
713
 * @param mgr           The video format manager. Specify NULL to use
 
714
 *                      the singleton instance (however, a video format
 
715
 *                      manager still must have been created prior to
 
716
 *                      calling this function).
 
717
 * @param id            The format id which format info is to be
 
718
 *                      retrieved.
 
719
 *
 
720
 * @return              The video format info.
 
721
 */
 
722
PJ_DECL(const pjmedia_video_format_info*)
 
723
pjmedia_get_video_format_info(pjmedia_video_format_mgr *mgr,
 
724
                              pj_uint32_t id);
 
725
 
 
726
/**
 
727
 * Register a new video format to the framework. By default, built-in
 
728
 * formats will be registered automatically to the format manager when
 
729
 * it is created (note: built-in formats are ones which format id is
 
730
 * listed in pjmedia_format_id enumeration). This function allows
 
731
 * application to use user defined format id by registering that format
 
732
 * into the framework.
 
733
 *
 
734
 * @param mgr           The video format manager. Specify NULL to use
 
735
 *                      the singleton instance (however, a video format
 
736
 *                      manager still must have been created prior to
 
737
 *                      calling this function).
 
738
 * @param vfi           The video format info to be registered. This
 
739
 *                      structure must remain valid until the format
 
740
 *                      manager is destroyed.
 
741
 *
 
742
 * @return              PJ_SUCCESS on success, or the appripriate error value.
 
743
 */
 
744
PJ_DECL(pj_status_t)
 
745
pjmedia_register_video_format_info(pjmedia_video_format_mgr *mgr,
 
746
                                   pjmedia_video_format_info *vfi);
 
747
 
 
748
/**
 
749
 * Destroy a video format manager. If the manager happens to be the singleton
 
750
 * instance, the singleton instance will be set to NULL.
 
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
 */
 
757
PJ_DECL(void) pjmedia_video_format_mgr_destroy(pjmedia_video_format_mgr *mgr);
 
758
 
 
759
PJ_END_DECL
 
760
 
 
761
/**
 
762
 * @}
 
763
 */
 
764
 
 
765
#endif  /* __PJMEDIA_FORMAT_H__ */