











Codec Core Interface - CCI



November 30, 2000













Version
Key Author
Date Prepared
Reviewed by
Review Date
1.0 - Initial Draft
Adam Li
11/30/2000


1.1 - Revised
Adam Li
1/11/2001


1.2 - Decore Interface
Andrea Graziani
2/19/2001









TABLE OF CONTENTS
1.	INTRODUCTION	3
2.	CODEC OPEREATION OVERVIEW	4
3.	INTERFACE PROTOTYPE	5
4.	ENCORE OPERATION	6
4.1.	ENCORE - INITIALIZATION	6
4.2.	ENCORE - ENCODING	6
4.3.	ENCORE - RELEASE	7
5.	DECORE OPERATION	8
5.1.	DECORE - INITIALIZATION	8
5.2.	DECORE - DECODING	9
5.3.	DECORE - RELEASE	9
5.4.	DECORE - SETTINGS	9

1. Introduction 

The core of the codec is the central engine of the codec. It processes the video image and MPEG-4 bitstream, and it does the compression and decompression to convert information between the formats. 

The codec core includes two parts - the encoder and the decoder. The encoder core is named "encore" and the decoder core is named "decore" (any better name there?).

This document discribes the interface into the codec core.
2. Codec Opereation Overview

The encoding by the codec will have the following process:

1. The encore() is called to initialize a new instance and its coding parameters, references and other necessary information.
2. The 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.
3. 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.

The decoding by the codec will have the following process:

1. The decore() is called to initialize a new instance and its coding parameters, references and other necessary information.
2. The 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 all the bitstream is completed. The decore() is called one more time to end the instance and release all the resources allocated for it.

Please note that with this "one-frame-at-a-time" process imposed by Windows, it is not possible to encode B frames for now.
3. Interface Prototype

The interface has the following prototype:

// the prototype of the encore() - main encode engine entrance
int encore(
	unsigned long handle,	// handle	- the handle of the calling entity, must be unique
	unsigned long enc_opt,	// enc_opt	- the option for encoding, see below
	void *param1,		// param1	- the pointer to input parameter structure
	void *param2		// param2	- the pointer to output parameter structure 
);

// the prototype of the decore() - main encode engine entrance
int encore(
	unsigned long handle,	// handle	- the handle of the calling entity, must be unique
	unsigned long dec_opt,	// dec_opt	- the option for decoding, see below
	void *param1,		// param1	- the pointer to input parameter structure
	void *param2		// param2	- the pointer to output parameter structure
);


handle is a unique unsigned long interger for each encore/decore instance.  The codec core will remember the corresponding coding parameters and reference pictures for each unique handle. It can be any value as long as it is unique. The calling application/thread that calls the codec core will provide with the handle so the core knows which instance reference this coming operation is associated with. Usually, the calling thread can use the pointer to the thread (or the instance) itself as the handle to ensure the uniqueness.

enc_opt / dec_opt are the parameters to instruct the core on the operations it needs to perform. param1 / param2 are two parameters whose meaning depending on the operations. Usually, param1 passes a pointer to the parameter structure that inputs to the codec, and param2 passes a pointer to the parameter structure that outputs from the codec.

4. Encore Operation

The encore has the following encoding options.

// encore options (the enc_opt parameter of encore())
#define ENC_OPT_INIT	32768	// initialize the encoder for an handle
#define ENC_OPT_RELEASE 	65536	// release all the resource associated with the handle

The encore return value takes the following values.

// return code of encore()
#define ENC_OK		0
#define	ENC_MEMORY	1
#define ENC_BAD_FORMAT	2

4.1. Encore - Initialization

Encore initialization process goes when ENC_OPT_INIT is set at enc_opt. The encore will initialize a new instance associated with handle.

When ENC_OPT_INIT is set, the calling thread need to provide param1 pointing to the following data structure. param2 has no meaning and should be set to NULL.

typedef struct _ENC_PARAM_ {
	int x_dim;		// the x dimension of the frames to be encoded
	int y_dim;		// the y dimension of the frames to be encoded
	float framerate;		// the frame rate of the sequence to be encoded
	long bitrate;		// the bitrate of the target encoded stream
	long rc_period; 		// the intended keyframe_rate for encoding
	int max_quantizer; 	// the upper limit of the quantizer
	int min_quantizer; 	// the lower limit of the quantizer
	int search_range; 	// the forward search range for motion estimation
	int flip; 			// the flag to indicate whether to flip the input image
} ENC_PARAM;

Encore returns ENC_OK if all the encore process goes all right. Encore returns ENC_MEMORY if there is memory allocation error. 
4.2. Encore - Encoding

Encore encoding process goes when neither ENC_OPT_INIT nor ENC_OPT_INIT 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 calling thread need to provide param1 and param2 pointing to the following data struture. 

typedef struct _ENC_FRAME_ {
	void *bmp;		// the 24-bit bitmap to be encoded
	void *bitstream;		// the buffer for encoded bitstream
	long length;		// the length of the encoded bitstream
} ENC_FRAME;

