|
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 |
|
|
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.
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.
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.
- 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.
- 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.
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_ERRORCODE 3
#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
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 can’t 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.
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.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; it’ll 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.
