DivX MPEG-4 Codec and Its Interface

December 6, 2002

Version

Key Author

Date Prepared

Reviewed by

Review Date

1.0 - Initial Draft

Adam Li

6/24/2001

Eugene Kuznetsov

5/15/2001

1.1 Decore Operation

Andrea Graziani

7/3/2001

Eugene Kuznetsov

7/10/2001

1.2 5.0 Encore

Adam Li

3/10/2002

John Funnell

Eugene Kuznetsov

Andrea Graziani

Darrius Thompson

3/11/2002

3/12/2002

03/13/2002

1.3 - 5.03 Encore Eugene Kuznetsov 06/24/2002    
1.4 - 5.03 Decore Eugene Kuznetsov 10/27/2002    
1.5 - 5.03 Encore Eugene Kuznetsov 12/06/2002    

 

 

1. Introduction

The DivX MPEG-4 Codec is a Windows installable driver. In other words, it is a DLL (dynamic linked library) that can be installed into the Windows system, and be loaded and called by any Windows applications that need to access the function of the codec.

The name of the DivX MPEG-4 Codec DLL is DivX.dll.

The center of DivX MPEG-4 Codec is the DivX codec core. It is the engine of the codec. The codec core processes either the video image or MPEG-4 bitstream, and it uses the compression and decompression to convert information between the formats. The codec core includes two parts an encoder (that compresses the video image into MPEG-4 bitstreams) and a decoder (that decompresses the MPEG-4 bitstream back into video images). The encoder core is named encore, and the decoder core decore.

The DivX.dll encapsules the DivX codec core, so the Windows application can access the codec core through the Windows installable driver interface. In addition, application can also access the codec core functionalities by directly call the codec core functions.

This document discribes the interface into DivX MPEG-4 Codec through both Windows installable driver interface and the codec core interface.

2. Interface Through the Windows Installable Driver

As specified by Windows, the entry point to the DivX MPEG-4 Codec through the Windows installable driver interface is through the DriverProc() function. DivX MPEG-4 Codec follows and processes all the Video for Windows (VfW) messages. For more details on the messages, please refer to the the page on Microsoft site:

http://msdn.microsoft.com/library/default.asp?url=/library/en-us/multimed/hh/multimed/avifile_8dgz.asp

In particular, message ICM_CONFIG will instruct the codec DLL to pop up a configuration window, enabling users to configure the process and parameters for the DivX MPEG-4 Codec. The significance of the parameters can be found in later sections of this document.

3. Interface Through the Codec Core Interface - Operation Overview

Before we go into the detail of the interface through the codec core functions, first let us go over a brief overview on the operation process of the codec core.

The encoding by the codec will have the following process:

For single-pass encoding:

1.       Encore() is called to initialize a new instance and its coding parameters, references and other necessary information.

  1. Encore() is called once for each frame to be encoded. The input will be the video frame to codec and its coding parameter. The output will be the compressed MPEG-4 bitstream.
  2. After all the video frames are completed. The encore() is called one more time to end the instance and release all the resources allocated for it.

For two-pass encoding:

The above single-pass encoding will be executed twice. In the first pass, the codec will measure and record the complexity of the video (without writing the actually bitstream). The result is the analyzed to determine the best parameters for each frame of encoding (currently this is done outside of encore). In the second pass, the codec will encode the video accordingly and output the actual MPEG-4 bitstream.

The decoding by the codec will have the following process:

1.       Decore() is called to initialize a new instance and its coding parameters, references and other necessary information.

2.       Decore() is called once for each frame to be encoded. The input will be the compressed MPEG-4 bitstream.The output will be the decodec video frame.

3.       After the entire bitstream is completed, ecore() is called one more time to end the instance and release all the resources allocated for it.

4. Encore Operation

The encore interface has the following prototype:

// the prototype of the encore() - main encode engine entrance
int encore(void* handle, int enc_opt, void *param1, void *param2);

handle is a unique non-NULL handle of the instance of the encoder. It is returned when encoder is requested to create a new instance. Most calls to encore() require a valid value of handle.

Acceptable values for enc_opt are:

