Group PJMEDIA_FORMAT

group PJMEDIA_FORMAT

Media format.

Defines

PJMEDIA_FORMAT_PACK(C1, C2, C3, C4)

Macro for packing format from a four character code, similar to FOURCC. This macro is used for building the constants in pjmedia_format_id enumeration.

PJMEDIA_FORMAT_DETAIL_USER_SIZE

This macro declares the size of the detail section in pjmedia_format to be reserved for user defined detail.

Typedefs

typedef struct pjmedia_video_format_mgr pjmedia_video_format_mgr

Opaque data type for video format manager. The video format manager manages the repository of video formats that the framework recognises. Typically it is a singleton instance, although application may instantiate more than one instances of this if required.

Enums

enum pjmedia_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.

Values:

PJMEDIA_FORMAT_L16 = 0

16bit signed integer linear PCM audio

PJMEDIA_FORMAT_PCM = PJMEDIA_FORMAT_L16

Alias for PJMEDIA_FORMAT_L16

PJMEDIA_FORMAT_PCMA = PJMEDIA_FOURCC('A', 'L', 'A', 'W')

G.711 ALAW

PJMEDIA_FORMAT_ALAW = PJMEDIA_FORMAT_PCMA

Alias for PJMEDIA_FORMAT_PCMA

PJMEDIA_FORMAT_PCMU = PJMEDIA_FOURCC('u', 'L', 'A', 'W')

G.711 ULAW

PJMEDIA_FORMAT_ULAW = PJMEDIA_FORMAT_PCMU

Aliaw for PJMEDIA_FORMAT_PCMU

PJMEDIA_FORMAT_AMR = PJMEDIA_FOURCC(' ', 'A', 'M', 'R')

AMR narrowband

PJMEDIA_FORMAT_G729 = PJMEDIA_FOURCC('G', '7', '2', '9')

ITU G.729

PJMEDIA_FORMAT_ILBC = PJMEDIA_FOURCC('I', 'L', 'B', 'C')

Internet Low Bit-Rate Codec (ILBC)

PJMEDIA_FORMAT_RGB24 = PJMEDIA_FOURCC('R', 'G', 'B', '3')

24bit RGB

PJMEDIA_FORMAT_RGBA = PJMEDIA_FOURCC('R', 'G', 'B', 'A')

32bit RGB with alpha channel

PJMEDIA_FORMAT_BGRA = PJMEDIA_FOURCC('B', 'G', 'R', 'A')
PJMEDIA_FORMAT_RGB32 = PJMEDIA_FORMAT_RGBA

Alias for PJMEDIA_FORMAT_RGBA

PJMEDIA_FORMAT_DIB = PJMEDIA_FOURCC('D', 'I', 'B', ' ')

Device Independent Bitmap, alias for 24 bit RGB

PJMEDIA_FORMAT_GBRP = PJMEDIA_FOURCC('G', 'B', 'R', 'P')

This is planar 4:4:4/24bpp RGB format, the data can be treated as three planes of color components, where the first plane contains only the G samples, the second plane contains only the B samples, and the third plane contains only the R samples.

PJMEDIA_FORMAT_AYUV = PJMEDIA_FOURCC('A', 'Y', 'U', 'V')

This is a packed 4:4:4/32bpp format, where each pixel is encoded as four consecutive bytes, arranged in the following sequence: V0, U0, Y0, A0. Source: http://msdn.microsoft.com/en-us/library/dd206750%28v=VS.85%29.aspx#ayuv

PJMEDIA_FORMAT_YUY2 = PJMEDIA_FOURCC('Y', 'U', 'Y', '2')

This is packed 4:2:2/16bpp YUV format, the data can be treated as an array of unsigned char values, where the first byte contains the first Y sample, the second byte contains the first U (Cb) sample, the third byte contains the second Y sample, and the fourth byte contains the first V (Cr) sample, and so forth. Source: http://msdn.microsoft.com/en-us/library/dd206750%28v=VS.85%29.aspx#yuy2

PJMEDIA_FORMAT_UYVY = PJMEDIA_FOURCC('U', 'Y', 'V', 'Y')

