BLOG | DOCUMENTATION | TRAC

Home --> Documentations --> PJMEDIA Reference

Media format. More...

Data Structures

struct  pjmedia_audio_format_detail
 
struct  pjmedia_video_format_detail
 
struct  pjmedia_format
 
struct  pjmedia_video_apply_fmt_param
 
struct  pjmedia_video_format_info
 

Macros

#define PJMEDIA_FORMAT_PACK(C1, C2, C3, C4)   PJMEDIA_FOURCC(C1, C2, C3, C4)
 
#define PJMEDIA_FORMAT_DETAIL_USER_SIZE   1
 

Typedefs

typedef struct pjmedia_video_format_mgr pjmedia_video_format_mgr
 

Enumerations

enum  pjmedia_format_id {
  PJMEDIA_FORMAT_L16 = 0,
  PJMEDIA_FORMAT_PCM = PJMEDIA_FORMAT_L16,
  PJMEDIA_FORMAT_PCMA = PJMEDIA_FOURCC( 'A' , 'L' , 'A' , 'W' ),
  PJMEDIA_FORMAT_ALAW = PJMEDIA_FORMAT_PCMA,
  PJMEDIA_FORMAT_PCMU = PJMEDIA_FOURCC( 'u' , 'L' , 'A' , 'W' ),
  PJMEDIA_FORMAT_ULAW = PJMEDIA_FORMAT_PCMU,
  PJMEDIA_FORMAT_AMR = PJMEDIA_FOURCC( ' ' , 'A' , 'M' , 'R' ),
  PJMEDIA_FORMAT_G729 = PJMEDIA_FOURCC( 'G' , '7' , '2' , '9' ),
  PJMEDIA_FORMAT_ILBC = PJMEDIA_FOURCC( 'I' , 'L' , 'B' , 'C' ),
  PJMEDIA_FORMAT_RGB24 = PJMEDIA_FOURCC( 'R' , 'G' , 'B' , '3' ),
  PJMEDIA_FORMAT_RGBA = PJMEDIA_FOURCC( 'R' , 'G' , 'B' , 'A' ),
  PJMEDIA_FORMAT_BGRA = PJMEDIA_FOURCC( 'B' , 'G' , 'R' , 'A' ),
  PJMEDIA_FORMAT_RGB32 = PJMEDIA_FORMAT_RGBA,
  PJMEDIA_FORMAT_DIB = PJMEDIA_FOURCC( 'D' , 'I' , 'B' , ' ' ),
  PJMEDIA_FORMAT_GBRP = PJMEDIA_FOURCC( 'G' , 'B' , 'R' , 'P' ),
  PJMEDIA_FORMAT_AYUV = PJMEDIA_FOURCC( 'A' , 'Y' , 'U' , 'V' ),
  PJMEDIA_FORMAT_YUY2 = PJMEDIA_FOURCC( 'Y' , 'U' , 'Y' , '2' ),
  PJMEDIA_FORMAT_UYVY = PJMEDIA_FOURCC( 'U' , 'Y' , 'V' , 'Y' ),
  PJMEDIA_FORMAT_YVYU = PJMEDIA_FOURCC( 'Y' , 'V' , 'Y' , 'U' ),
  PJMEDIA_FORMAT_I420 = PJMEDIA_FOURCC( 'I' , '4' , '2' , '0' ),
  PJMEDIA_FORMAT_IYUV = PJMEDIA_FORMAT_I420,
  PJMEDIA_FORMAT_YV12 = PJMEDIA_FOURCC( 'Y' , 'V' , '1' , '2' ),
  PJMEDIA_FORMAT_NV12 = PJMEDIA_FOURCC( 'N' , 'V' , '1' , '2' ),
  PJMEDIA_FORMAT_NV21 = PJMEDIA_FOURCC( 'N' , 'V' , '2' , '1' ),
  PJMEDIA_FORMAT_I422 = PJMEDIA_FOURCC( 'I' , '4' , '2' , '2' ),
  PJMEDIA_FORMAT_I420JPEG = PJMEDIA_FOURCC( 'J' , '4' , '2' , '0' ),
  PJMEDIA_FORMAT_I422JPEG = PJMEDIA_FOURCC( 'J' , '4' , '2' , '2' ),
  PJMEDIA_FORMAT_H261 = PJMEDIA_FOURCC( 'H' , '2' , '6' , '1' ),
  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 {
  PJMEDIA_FORMAT_DETAIL_NONE,
  PJMEDIA_FORMAT_DETAIL_AUDIO,
  PJMEDIA_FORMAT_DETAIL_VIDEO,
  PJMEDIA_FORMAT_DETAIL_MAX
}
 
enum  pjmedia_color_model {
  PJMEDIA_COLOR_MODEL_NONE,
  PJMEDIA_COLOR_MODEL_RGB,
  PJMEDIA_COLOR_MODEL_YUV
}
 

Functions

unsigned PJMEDIA_SPF (unsigned clock_rate, unsigned usec_ptime, unsigned channel_count)
 
unsigned PJMEDIA_SPF2 (unsigned clock_rate, const pjmedia_ratio *fr, unsigned channel_count)
 
unsigned PJMEDIA_FSZ (unsigned bps, unsigned usec_ptime)
 
unsigned PJMEDIA_PTIME (const pjmedia_ratio *frame_rate)
 
unsigned PJMEDIA_AFD_SPF (const pjmedia_audio_format_detail *pafd)
 
unsigned PJMEDIA_AFD_AVG_FSZ (const pjmedia_audio_format_detail *afd)
 
unsigned PJMEDIA_AFD_MAX_FSZ (const pjmedia_audio_format_detail *afd)
 
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)
 