// encore options (the enc_opt parameter of encore())
#define ENC_OPT_INIT 0
#define ENC_OPT_RELEASE 1
#define ENC_OPT_ENCODE 2
#define ENC_OPT_ERRORCODE3
#define ENC_OPT_VERSION 4
#define ENC_OPT_SETDEBUG 5

#define ENC_OPT_TAGNAME 6
#define ENC_OPT_PROFILE 7


Return value of encore() can be one of the following:

// return code of encore()
#define ENC_BUFFER -2
#define ENC_FAIL -1
#define ENC_OK 0
#define ENC_MEMORY 1
#define ENC_BAD_FORMAT 2
#define ENC_INTERNAL 3

4.1. Encore Initialization

Before initialization, caller should verify that version of codec executable corresponds to the version of used header file. To do this, version of codec executable can be retrieved using the following sample code:

int iVersionBinary = encore(0, ENC_OPT_VERSION, 0, 0);
int iVersionHeader = ENC_VERSION;
if(iVersionBinary != iVersionHeader)
// interfaces are incompatible, encoding cant be performed
        return 1;

To create an instance of encoder, call encore() with enc_opt set to ENC_OPT_INIT. You need to provide handle pointing to the variable of type void* that will hold a handle, param1 pointing to DivXBitmapInfoHeader structure describing input format and param2 pointing to SETTINGS structure describing desired encoder settings.

DivXBitmapInfoHeader is binary compatible with a standard Win32 API structure BITMAPINFOHEADER and contains information about the dimensions and color format of the bitmap (in this case, of encoder input format). It is defined as follows:

typedef struct tagDivXBitmapInfoHeader
{
uint32_t biSize;
int32_t biWidth;
int32_t biHeight;
uint16_t biPlanes;
uint16_t biBitCount;
uint32_t biCompression;
uint32_t biSizeImage;
int32_t biXPelsPerMeter;
int32_t biYPelsPerMeter;
uint32_t biClrUsed;
uint32_t biClrImportant;
} DivXBitmapInfoHeader;

biSize must be set to the size of structure. biCompression and ( in case of RGB colorspaces ) biBitCount must be initialized. biWidth and biHeight define the dimensions of picture. They must be positive, biWidth must be multiple of 4 and biHeight must be multiple of 2. It is recommended for optimal performance and compression efficiency to operate on dimensions, multiple of 16.
biCompression has to contain one of valid FOURCC codes. The following macro can be used to define the FOURCC on low-endian machine:

#define FOURCC(A, B, C, D) ( ((uint8_t) (A)) | (((uint8_t) (B))<<8) | (((uint8_t) (C))<<16) | (((uint8_t) (D))<<24) )
uint32_t fccYV12=FOURCC(Y, V, 1, 2); // fourcc YV12


List of combinations of biCompression and biBitCount, supported by encoder:

biCompression

BiBitCount format remarks
0 24 24-bit RGB order of components in memory B-G-R
0 32 32-bit RGB  
"YUY2", "YUYV", "V422" n/a packed 4:2:2 YUV, order Y-U-Y-V

UYVY

n/a packed 4:2:2 YUV, order U-Y-V-Y

"YVYU"

n/a packed 4:2:2 YUV, order Y-V-Y-U
I420, IYUV n/a Planar 4:2:0 YUV, order Y-U-V
YV12 n/a Planar 4:2:0 YUV, order Y-V-U

Note that 16-bit RGB input is not supported. It is generally not recommended to use 8 or 16-bit RGB as an intermediate formats prior to compression.


SETTINGS structure is defined as:

typedef struct
{
int vbr_mode;
int bitrate;
float quantizer;
int use_bidirect;

int input_clock;
int input_frame_period;
int internal_timescale;

int max_key_interval;
int key_frame_threshold;

int vbv_bitrate;
int vbv_size;
int vbv_occupancy;

double complexity_modulation;
const char* log_file_read;
const char* log_file_write;
const char* mv_file;

int deinterlace;
int quality;
int data_partitioning;
int quarter_pel;
int use_gmc;

int psychovisual;
double pv_strength_frame;
double pv_strength_MB;

int interlace_mode;

int enable_crop;
int enable_resize;

int resize_width;
int resize_height;
int crop_left;
int crop_right;
int crop_top;
int crop_bottom;

int resize_mode;
double bicubic_B;
double bicubic_C;

int temporal_enable;
int spatial_passes;
double temporal_level;
double spatial_level;

void* custom_rc;
void* custom_preproc;
void* custom_encoder;
void* custom_callback;
} SETTINGS;