This format is the same as the YUY2 format except the byte order is reversed that is, the chroma and luma bytes are flipped. If the image is addressed as an array of two little-endian WORD values, the first WORD contains U in the LSBs and Y0 in the MSBs, and the second WORD contains V in the LSBs and Y1 in the MSBs. Source: http://msdn.microsoft.com/en-us/library/dd206750%28v=VS.85%29.aspx#uyvy

PJMEDIA_FORMAT_YVYU = PJMEDIA_FOURCC('Y', 'V', 'Y', 'U')

This format is the same as the YUY2 and UYVY format except the byte order is reversed that is, the chroma and luma bytes are flipped. If the image is addressed as an array of two little-endian WORD values, the first WORD contains Y0 in the LSBs and V in the MSBs, and the second WORD contains Y1 in the LSBs and U in the MSBs.

PJMEDIA_FORMAT_I420 = PJMEDIA_FOURCC('I', '4', '2', '0')

This is planar 4:2:0/12bpp YUV format, the data can be treated as three planes of color components, where the first plane contains only the Y samples, the second plane contains only the U (Cb) samples, and the third plane contains only the V (Cr) sample.

PJMEDIA_FORMAT_IYUV = PJMEDIA_FORMAT_I420

IYUV is alias for I420.

PJMEDIA_FORMAT_YV12 = PJMEDIA_FOURCC('Y', 'V', '1', '2')

This is planar 4:2:0/12bpp YUV format, similar to I420 or IYUV but the U (Cb) and V (Cr) planes order is switched, i.e: the second plane contains the V (Cb) samples and the third plane contains the V (Cr) samples.

PJMEDIA_FORMAT_NV12 = PJMEDIA_FOURCC('N', 'V', '1', '2')

This is planar 4:2:0/12bpp YUV format, the data can be treated as two planes of color components, where the first plane contains only the Y samples, the second plane contains interleaved U (Cb) - V (Cr) samples.

PJMEDIA_FORMAT_NV21 = PJMEDIA_FOURCC('N', 'V', '2', '1')

This is planar 4:2:0/12bpp YUV format, the data can be treated as two planes of color components, where the first plane contains only the Y samples, the second plane contains interleaved V (Cr) - U (Cb) samples.

PJMEDIA_FORMAT_I422 = PJMEDIA_FOURCC('I', '4', '2', '2')

This is planar 4:2:2/16bpp YUV format, the data can be treated as three planes of color components, where the first plane contains only the Y samples, the second plane contains only the U (Cb) samples, and the third plane contains only the V (Cr) sample.

PJMEDIA_FORMAT_I420JPEG = PJMEDIA_FOURCC('J', '4', '2', '0')

The JPEG version of planar 4:2:0/12bpp YUV format.

PJMEDIA_FORMAT_I422JPEG = PJMEDIA_FOURCC('J', '4', '2', '2')

The JPEG version of planar 4:2:2/16bpp YUV format.

PJMEDIA_FORMAT_H261 = PJMEDIA_FOURCC('H', '2', '6', '1')

Encoded video formats

PJMEDIA_FORMAT_H263 = PJMEDIA_FOURCC('H', '2', '6', '3')
PJMEDIA_FORMAT_H263P = PJMEDIA_FOURCC('P', '2', '6', '3')
PJMEDIA_FORMAT_H264 = PJMEDIA_FOURCC('H', '2', '6', '4')
PJMEDIA_FORMAT_VP8 = PJMEDIA_FOURCC('V', 'P', '8', '0')
PJMEDIA_FORMAT_VP9 = PJMEDIA_FOURCC('V', 'P', '9', '0')
PJMEDIA_FORMAT_MJPEG = PJMEDIA_FOURCC('M', 'J', 'P', 'G')
PJMEDIA_FORMAT_MPEG1VIDEO = PJMEDIA_FOURCC('M', 'P', '1', 'V')
PJMEDIA_FORMAT_MPEG2VIDEO = PJMEDIA_FOURCC('M', 'P', '2', 'V')
PJMEDIA_FORMAT_MPEG4 = PJMEDIA_FOURCC('M', 'P', 'G', '4')
enum pjmedia_format_detail_type

This enumeration specifies what type of detail is included in a pjmedia_format structure.

