DivXNetworks, Inc.
Main Page | Namespace List | Data Structures | Directories | File List | Namespace Members | Data Fields | Globals | Related Pages

LibQDec.h File Reference


Detailed Description

$Id: LibQDec.h 5136 2005-11-14 19:43:50Z ekuznetsov $

Copyright (c) 2002-2004 DivX, Inc. All rights reserved.

This software is the confidential and proprietary information of DivX, Inc.,
Inc. and may be used only in accordance with the terms of your license from
DivX, Inc.

Decoder API header file. Contains the entrance function of the decoder core.

#include "../common/FourCC.h"
#include "../common/FormatInfo.h"

Go to the source code of this file.

Data Structures

struct  DecInit
struct  DecBitstream
 Structure containing compressed video bitstream. More...
struct  DecInfo
 Structure used to obtain information about the decoded video. More...
struct  DecFrame

Defines

#define DEC_OPT_INIT   0
#define DEC_OPT_RELEASE   1
#define DEC_OPT_INFO   2
#define DEC_OPT_FRAME   3
#define DEC_OPT_SET   4
#define DEC_OPT_FLUSH   5
#define DEC_PAR_OUTPUT   0
#define DEC_PAR_POSTPROCESSING   1
#define DEC_PAR_POSTPROCDEBLOC   2
#define DEC_PAR_POSTPROCDERING   3
#define DEC_PAR_WARMTHLEVEL   4
#define DEC_PAR_CONTRAST   5
#define DEC_PAR_BRIGHTNESS   6
#define DEC_PAR_SATURATION   7
#define DEC_PAR_LOGO   8
#define DEC_PAR_SMOOTH   9
#define DEC_PAR_SHOWPP   10
#define DEC_OK   0
#define DEC_INVALID_SYNTAX   -1
#define DEC_FAIL   1
#define DEC_INVALID_ARGUMENT   3
#define DEC_NOT_IMPLEMENTED   4

Typedefs

typedef DecInit DecInit
typedef DecBitstream DecBitstream
typedef DecInfo DecInfo
typedef DecFrame DecFrame
typedef int( LibQDecoreFunction )(void *pHandle, int decOpt, void *pParam1, void *pParam2)

Functions

LibQDecoreFunctiongetDecore (unsigned long fccFormat)


Define Documentation

#define DEC_FAIL   1
 

General failure message. An unexpected problem occourred.

#define DEC_INVALID_ARGUMENT   3
 

One of the arguments passed to the decoder is invalid.

#define DEC_INVALID_SYNTAX   -1
 

A semantic error occourred while parsing the stream.

#define DEC_NOT_IMPLEMENTED   4
 

The stream requires tools that have not been implemented.

#define DEC_OK   0
 

Decoder call succeded.

#define DEC_OPT_FLUSH   5
 

Flush the decoder status.

#define DEC_OPT_FRAME   3
 

Decode a frame. See LibQDecoreFunction for example usage.

#define DEC_OPT_INFO   2
 

Obtain information about the video. See LibQDecoreFunction for example usage.

#define DEC_OPT_INIT   0
 

Initialize the decoder. See LibQDecoreFunction for example usage.

#define DEC_OPT_RELEASE   1
 

Release the decoder. See LibQDecoreFunction for example usage.

#define DEC_OPT_SET   4
 

Specify a parameter to adjust/set.

#define DEC_PAR_BRIGHTNESS   6
 

pParam2 will specify the brightness of the output image.

#define DEC_PAR_CONTRAST   5
 

pParam2 will specify the contrast of the output image.

#define DEC_PAR_LOGO   8
 

Display the DivX logo on the bottom right of the picture when pParam is the to 1.

#define DEC_PAR_OUTPUT   0
 

Specify a different output format. pParam2 will point to a DecInit structure.

#define DEC_PAR_POSTPROCDEBLOC   2
 

pParam2 will specify a deblocking level.

#define DEC_PAR_POSTPROCDERING   3
 

pParam2 will specify a deringing level.

#define DEC_PAR_POSTPROCESSING   1
 

pParam2 will specify a postprocessing level.

#define DEC_PAR_SATURATION   7
 

pParam2 will specify the saturation of the output image.