The bmp points to the input bitmap. The bitstream points to a buffer large enough to hold the output MPEG-4 bitstream. The encore will also set length to indicate how many bytes are written into the bitstream buffer.

typedef struct _ENC_RESULT_ {
	int isKeyFrame; 	// the current frame is encoded as a key frame
} ENC_RESULT;

The isKeyFrame variable is set to 1 if the currented frame is encoded as a key frame, otherwise it is set to 0.

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. 
4.3. Encore - Release

Encore releasing process goes when ENC_OPT_RELEASE is set at enc_opt. The encore will purge all the information and release all the resources allocated for handle, and delete handle from its database.

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

Encore returns ENC_OK.
5. Decore Operation

The decore has the following decoding options.

// decore options
#define DEC_OPT_INIT	0x00008000 // initialize the decoder 
#define DEC_OPT_RELEASE 	0x00010000 // release the resources associated 
#define DEC_OPT_SETPP	0x00020000 // set postprocessing mode
#define DEC_OPT_SETOUT  	0x00040000 // set output mode

The decore returns the following values:

// decore return values
#define DEC_OK		0
#define DEC_MEMORY	1
#define DEC_BAD_FORMAT	2

5.1. Decore - Initialization

Decore initialization process goes when DEC_OPT_INIT is set at dec_opt. The decore will initialize a new instance associated with handle.

When DEC_OPT_INIT is set, the calling thread need to provide param1 pointing to the following data structure. param2 has no meaning and should be set to NULL.

typedef struct _DEC_PARAM_ 
{
    int x_dim; // x dimension of the frames to be decoded
    int y_dim; // y dimension of the frames to be decoded
    unsigned long color_depth; // leaved for compatibility (new value must be NULL)
    int output_format; // output format of the bitmap
} DEC_PARAM;

Decore returns DEC_OK if all the decore process goes all right. Decore returns DEC_MEMORY if there is memory allocation error. 
The output value must be choosed between the following valid formats:

// supported output formats
#define YUV12		1
#define RGB32		2
#define RGB24		3
#define RGB555		4
#define RGB565  	5
#define YUV2    	6

Important: the field color_depth must be NULL (this field is leaved for backward compatibility with the previous release of decore).

5.2. Decore - Decoding

Decore decoding process goes when neither DEC_OPT_INIT nor DEC_OPT_INIT is set at dec_opt. The decore will decode the input bitstream using the coding parameter and reference frame associated with the handle. 

In this operation, the calling thread need to provide param1 pointing to the following data struture. param2 has no meaning and should be set to NULL.

typedef struct _DEC_FRAME_ {
	void *bmp;		// the 24-bit bitmap to be encoded
	void *bitstream;		// the buffer for encoded bitstream
	long length;		// the length of the encoded bitstream
	int render_flag;        // 1: render the bitmap, 0: avoid to render the output in the bmp buffer (dropped frame)
} DEC_FRAME;

The bitstream points to a buffer holding the output MPEG-4 bitstream. The length indicates how many bytes in the bitstream buffer holds the actual bitstream. The bmp points to a bitmap to hold the output image. 
The render_flag is used to speed up the decoder if it is in late. In particular, if render_flag is 0, the decoder will not produce a valid bmp. The renderer should avoid as a consequence to display the returned bmp.

Decore returns DEC_OK if all the decore process goes all right. Decore returns DEC_BAD_FORMAT if the input bitstream does not match the format set at initialization with the current handle. 
5.3. Decore - Release

Decore releasing process goes when DEC_OPT_RELEASE is set at dec_opt. The decore will purge all the information and release all the resources allocated for handle, and delete handle from its database.

When DEC_OPT_RELEASE is set, both param1 and param2 have no meaning and should be set to NULL.

Decore returns DEC_OK.


5.4. Decore - Extra Settings

It is possible to change the output format or the postprocessing level of the decoder using as decoding options DEC_OPT_SETOUT or DEC_OPT_SETPP.
In particular:

To change the output format of the decoder, the user must set the DEC_PARAM structure according to the output format he wants the decoder to write in bmp, then call decore passing as param1 the DEC_PARAM structure and setting DEC_OPT_SETOUT as decoder option. Here's an example:

{
   DEC_PARAM DecParam;
   DecParam.color_depth = NULL;
   DecParam.output_format = RGB32;

  decore(NULL, DEC_OPT_SETOUT, &DecParam, NULL);  // tell the decoder to output in RGB32 mode

  ...
}

To change the postprocessing level of the decoder the user must set the DEC_SET structure in accordance with the postprocessing level desired and call the decore API passing as param1 the DEC_SET structure and setting DEC_OPT_SETPP as decoder option. 

The DEC_SET structure is defined as:

typedef struct _DEC_SET_
{
   int postproc_level; // valid interval are [0..100]
} DEC_SET;

Note that the valid value for postproc_level are integer numbers between 0 and 100. 
Here's a code example:

{
   DEC_SET dec_set;
   dec_set.postproc_level = m_iPPLevel;

   decore(NULL, DEC_OPT_SETPP, &dec_set, NULL);
}