Values:

PJMEDIA_FORMAT_DETAIL_NONE

Format detail is not specified.

PJMEDIA_FORMAT_DETAIL_AUDIO

Audio format detail.

PJMEDIA_FORMAT_DETAIL_VIDEO

Video format detail.

PJMEDIA_FORMAT_DETAIL_MAX

Number of format detail type that has been defined.

enum pjmedia_color_model

This enumeration describes video color model. It mostly serves as information only.

Values:

PJMEDIA_COLOR_MODEL_NONE

The color model is unknown or unspecified.

PJMEDIA_COLOR_MODEL_RGB

RGB color model.

PJMEDIA_COLOR_MODEL_YUV

YUV color model.

Functions

unsigned PJMEDIA_SPF(unsigned clock_rate, unsigned usec_ptime, unsigned channel_count)

General utility routine to calculate samples per frame value from clock rate, ptime (in usec), and channel count. Application should use this macro whenever possible due to possible overflow in the math calculation.

Return

The samples per frame value.

Parameters
  • clock_rate: Clock rate.

  • usec_ptime: Frame interval, in microsecond.

  • channel_count: Number of channels.

unsigned PJMEDIA_SPF2(unsigned clock_rate, const pjmedia_ratio *fr, unsigned channel_count)

Variant of PJMEDIA_SPF() which takes frame rate instead of ptime.

unsigned PJMEDIA_FSZ(unsigned bps, unsigned usec_ptime)

Utility routine to calculate frame size (in bytes) from bitrate and frame interval values. Application should use this macro whenever possible due to possible overflow in the math calculation.

Return

Frame size in bytes.

Parameters
  • bps: The bitrate of the stream.

  • usec_ptime: Frame interval, in microsecond.

unsigned PJMEDIA_PTIME(const pjmedia_ratio *frame_rate)

General utility routine to calculate ptime value from frame rate. Application should use this macro whenever possible due to possible overflow in the math calculation.

Return

The ptime value (in usec).

Parameters
  • frame_rate: Frame rate

unsigned PJMEDIA_AFD_SPF(const pjmedia_audio_format_detail *pafd)

Utility to retrieve samples_per_frame value from pjmedia_audio_format_detail.

Return

Samples per frame

Parameters

unsigned PJMEDIA_AFD_AVG_FSZ(const pjmedia_audio_format_detail *afd)

Utility to retrieve average frame size from pjmedia_audio_format_detail. The average frame size is derived from the average bitrate of the audio stream.

Return

Average frame size.

Parameters

unsigned PJMEDIA_AFD_MAX_FSZ(const pjmedia_audio_format_detail *afd)

Utility to retrieve maximum frame size from pjmedia_audio_format_detail. The maximum frame size is derived from the maximum bitrate of the audio stream.

Return

Average frame size.

Parameters

void pjmedia_format_init_audio(pjmedia_format *fmt, pj_uint32_t fmt_id, unsigned clock_rate, unsigned channel_count, unsigned bits_per_sample, unsigned frame_time_usec, pj_uint32_t avg_bps, pj_uint32_t max_bps)

Initialize the format as audio format with the specified parameters.

Parameters
  • fmt: The format to be initialized.

  • fmt_id: Format ID. See pjmedia_format_id

  • clock_rate: Audio clock rate.

  • channel_count: Number of channels.

  • bits_per_sample: Number of bits per sample.

  • frame_time_usec: Frame interval, in microsecond.

  • avg_bps: Average bitrate.

  • max_bps: Maximum bitrate.

void pjmedia_format_init_video(pjmedia_format *fmt, pj_uint32_t fmt_id, unsigned width, unsigned height, unsigned fps_num, unsigned fps_denum)

Initialize the format as video format with the specified parameters. A format manager should have been created, as this function will need to consult to a format manager in order to fill in detailed information about the format.

Parameters
  • fmt: The format to be initialised.

  • fmt_id: Format ID. See pjmedia_format_id

  • width: Image width.

  • height: Image heigth.

  • fps_num: FPS numerator.

  • fps_denum: FPS denumerator.

  • avg_bps: Average bitrate.

  • max_bps: Maximum bitrate.

