Xvid core API Overview: Decoding

**************************************** *********************

* Short explanation for the Xvid data strutures and routines

*

* Decoding part

*

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

*

**************************************** **********************/

/* These are structures/routines from XviD. h needed for decoding */

--------------------------------------------------------------------------

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

This is the revision of the XviD. h file that you have in front of you.

Check it against

Library's version.

--------------------------------------------------------------------------

Typedef struct

{

Int cpu_flags; [in/out]

Int api_version; [out]

Int core_build; [out]

} Xvid_init_param;

This is filled by xvid_init with the correct CPU flags for initialization

(Auto-detect), unless you pass flag to it (cpu_flags! = 0). Do not use that

Unless you really know what you are doing.

Api_version can (shocould) be checked against api_version, to see if you

Have the Right core library.

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

--------------------------------------------------------------------------

Typedef struct

{

Int width; [in] (shocould be a multiple of 16, Max is)

Int height; [in] (shocould be a multiple of 16, Max is)

Void * handle; [out]

} Xvid_dec_param;

When creating decoder, you have to provide it with height and width of

Image to decode (this is _ not _ in the bytestream itself !).

In handle a unique handle is given back, that has to be used to identify

This instance of decoding.

Used in: xerr = xvid_decore (null, xvid_dec_create, & xparam, null );

--------------------------------------------------------------------------

Typedef struct

{

Void * bitstream; [in]

Int length; [in]

Void * image; [in]

Int stride; [in]

Int colorspace; [in]

} Xvid_dec_frame;

This is the main structure for decoding itself. You provide

MPEG4-bitstream and it's length,

Image is the position where the decoded picture shoshould be stored.

Stride is the difference between the memory address of the first pixel

A row in the image and the first pixel of the next row. If the image is

Going to be one big block, then stride = width, but by making it larger you

Can create an "edged" picture.

By colorspace the output format for the image is given, xvid_csp_rgb24 or

Xvid_csp_yv12 might be might common.

A special case is xvid_csp_user. If you use this, then * image will not

Filled with the image but with a structure that contains pointers to

Decoder's internal representation of it. That's faster, because no memcopy

Is involved, but don't use it, if you don't know what you're re doing.

Used in: xerr = xvid_decore (dechandle, xvid_dec_decode, & xframe, null );

--------------------------------------------------------------------------

Int xvid_decore (void * handle, [in/out]

Int opt, [in]

Void * param1, [in]

Void * param2); [in]

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

This routine. The opt parameter chooses the behaviour of the routine:

Xvid_dec_create: Create a New decoder, xvid_dec_param in param1,

A handle to the new decoder is returned in handle

Xvid_dec_decode: Decode one frame, XVID_DEC_FRAME-structure in param1

Xvid_dec_destroy: Shut down this decoder, do not use handle afterwards