void pjmedia_format_init_video (pjmedia_format *fmt, pj_uint32_t fmt_id, unsigned width, unsigned height, unsigned fps_num, unsigned fps_denum)
 
pjmedia_formatpjmedia_format_copy (pjmedia_format *dst, const pjmedia_format *src)
 
pjmedia_audio_format_detailpjmedia_format_get_audio_format_detail (const pjmedia_format *fmt, pj_bool_t assert_valid)
 
pjmedia_video_format_detailpjmedia_format_get_video_format_detail (const pjmedia_format *fmt, pj_bool_t assert_valid)
 
pj_status_t pjmedia_video_format_mgr_create (pj_pool_t *pool, unsigned max_fmt, unsigned options, pjmedia_video_format_mgr **p_mgr)
 
pjmedia_video_format_mgrpjmedia_video_format_mgr_instance (void)
 
void pjmedia_video_format_mgr_set_instance (pjmedia_video_format_mgr *mgr)
 
const pjmedia_video_format_infopjmedia_get_video_format_info (pjmedia_video_format_mgr *mgr, pj_uint32_t id)
 
pj_status_t pjmedia_register_video_format_info (pjmedia_video_format_mgr *mgr, pjmedia_video_format_info *vfi)
 
void pjmedia_video_format_mgr_destroy (pjmedia_video_format_mgr *mgr)
 

Detailed Description

Macro Definition Documentation

◆ PJMEDIA_FORMAT_PACK

