Changes between Version 5 and Version 6 of RelNotes-2.0_GDS


Ignore:
Timestamp:
May 22, 2012 7:23:35 AM (12 years ago)
Author:
nanang
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • RelNotes-2.0_GDS

    v5 v6  
    22 
    33==== Media Format ==== 
    4  - [http://www.pjsip.org/docs/latest/pjmedia/docs/html/structpjmedia__format.htm pjmedia_format] — Defined as all information needed to completely describe a media, which containing: 
    5    - Format ID — Specifies the audio sample or video pixel format. Enumeration of some well known formats IDs is defined in [http://www.pjsip.org/docs/latest/pjmedia/docs/html/group__PJMEDIA__FORMAT.htm#ga7a0830cb291693cabb364a3403777bda pjmedia_format_id]. 
     4Containing all information needed to completely describe a media. 
     5 - '''Changed''': [http://www.pjsip.org/docs/latest-2/pjmedia/docs/html/structpjmedia__format.htm pjmedia_format] — it is now virtually desribing any media types (in 1.x it was containing extended info for audio format). Here are the core contents: 
     6   - Format ID — Specifies the audio sample or video pixel format. Enumeration of some well known formats IDs is defined in [http://www.pjsip.org/docs/latest-2/pjmedia/docs/html/group__PJMEDIA__FORMAT.htm#ga7a0830cb291693cabb364a3403777bda pjmedia_format_id]. 
    67   - Media type — The top-most type of the media, as an information. 
    7    - Format detail — Detail section to describe the media. As the details are different among media types, this field is declared as union and [http://www.pjsip.org/docs/latest/pjmedia/docs/html/group__PJMEDIA__FORMAT.htm#ga3272e8f9dc6d369dc9fe5dcb67408fc5 pjmedia_format_detail_type] is introduced to recognize the content. Currently there are two predefined structures: 
    8      - [http://www.pjsip.org/docs/latest/pjmedia/docs/html/structpjmedia__audio__format__detail.htm pjmedia_audio_format_detail] for audio format detail 
    9      - [http://www.pjsip.org/docs/latest/pjmedia/docs/html/structpjmedia__video__format__detail.htm pjmedia_video_format_detail] for video format detail. 
     8   - Format detail — Detail section to describe the media. As the details are different among media types, this field is declared as union and [http://www.pjsip.org/docs/latest-2/pjmedia/docs/html/group__PJMEDIA__FORMAT.htm#ga3272e8f9dc6d369dc9fe5dcb67408fc5 pjmedia_format_detail_type] is introduced to recognize the content. Currently there are two predefined structures: 
     9     - [http://www.pjsip.org/docs/latest-2/pjmedia/docs/html/structpjmedia__audio__format__detail.htm pjmedia_audio_format_detail] for audio format detail 
     10     - [http://www.pjsip.org/docs/latest-2/pjmedia/docs/html/structpjmedia__video__format__detail.htm pjmedia_video_format_detail] for video format detail. 
    1011 
    11  - Video format helper: 
    12    - [http://www.pjsip.org/docs/latest/pjmedia/docs/html/structpjmedia__video__format__info.htm pjmedia_video_format_info] — Information to describe a raw video format, such as RGB/YUV color model, number of bits per pixel, planar/packed data representation, and pointer to function to get ''real-time'' information of a raw video format (such as buffer size needed for a picture, byte size of a picture line, pointer and buffer size of each plane). 
    13    - [http://www.pjsip.org/docs/latest/pjmedia/docs/html/structpjmedia__video__apply__fmt__param.htm pjmedia_video_apply_fmt_param] — Information to apply a raw video format against size and buffer information, and get additional information from it. To do that, application fills up the input fields of this structure, and give this structure to {{{apply_fmt()}}} function of {{{pjmedia_video_format_info}}} structure. 
     12 - '''New''': Video format helper: 
     13   - [http://www.pjsip.org/docs/latest-2/pjmedia/docs/html/structpjmedia__video__format__info.htm pjmedia_video_format_info] — Information to describe a raw video format, such as RGB/YUV color model, number of bits per pixel, planar/packed data representation, and pointer to function to get ''real-time'' information of a raw video format (such as buffer size needed for a picture, byte size of a picture line, pointer and buffer size of each plane). 
     14   - [http://www.pjsip.org/docs/latest-2/pjmedia/docs/html/structpjmedia__video__apply__fmt__param.htm pjmedia_video_apply_fmt_param] — Information to apply a raw video format against size and buffer information, and get additional information from it. To do that, application fills up the input fields of this structure, and give this structure to {{{apply_fmt()}}} function of {{{pjmedia_video_format_info}}} structure. 
    1415 
    15  
    16 {{{ 
    17 /** 
    18  * This structure contains all the information needed to completely describe 
    19  * a media. 
    20  */ 
    21 typedef struct pjmedia_format 
    22 { 
    23     /** 
    24      * The format id that specifies the audio sample or video pixel format. 
    25      * Some well known formats ids are declared in pjmedia_format_id 
    26      * enumeration. 
    27      * 
    28      * @see pjmedia_format_id 
    29      */ 
    30     pj_uint32_t                  id; 
    31  
    32     /** 
    33      * The top-most type of the media, as an information. 
    34      */ 
    35     pjmedia_type                 type; 
    36  
    37     /** 
    38      * The type of detail structure in the \a detail pointer. 
    39      */ 
    40     pjmedia_format_detail_type   detail_type; 
    41  
    42     /** 
    43      * Detail section to describe the media. 
    44      */ 
    45     union 
    46     { 
    47         /** 
    48          * Detail section for audio format. 
    49          */ 
    50         pjmedia_audio_format_detail     aud; 
    51  
    52         /** 
    53          * Detail section for video format. 
    54          */ 
    55         pjmedia_video_format_detail     vid; 
    56  
    57         /** 
    58          * Reserved area for user-defined format detail. 
    59          */ 
    60         char                            user[PJMEDIA_FORMAT_DETAIL_USER_SIZE]; 
    61     } det; 
    62  
    63 } pjmedia_format; 
    64 }}} 
    65  
    66 Media format ID: 
    67 {{{ 
    68 /** 
    69  * This enumeration uniquely identify audio sample and/or video pixel formats. 
    70  * Some well known formats are listed here. The format ids are built by 
    71  * combining four character codes, similar to FOURCC. The format id is 
    72  * extensible, as application may define and use format ids not declared 
    73  * on this enumeration. 
    74  * 
    75  * This format id along with other information will fully describe the media 
    76  * in #pjmedia_format structure. 
    77  */ 
    78 typedef enum pjmedia_format_id 
    79 { 
    80     /* 
    81      * Audio formats 
    82      */ 
    83  
    84     /** 16bit signed integer linear PCM audio */ 
    85     PJMEDIA_FORMAT_L16      = 0, 
    86  
    87     /** Alias for PJMEDIA_FORMAT_L16 */ 
    88     PJMEDIA_FORMAT_PCM      = PJMEDIA_FORMAT_L16, 
    89  
    90     /** G.711 ALAW */ 
    91     PJMEDIA_FORMAT_PCMA     = PJMEDIA_FORMAT_PACK('A', 'L', 'A', 'W'), 
    92     ... 
    93  
    94     /* 
    95      * Video formats. 
    96      */ 
    97     /** 
    98      * 24bit RGB 
    99      */ 
    100     PJMEDIA_FORMAT_RGB24    = PJMEDIA_FORMAT_PACK('R', 'G', 'B', '3'), 
    101  
    102     /** 
    103      * 32bit RGB with alpha channel 
    104      */ 
    105     PJMEDIA_FORMAT_RGBA     = PJMEDIA_FORMAT_PACK('R', 'G', 'B', 'A'), 
    106     PJMEDIA_FORMAT_BGRA     = PJMEDIA_FORMAT_PACK('B', 'G', 'R', 'A'), 
    107     ... 
    108  
    109     /** 
    110      * Encoded video formats 
    111      */ 
    112  
    113     PJMEDIA_FORMAT_H261     = PJMEDIA_FORMAT_PACK('H', '2', '6', '1'), 
    114     PJMEDIA_FORMAT_H263     = PJMEDIA_FORMAT_PACK('H', '2', '6', '3'), 
    115     PJMEDIA_FORMAT_H263P    = PJMEDIA_FORMAT_PACK('P', '2', '6', '3'), 
    116     PJMEDIA_FORMAT_H264     = PJMEDIA_FORMAT_PACK('H', '2', '6', '4'), 
    117     ... 
    118  
    119 } pjmedia_format_id; 
    120 }}} 
    121  
    122 Format detail types: 
    123 {{{ 
    124 /** 
    125  * This enumeration specifies what type of detail is included in a 
    126  * #pjmedia_format structure. 
    127  */ 
    128 typedef enum pjmedia_format_detail_type 
    129 { 
    130     /** Format detail is not specified. */ 
    131     PJMEDIA_FORMAT_DETAIL_NONE, 
    132  
    133     /** Audio format detail. */ 
    134     PJMEDIA_FORMAT_DETAIL_AUDIO, 
    135  
    136     /** Video format detail. */ 
    137     PJMEDIA_FORMAT_DETAIL_VIDEO, 
    138  
    139     /** Number of format detail type that has been defined. */ 
    140     PJMEDIA_FORMAT_DETAIL_MAX 
    141  
    142 } pjmedia_format_detail_type; 
    143 }}} 
    144  
    145 Audio format detail: 
    146 {{{ 
    147 /** 
    148  * This structure is put in \a detail field of #pjmedia_format to describe 
    149  * detail information about an audio media. 
    150  */ 
    151 typedef struct pjmedia_audio_format_detail 
    152 { 
    153     unsigned    clock_rate;     /**< Audio clock rate in samples or Hz. */ 
    154     unsigned    channel_count;  /**< Number of channels.                */ 
    155     unsigned    frame_time_usec;/**< Frame interval, in microseconds.   */ 
    156     unsigned    bits_per_sample;/**< Number of bits per sample.         */ 
    157     pj_uint32_t avg_bps;        /**< Average bitrate                    */ 
    158     pj_uint32_t max_bps;        /**< Maximum bitrate                    */ 
    159 } pjmedia_audio_format_detail; 
    160 }}} 
    161  
    162 Video format detail: 
    163 {{{ 
    164 /** 
    165  * This structure is put in \a detail field of #pjmedia_format to describe 
    166  * detail information about a video media. 
    167  * 
    168  * Additional information about a video format can also be retrieved by 
    169  * calling #pjmedia_get_video_format_info(). 
    170  */ 
    171 typedef struct pjmedia_video_format_detail 
    172 { 
    173     pjmedia_rect_size   size;   /**< Video size (width, height)         */ 
    174     pjmedia_ratio       fps;    /**< Number of frames per second.       */ 
    175     pj_uint32_t         avg_bps;/**< Average bitrate.                   */ 
    176     pj_uint32_t         max_bps;/**< Maximum bitrate.                   */ 
    177 } pjmedia_video_format_detail; 
    178 }}} 
    179  
     16Check the media format documentation [http://www.pjsip.org/docs/latest-2/pjmedia/docs/html/group__PJMEDIA__FORMAT.htm here] for details. 
    18017 
    18118==== Missing samples_per_frame ==== 
    18219 
    183 Use PJMEDIA_AFD_SAMPLES_PER_FRAME(afd) 
     20 - '''Removed''': {{{samples_per_frame}}}, which was used in many PJMEDIA components and functions. Generally, application can now use {{{PJMEDIA_AFD_SAMPLES_PER_FRAME(audio-format-detail)}}} to get the same result. 
    18421 
    18522==== Port info ==== 
    18623 
    187 Media format description fields have been replaced by {{{pjmedia_format}}}: 
    188 {{{ 
    189 /** 
    190  * Port info. 
    191  */ 
    192 typedef struct pjmedia_port_info 
    193 { 
    194     pj_str_t        name;               /**< Port name.                     */ 
    195     pj_uint32_t     signature;          /**< Port signature.                */ 
    196     pjmedia_dir     dir;                /**< Port direction.                */ 
    197     pjmedia_format  fmt;                /**< Format.                        */ 
    198 } pjmedia_port_info; 
    199 }}} 
     24 - '''Changed''': All fields in the port info that desribe the media format have been removed and replaced by {{{pjmedia_format}}}. Check the port info documentation [http://www.pjsip.org/docs/latest-2/pjmedia/docs/html/structpjmedia__port__info.htm here] for details. 
    20025 
    20126==== put_frame() callback of pjmedia_port ==== 
    20227 
    203 Removed const qualifier from the frame argument. 
    204  
    205 Sample warnings: 
     28 - '''Changed''': Removed const qualifier from the frame argument, this is to accomodate ''in-place'' media processing by PJMEDIA port. 
     29 - Sample warnings in building application after upgrading from 1.x to 2.0: 
    20630{{{ 
    20731../src/pjmedia/bidirectional.c: In function ‘put_frame’: 
    … …  
    21337==== pjsua_call_info ==== 
    21438 
    215 As now call can have multiple media streams, e.g: M audio streams and N video streams, {{{pjsua_call_info}}} also has array of media info: 
    216 {{{ 
    217 /** 
    218  * This structure describes the information and current status of a call. 
    219  */ 
    220 typedef struct pjsua_call_info 
    221 { 
    222     /** Call identification. */ 
    223     pjsua_call_id       id; 
     39 - '''Changed''': As now call can have multiple media streams, e.g: M audio streams and N video streams, {{{pjsua_call_info}}} also has array of media info. Check the call info documentation [http://www.pjsip.org/docs/latest-2/pjsip/docs/html/structpjsua__call__info.htm here] for details. 
    22440 
    225     ... 
    226  
    227     /** Array of media stream information */ 
    228     struct 
    229     { 
    230         /** Media index in SDP. */ 
    231         unsigned                index; 
    232  
    233         /** Media type. */ 
    234         pjmedia_type            type; 
    235  
    236         /** Media direction. */ 
    237         pjmedia_dir             dir; 
    238  
    239         /** Call media status. */ 
    240         pjsua_call_media_status status; 
    241  
    242         /** The specific media stream info. */ 
    243         union { 
    244             /** Audio stream */ 
    245             struct { 
    246                 /** The conference port number for the call.  */ 
    247                 pjsua_conf_port_id   conf_slot; 
    248             } aud; 
    249  
    250             /** Video stream */ 
    251             struct { 
    252                 /** 
    253                  * The window id for incoming video, if any, or 
    254                  * PJSUA_INVALID_ID. 
    255                  */ 
    256                 pjsua_vid_win_id     win_in; 
    257  
    258                 /** The video capture device for outgoing transmission, 
    259                  *  if any, or PJMEDIA_VID_INVALID_DEV 
    260                  */ 
    261                 pjmedia_vid_dev_index   cap_dev; 
    262  
    263             } vid; 
    264         } stream; 
    265  
    266     } media[PJMEDIA_MAX_SDP_MEDIA]; 
    267  
    268     ... 
    269  
    270 } pjsua_call_info; 
    271  
    272 }}}