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:

enumerator PJMEDIA_FORMAT_L16: 16bit signed integer linear PCM audio

enumerator PJMEDIA_FORMAT_PCM: Alias for PJMEDIA_FORMAT_L16

enumerator PJMEDIA_FORMAT_PCMA: G.711 ALAW

enumerator PJMEDIA_FORMAT_ALAW: Alias for PJMEDIA_FORMAT_PCMA

enumerator PJMEDIA_FORMAT_PCMU: G.711 ULAW

enumerator PJMEDIA_FORMAT_ULAW: Aliaw for PJMEDIA_FORMAT_PCMU

enumerator PJMEDIA_FORMAT_AMR: AMR narrowband

enumerator PJMEDIA_FORMAT_G729: ITU G.729

enumerator PJMEDIA_FORMAT_ILBC: Internet Low Bit-Rate Codec (ILBC)

enumerator PJMEDIA_FORMAT_RGB24: 24bit RGB

enumerator PJMEDIA_FORMAT_RGBA: 32bit RGB with alpha channel

enumerator PJMEDIA_FORMAT_BGRA

enumerator PJMEDIA_FORMAT_RGB32: Alias for PJMEDIA_FORMAT_RGBA

enumerator PJMEDIA_FORMAT_DIB: Device Independent Bitmap, alias for 24 bit RGB

enumerator PJMEDIA_FORMAT_GBRP: 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.

enumerator PJMEDIA_FORMAT_AYUV: 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

enumerator PJMEDIA_FORMAT_YUY2: 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

enumerator PJMEDIA_FORMAT_UYVY: 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

enumerator PJMEDIA_FORMAT_YVYU: 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.

enumerator PJMEDIA_FORMAT_I420: 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.

enumerator PJMEDIA_FORMAT_IYUV: IYUV is alias for I420.

enumerator PJMEDIA_FORMAT_YV12: 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.

enumerator PJMEDIA_FORMAT_NV12: 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.

enumerator PJMEDIA_FORMAT_NV21: 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.

enumerator PJMEDIA_FORMAT_I422: 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.

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

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

enumerator PJMEDIA_FORMAT_H261: Encoded video formats

enumerator PJMEDIA_FORMAT_H263

enumerator PJMEDIA_FORMAT_H263P

enumerator PJMEDIA_FORMAT_H264

enumerator PJMEDIA_FORMAT_VP8

enumerator PJMEDIA_FORMAT_VP9

enumerator PJMEDIA_FORMAT_MJPEG

enumerator PJMEDIA_FORMAT_MPEG1VIDEO

enumerator PJMEDIA_FORMAT_MPEG2VIDEO

enumerator PJMEDIA_FORMAT_MPEG4

enumerator PJMEDIA_FORMAT_INVALID

enum pjmedia_format_detail_type

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

Values:

enumerator PJMEDIA_FORMAT_DETAIL_NONE: Format detail is not specified.

enumerator PJMEDIA_FORMAT_DETAIL_AUDIO: Audio format detail.

enumerator PJMEDIA_FORMAT_DETAIL_VIDEO: Video format detail.

enumerator 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:

enumerator PJMEDIA_COLOR_MODEL_NONE: The color model is unknown or unspecified.

enumerator PJMEDIA_COLOR_MODEL_RGB: RGB color model.

enumerator 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.

Parameters:

clock_rate – Clock rate.
usec_ptime – Frame interval, in microsecond.
channel_count – Number of channels.

Returns:

The samples per frame value.

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.

Parameters:

bps – The bitrate of the stream.
usec_ptime – Frame interval, in microsecond.

Returns:

Frame size in bytes.

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.

Parameters:: frame_rate – Frame rate
Returns:: The ptime value (in usec).

unsigned PJMEDIA_AFD_SPF(const pjmedia_audio_format_detail *pafd)

Utility to retrieve samples_per_frame value from pjmedia_audio_format_detail.

Parameters:: pafd – Pointer to pjmedia_audio_format_detail
Returns:: Samples per frame

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.

Parameters:: afd – Pointer to pjmedia_audio_format_detail
Returns:: Average frame size.

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.

Parameters:: afd – Pointer to pjmedia_audio_format_detail
Returns:: Average frame size.

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.

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

Copy format to another.

Parameters:

dst – The destination format.
src – The source format.

Returns:

Pointer to destination 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.

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.

Returns:

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

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.

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.

Returns:

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

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.

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.

Returns:

PJ_SUCCESS on success, or the appripriate error value.

pjmedia_video_format_mgr *pjmedia_video_format_mgr_instance(void)

Get the singleton instance of the video format manager.

Returns:: 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.

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.

Returns:

The video format info.

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.

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.

Returns:

PJ_SUCCESS on success, or the appripriate error value.

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).

pj_status_t pjmedia_video_format_fill_black(const pjmedia_format *fmt, void *buf, pj_size_t buf_size)

Fill video frame buffer with black color.

Parameters:

fmt – The video format.
buf – The frame buffer.
buf_size – The frame buffer size.

Returns:

PJ_SUCCESS if successfull.

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.

Public Members

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

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().

Public Members

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.

struct pjmedia_format

#include <format.h>

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

Public Members

pj_uint32_t id

The format id that specifies the audio sample or video pixel format. Some well known formats ids are declared in pjmedia_format_id enumeration.