Xvid core API Overview: Encoding

+ -------------------------------------------------------------------- +

Short explanation for the Xvid data strutures and routines

The encoding part

If you have further questions, visit http://www.xvid.org

+ -------------------------------------------------------------------- +

Document version:

$ ID: xvid-encoder.txt, V 1.3 2002/06/27 14:49:05 edgomez exp $

+ -------------------------------------------------------------------- +

| Abstract

+ -------------------------------------------------------------------- +

This document presents the basic structures and API of XviD. It tries

To explain how to use them to obtain a simple profile compliant MPEG4

Stream feeding the encoder with a sequence of frames.

+ ------------------------------------------------------------------- +

| Document

+ ------------------------------------------------------------------- +

Chapter 1: The Xvid version

+ ----------------------------------------------------------------- +

The Xvid version is defined at library compilation time using

Constant defined in XviD. h

# Define api_version (2 <16) | (1 ))

Where 2 stands for the major Xvid version, and 1 for the minor version

Number.

The current version of the API is 2.1 and shocould be incremented each

Time a user defined structure is modified (xvid_init_param,

Xvid_enc_param... we will discuss about them later ).

When you're writing a program/library which uses the Xvid library, you

Must check your Xvid API version against the available Library

Version. We will see how to check the version number in the next

Chapter.

Chapter 2: The xvid_init_param

+ ----------------------------------------------------------------- +

Typedef struct

{

Int cpu_flags; [in/out]

Int api_version; [out]

Int core_build; [out]

} Xvid_init_param;

Used in: xvid_init (null, 0, & xinit, null );

This tructure is used and filled by the xvid_init function depending

On the cpu_flags value.

List of valid flags for the cpu_flags member:

-Xvid_cpu_mmx: CPU feature

-Xvid_cpu_mmxext: CPU feature

-Xvid_cpu_sse: CPU feature

-Xvid_cpu_sse2: CPU feature

-Xvid_cpu_3dnow: CPU feature

-Xvid_cpu_3dnowext: CPU feature

-Xvid_cpu_tsc: CPU feature

-Xvid_cpu_ia64: CPU feature

-Xvid_cpu_chkonly: Command

-Xvid_cpu_force: Command

In order to set a flag: xinit. cpu_flags | = desired_flag_constant;

1st Case: You call xvid_init without setting the xvid_cpu_chkonly or

The xvid_cpu_force flag, the xvid_init function detects auto magically

The host CPU features and fills the cpu_flags member. The xvid_init

Function also performs all internal function pointers Initialization

According to deteced features and then returns xvid_err_ OK.

2nd Case: You call xvid_init setting the xvid_cpu_chkonly flag,

Xvid_init function will just detect the host CPU features and return

Xvid_err_ OK without initializing the internal function pointers (NB:

The Xvid library is not usable after such a call to xvid_init ).

3rd case: You call xvid_init with the cpu_flags xvid_cpu_force and

Desired feature flags set up (eg: xvid_cpu_sse | xvid_cpu_mmx). In

This case you force Xvid to use the given CPU features passed in

Cpu_flags member. Use this if you know what you're doing.

NB for PowerPC archs: the PPC Arch has not automatic detection,

Library must be compiled for a specific PPC target using the right

Makefile (the cpu_flags is irrevelevant for these archs). Use

Makefile. linuxppc for standard PPC optimized functions and

Makefile. linuxppc_altivec for altivec SIMD optimized functions.

NB for IA64 archs: There's optimized IA64 assembly functions provided

In the library, they must be forced using

Xvid_cpu_force | xvid_cpu_ia64 pair of flags.

To check the Xvid library version against your own Xvid header file,

You have just to call the xvid_init function (no matter the cpu_flags)

And compare the returnded xinit. api_version integer with your

Api_version number. The core_build build Member is not relevant at

Moment but is reserved for future use (when Xvid wowould have reached

Certain stability in its API and releases ).

Chapter 3: xvid_enc_param Structure

+ ----------------------------------------------------------------- +

Typedef struct

{

Int width, height; [in]

Int fincr, fbase; [in]

Int rc_bitrate; [in]

Int rc_reaction_delay_factor; [in]

Int rc_averaging_period; [in]

Int rc_buffer; [in]

Int max_quantizer; [in]

Int min_quantizer; [in]

Int max_key_interval; [in]

Void * handle; [out]

}

Xvid_enc_param;

Used in: xerr = xvid_encore (null, xvid_enc_create, & xparam, null );

This structure has to be filled to create a new encoding instance:

-Width and height.

They have to be set to the size of the image to be encoded.

-Fincr and fbase (<0 forces default value 25fps-[25, 1]).

