Alexandre Lision | 8af73cb | 2013-12-10 14:11:20 -0500 | [diff] [blame] | 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: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__ */ |
| 766 | |