Encore returns ENC_OK if initialization process is successful. Otherwise it returns an error code.

All parameters in SETTINGS structure can be set to 0, in which case they'll be initialized to default values, or can be specified directly.

internal_timescale can be used to set MPEG-4 stream timescale parameter. Valid range is 1 to 65535, if it is set to 0, default value of 30000 will be used.

input_clock and input_frame_period define framerate of input video. input_clock divided by input_frame_period is equal to framerate in frames per second.

The max_key_interval sets the maximum interval between the key (INTRA) frames. In the one-pass mode, the key frame is automatically inserted in the encoding when codec detects scene change. In the case that the scene goes a long stretch without a cut, a key frame will be inserted to insure the interval to be always less or equal than the set maximum key frame interval.

The quality parameter determines the motion estimation algorithm the encore will perform on the input frames. For the higher quality settings, more thorough motion search will be performed. This will usually results in a better match of the blocks, and hence fewer bits needed for coding the residue texture errors. In the other words, the quality of the decoded video will be better for the same resulting bitrate.

The signal parameters in the following should be set to non-zero values to make signal activate the feature, and zero values to signal not-activate of the feature. The use_bidirect parameter signals using of B-frame video coding. The data_partitioning signals using of data partitioning. The quarter_pel signals using of quarter pixel motion compensation mode. The key_frame_threshold signals a threshold for the codec to decide between I and P frames. The default value is 50. The psychovisual parameter signals the using of psychovisual enhancement mode. The pv_strength_frame and pv_strength_MB convey the strength of the psychovisual enhancement at frame and MB level. The value should be between 0 and 1.

The interlace_mode may be set to one of three settings:

0 = Encode all frames as progressive no processing here,
1 = Encode all frames as interlaced - frames will be encoded using special syntax for interlaced content,
2 = Deinterlace all frames - an adaptive frame deinterlace will be applied to every frame,
3 = Intelligent IVTC/deinterlace - warrants its own paragraph

The Intelligent IVTC deinterlace is a special mode of the codec that allows it to process content that is any mixture of interlaced, frame progressive and 3:2 pulldown material. Interlaced sections will be deinterlaced and encoded at frame rate. Frame progressive sections are encoded as-is. An IVTC process is applied to 3:2 pulldown material before encoding. The IVTC processes means that the one-to-one relationship between input bitmaps and output encoded frames is broken.

The encoder is able to crop and/or resize the image prior to encoding. To crop the image, first set enable_crop to 1 (default is 0 off). The four crop parameters crop_left, crop_right, crop_top and crop_bottom must then be set. For example, setting crop_top = 8 and the others to 0 will remove the top 8 lines from the picture.

By default, the size of the encoded image will be the dimensions of the input image after subtracting any crop values. To encode at a different resolution, set enable_resize = 1 (default is 0 off) and the resize_width and resize_height to the desired encoding resultion. Currently, two resize algorithms are implanted: Bilinear and bicubic. To use the bilinear resize, set resize_mode = 0 (default). For the bicubic resize, set resize_mode = 1. The constants bicubic_B and bicubic_C are spline parameters which influence the characteristics of the resized image. It is recommended to use the Cartmull-Rom Spline (resize_mode = 0, bicubic_B = 0, bicubic_C = 0.5) or the bilinear algorithm (resize_mode = 1) according to personal preference.

Two noise-reduction prefilters are incorporated into the encoder. One is a temporal filter and the other spatial. To enable the temporal filter, set temporal_enable = 1 (default is 0 off). spatial_level should then be set in the range 0.0 (off) to 1.0 (full strength spatial filtering). To enable the spatial filter, set spatial_passes in the range 1 to 3 (default is 0 off). Likewise, then set spatial_level in the range 0.0 (off) to 1.0 (full strength spatial filtering).