They are the MPEG-way of defining the framerate. If you have

Integer framerate, say 24, 25 or 30fps, use fincr = 1, fbase = framerate.

However, if framerate is non-integer, like 23.996fps you can

E.g. multiply with 1000, getting fincr = 1000 and fbase = 23996, giving

You integer values again.

-Rc_bitrate (<0 forces default value: 900000 ).

This the desired target bitrate. XviD will try to do its best

Respect this setting but keep in mind Xvid is still in development and

It has not been tuned for very low bitrates.

-Any other rc_xxxx parameter are for the bit rate controler in order

To respect your rc_bitrate setting the best it can. (<0 forces

Default values)

Default's are good enough and you shoshould not change them.

Todo: Describe briefly their impact on the bit rate variations and

The rc_bitrate setting respect.

-Min_quantizer and max_quantizer (<0 forces default values: 1, 31 ).

These 2 memebers limit the range of allowed quantizers. Normally,

Quantizer's range is [1 .. 31], So Min = 1 and max = 31.

NB: the higher the quantizer, the lower the quality.

The higher the quantizer, the higher the compression ratio.

Min_quant = 1 is somewhat overkill, min_quant = 2 is good enough max_quant

Depends on what you encode, leave it with 31 or lower it to something

Like 15 or 10 for better quality (but encoding with very low bitrate

Might fail then ).

-Max_key_interval (<0 forces default value: 10 * framerate = 10 s)

This is the maximum value of frames between two keyframes

(I-frames). keyframes are also inserted dynamically at scene breaks.

It is important to have some keyframes, even in longer scenes, if you

Want to skip position in the resulting file, because skipping is only

Possible from one keyframe to the next. However, keyframes are much

Larger than non-keyframes, so do not use too records of them. A value

Framerate * 10 is a good choice normally.

-Handle

This is the returned internal encoder instance.

Chapter 4: The xvid_enc_frame structure.

+ ----------------------------------------------------------------- +

Typedef struct

{

Int General; [in]

Int motion; [in]

Void * bitstream; [in]

Int length; [out]

Void * image; [in]

Int colorspace; [in]

Unsigned char * quant_intra_matrix; [in]

Unsigned char * quant_inter_matrix; [in]

Int quant; [in]

Int intra; [in/out]

Hintinfo hint; [in/out]

}

Xvid_enc_frame;

Used in:

Xerr = xvid_encore (enchandle, xvid_enc_encode, & xframe, & xstats );

This is the main structure to encode a frame, it gives hints to

Encoder on how to process an image.

-General flag Member.

The general flag Member informs Xvid on general algorithm choices made

By the library client.

Valid flags:

-Xvid_custom_qmatrix: informs Xvid to use the Custom User

Matrices.

-Xvid_h263quant: informs Xvid to use h263 Quantization

Algorithm.

-Xvid_mpegquant: informs Xvid to use MPEG Quantization

Algorithm.

-Xvid_halfpel: informs Xvid to perform a half pixel motion

Estimation.

-Xvid_adaptivequant: informs Xvid to perform an adaptative

Quantization.

-Xvid_lumimasking: infroms Xvid to use a lumimasking algorithm.

-Xvid_lateintra :???

-Xvid_interlacing: informs Xvid to use the MPEG4 interlaced

Mode.

-Xvid_topfieldfirst :???

-Xvid_alternatescan :???

-Xvid_hintedme_get: informs Xvid to return Motion Estimation

Vectors from the ME encoder algorithm. Used during a first pass.

-Xvid_hintedme_set: informs Xvid to use the user given Motion

Estimation vectors as hints for the encoder me algorithms. Used

During a 2nd pass.

-Xvid_inter4v: Forces Xvid to search a vector for each 8x8 Block

Within the 16x16 macro block. This mode shoshould be used only if

The xvid_halfpel mode is activated (this cocould change in

Future ).

-Xvid_me_zero: Forces Xvid to use the zero me algorithm.

-Xvid_me_logarithmic: Forces Xvid to use the logarithmic

Me algorithm.

-Xvid_me_fullsearch: Forces Xvid to use the full search me

Algorithm.

-Xvid_me_pmvfast: Forces Xvid to use the pmvfast me algorithm.

-Xvid_me_epzs: Forces Xvid to use the EPZs me algorithm.

Todo: fill the void entries in flags, and describe briefly each me

Algorithm.

-Motion member.

Valid flags for 16x16 motion estimation (no xvid_inter4v flag in

General flag ).

-Pmv_advanceddiamond16: Xvid has a modified diamond Algorithm

That performs a bit faster than the original one. Use this flag

If you want to use the Speed Optimized diamond serach.