#define PJMEDIA_FORMAT_PACK (   C1,
  C2,
  C3,
  C4 
)    PJMEDIA_FOURCC(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

#define PJMEDIA_FORMAT_DETAIL_USER_SIZE   1

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

Typedef Documentation

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

Enumeration Type Documentation

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

Enumerator
PJMEDIA_FORMAT_L16 

16bit signed integer linear PCM audio

PJMEDIA_FORMAT_PCM 

Alias for PJMEDIA_FORMAT_L16

PJMEDIA_FORMAT_PCMA 

G.711 ALAW

PJMEDIA_FORMAT_ALAW 

Alias for PJMEDIA_FORMAT_PCMA

PJMEDIA_FORMAT_PCMU 

G.711 ULAW

PJMEDIA_FORMAT_ULAW 

Aliaw for PJMEDIA_FORMAT_PCMU

PJMEDIA_FORMAT_AMR 

AMR narrowband

PJMEDIA_FORMAT_G729 

ITU G.729

PJMEDIA_FORMAT_ILBC 

Internet Low Bit-Rate Codec (ILBC)

PJMEDIA_FORMAT_RGB24 

24bit RGB

PJMEDIA_FORMAT_RGBA 

32bit RGB with alpha channel

PJMEDIA_FORMAT_RGB32 

Alias for PJMEDIA_FORMAT_RGBA

PJMEDIA_FORMAT_DIB 

Device Independent Bitmap, alias for 24 bit RGB

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.

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

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

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

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.

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.

PJMEDIA_FORMAT_IYUV 

IYUV is alias for I420.

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.

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.

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.

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.

PJMEDIA_FORMAT_I420JPEG 

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

PJMEDIA_FORMAT_I422JPEG 

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

PJMEDIA_FORMAT_H261 

Encoded video formats

◆ pjmedia_format_detail_type

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

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

◆ pjmedia_color_model

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

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

Function Documentation

◆ PJMEDIA_SPF()

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_rateClock rate.
usec_ptimeFrame interval, in microsecond.
channel_countNumber of channels.
Returns
The samples per frame value.

References PJ_INLINE.

Referenced by PJMEDIA_AFD_SPF().

◆ PJMEDIA_SPF2()

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

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

References pjmedia_ratio::denum, and PJ_INLINE.

◆ PJMEDIA_FSZ()

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
bpsThe bitrate of the stream.
usec_ptimeFrame interval, in microsecond.
Returns
Frame size in bytes.

References PJ_INLINE.

Referenced by PJMEDIA_AFD_AVG_FSZ(), and PJMEDIA_AFD_MAX_FSZ().

◆ PJMEDIA_PTIME()

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_rateFrame rate
Returns
The ptime value (in usec).

References pjmedia_ratio::denum, and PJ_INLINE.

◆ PJMEDIA_AFD_SPF()

unsigned PJMEDIA_AFD_SPF ( const pjmedia_audio_format_detail pafd)

◆ PJMEDIA_AFD_AVG_FSZ()

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
afdPointer to pjmedia_audio_format_detail
Returns
Average frame size.

References pjmedia_audio_format_detail::avg_bps, pjmedia_audio_format_detail::frame_time_usec, PJ_INLINE, and PJMEDIA_FSZ().

Referenced by PJMEDIA_PIA_AVG_FSZ().

◆ PJMEDIA_AFD_MAX_FSZ()

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
afdPointer to pjmedia_audio_format_detail
Returns
Average frame size.

References pjmedia_audio_format_detail::frame_time_usec, pjmedia_audio_format_detail::max_bps, PJ_INLINE, and PJMEDIA_FSZ().

Referenced by PJMEDIA_PIA_MAX_FSZ().

◆ pjmedia_format_init_audio()

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
fmtThe format to be initialized.
fmt_idFormat ID. See pjmedia_format_id
clock_rateAudio clock rate.
channel_countNumber of channels.
bits_per_sampleNumber of bits per sample.
frame_time_usecFrame interval, in microsecond.
avg_bpsAverage bitrate.
max_bpsMaximum bitrate.

References pjmedia_format::aud, pjmedia_audio_format_detail::avg_bps, pjmedia_audio_format_detail::bits_per_sample, pjmedia_audio_format_detail::channel_count, pjmedia_audio_format_detail::clock_rate, pjmedia_format::det, pjmedia_format::detail_type, pjmedia_audio_format_detail::frame_time_usec, pjmedia_format::id, pjmedia_audio_format_detail::max_bps, PJ_INLINE, PJMEDIA_FORMAT_DETAIL_AUDIO, PJMEDIA_TYPE_AUDIO, and pjmedia_format::type.

◆ pjmedia_format_init_video()

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
fmtThe format to be initialised.
fmt_idFormat ID. See pjmedia_format_id
widthImage width.
heightImage heigth.
fps_numFPS numerator.
fps_denumFPS denumerator.
avg_bpsAverage bitrate.
max_bpsMaximum bitrate.

◆ pjmedia_format_copy()

pjmedia_format* pjmedia_format_copy ( pjmedia_format dst,
const pjmedia_format src 
)

Copy format to another.

Parameters
dstThe destination format.
srcThe source format.
Returns
Pointer to destination format.

◆ pjmedia_format_get_audio_format_detail()

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
fmtThe format structure.
assert_validIf 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_format_get_video_format_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
fmtThe format structure.
assert_validIf 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.

◆ pjmedia_video_format_mgr_create()

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
poolThe pool to allocate memory.
max_fmtMaximum number of formats to accommodate.
optionsOption flags. Must be zero for now.
p_mgrPointer to hold the created instance.
Returns
PJ_SUCCESS on success, or the appripriate error value.

◆ pjmedia_video_format_mgr_instance()

pjmedia_video_format_mgr* pjmedia_video_format_mgr_instance ( void  )

Get the singleton instance of the video format manager.

Returns
The instance.

◆ pjmedia_video_format_mgr_set_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
mgrThe instance to be used as the singleton instance. Application may specify NULL to clear the singleton singleton instance.

◆ pjmedia_get_video_format_info()

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
mgrThe 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).
idThe format id which format info is to be retrieved.
Returns
The video format info.

◆ pjmedia_register_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
mgrThe 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).
vfiThe 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.

◆ pjmedia_video_format_mgr_destroy()

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

 


PJMEDIA small footprint Open Source media stack
Copyright (C) 2006-2008 Teluu Inc.