The string mv_file gives the name of the file that codec used to same some coding information in the first pass of the 2-pass encoding. The same file will be provided in the second pass to provide the information to expedite the encoding process.

custom_rc, custom_preproc, custom_encoder, and custom_callback pointers can be used to provide external objects to encoder as implementations of rate control, preprocessing module, low-level encoder and user interaction module. Refer to headers architecture.h and IEncoreCallback.h for details.

4.2. Encore Encoding

Encore encoding process starts when ENC_OPT_ENCODE is set at enc_opt. The encore will encode the input video frame using the coding parameter and reference frame associated with the handle.

In this operation, the caller need to provide param1 pointing at the structure of type ENC_FRAME and param2 pointing at the structure of type ENC_RESULT.

typedef struct _ENC_FRAME_ {
void *image;
void *bitstream;
int length;
int produce_empty_frame;
} ENC_FRAME;

The image points to the input bitmap. The bitstream points to a buffer large enough to hold the output MPEG-4 bitstream. Checks for buffer overflow are normally not performed. Theoretical upper limit of frame size is around 6 bytes/pixel or 2.5 Mb for 720x576 frame. On success, encore will also set length to indicate how many bytes are written into the bitstream buffer.

Encoder is most effective with planar YUV 4:2:0 as its input. Conversion from "UYVY" format is currently not optimized.

The ENC_RESULT parameter is used for the encore to return some results of the encoding operation.

typedef struct _ENC_RESULT_ {
/** same as before **/
int iMotionBits;
int iTextureBits;
/* int iSegmentationBits; */
int iTotalBits;
int iStuffingBits;
int iQuant;
int iSequenceNumber;
int iMvSum;
int iMvCount;

char cType;
/** which frame this one turned out to be **/
/** can be '\0' - no frame produced */

int iDisplayTimestamp; } ENC_RESULT;

Encore returns ENC_OK if all the encore process goes all right. Encore returns ENC_BAD_FORMAT if the input frame format does not match the format set at initialization with the current handle.

When the interlace_mode is set to 2 (Intelligent IVTC/deinterlace) the one-to-one relationship between bitmaps and encoded frames is broken. For example, several ENC_OPT_ENCODE operations may be performed before the encoder begins to return bitstream. Similarly, calling ENC_OPT_ENCODE with a new frame may allowencore to encode two or more frames due to the ivtc process. The ENC_OPT_ENCODE calling convention has been enhanced to deal with this special case. If the encoder cannot return compressed bitstream due to the ivtc process, then it returns with ENC_FRAME::length < 0. If the encoder does produce bitstream (i.e. ENC_FRAME::length >= 0), then it is possible that it can produce a second or third frame. Repeated calls should be made to encore, with ENC_FRAME::image set to 0, until ENC_FRAME::length < 0.

4.3. Encore - B-frames usage

A special paragraph must be dedicated to discussion of encoding when use_bidirect field is set to 1 in SETTINGS structure that was used to construct the encoder. In this case encoder will produce encoded frames in "decoding order". Consider this example:

Frame 1 - I
Frame 2 - B
Frame 3 - P

In order to display frame 2, it is necessary to decode frame 3 first, because frame 2 is backwards predicted from frame 3. The order of frames "132" is called "decoding order". It is the order in which encoder will produce frames. Naturally, it cannot encode frame 3 before it has seen it, so the second call to encore() will not produce any output - cType field in ENC_RESULT structure will be set to '\0'. Frame 2 will be cached inside the encoder for future use.
When output of encoder is wrapped into a file format that is not aware of existence of B-frames ( such as AVI ), a technique called "VOP grouping" can be applied to make sure that frame-in frame-out decoder does not have to introduce any delay in its output. See "DivX MPEG-4 Video and Containers" document for details. This process is optional and external to the codec. Not coded VOPs, mentioned in the document, can be produced by calling encore() with enc_opt set to ENC_OPT_ENCODE and produce_empty_frame field of ENC_FRAME set to 1.