Quality loss is not big (better quality than square search

Less than the normal diamond search ).

-Pmv_halfpeldiamond16: switches the search algorithm from 1 or 2

Full pixels precision to 1 or 2 half pixel precision.

-Pmv_halfpelrefine16: after normal Diamond Search, an extra

Halfpel refinement step is already med. shoshould always be used if

Xvid_halfpel is on, because it gives a rather big increase in

Quality.

-Pmv_extsearch16: normal pmvfast predicts one start vector and

Does Diamond Search around this position. extsearch means that 2

More start vectors are used: (0, 0) and median predictor and

Diamond Search is done for those, too. Makes search slightly

Slower, but quality sometimes gets better.

-Pmv_earlystop16: pmvfast and EPZs stop search if current best

Is below some dynamic threshhold. No diamond search is done,

Only halfpel refinement (if active). Without earlystop Diamond

Search is always done. That wocould be much slower, but not really

Lead to better quality.

-Pmv_quickstop16: Like earlystop, but not even halfpel

Refinement is done. Normally worse quality, so it defaults

Off. Might be removed, too.

-Pmv_unrestricted16: "unrestricted me" is a feature

Mpeg4. it's not implemented, so this flag is ignored (not even

Checked ).

-Pmv_overlapping16: Same as unrestricted. not implemented, nor

Checked.

-Pmv_usesquares16: Replace the diamond search with a square

Search.

Valid flags when using 4 vectors mode prediction. They have the same

Meaning as their 16x16 counter part so we only give the list:

-Pmv_advanceddiamond8

-Pmv_halfpeldiamond8

-Pmv_halfpelrefine8

-Pmv_extsearch8

-Pmv_earlystop8

-Pmv_quickstop8

-Pmv_unrestricted8

-Pmv_overlapping8

-Pmv_usesquares8

-Quant member.

The quantizer value is used when the DCT coefficients are divided

Zero those coefficients not important (according to the target bitrate

Not the image quality

Valid values:

-0 (zero): Then the rate controler chooses the right Quantizer

For you. tipically used in ABR encoding or first pass of A VBR

Encoding session.

-! = 0: Then you force the encoder to use this specific

Quantizer value. It is clamped in the interval

[1 .. 31]. tipically used during the 2nd pass of a vbr Encoding

Session.

-Intra member.

[In usage]

The intra value decides wether the frame is going to be a keyframe or

Not.

Valid values:

-1: forces the encoder to create a keyframe. Mainly used

A vbr 2nd pass.

-0: forces the encoder not to create a keyframe. minaly used

During a VBR second pass

--1: Let the encoder decide (based on contents and

Max_key_interval). Mainly used in ABR mode and dunring a 1st

VBR pass.

[Out usage]

When first set to-1, the encoder returns the valid keyframe state

Of the frame.

-0: the resulting frame is not a keyframe

-1: The resulting frame is a keyframe (Scene Change ).

-2: The resulting frame is a keyframe (max_keyframe Interval

Reached)

-Quant_intra_matrix and quant_inter_matrix members.

These are pointers to a pair of user quantization matrices. You

Must set the general xvid_custom_qmatrix flag to make sure Xvid uses

Them.

When set to null, the default Xvid matrices are used.

NB: each time the matrices change, Xvid must write a header into

Bitstream, so try not changing these matrices very often. This will

Save space.

Chapter 5: The xvid_enc_stats Structure

+ ----------------------------------------------------------------- +

Typedef struct

{

Int quant; // [out] frame Quantizer

Int hlength; // [out] header length (bytes)

Int kblks, keys KS, ublks; // [out]

} Xvid_enc_stats;

Used in:

Xerr = xvid_encore (enchandle, xvid_enc_encode, & xframe, & xstats );

In this structure the encoder return statistical data about

Encoding Process, e.g. To be saved for two-pass-encoding. quant is

The quantizer chosen for this frame (if you let ratecontrol do it)

Hlength is the length of the frame's header, including motion

Information etc. kblks, keys KS, ublks are unused at the moment.

Chapter 6: The xvid_encode Function

+ ----------------------------------------------------------------- +

Int xvid_encore (void * handle,

Int opt,

Void * param1,

Void * param2 );

Xvid uses a single-function API, so everything you want to do is done

By this routine. The opt parameter chooses the behaviour of

Routine:

Xvid_enc_create: Create a New encoder, xvid_enc_param in param1,

Handle to the new encoder is returned in handle.

Xvid_enc_encode: encode one frame, XVID_ENC_FRAME-structure in param1,

Xvid_enc_stats in param2 (or null, if you are not interested in

Statistical data ).

Xvid_dec_destroy: Shut down this encoder, do not use handle afterwards.