General Data Structure changes in 2.0

Media Format

• ​pjmedia_format — Defined as all information needed to completely describe a media, which containing:
  • Format ID — Specifies the audio sample or video pixel format. Enumeration of some well known formats IDs is defined in ​pjmedia_format_id.
  • Media type — The top-most type of the media, as an information.
  • Format detail — Detail section to describe the media. As the details are different among media types, this field is declared as union and ​pjmedia_format_detail_type is introduced to recognize the content. Currently there are two predefined structures:
    • ​pjmedia_audio_format_detail for audio format detail
    • ​pjmedia_video_format_detail for video format detail.

• Video format helper:
  • ​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).
  • ​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.

/**
 * This structure contains all the information needed to completely describe
 * a media.
 */
typedef struct pjmedia_format
{
    /**
     * The format id that specifies the audio sample or video pixel format.
     * Some well known formats ids are declared in pjmedia_format_id
     * enumeration.
     *
     * @see pjmedia_format_id
     */
    pj_uint32_t		 	 id;

    /**
     * The top-most type of the media, as an information.
     */
    pjmedia_type		 type;

    /**
     * The type of detail structure in the \a detail pointer.
     */
    pjmedia_format_detail_type	 detail_type;

    /**
     * Detail section to describe the media.
     */
    union
    {
	/**
	 * Detail section for audio format.
	 */
	pjmedia_audio_format_detail	aud;

	/**
	 * Detail section for video format.
	 */
	pjmedia_video_format_detail	vid;

	/**
	 * Reserved area for user-defined format detail.
	 */
	char				user[PJMEDIA_FORMAT_DETAIL_USER_SIZE];
    } det;

} pjmedia_format;

Media format ID:

/**
 * This enumeration uniquely identify audio sample and/or video pixel formats.
 * Some well known formats are listed here. The format ids are built by
 * combining four character codes, similar to FOURCC. The format id is
 * extensible, as application may define and use format ids not declared
 * on this enumeration.
 *
 * This format id along with other information will fully describe the media
 * in #pjmedia_format structure.
 */
typedef enum pjmedia_format_id
{
    /*
     * Audio formats
     */

    /** 16bit signed integer linear PCM audio */
    PJMEDIA_FORMAT_L16	    = 0,

    /** Alias for PJMEDIA_FORMAT_L16 */
    PJMEDIA_FORMAT_PCM	    = PJMEDIA_FORMAT_L16,

    /** G.711 ALAW */
    PJMEDIA_FORMAT_PCMA	    = PJMEDIA_FORMAT_PACK('A', 'L', 'A', 'W'),
    ...

    /*
     * Video formats.
     */
    /**
     * 24bit RGB
     */
    PJMEDIA_FORMAT_RGB24    = PJMEDIA_FORMAT_PACK('R', 'G', 'B', '3'),

    /**
     * 32bit RGB with alpha channel
     */
    PJMEDIA_FORMAT_RGBA     = PJMEDIA_FORMAT_PACK('R', 'G', 'B', 'A'),
    PJMEDIA_FORMAT_BGRA     = PJMEDIA_FORMAT_PACK('B', 'G', 'R', 'A'),
    ...

    /**
     * Encoded video formats
     */

    PJMEDIA_FORMAT_H261     = PJMEDIA_FORMAT_PACK('H', '2', '6', '1'),
    PJMEDIA_FORMAT_H263     = PJMEDIA_FORMAT_PACK('H', '2', '6', '3'),
    PJMEDIA_FORMAT_H263P    = PJMEDIA_FORMAT_PACK('P', '2', '6', '3'),
    PJMEDIA_FORMAT_H264     = PJMEDIA_FORMAT_PACK('H', '2', '6', '4'),
    ...

} pjmedia_format_id;

Format detail types:

/**
 * This enumeration specifies what type of detail is included in a
 * #pjmedia_format structure.
 */