4.4. Encore Release

Instance of the encoder can be destroyed by calling encore() with enc_opt set to ENC_OPT_RELEASE. The library will purge all the information and release all the resources allocated for handle.

When ENC_OPT_RELEASE is set, both param1 and param2 have no meaning and can be set to NULL.

Encore returns ENC_OK if handle was successfully destroyed.

4.5. Encore - Other options

Encoder binaries are available in several profiles. The profile of used binary can be determined with call to encore() with enc_opt set to ENC_OPT_PROFILE:

char profile = (char) encore(0, ENC_OPT_PROFILE, 0, 0);

Possible values include:

'S' - 'Standard' version, with several advanced features ( B-frames, GMC, quarter-pel, preprocessing, etc. ) disabled.
If unavailable feature is requested from codec, value in SETTINGS structure will be reset to zero during initialization.
'P' - 'Professional' ( full-featured ) version, protected with serial number. Available for Windows only.
'A' - 'Ad-supported' version. Provides the same set of features as 'Professional', does not need a serial number, but requires a special software to be installed and running in the background. Available for Windows only.
'U' - 'Unprotected' version. As the name implies, it is a version with full set of features and no protection against illegal copying.

ENC_OPT_ERRORCODE, ENC_OPT_SETDEBUG, and ENC_OPT_TAGNAME options are reserved for future or internal use.

5. Decore Operation

5.1. Interface function declaration.


int decore(void* handle, int dec_opt, void* param1, void* param2);

dec_opt can have the following values:

#define DEC_OPT_INIT 1
#define DEC_OPT_RELEASE 2
#define DEC_OPT_SETOUT 3
#define DEC_OPT_ADJUST 4
#define DEC_OPT_FRAME 5
#define DEC_OPT_INIT_VOL 6
#define DEC_OPT_FLUSH 7
#define DEC_OPT_VERSION 8
#define DEC_OPT_SETDEBUG 9
#define DEC_OPT_CONVERTYUV 10
#define DEC_OPT_CONVERTYV12 11

5.2. Initialization


Decoder instance is created when decore() is called with dec_opt == DEC_OPT_INIT. handle points to void* placeholder for the newly created handle. param1 is optional and points to DEC_INIT structure or is set to 0. param2 is unused.

DEC_INIT structure contains optional settings for the decoder.

typedef struct
{
uint32_t codec_version;
uint32_t smooth_playback;
void* (*alloc) (uint32_t);
void (*free) (void*);
} DEC_INIT;

codec_version should be set to the version of format if it is known externally. Use 0 for general MPEG-4 compliant content, 311 for DivX 3.11/3.20, 412 for DivX 4.

smooth_playback is a feature that allows to even the CPU load when decoder is used to decode streams which use VOP grouping ( see "DivX MPEG-4 Video and Containers" document ). When smooth_playback is 0 ( default ), decoder always produces no-delay output but may occasionally need to decode 2 VOPs during one call. When smooth_playback is 1, decoder never decodes more than 1 VOP per call, but introduces a delay of 1 frame if input uses VOP grouping.
If input stream does not contain B-frames, smooth_playback is ignored.

alloc and free provide the decoder with option to use external memory allocation function rather than standard C library malloc/free. They can be set to 0.

Example:

void* handle;
DEC_INIT di;
memset(&di, 0, sizeof(di));
int err=decore(&handle, DEC_OPT_INIT, &di, 0);
if(err!=DEC_OK)
{
assert(!handle);
// abort process
}
assert(handle);

5.3. Setting output format

Decoder is able to produce the uncompressed output in the variety of standard RGB and YUV formats, which are listed below. To select the desired output format, use decore() call with dec_opt set to DEC_OPT_SETOUT and param1 set to the pointer to the DivXBitmapInfoHeader structure ( see paragraph 4.1 for definition of DivXBitmapInfoHeader ).

biSize must be set to the size of structure. biCompression and ( in case of RGB colorspaces ) biBitCount must be initialized. biWidth and biHeight define the dimensions of picture. In all RGB modes it is legal to set biHeight to negative value; itll mean that the decoder has to flip the output buffer. Decoder will ignore all other fields.

