Ignore:
Timestamp:
Feb 24, 2011 7:47:55 AM (13 years ago)
Author:
nanang
Message:

Re #1182:

  • Added video stream interface in vid_stream.h, the video stream will be able to handle different video formats in encoding and decoding direction.
  • Renamed video device stream class identifiers from 'pjmedia_vid_stream*' to 'pjmedia_vid_dev_stream*' as 'pjmedia_vid_stream' is used by video stream interface.
  • Added ffmpeg video capability to be able to parse SDP format param for H263 and also decide video format for encoding direction based on remote preference and local format-capability setting.
  • Added some new APIs in jitter buffer for handling video stream: pjmedia_jbuf_put_frame3(), pjmedia_jbuf_get_frame3(), pjmedia_jbuf_peek_frame(), and pjmedia_jbuf_remove_frame().
  • Moved pjmedia_stream_info_from_sdp() from session to stream
File:
1 edited

Legend:

Unmodified
Added
Removed

  • pjproject/branches/projects/2.0-dev/pjmedia/include/pjmedia/vid_codec.h

    r3392 r3420  
    2323 
    2424/** 
    25  * @file codec.h 
    26  * @brief Codec framework. 
     25 * @file vid_codec.h 
     26 * @brief Video codec framework. 
    2727 */ 
    2828 
    … …  
    4646    pjmedia_format_id   fmt_id;         /**< Encoded format ID              */ 
    4747    pj_str_t            encoding_name;  /**< Encoding name                  */ 
     48    unsigned            pt;             /**< Payload type (may be 255 for 
     49                                             dynamic payload type)          */ 
     50    unsigned            clock_rate;     /**< Clock rate                     */ 
    4851    pjmedia_dir         dir;            /**< Direction                      */ 
    49     unsigned            pt;             /**< Payload type (may be 0 for 
    50                                              dynamic payload type)          */ 
    51     unsigned            clock_rate;     /**< (?) Clock rate                 */ 
    52     unsigned            dec_fmt_id_cnt; 
     52    unsigned            dec_fmt_id_cnt; /**< # of supported encoding source  
     53                                             format IDs                     */ 
    5354    pjmedia_format_id   dec_fmt_id[PJMEDIA_VID_CODEC_MAX_DEC_FMT_CNT]; 
    5455                                        /**< Supported encoding source  
    5556                                             format IDs                     */ 
    56     unsigned            fps_cnt;        /**< zero if support any fps        */ 
    57     pjmedia_ratio       fps[PJMEDIA_VID_CODEC_MAX_FPS_CNT];     
    58                                         /**< (?) supported FPSes,  
    59                                              ffmpeg has this                */ 
     57    unsigned            fps_cnt;        /**< # of supported frame-rates, can be 
     58                                             zero (support any frame-rate)  */ 
     59    pjmedia_ratio       fps[PJMEDIA_VID_CODEC_MAX_FPS_CNT]; 
     60                                        /**< Supported frame-rates          */ 
    6061} pjmedia_vid_codec_info; 
     62 
    6163 
    6264/**  
    … …  
    8082 
    8183    unsigned            enc_mtu;        /**< MTU or max payload size setting*/ 
    82     unsigned            pt;             /**< Payload type.                  */ 
    8384} pjmedia_vid_codec_param; 
    8485 
    8586 
    86  
    87 /* 
    88  * Forward declaration for pjmedia_vid_codec. 
     87/** 
     88 * Enumeration of video codec events. 
     89 */ 
     90typedef enum pjmedia_vid_codec_event 
     91{ 
     92    /** 
     93     * Format changed event. The decoder output format is not really 
     94     * configurable, so that the output format setting configured in the 
     95     * initialization may be changed. Application can catch this event 
     96     * by checking the bit_info field of the pjmedia_frame of the decoder 
     97     * output frame. 
     98     */ 
     99    PJMEDIA_VID_CODEC_EVENT_FMT_CHANGED = 1, 
     100 
     101} pjmedia_vid_codec_event; 
     102 
     103 
     104/** 
     105 * Forward declaration for video codec. 
    89106 */ 
    90107typedef struct pjmedia_vid_codec pjmedia_vid_codec; 
    … …  
    112129     * Open the codec and initialize with the specified parameter. 
    113130     * Upon successful initialization, the codec may modify the parameter 
    114      * and fills in the unspecified values (such as enc_ptime, when 
    115      * encoder ptime is different than decoder ptime). 
     131     * and fills in the unspecified values (such as size or frame rate of 
     132     * the encoder format, as it may need to be negotiated with remote 
     133     * preferences via SDP fmtp). 
    116134     * 
    117135     * @param codec     The codec instance. 
    … …  
    139157     * non-PJ_SUCCESS, and the original parameters will not be changed. 
    140158     * 
    141      * Application can expect changing trivial codec settings such as 
    142      * changing VAD setting to succeed. 
    143      * 
    144159     * @param codec     The codec instance. 
    145160     * @param param     The new codec parameter. 
    … …  
    148163     */ 
    149164    pj_status_t (*modify)(pjmedia_vid_codec *codec,  
    150                           const pjmedia_vid_codec_param *param ); 
     165                          const pjmedia_vid_codec_param *param); 
     166 
     167    /**  
     168     * Get the codec parameter after the codec is opened.  
     169     * 
     170     * @param codec     The codec instance. 
     171     * @param param     The codec parameter. 
     172     * 
     173     * @return          PJ_SUCCESS on success. 
     174     */ 
     175    pj_status_t (*get_param)(pjmedia_vid_codec *codec, 
     176                             pjmedia_vid_codec_param *param); 
    151177 
    152178    /** 
    153      * Instruct the codec to inspect the specified payload/packet and 
    154      * split the packet into individual base frames. Each output frames will 
    155      * have ptime that is equal to basic frame ptime (i.e. the value of 
    156      * info.frm_ptime in #pjmedia_vid_codec_param). 
     179     * Instruct the codec to generate a payload/packet from a picture 
     180     * bitstream to be sent (via network). The maximum payload size or 
     181     * MTU is configurable via enc_mtu field of #pjmedia_vid_codec_param. 
     182     * For a long bitstream, application usually need to call this function 
     183     * multiple times until the whole bitstream is sent. Note that, for 
     184     * performance reason, the packetization will be done in-place, so the 
     185     * original bitstream may be modified by this function. 
     186     * 
     187     * @param codec     The codec instance 
     188     * @param bits      The picture bitstream. 
     189     * @param bits_len  The length of the bitstream. 
     190     * @param bits_pos  On input, the start position of the bitstream 
     191     *                  to be packetized. On output, the next position for 
     192     *                  next packet. 
     193     * @param pkt       The pointer of the generated payload. 
     194     * @param pkt_len   The payload length. 
     195     * 
     196     * @return          PJ_SUCCESS on success. 
     197     */ 
     198    pj_status_t (*packetize) (pjmedia_vid_codec *codec, 
     199                              pj_uint8_t *bits, 
     200                              pj_size_t bits_len, 
     201                              unsigned *bits_pos, 
     202                              const pj_uint8_t **pkt, 
     203                              pj_size_t *pkt_len); 
     204 
     205    /** 
     206     * Instruct the codec to parse a payload and append it into a picture 
     207     * bitstream. A picture bitstreams may need to be reconstructed from 
     208     * one or more payloads. Note that this function will not provide the 
     209     * detection of picture boundary, so application should manage the 
     210     * picture boundary detection by itself, e.g: for RTP delivery, payloads 
     211     * belong to the same picture will share the same RTP timestamp and also 
     212     * there is marker bit in the RTP header that is usually reserved for 
     213     * end-of-picture flag. 
    157214     * 
    158215     * @param codec     The codec instance 
    … …  
    168225     * @return          PJ_SUCCESS on success. 
    169226     */ 
    170     pj_status_t (*packetize) (pjmedia_vid_codec *codec, 
    171                               pj_uint8_t *buf, 
    172                               pj_size_t buf_len, 
    173                               unsigned *pos, 
    174                               const pj_uint8_t **payload, 
    175                               pj_size_t *payload_len); 
    176  
    177     /** 
    178      * Instruct the codec to inspect the specified payload/packet and 
    179      * split the packet into individual base frames. Each output frames will 
    180      * have ptime that is equal to basic frame ptime (i.e. the value of 
    181      * info.frm_ptime in #pjmedia_vid_codec_param). 
    182      * 
    183      * @param codec     The codec instance 
    184      * @param pkt       The input packet. 
    185      * @param pkt_size  Size of the packet. 
    186      * @param timestamp The timestamp of the first sample in the packet. 
    187      * @param frame_cnt On input, specifies the maximum number of frames 
    188      *                  in the array. On output, the codec must fill 
    189      *                  with number of frames detected in the packet. 
    190      * @param frames    On output, specifies the frames that have been 
    191      *                  detected in the packet. 
    192      * 
    193      * @return          PJ_SUCCESS on success. 
    194      */ 
    195227    pj_status_t (*unpacketize)(pjmedia_vid_codec *codec, 
    196228                               const pj_uint8_t *payload, 
    197229                               pj_size_t   payload_len, 
    198                                pj_uint8_t *buf, 
    199                                pj_size_t  *buf_len); 
     230                               pj_uint8_t *bits, 
     231                               pj_size_t  *bits_len); 
    200232 
    201233    /**  
    202234     * Instruct the codec to encode the specified input frame. The input 
    203      * PCM samples MUST have ptime that is multiplication of base frame 
    204      * ptime (i.e. the value of info.frm_ptime in #pjmedia_vid_codec_param). 
     235     * MUST contain only one picture with appropriate format as specified 
     236     * in opening the codec. 
    205237     * 
    206238     * @param codec     The codec instance. 
    … …  
    218250    /**  
    219251     * Instruct the codec to decode the specified input frame. The input 
    220      * frame MUST have ptime that is exactly equal to base frame 
    221      * ptime (i.e. the value of info.frm_ptime in #pjmedia_vid_codec_param). 
    222      * Application can achieve this by parsing the packet into base 
    223      * frames before decoding each frame. 
     252     * frame MUST contain exactly one picture. Note that the decoded picture 
     253     * format may different to the current setting, e.g: the format specified 
     254     * in the #pjmedia_vid_codec_param when opening the codec, in this case the 
     255     * PJMEDIA_VID_CODEC_EVENT_FMT_CHANGED flag will be set in the bit_info 
     256     * field of the output frame and application can query the new format 
     257     * using #get_param(). 
    224258     * 
    225259     * @param codec     The codec instance. 
    … …  
    248282                           unsigned out_size, 
    249283                           pjmedia_frame *output); 
     284 
    250285} pjmedia_vid_codec_op; 
    251286 
    … …  
    259294 
    260295/** 
    261  * This structure describes a codec instance.  
     296 * This structure describes a video codec instance.  
    262297 */ 
    263298struct pjmedia_vid_codec 
    … …  
    267302 
    268303    /** Codec's private data. */ 
    269     void                    *codec_data; 
     304    void                        *codec_data; 
    270305 
    271306    /** Codec factory where this codec was allocated. */ 
    … …  
    273308 
    274309    /** Operations to codec. */ 
    275     pjmedia_vid_codec_op            *op; 
     310    pjmedia_vid_codec_op        *op; 
    276311}; 
    277312 
    … …  
    377412 
    378413/** 
     414 * Opaque declaration for codec manager. 
     415 */ 
     416typedef struct pjmedia_vid_codec_mgr pjmedia_vid_codec_mgr; 
     417 
     418/** 
    379419 * Declare maximum codecs 
    380420 */ 
    … …  
    382422 
    383423 
    384 /**  
    385  * Codec manager maintains array of these structs for each supported 
    386  * codec. 
    387  */ 
    388 typedef struct pjmedia_vid_codec_desc 
    389 { 
    390     pjmedia_vid_codec_info           info;      /**< Codec info.            */ 
    391     pjmedia_codec_id                 id;        /**< Fully qualified name   */ 
    392     pjmedia_codec_priority           prio;      /**< Priority.              */ 
    393     pjmedia_vid_codec_factory       *factory;   /**< The factory.           */ 
    394     pjmedia_vid_codec_param         *def_param; /**< Default codecs  
    395                                                      parameters.            */ 
    396 } pjmedia_vid_codec_desc; 
    397  
    398  
    399 /** 
    400  * The declaration for codec manager. Application doesn't normally need 
    401  * to see this declaration, but nevertheless this declaration is needed 
    402  * by media endpoint to instantiate the codec manager. 
    403  */ 
    404 typedef struct pjmedia_vid_codec_mgr 
    405 { 
    406     /** Codec manager mutex. */ 
    407     pj_mutex_t                  *mutex; 
    408  
    409     /** List of codec factories registered to codec manager. */ 
    410     pjmedia_vid_codec_factory    factory_list; 
    411  
    412     /** Number of supported codecs. */ 
    413     unsigned                     codec_cnt; 
    414  
    415     /** Array of codec descriptor. */ 
    416     pjmedia_vid_codec_desc       codec_desc[PJMEDIA_CODEC_MGR_MAX_CODECS]; 
    417  
    418 } pjmedia_vid_codec_mgr; 
    419  
    420  
    421  
    422 /** 
    423  * Initialize codec manager. Normally this function is called by pjmedia 
     424 
     425/** 
     426 * Initialize codec manager. If there is no the default video codec manager, 
     427 * this function will automatically set the default video codec manager to 
     428 * the new codec manager instance. Normally this function is called by pjmedia 
    424429 * endpoint's initialization code. 
    425430 * 
    426  * @param mgr       Codec manager instance. 
    427  * @param pf        Pool factory instance. 
     431 * @param pool      The pool instance. 
     432 * @param mgr       The pointer to the new codec manager instance. 
    428433 * 
    429434 * @return          PJ_SUCCESS on success. 
    … …  
    437442 * endpoint's deinitialization code. 
    438443 * 
    439  * @param mgr       Codec manager instance. 
     444 * @param mgr       Codec manager instance.  If NULL, it is the default codec 
     445 *                  manager instance will be destroyed. 
    440446 * 
    441447 * @return          PJ_SUCCESS on success. 
    … …  
    443449PJ_DECL(pj_status_t) pjmedia_vid_codec_mgr_destroy(pjmedia_vid_codec_mgr *mgr); 
    444450 
     451 
     452/** 
     453 * Get the default codec manager instance. 
     454 * 
     455 * @return          The default codec manager instance or NULL if none. 
     456 */ 
    445457PJ_DECL(pjmedia_vid_codec_mgr*) pjmedia_vid_codec_mgr_instance(void); 
     458 
     459 
     460/** 
     461 * Set the default codec manager instance. 
     462 * 
     463 * @param mgr       The codec manager instance. 
     464 */ 
    446465PJ_DECL(void) pjmedia_vid_codec_mgr_set_instance(pjmedia_vid_codec_mgr* mgr); 
    447466 
    … …  
    451470 * all supported codecs in the factory to the codec manager. 
    452471 * 
    453  * @param mgr       The codec manager instance. Application can get the 
    454  *                  instance by calling #pjmedia_endpt_get_codec_mgr(). 
     472 * @param mgr       The codec manager instance. If NULL, the default codec 
     473 *                  manager instance will be used. 
    455474 * @param factory   The codec factory to be registered. 
    456475 * 
    … …  
    466485 * codec manager's list of supported codecs. 
    467486 * 
    468  * @param mgr       The codec manager instance. Application can get the 
    469  *                  instance by calling #pjmedia_endpt_get_codec_mgr(). 
     487 * @param mgr       The codec manager instance. If NULL, the default codec 
     488 *                  manager instance will be used. 
    470489 * @param factory   The codec factory to be unregistered. 
    471490 * 
    … …  
    480499 * codec manager by codec factories. 
    481500 * 
    482  * @param mgr       The codec manager instance. Application can get the 
    483  *                  instance by calling #pjmedia_endpt_get_codec_mgr(). 
     501 * @param mgr       The codec manager instance. If NULL, the default codec 
     502 *                  manager instance will be used. 
    484503 * @param count     On input, specifies the number of elements in 
    485504 *                  the array. On output, the value will be set to 
    … …  
    501520 * Get codec info for the specified static payload type. 
    502521 * 
    503  * @param mgr       The codec manager instance. Application can get the 
    504  *                  instance by calling #pjmedia_endpt_get_codec_mgr(). 
     522 * @param mgr       The codec manager instance. If NULL, the default codec 
     523 *                  manager instance will be used. 
    505524 * @param pt        Static payload type/number. 
    506  * @param inf       Pointer to receive codec info. 
     525 * @param info      Pointer to receive codec info. 
    507526 * 
    508527 * @return          PJ_SUCCESS on success. 
    … …  
    511530pjmedia_vid_codec_mgr_get_codec_info( pjmedia_vid_codec_mgr *mgr, 
    512531                                      unsigned pt, 
    513                                       const pjmedia_vid_codec_info **inf); 
     532                                      const pjmedia_vid_codec_info **info); 
    514533 
    515534/** 
    516535 * Convert codec info struct into a unique codec identifier. 
    517  * A codec identifier looks something like "L16/44100/2". 
     536 * A codec identifier looks something like "H263/90000". 
    518537 * 
    519538 * @param info      The codec info 
    … …  
    532551 * Find codecs by the unique codec identifier. This function will find 
    533552 * all codecs that match the codec identifier prefix. For example, if 
    534  * "L16" is specified, then it will find "L16/8000/1", "L16/16000/1", 
     553 * "H26" is specified, then it will find "H263/90000", "H264/90000", 
    535554 * and so on, up to the maximum count specified in the argument. 
    536555 * 
    537  * @param mgr       The codec manager instance. Application can get the 
    538  *                  instance by calling #pjmedia_endpt_get_codec_mgr(). 
     556 * @param mgr       The codec manager instance. If NULL, the default codec 
     557 *                  manager instance will be used. 
    539558 * @param codec_id  The full codec ID or codec ID prefix. If an empty 
    540559 *                  string is given, it will match all codecs. 
    … …  
    549568 */ 
    550569PJ_DECL(pj_status_t)  
    551 pjmedia_vid_codec_mgr_find_codecs_by_id( pjmedia_vid_codec_mgr *mgr, 
    552                                      const pj_str_t *codec_id, 
    553                                      unsigned *count, 
    554                                      const pjmedia_vid_codec_info *p_info[], 
    555                                      unsigned prio[]); 
     570pjmedia_vid_codec_mgr_find_codecs_by_id(pjmedia_vid_codec_mgr *mgr, 
     571                                        const pj_str_t *codec_id, 
     572                                        unsigned *count, 
     573                                        const pjmedia_vid_codec_info *p_info[], 
     574                                        unsigned prio[]); 
    556575 
    557576 
    … …  
    562581 * priorities of all those codecs. 
    563582 * 
    564  * @param mgr       The codec manager instance. Application can get the 
    565  *                  instance by calling #pjmedia_endpt_get_codec_mgr(). 
     583 * @param mgr       The codec manager instance. If NULL, the default codec 
     584 *                  manager instance will be used. 
    566585 * @param codec_id  The full codec ID or codec ID prefix. If an empty 
    567586 *                  string is given, it will match all codecs. 
    … …  
    574593PJ_DECL(pj_status_t) 
    575594pjmedia_vid_codec_mgr_set_codec_priority(pjmedia_vid_codec_mgr *mgr,  
    576                                     const pj_str_t *codec_id, 
    577                                     pj_uint8_t prio); 
     595                                        const pj_str_t *codec_id, 
     596                                        pj_uint8_t prio); 
    578597 
    579598 
    … …  
    581600 * Get default codec param for the specified codec info. 
    582601 * 
    583  * @param mgr       The codec manager instance. Application can get the 
    584  *                  instance by calling #pjmedia_endpt_get_codec_mgr(). 
     602 * @param mgr       The codec manager instance. If NULL, the default codec 
     603 *                  manager instance will be used. 
    585604 * @param info      The codec info, which default parameter's is being 
    586605 *                  queried. 
    … …  
    591610 */ 
    592611PJ_DECL(pj_status_t)  
    593 pjmedia_vid_codec_mgr_get_default_param( pjmedia_vid_codec_mgr *mgr, 
    594                                      const pjmedia_vid_codec_info *info, 
    595                                      pjmedia_vid_codec_param *param ); 
     612pjmedia_vid_codec_mgr_get_default_param(pjmedia_vid_codec_mgr *mgr, 
     613                                        const pjmedia_vid_codec_info *info, 
     614                                        pjmedia_vid_codec_param *param); 
    596615 
    597616 
    … …  
    599618 * Set default codec param for the specified codec info. 
    600619 * 
    601  * @param mgr       The codec manager instance. Application can get the 
    602  *                  instance by calling #pjmedia_endpt_get_codec_mgr(). 
     620 * @param mgr       The codec manager instance. If NULL, the default codec 
     621 *                  manager instance will be used. 
     622 * @param pool      The pool instance. 
    603623 * @param info      The codec info, which default parameter's is being 
    604624 *                  updated. 
    … …  
    620640 * until it finds factory that is able to create the specified codec. 
    621641 * 
    622  * @param mgr       The codec manager instance. Application can get the 
    623  *                  instance by calling #pjmedia_endpt_get_codec_mgr(). 
     642 * @param mgr       The codec manager instance. If NULL, the default codec 
     643 *                  manager instance will be used. 
    624644 * @param info      The information about the codec to be created. 
    625645 * @param p_codec   Pointer to receive the codec instance. 
    … …  
    636656 * the instance of the codec back to its factory. 
    637657 * 
    638  * @param mgr       The codec manager instance. Application can get the 
    639  *                  instance by calling #pjmedia_endpt_get_codec_mgr(). 
     658 * @param mgr       The codec manager instance. If NULL, the default codec 
     659 *                  manager instance will be used. 
    640660 * @param codec     The codec instance. 
    641661 * 
    … …  
    655675 
    656676/** 
    657  * @defgroup PJMEDIA_CODEC_CODECS Supported codecs 
     677 * @defgroup PJMEDIA_CODEC_VID_CODECS Supported video codecs 
    658678 * @ingroup PJMEDIA_CODEC 
    659  * @brief Documentation about individual codec supported by PJMEDIA 
     679 * @brief Documentation about individual video codec supported by PJMEDIA 
    660680 * @{ 
    661681 * Please see the APIs provided by the individual codecs below. 
Note: See TracChangeset for help on using the changeset viewer.