#define DEC_PAR_SHOWPP   10
 

Show the postprocessing level in use on the top left corner of the output image.

#define DEC_PAR_SMOOTH   9
 

Use smooth playback when pParam is set to 1.

#define DEC_PAR_WARMTHLEVEL   4
 

pParam2 will specify a level for the warmth filter (film effect).


Typedef Documentation

typedef struct DecBitstream DecBitstream
 

Structure containing compressed video bitstream.

typedef struct DecFrame DecFrame
 

Structure containing input bitstream and decoder frame buffer. Default settings are when the structure is memset() to 0.

typedef struct DecInfo DecInfo
 

Structure used to obtain information about the decoded video.

typedef struct DecInit DecInit
 

Structure with parameters used to instantiate a decoder. Set by caller.

typedef int( LibQDecoreFunction)(void *pHandle, int decOpt, void *pParam1, void *pParam2)
 

Main decode engine function type. Decoder operation comprises instantiation, initialization, decoding each frame and release. All these operations may be achieved by calls to this function - see the example below.

Decoder instantiation is achieved like this:

    LibQDecoreFunction* pDecore = LibQDecoreMPEG4;
    DecInit decInit;
    // ...set up decInit members here...
    
    void *pHandle;
    int iRetVal=pDecore(NULL, DEC_OPT_INIT, (void*) &pHandle, &decInit);
    
    assert(pHandle != 0);
    assert(iRetVal == DEC_OK);

Next the user may call the decoder with the first chunk of bitstream to have the decoder detirmine width, height and other pertinent information. This step is necessary only if the user needs to garner information from the bitstream such as video frame width and height.

    DecInfo decInfo;
    // ...set up decInfo.bitstream...
    
    int rv = pDecore(pHandle, DEC_OPT_INFO, &decInfo, 0);
    assert(rv == DEC_OK);
    
    // Members of decInfo.formatInfo are now populated with
    // information about the video:
    // width, height, etc.

Video frames are decoded by further calls to the decoder function. The decoder outputs video frames in display order - it performs any necessary reordering.

    while (!bEndOfStream)
    {
        DecFrame decFrame;
        memset(&decFrame, 0, sizeof(DecFrame));
   
        // ...load up decFrame.bitstream with the next bitstream chunk
        // and set any necessary DecFrame parameters here...
   
        // Depending on the bitstream, the decoder may produce
        // more than one decoded frame per input bitstream chunk.
        // Multiple calls to pDecore achieve this (decFrame.bitstream is
        // updated as the decoder consumes the chunk).
        while (1)
        {
            int rv = pDecore(pHandle, DEC_OPT_FRAME, &decFrame, 0);
            assert(rv == DEC_OK);
    
            if (!decFrame.frameWasDecoded)
            {
                break;
            }
    
            // ...read out decompressed frame from decFrame.pBmp...
        }
    }

When decoding is finished the decoder should be released:

    int rv = pDecore(pHandle, DEC_OPT_RELEASE, 0, 0);
    assert(rv == DEC_OK);

Some decoder properties (contrast, saturation, brightness, warmth level, ...) can be changed at runtime. In order to do this the user may call the decoder specifying the parameter he wants to change and the new value:

    int iOperation = DEC_PAR_CONTRAST;
    int iLevel = 0; // set the contrast level to zero
    int rv = pDecore(pHandle, DEC_OPT_SET, &iLevel, &iOperation);

Parameters:
pHandle - Handle of the Decore instance.
decOpt - Method specifier. Controls function performed by this call. Use one of the following method specifiers:
pParam1 - First parameter (meaning depends on DecOpt). When this parameter is set the DEC_OPT_SET, the following operation specifiers are valid:
pParam2 - Second parameter (meaning depends on DecOpt).
Returns:
Returns one of the following:


Function Documentation

LibQDecoreFunction* getDecore unsigned long  fccFormat  ) 
 

Retrieves a pointer to the appropriate decore function for the specified video format.

Parameters:
fourCC FourCC of the video format that is to be decoded.
Returns:
Decore function pointer on success or null on failure.


Generated on Tue Jan 24 16:43:33 2006 for DivX Codec API Documentation.