List of combinations of biCompression and biBitCount, supported by decoder:

biCompression

BiBitCount format remarks
0 24 24-bit RGB order of components in memory B-G-R
0 32 32-bit RGB Alpha plane set to 0
0 16 16-bit RGB (555)
3 16 16-bit RGB (565) See remark 1
"ARGB" 32 32-bit RGB Alpha plane set to 255
"ABGR" 24 24-bit BGR order of components in memory R-G-B
"ABGR" 32 32-bit BGR order of components in memory R-G-B-A
"YUY2" n/a packed 4:2:2 YUV, order Y-U-Y-V

UYVY

n/a packed 4:2:2 YUV, order U-Y-V-Y
I420, IYUV n/a Planar 4:2:0 YUV, order Y-U-V
YV12 n/a Planar 4:2:0 YUV, order Y-V-U

USER

n/a No output See remark 2

Remark 1. Use the following sample code to request 16-bit 565 output:

void* handle;
// create the instance of decoder here
int iSize= sizeof(DivXBitmapInfoHeader)+12;
DivXBitmapInfoHeader* pbi=malloc(iSize);
memset(pbi, 0, iSize);
pbi->biSize= iSize;
pbi->biCompression=3;
pbi->biBitCount=16;
uint32_t* piColor=(uint32_t*) (pbi+1);
piColor[0]=0xf800;
piColor[1]=0x07e0;
piColor[2]=0x001f;
int iErr=decore(handle, DEC_OPT_SETOUT, pbi, 0);
free(pbi);

Remark 2. Output format, selected by setting biCompression to USER, is not a standard format. It can used if the application does not want the decoder to do any rendering or color space conversion. When a frame is decoded with this format chosen as output format, output buffer is not modified. You still can use the contents of DEC_FRAME_INFO structure ( see below ) to access the data.

5.3.1. Output formats and image dimensions

There are two possible sources for the dimensions of video stream.
First, the dimensions can be stored in the special fields of wrapper format used to store the video ( for example, AVI ). This is the only way to know the dimensions of DivX 3.11 video stream. Second, the same information is stored in one of the headers, named VOL or video object layer header, of any MPEG-4 compliant ( such as DivX 4.x or newer ) stream.
Former versions of decore API required the application to either keep the dimensions in the wrapper format or to do various tricks to get this information from the stream. There was no straightforward way to do it.
5.1 API deals with it by allowing the application to create an instance of decoder without knowing the dimensions beforehand. The following are most typical scenarios:
(1)
Decoder is used to decode stream, wrapped in AVI format or other format that keeps track of dimensions.
An instance of decoder is created with call to decore(DEC_OPT_INIT). Dimensions are taken from the AVI headers and used to initialize biWidth and biHeight fields of DivXBitmapInfoHeader ( with optional reversing the sign of biHeight ). Output format is set with decore(DEC_OPT_SETOUT).
(2) Decoder is used to decode stream, wrapped in MP4 video format.
In MP4 video files video object layer header is located in a special area known as decoder-specific info area.
In this case the call to decore(DEC_OPT_INIT) is followed by the call to decore(DEC_OPT_INIT_VOL). This call is similar in syntax to DEC_OPT_FRAME ( see below ), except that application passes the pointer to DEC_VOL_INFO structure as param2:

typedef struct
{
uint32_t x_dim; // x dimension of the frames to be decoded
uint32_t y_dim; // y dimension of the frames to be decoded
uint32_t output_format; // output color format
uint32_t time_incr;
uint32_t codec_version;
uint32_t build_number;
uint32_t prefixed;
} DEC_VOL_INFO;


Decoder will parse the header and return the dimensions of the picture. They can be used to perform the call to decore(DEC_OPT_SETOUT) before starting decoding.
(3) Decoder is used to decode stream, wrapped in any other simple video format. In this case all key-frames of the stream ( 1st frame of any stream is always a key-frame ) will be prefixed with the named header. So, instead of passing the header to decore(DEC_OPT_INIT_VOL), application can just pass the 1st frame. Naturally, 1st frame has to be passed to the decoder twice
once with the call to decore(DEC_OPT_INIT_VOL) and once with the first call to decore(DEC_OPT_FRAME).