pjmedia_format *pjmedia_format_copy(pjmedia_format *dst, const pjmedia_format *src)

Copy format to another.

Return

Pointer to destination format.

Parameters
  • dst: The destination format.

  • src: The source format.

pjmedia_audio_format_detail *pjmedia_format_get_audio_format_detail(const pjmedia_format *fmt, pj_bool_t assert_valid)

Check if the format contains audio format, and retrieve the audio format detail in the format.

Return

The instance of audio format detail in the format structure, or NULL if the format doesn’t contain audio detail.

Parameters
  • fmt: The format structure.

  • assert_valid: If this is set to non-zero, an assertion will be raised if the detail type is not audio or if the the detail is NULL.

pjmedia_video_format_detail *pjmedia_format_get_video_format_detail(const pjmedia_format *fmt, pj_bool_t assert_valid)

Check if the format contains video format, and retrieve the video format detail in the format.

Return

The instance of video format detail in the format structure, or NULL if the format doesn’t contain video detail.

Parameters
  • fmt: The format structure.

  • assert_valid: If this is set to non-zero, an assertion will be raised if the detail type is not video or if the the detail is NULL.

pj_status_t pjmedia_video_format_mgr_create(pj_pool_t *pool, unsigned max_fmt, unsigned options, pjmedia_video_format_mgr **p_mgr)

Create a new video format manager instance. This will also set the pointer to the singleton instance if the value is still NULL.

Return

PJ_SUCCESS on success, or the appripriate error value.

Parameters
  • pool: The pool to allocate memory.

  • max_fmt: Maximum number of formats to accommodate.

  • options: Option flags. Must be zero for now.

  • p_mgr: Pointer to hold the created instance.

pjmedia_video_format_mgr *pjmedia_video_format_mgr_instance(void)

Get the singleton instance of the video format manager.

Return

The instance.

void pjmedia_video_format_mgr_set_instance(pjmedia_video_format_mgr *mgr)

Manually assign a specific video manager instance as the singleton instance. Normally this is not needed if only one instance is ever going to be created, as the library automatically assign the singleton instance.

Parameters
  • mgr: The instance to be used as the singleton instance. Application may specify NULL to clear the singleton singleton instance.

const pjmedia_video_format_info *pjmedia_get_video_format_info(pjmedia_video_format_mgr *mgr, pj_uint32_t id)

Retrieve a video format info for the specified format id.

Return

The video format info.

Parameters
  • mgr: The video format manager. Specify NULL to use the singleton instance (however, a video format manager still must have been created prior to calling this function).

  • id: The format id which format info is to be retrieved.

pj_status_t pjmedia_register_video_format_info(pjmedia_video_format_mgr *mgr, pjmedia_video_format_info *vfi)

Register a new video format to the framework. By default, built-in formats will be registered automatically to the format manager when it is created (note: built-in formats are ones which format id is listed in pjmedia_format_id enumeration). This function allows application to use user defined format id by registering that format into the framework.

Return

PJ_SUCCESS on success, or the appripriate error value.

Parameters
  • mgr: The video format manager. Specify NULL to use the singleton instance (however, a video format manager still must have been created prior to calling this function).

  • vfi: The video format info to be registered. This structure must remain valid until the format manager is destroyed.

void pjmedia_video_format_mgr_destroy(pjmedia_video_format_mgr *mgr)

Destroy a video format manager. If the manager happens to be the singleton instance, the singleton instance will be set to NULL.

Parameters
  • mgr: The video format manager. Specify NULL to use the singleton instance (however, a video format manager still must have been created prior to calling this function).

struct pjmedia_audio_format_detail
#include <format.h>

This structure is put in detail field of pjmedia_format to describe detail information about an audio media.

struct pjmedia_video_format_detail
#include <format.h>

This structure is put in 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().

struct pjmedia_format
#include <format.h>

This structure contains all the information needed to completely describe a media.

struct pjmedia_video_apply_fmt_param
#include <format.h>

This structure holds information to apply a specific 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.

struct pjmedia_video_format_info
#include <format.h>

This structure holds information to describe a video format. Application can retrieve this structure by calling pjmedia_get_video_format_info() funcion.