typedef enum pjmedia_format_detail_type
{
    /** Format detail is not specified. */
    PJMEDIA_FORMAT_DETAIL_NONE,

    /** Audio format detail. */
    PJMEDIA_FORMAT_DETAIL_AUDIO,

    /** Video format detail. */
    PJMEDIA_FORMAT_DETAIL_VIDEO,

    /** Number of format detail type that has been defined. */
    PJMEDIA_FORMAT_DETAIL_MAX

} pjmedia_format_detail_type;

Audio format detail:

/**
 * This structure is put in \a detail field of #pjmedia_format to describe
 * detail information about an audio media.
 */
typedef struct pjmedia_audio_format_detail
{
    unsigned	clock_rate;	/**< Audio clock rate in samples or Hz. */
    unsigned	channel_count;	/**< Number of channels.		*/
    unsigned	frame_time_usec;/**< Frame interval, in microseconds.	*/
    unsigned	bits_per_sample;/**< Number of bits per sample.		*/
    pj_uint32_t	avg_bps;	/**< Average bitrate			*/
    pj_uint32_t	max_bps;	/**< Maximum bitrate			*/
} pjmedia_audio_format_detail;

Video format detail:

/**
 * This structure is put in \a detail field of #pjmedia_format to describe
 * detail information about a video media.
 *
 * Additional information about a video format can also be retrieved by
 * calling #pjmedia_get_video_format_info().
 */
typedef struct pjmedia_video_format_detail
{
    pjmedia_rect_size	size;	/**< Video size (width, height) 	*/
    pjmedia_ratio	fps;	/**< Number of frames per second.	*/
    pj_uint32_t		avg_bps;/**< Average bitrate.			*/
    pj_uint32_t		max_bps;/**< Maximum bitrate.			*/
} pjmedia_video_format_detail;

Missing samples_per_frame

Use PJMEDIA_AFD_SAMPLES_PER_FRAME(afd)

Port info

Media format description fields have been replaced by pjmedia_format:

/**
 * Port info.
 */
typedef struct pjmedia_port_info
{
    pj_str_t	    name;		/**< Port name.			    */
    pj_uint32_t	    signature;		/**< Port signature.		    */
    pjmedia_dir     dir;                /**< Port direction.                */
    pjmedia_format  fmt;                /**< Format.		            */
} pjmedia_port_info;

put_frame() callback of pjmedia_port

Removed const qualifier from the frame argument.

Sample warnings:

../src/pjmedia/bidirectional.c: In function ‘put_frame’:
../src/pjmedia/bidirectional.c:39: warning: passing argument 2 of ‘pjmedia_port_put_frame’ discards qualifiers from pointer target type
../include/pjmedia/port.h:334: note: expected ‘struct pjmedia_frame *’ but argument is of type ‘const struct pjmedia_frame *’
../src/pjmedia/bidirectional.c:70: warning: assignment from incompatible pointer type

pjsua_call_info

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:

/**
 * This structure describes the information and current status of a call.
 */
typedef struct pjsua_call_info
{
    /** Call identification. */
    pjsua_call_id	id;

    ...

    /** Array of media stream information */
    struct
    {
	/** Media index in SDP. */
	unsigned		index;

	/** Media type. */
	pjmedia_type		type;

	/** Media direction. */
	pjmedia_dir		dir;

	/** Call media status. */
	pjsua_call_media_status status;

	/** The specific media stream info. */
	union {
	    /** Audio stream */
	    struct {
		/** The conference port number for the call.  */
		pjsua_conf_port_id   conf_slot;
	    } aud;

	    /** Video stream */
	    struct {
		/**
		 * The window id for incoming video, if any, or
		 * PJSUA_INVALID_ID.
		 */
		pjsua_vid_win_id     win_in;

		/** The video capture device for outgoing transmission,
		 *  if any, or PJMEDIA_VID_INVALID_DEV
		 */
		pjmedia_vid_dev_index	cap_dev;

	    } vid;
	} stream;

    } media[PJMEDIA_MAX_SDP_MEDIA];

    ...

} pjsua_call_info;