Finally, if the application does not specify the output video format at all ( no calls to DEC_OPT_SETOUT take place ), there are two possible outcomes. If the decoder knows the dimensions of stream ( it found the valid VOL header in the first frame or received it with the direct call ), it will operate as if application has requested USER output format. Otherwise, all attempts to call decore(DEC_OPT_FRAME) will fail with DEC_BAD_FORMAT error.

5.4. Decoding

Decoding frames is performed by calling decore with dec_opt set to DEC_OPT_FRAME, param1 set to pointer to DEC_FRAME structure, and param2 set either to pointer to DEC_FRAME_INFO structure or to 0.

typedef struct
{
void *bmp; // decoded bitmap
const void *bitstream; // decoder buffer
uint32_t length; // length of the decoder stream
uint32_t render_flag; // 1: the frame is going to be rendered
uint32_t stride; // decoded bitmap stride
} DEC_FRAME;

typedef struct
{
const int *quant_store;
int quant_stride;
int prediction_type;
int frame_length;
int frame_num;
int vop_coded;
void* y;
void* u;
void* v;
int stride_y;
int stride_uv;
} DEC_FRAME_INFO;

bitstream should point to the bitstream to decode, and length should contain length of the bitstream in bytes, if known. Buffer, pointed to by bitstream, should be at least length+8 bytes long.

render_flag specifies whether the decoded image should be rendered. If it is not 0, decoder will perform the color space conversion, prostprocessing and write the processed image into the buffer pointed by bmp. If it is 0, no rendering will occur. If render_flag is 0, bmp can be 0 as well.

stride specifies the desired stride of output bitmap, in pixels. It should be set to 0 ( to make stride equal to width of video ) or to any number equal or larger than width.

DEC_FRAME_INFO is an output structure, it can be used to get extended information about decoded frame.

5.5. Releasing the decoder

To release the instance of the decoder, simply call decore() with handle set to the instance handle and dec_opt set to DEC_OPT_RELEASE. param1 and param2 are ignored.

5.6. Changing output format in run-time

Call decore() with dec_opt set to DEC_OPT_SETOUT and param1 pointing to new DivXBitmapInfoHeader structure. It will return DEC_OK if new format is acceptable, DEC_MEMORY if param1 does not point to valid memory, DEC_BAD_FORMAT if new format is not acceptable.

It is legal to perform this call with handle set to 0 to query if specified output format is acceptable.

5.7. Setting postprocessing and other filters

Call decore() with dec_opt set to DEC_OPT_ADJUST, param1 pointing to integer that specifies parameter to adjust ( such as postprocessing level, warmth, brightness, contrast, saturation ) and param2 pointing either to the new value or to the placeholder for the current value, depending on whether the decoder is requested to retrieve or to set the value.

Valid settings are 0..60 for postprocessing, -128..127 for brightness, contrast and saturation, and 0..8 for warmth.

Example.

int32_t iInstruction=DEC_ADJ_POSTPROCESSING | DEC_ADJ_RETRIEVE;
int32_t iPostproc;
decore(handle, DEC_OPT_ADJUST, &iInstruction, &iPostproc);
iInstruction=DEC_ADJ_POSTPROCESSING | DEC_ADJ_SET;
iPostproc++;
decore(handle, DEC_OPT_ADJUST, &iInstruction, &iPostproc);

5.8. Miscellaneous

DEC_OPT_VERSION option can be used to retrieve binary version of the API.

int32_t iVersion=decore(0, DEC_OPT_VERSION, 0, 0);

Known values are 20020304 for DivX 5.0, 20020322 for DivX 5.0.1-5.0.2, 20021027 for DivX 5.1.

DEC_OPT_SETDEBUG option provides access to debug features such as disabling motion compensation, etc.

DEC_OPT_CONVERTYUV and DEC_OPT_CONVERTYV12 allow to use decoder for the conversion from planar YUV formats to currently selected color space.

DEC_OPT_FLUSH deals with seeking issues when smooth mode is on.