/* Copyright (c) 2006 NVIDIA Corporation.  All rights reserved.
 *
 * NVIDIA Corporation and its licensors retain all intellectual property 
 * and proprietary rights in and to this software, related documentation 
 * and any modifications thereto.  Any use, reproduction, disclosure or 
 * distribution of this software and related documentation without an 
 * express license agreement from NVIDIA Corporation is strictly prohibited.
 */

/** @file GFMxDecRV9.h
    GFSDK RV9 Decode API header file.
*/

#ifndef _GF_MPEG_DEC_RV9__
#define _GF_MPEG_DEC_RV9__

#include "nvtypes.h"
#include "GFVx.h"

#ifdef __cplusplus
extern "C" {  // only need to export C interface if
              // used by C++ source code
#endif
/** @addtogroup group  MxDecRV9API 
*/
/*@{*/


// MXDECRV9 CapabilityEx Flag 
#define GF_MXDEC_RV9_CAPEx_USE_DSP  0x00000001   
// Whenever DSP is used for decoding 
// Surace type should be = GF_SURFACE_VIDEO_MEMORY
// Surface hint type = GF_MEMORY_HINT_BOTTOM_UP
// In case of Host Used for decoding 
// Surace type = GF_SURFACE_SYSTEM_MEMORY
// Surface hint type = 0
// MXDECRV9CapFlags
/************************************************************************************************************/

/** Argument "GFPROPERTY pMXProp" for MxDecRV9GetProperty().\n
    Application returns the properties, in GFPROPERTY structure \n    
@see GFMXDECRV9TABLE::MxDecRV9GetProperty , GFPROPERTY::Capability 
*/
#define GF_MXDEC_RV9_CAP_SIMPLE     0x00000001    

/** Argument "GFPROPERTY pMXProp" for MxDecRV9GetProperty().\n
    Application returns the properties, in GFPROPERTY structure   \n  
@see GFMXDECRV9TABLE::MxDecRV9GetProperty , GFPROPERTY::Capability 
*/
#define GF_MXDEC_RV9_CAP_MEDIUM     0x00000002

/** Argument "GFPROPERTY pMXProp" for MxDecRV9GetProperty().\n
    Application returns the properties, in GFPROPERTY structure   \n  
@see GFMXDECRV9TABLE::MxDecRV9GetProperty , GFPROPERTY::Capability 
*/
#define GF_MXDEC_RV9_CAP_COMPLEX    0x00000004 

/** Argument "GFPROPERTY pMXProp" for MxDecRV9GetProperty().\n
    Application returns the properties, in GFPROPERTY structure     \n
@see GFMXDECRV9TABLE::MxDecRV9GetProperty , GFPROPERTY::Capability 
*/
#define GF_MXDEC_RV9_CAP_LEVEL1     0x00000100   

/** Argument "GFPROPERTY pMXProp" for MxDecRV9GetProperty().\n
    Application returns the properties, in GFPROPERTY structure   \n  
@see GFMXDECRV9TABLE::MxDecRV9GetProperty , GFPROPERTY::Capability 
*/
#define GF_MXDEC_RV9_CAP_LEVEL2     0x00000200   

/** Argument "GFPROPERTY pMXProp" for MxDecRV9GetProperty().\n
    Application returns the properties, in GFPROPERTY structure   \n  
@see GFMXDECRV9TABLE::MxDecRV9GetProperty , GFPROPERTY::Capability 
*/
#define GF_MXDEC_RV9_CAP_LEVEL3     0x00000400    

/** Argument "GFPROPERTY pMXProp" for MxDecRV9GetProperty().\n
    Application returns the properties, in GFPROPERTY structure    \n 
@see GFMXDECRV9TABLE::MxDecRV9GetProperty , GFPROPERTY::Capability 
*/
#define GF_MXDEC_RV9_CAP_LEVEL4     0x00000800    

/** Argument "GFPROPERTY pMXProp" for MxDecRV9GetProperty().\n
    Application returns the properties, in GFPROPERTY structure  \n   
@see GFMXDECRV9TABLE::MxDecRV9GetProperty , GFPROPERTY::Capability 
*/
#define GF_MXDEC_RV9_CAP_DB         0x00001000    

/** Argument "GFPROPERTY pMXProp" for MxDecRV9GetProperty().\n
    Application returns the properties, in GFPROPERTY structure     \n
@see GFMXDECRV9TABLE::MxDecRV9GetProperty , GFPROPERTY::Capability 
*/
#define GF_MXDEC_RV9_CAP_DR         0x00002000 
/*********************************************************************************************************************/



 /** This structure holds various informations each of the frame to be decoded .
This structure is passed as parameter to GFMXDECRV9TABLE::MxDecRV9DecodeFrame.
*/

typedef struct _GFMXDECRV9FRAME
{


    NvU32   uiFrameOption;  /**< uiFrameOption values  
                            <table>
                            <tr><td>#GF_MXDEC_RV9_DEC_FRAME_SPECIFY_SURF_RECT</td>
                            <td>specify rect area to hold the reconstructed image.</td></tr>
                            <table>
                            */
    PGFRECT pFrameRect;    /**< not in use */
    NvU32   uiFrameType;  /**< set new frame type information
                            <table>
                            <tr><td>#GF_MXDEC_RV9_DISPLAY_FRAME</td>
                            <tr><td>#GF_MXDEC_RV9_KEY_FRAME</td>
                            <tr><td>#GF_MXDEC_RV9_P_FRAME</td>
                            <tr><td>#GF_MXDEC_RV9_B_FRAME</td>
                            <tr><td>#GF_MXDEC_RV9_DONT_DISPLAY_FRAME</td>
                            <tr><td>#GF_MXDEC_RV9_ERRONEOUS_FRAME</td>
                            </table>
                            */
    PGFRMSURFACE pReconstructedSurf;/**< This is the surface to hold the decoded picture */                   
    NvU32   uiFrameSequenceCount; /**< set by GFMxDecRV9API */                    
    NvU32   uiTimeStamp;           /**< in terms of millisecond */                
    NvU8*   pPreFillBuffer;        /**< Input, Pointer bitstream for frame to decode */ 
    NvU32   PreFillBufferLength;  /**< Input, Length of bitstream in bytes, must cover the entire frame */ 

}GFMXDECRV9FRAME, *PGFMXDECRV9FRAME;

//uiFrameOption
/******************************************************************************************/
/** uiFrameOption for GFMXDECRV9FRAME passed as an argument in MxDecRV9DecodeFrame(). \n
specify rect area to hold the reconstructed image.\n
@see GFMXDECRV9FRAME, GFMXDECRV9TABLE::MxDecRV9DecodeFrame.
*/
#define GF_MXDEC_RV9_DEC_FRAME_SPECIFY_SURF_RECT 0x00000001   

//uiFrameType values

/******************************************************************************************/
/** uiFrameType values for GFMXDECRV9FRAME set by MxDecRV9DecodeFrame(). \n

@see GFMXDECRV9FRAME, GFMXDECRV9TABLE::MxDecRV9DecodeFrame
*/
#define GF_MXDEC_RV9_DISPLAY_FRAME      0x0

/** uiFrameType values for GFMXDECRV9FRAME set by MxDecRV9DecodeFrame(). \n
    The decoded Frame is I-frame.
@see GFMXDECRV9FRAME, GFMXDECRV9TABLE::MxDecRV9DecodeFrame
*/
#define GF_MXDEC_RV9_KEY_FRAME          0x1 

/** uiFrameType values for GFMXDECRV9FRAME  set by MxDecRV9DecodeFrame(). \n
The Decoded Frame is P-frame.
@see GFMXDECRV9FRAME, GFMXDECRV9TABLE::MxDecRV9DecodeFrame
*/
#define GF_MXDEC_RV9_P_FRAME            0x2

/** uiFrameType values for GFMXDECRV9FRAME set by MxDecRV9DecodeFrame(). \n
    The decoded Frame is B-frame.
@see GFMXDECRV9FRAME, GFMXDECRV9TABLE::MxDecRV9DecodeFrame
*/
#define GF_MXDEC_RV9_B_FRAME            0x4

/** uiFrameType values for GFMXDECRV9FRAME passed as an argument in MxDecRV9DecodeFrame(). \n

@see GFMXDECRV9FRAME, GFMXDECRV9TABLE::MxDecRV9DecodeFrame
*/
#define GF_MXDEC_RV9_DONT_DISPLAY_FRAME 0x8

/** uiFrameType values for GFMXDECRV9FRAME passed as an argument in MxDecRV9DecodeFrame(). \n
    Decode frame is Erroneous
@see GFMXDECRV9FRAME, GFMXDECRV9TABLE::MxDecRV9DecodeFrame
*/
#define GF_MXDEC_RV9_ERRONEOUS_FRAME    0x16 
/***********************************************************************************************************************/

/** This structure holds various informations needed for Post Processing of decoded frame .
This structure is passed as parameter to MxDecRV9PostProcessing().
*/
typedef struct _GFMXDECRV9PP
{
        PGFRMSURFACE pPPSurf;
                            /**< pointer to surface that will 
                            hold the result from Post Processing
                            */
        PGFRECT   pPPRect;
                         /**< Rectangle area to be processed for both  
                         source and destination surface
                           */
        
        PGFRMSURFACE pSrcSurf;
                              /**< pointer to surface that will  
                              hold the result from Post Processing
                              */      
        PGFRECT   pSrcRect;
                          /**< Rectangle area to be processed for both  
                              source and destination surface
                           */  
} GFMXDECRV9PP, *PGFMXDECRV9PP;

// PPOption
#define GF_MXDEC_RV9_PP_SM_OFF      0x0 //Turn OFF Smoothing filter for this frame
#define GF_MXDEC_RV9_PP_SM_ON       0x1 //Turn ON  Smoothing filter for this frame
#define GF_MXDEC_RV9_PP_DR_ON       0x2 //Turn ON  DeRinging filter for this frame


// Hardware Status
/************************************************************************************************************/

#define GF_DECODER_FRAME_DONE    0x00000010



#define GF_DECODER_PP_FRAME_DONE 0x00000020

/*********************************************************************************************************/
#define GF_DECODER_PP_FRAME_RV9  0x00000040//


/** Attribute MxDecRV9Set::uiFeature.\n
    Application sets this attribute to register a callback function and
    its correpnding parameter to read bitstream data .
@see GFMXDECRV9TABLE::MxDecRV9Set, pInfo should be a pointer to PGFMXDECRV9CALLBACK \n
*/
#define GF_MXDEC_RV9_SET_READBITSTREAM          0x1   



/** Attribute MxDecRV9Set::uiFeature \n
     This will setup the surface list, including all of the ref surface and one reconstructed one. \n
@see GFMXDECRV9TABLE::MxDecRV9Set, pInfo should a pointer PGFMXDECRV9SURFLIST
*/
#define GF_MXDEC_RV9_SET_SURFACE_LIST           0x2



/** Attribute MxDecRV9Set::uiFeature \n
    This will Set the GFMxDecRV9API to decode the RV8 stream
    By default GFMxDecRV9API will assume the stream to be RV9 stream\n
@see GFMXDECRV9TABLE::MxDecRV9Set
*/
#define GF_MXDEC_RV9_BITSTREAM_RV8              0x4


/** Attribute GFMxDecRV9SetAttribute::uiFeature and GFMxDecRV9GetAttribute::uiFeature \n
    Application will determine the decoding boundary, for RV9, this boundary means VOL
    and VOP boundary. For certain file formats, those boundary information are
    stored in the video file, APP can easily use those information to determine
    the boundary.
    If APP wants API to detect the boundary,App should not disable this attribute. This is mainly for streaming case, APP does
    not have those handy boundary information. API will automatically detects those
    boundaries. APP does not need to parse the bitstream to detect those boundaries.\n
    *pInfo: 1: APP will determine the decoding boudary\n
    *pInfo: 0: APP will not determine the decoding boundary \n
@see GFMXDECRV9TABLE::MxDecRV9SetAttribute
*/
#define GF_MXDEC_RV9_ATTR_PRE_DETERMINED_BOUNDARY           0x00000001



/** Attribute GFMxDecRV9GetAttribute::uiFeature \n
    This attribute only can be used for GFMxDecGetAttribute
    If application wants to set pDestRect in GFMXDECVOP or GFMXDECMP4DECVOP,
    application must use this attributes to get allignment information and
    align the rectangle top & left corner accordinately.\n
    *pInfo: top fieled alignment in term of lines \n
@see GFMXDECRV9TABLE::MxDecRV9GetAttribute
*/
#define GF_MXDEC_ATTR_RV9_DEC_FRAME_RECT_TOP_ALIGNMENT     0x00000002



/** Attribute GFMxDecRV9GetAttribute::uiFeature \n
    This attribute only can be used for GFMxDecGetAttribute
    If application wants to set pDestRect in GFMXDECVOP or GFMXDECMP4DECVOP,
    application must use those attributes to get allignment information and
    align the rectangle top & left corner accordinately.\n
    *pInfo: left fieled alignment in term of pixels\n

@see GFMXDECRV9TABLE::MxDecRV9GetAttribute
*/
#define GF_MXDEC_ATTR_RV9_DEC_FRAME_RECT_LEFT_ALIGNMENT    0x00000003


/** Attribute GFMxDecRV9SetAttribute::uiFeature and GFMxDecRV9GetAttribute::uiFeature \n
    Application will fill the buffer and push the data to the decoder.
*/
#define GF_MXDEC_RV9_ATTR_PREFILLBUFFER 0x00000008

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

/** Structure holding the callback function pointer.
Used in registering the callback function
The callback function is a function which the API calls to request a portion of the bit stream from the application.
@see GFMXDECRV9TABLE::MxDecRV9Set
*/


    
typedef struct _GFMXDECRV9CALLBACK
{
    void *pPara;/**< pPara is a parameter passed from APP, 
                and APP wants API to call back with this parameter
                */
    NvU32 (*pCallBack)(void * pPara, NvU8 ** ppBuffer, NvU32 * BufferLength,NvU32 uFlag); 
                /**< Application callback function pointer.
                Register a callback function for fetching RV9 data.

                @param *pPara Parameter to pass on to application callback function
                @param  ppBuffer Buffer Pointer
                @param BufferLength Parameter to pass on to application callback function

                If APP set GF_MXDEC_RV9_ATTR_PRE_DETERMINED_BOUNDARY,
                APP should return GF_MXDEC_RV9HD_BOUNDARY_REACHED when the boundary is 
                detected.
                If APP does not set GF_MXDEC_RV9_ATTR_PRE_DETERMINED_BOUNDARY, 
                0 should be returned.
                */

}GFMXDECRV9CALLBACK, *PGFMXDECRV9CALLBACK;

#define GF_MXDEC_RV9HD_ENDOFFILE             0x00000200 
#define GF_MXDEC_RV9HD_APP_DETECT_BOUNDARY   0x00001000 
#define GF_MXDEC_RV9HD_BOUNDARY_REACHED      0x00002000  
#define GF_MXDEC_RV9HD_ENDOFFILE_REACHED     0x00004000  
#define GF_MXDEC_RV9HD_APP_PREFILLBUFFER     0x00008000  
#define GF_MXDEC_RV9HD_BEGININGOFFILE_REACHED 0x00010000  

 

/** MxDecRV9API GFMXDECRV9CALLBACK::(*pCallBack)(, , ,uFlag)\n
   for reading bitstream in forward direction
@see GFMXDECRV9CALLBACK
*/
#define GF_MXDEC_RV9_READ_BITSTREAM_FORWARD     0x00000002

/** MxDecRV9API GFMXDECRV9CALLBACK::(*pCallBack)(, , ,uFlag) \n
    for reading  bitstream in reverse direction.
@see GFMXDECRV9CALLBACK
*/
#define GF_MXDEC_RV9_READ_BITSTREAM_BACKWARD    0x00000003

//Resync options :

/** MxDecRV9API GFMxDecRV9Resync( ,ResyncOption)\n
    Resynchronize forward to the nearest I frame. If the GFMxDecRV9API is right 
    before an I frame, GFMxDecRV9Resync() returns immediately. Otherwise, 
    GFMxDecRV9Resync() moves forward, parsing bits until it reaches the first bit of the next I frame.
@see ResyncOption, GFMXDECRV9TABLE::MxDecRV9Resync
*/

#define GF_MXDEC_RV9_RESYNC_FORWARD_NEAREST_I_FRAME 0x00000001
    
/** MxDecRV9API GFMxDecRV9Resync(,ResyncOption)\n
     Resynchronize backward to the nearest I frame.  
    GFMxDecRV9Resync() moves backward, parsing bits until it reaches the first bit of the previous I frame.
@see ResyncOption, GFMXDECRV9TABLE::MxDecRV9Resync
*/
#define GF_MXDEC_RV9_RESYNC_BACKWARD_NEAREST_I_FRAME  0x00000002
    
/** MxDecRV9API GFMxDecRV9Resync(,ResyncOption)\n
     Resynchronize backward to the nearest P frame.  
    GFMxDecRV9Resync() moves backward, parsing bits until it reaches the first bit of the previous P frame.
@see ResyncOption, GFMXDECRV9TABLE::MxDecRV9Resync
*/
#define GF_MXDEC_RV9_RESYNC_BACKWARD_NEAREST_P_FRAME  0x00000004
    


/** this macro is used in GFMXDECRV9SURFLIST structure \n
    Reference surfaces for RV9 decoder. */
#define GF_MXDEC_RV9_NUM_SURFACES               3 

/** This structure is used to Set up a list of surfaces for RV9
    decoder .
*/

typedef struct _GFMXDECRV9SURFLIST
{
    
    PGFRMSURFACE SurfList[GF_MXDEC_RV9_NUM_SURFACES];
    /**< an array of PGFRMSURFACE
    @see #GF_MXDEC_RV9_NUM_SURFACES
    */
   
        
}GFMXDECRV9SURFLIST, *PGFMXDECRV9SURFLIST;

/** This structure is passed to MxDecRV9DecodePictureHeader() function, which sets 
    different fields of this structure.
*/
typedef struct _GFMXDECRV9PICHDR
{
    NvU32           uiRV8StreamInfo;    
                                       /**< set by GFMxDecRV9API. Valid only if it is RV8 stream
                                            <table>
                                            <tr><td>#GF_MXDEC_RV8_UMV</td>
                                            <td>Unrestricted Motion Vector</td></tr>
                                            <tr><td>#GF_MXDEC_RV8_DF</td>
                                            <td>In loop Deblocking filter</td></tr>
                                            <tr><td>#GF_MXDEC_RV8_SS</td>
                                            <td>Slice Structured </td></tr>
                                            <tr><td>#GF_MXDEC_RV8_RPR</td>
                                            <td>Reference Picture Resampling</td></tr>
                                            <tr><td>#GF_MXDEC_RV8_ROUND</td>
                                            <td>Round off for half pixel motion compensation</td></tr>
                                            </table>
                                            */
    NvU32           uiRV9StreamInfo;    
                                      /**< set by GFMxDecRV9API. Valid only if it is RV9 stream
                                            <table>
                                            <tr><td>#GF_MXDEC_RV9_INTERLACE</td>
                                            <td>Interlaced mode used</td></tr>
                                            <tr><td>#GF_MXDEC_RV9_DF_PASS_THRU</td>
                                            <td>In loop Deblocking filter is disabled</td></tr>
                                            </table>
                                            */
    NvU32           uiWidth;            /**< Video width  */
    NvU32           uiHeight;           /**< Video height  */
    NvU32           uiTR;               /**< Temporal reference in milliseconds */

}GFMXDECRV9PICHDR, *PGFMXDECRV9PICHDR;

//uiRV8StreamInfo

/** MxDecRV9API GFMXDECRV9PICHDR::uiRV8StreamInfo \n
    Unrestricted Motion Vector.
@see GFMXDECRV9PICHDR, GFMXDECRV9TABLE::MxDecRV9DecodePictureHeader
*/
#define GF_MXDEC_RV8_UMV                0x00000001   

/** MxDecRV9API GFMXDECRV9PICHDR::uiRV8StreamInfo \n
    In loop Deblocking filter.
@see GFMXDECRV9PICHDR, GFMXDECRV9TABLE::MxDecRV9DecodePictureHeader
*/
#define GF_MXDEC_RV8_DF                 0x00000002  

/** MxDecRV9API GFMXDECRV9PICHDR::uiRV8StreamInfo\n
    Slice Structured.
@see GFMXDECRV9PICHDR, GFMXDECRV9TABLE::MxDecRV9DecodePictureHeader
*/
#define GF_MXDEC_RV8_SS                 0x00000004  

/** MxDecRV9API GFMXDECRV9PICHDR::uiRV8StreamInfo \n
   Reference Picture Resampling.
@see GFMXDECRV9PICHDR, GFMXDECRV9TABLE::MxDecRV9DecodePictureHeader
*/
#define GF_MXDEC_RV8_RPR                0x00000008  

/** MxDecRV9API GFMXDECRV9PICHDR::uiRV8StreamInfo \n
    Round off for half pixel motion compensation.
@see GFMXDECRV9PICHDR, GFMXDECRV9TABLE::MxDecRV9DecodePictureHeader
*/
#define GF_MXDEC_RV8_ROUND              0x00000010  

//uiRV9StreamInfo

/** MxDecRV9API GFMXDECRV9PICHDR::uiRV9StreamInfo \n
    Interlaced mode used.
@see GFMXDECRV9PICHDR, GFMXDECRV9TABLE::MxDecRV9DecodePictureHeader
*/
#define GF_MXDEC_RV9_INTERLACE          0x00000001

/** MxDecRV9API GFMXDECRV9PICHDR::uiRV9StreamInfo \n
    In loop Deblocking filter is disabled.
@see GFMXDECRV9PICHDR, GFMXDECRV9TABLE::MxDecRV9DecodePictureHeader
*/
#define GF_MXDEC_RV9_DF_PASS_THRU       0x00000002  

//resync options
//TBD

//when GF_ERROR is return check the following flag 
#define GF_MXDEC_RV9_BAD_MB        0x00010000  //there is at least one MB is wrong
                                        //if APP set up pMBInfo, APP can check which MB is wrong

/** MxDecRV9API interrupt operation types.
Constants to specify operation for a call to MxDecRV9InterruptControl().
@see GF_MXDEC_RV9_INTERRUPT_OPERATION_TYPE, GFMXDECRV9TABLE::MxDecRV9InterruptControl
*/
typedef enum
{
    /** Enable interrupt/status assertion for an interrupt type. */
    GF_MXDEC_RV9_INTERRUPT_ENABLE,

    /** Disable interrupt/status assertion for an interrupt type. */
    GF_MXDEC_RV9_INTERRUPT_DISABLE,

    /** Clear interrupt/status assertion for an interrupt type. */
    GF_MXDEC_RV9_INTERRUPT_CLEAR
} GF_MXDEC_RV9_INTERRUPT_OPERATION_TYPE; // Interrupt operation.



/** MxDecRV9API interrupt types.
@see GF_MXDEC_RV9_INTERRUPT_TYPE, GFMXDECRV9TABLE::MxDecRV9InterruptControl and  GFMXDECRV9TABLE::MxDecRV9InterruptHandler
*/
typedef enum
{
    /** Interrupt type is DSP Command Interrupt */
    GF_MXDEC_RV9_DSP_COMMAND_INTR,

    /** Interrupt type Post Processing done */
    GF_MXDEC_RV9_POST_PROCESSING_DONE_INTR,

    /** Interrupt type is Decoding done Interrupt */
    GF_MXDEC_RV9_DECODE_DONE_INTR
}  GF_MXDEC_RV9_INTERRUPT_TYPE;

/** MxDecRV9API virtual function pointer table. */
typedef struct _GFMXDECRV9TABLE
{
    
     /** This function returns version and capabilities of API and hardware.

    @param hMxDecRV9 (GFMxDecRV9Handle) Handle specific to MxDecRV9API
    @param pMXProp (PGFPROPERTY) Pointer to GFPROPERTY structure to be filled in

    @retval GF_SUCCESS \a pMXProp filled in successfully
    @retval GF_ERROR   Some error occured

    The GFPROPERTY structure passed with parameter \a pMXProp will be
    filled in on successfull return. The GFPROPERTY::Capability field
    will hold a combination of flagbits indicating capabilities specific
    to the MxDecRV9API:

    <table>
    <tr><td>#GF_MXDEC_RV9_CAP_SIMPLE      </td>
    <td>support simple profile.</td></tr>
    <tr><td>#GF_MXDEC_RV9_CAP_MEDIUM   </td>
    <td>support medium profile.</td></tr>
    <tr><td>#GF_MXDEC_RV9_CAP_COMPLEX   </td>
    <td>support complex profile</td></tr>
    <tr><td>#GF_MXDEC_RV9_CAP_LEVEL1</td>
    <td>support LEVEL 1.</td></tr>
    <tr><td>#GF_MXDEC_RV9_CAP_LEVEL2 </td>
    <td>support LEVEL 2.</td></tr>
    <tr><td>#GF_MXDEC_RV9_CAP_LEVEL3 </td>
    <td>support LEVEL 3.</td></tr>
    <tr><td>#GF_MXDEC_RV9_CAP_LEVEL4  </td>
    <td>support LEVEL 4.</td></tr>
    <tr><td>#GF_MXDEC_RV9_CAP_DB    </td>
    <td>support Post Processing's smoothing filter for RV8 streams.</td></tr>
    <tr><td>#GF_MXDEC_RV9_CAP_DR  </td>
    <td>support Post Processing's de-ringing.</td></tr>
    </table>

    It is a good practice to call this function to query for the API version
    and its capabilities before using the rest of the MxDecRV9API functions.

    @see GFPROPERTY
*/
    GF_RETTYPE (* MxDecRV9GetProperty)(GFMxDecRV9Handle hMxDecRV9, PGFPROPERTY pMXProp );


    
    GF_RETTYPE (* MxDecRV9GetStatus)(GFMxDecRV9Handle hMxDecRV9, NvU32 * pStatus);
    
    
    /** This function applies the postprocessing filters to the source surface and outputs
    the new image to the destitation surface.
    @param hMxDecRV9 (GFMxDecRV9Handle) Handle specific to MxDecRV9API
    @param pP (#PGFMXDECRV9PP) Pointer to the PGFMXDECRV9PP.
    @retval GF_SUCCESS \a if successful
    @retval GF_ERROR   Some error occured
    GF_ERROR Return values for the above function

    @see PGFMXDECRV9PP
*/
    GF_RETTYPE (* MxDecRV9PostProcessing)(GFMxDecRV9Handle hMxDecRV9, PGFMXDECRV9PP pP);
    
    
    /** This function sets the MxDecRV9API options.
    @param hMxDecRV9 (GFMxDecRV9Handle) Handle specific to MxDecRV9API
    @param uiFeature :
                        <table>
                        <tr><td>#GF_MXDEC_RV9_ATTR_PRE_DETERMINED_BOUNDARY  </td>
                        <td>will determine the VOL and VOP boundary, for RV9.</td></tr>
                        <tr><td>#GF_MXDEC_RV9_ATTR_PREFILLBUFFER</td>
                        <td>App will fill the buffer and push the data to the decoder.</td></tr>
                        </table>
    @param pInfo Pointer to the information buffer.
    @retval GF_SUCCESS \a if successful
    @retval GF_ERROR   Some error occured
    
*/
    GF_RETTYPE (* MxDecRV9SetAttribute)(GFMxDecRV9Handle hMxDecRV9, NvU32 uiFeature, NvU32* pInfo);
    
    
    /** This function gets the MxDecRV9API options.
    @param hMxDecRV9 (GFMxDecRV9Handle) Handle specific to MxDecRV9API
    @param uiFeature :
                        <table>
                        <tr><td>#GF_MXDEC_ATTR_RV9_DEC_FRAME_RECT_TOP_ALIGNMENT  </td>
                        <tr><td>#GF_MXDEC_ATTR_RV9_DEC_FRAME_RECT_LEFT_ALIGNMENT</td>
                        <tr><td>#GF_MXDEC_RV9_ATTR_PRE_DETERMINED_BOUNDARY </td>
                        <tr><td>#GF_MXDEC_RV9_ATTR_PREFILLBUFFER</td>
                        </table>
    @param pInfo Pointer to the information buffer.
    @retval GF_SUCCESS \a if successful
    @retval GF_ERROR   Some error occured
    
*/
    GF_RETTYPE (* MxDecRV9GetAttribute)(GFMxDecRV9Handle hMxDecRV9, NvU32 uiFeature, NvU32* pInfo);
     
    
    /** This function sets the MxDecRV9API options.
    @param hMxDecRV9 (GFMxDecRV9Handle) Handle specific to MxDecRV9API
    @param uiFeature :
                      <table>
                        <tr><td>#GF_MXDEC_RV9_SET_READBITSTREAM  </td>
                        <td>will Set up readbitstream call back function.</td></tr>
                        <tr><td>#GF_MXDEC_RV9_SET_SURFACE_LIST</td>
                        <td>will setup the surface list, including all of the ref surface and one reconstructed one.</td></tr>
                        <tr><td>#GF_MXDEC_RV9_BITSTREAM_RV8  </td>
                        <td>will Set the GFMxDecRV9API to decode the RV8 stream.</td></tr>
                        </table>
    @param pInfo Pointer to the information buffer.
    @retval GF_SUCCESS \a if successful
    @retval GF_ERROR   Some error occured
    
*/
    GF_RETTYPE (* MxDecRV9Set)(GFMxDecRV9Handle hMxDecRV9, NvU32 uiFeature, void * pInfo);
    
    
    
    
/** This function Decodes the picture header and gives the related information in
    PictureHeader.
    @param hMxDecRV9 (GFMxDecRV9Handle) Handle specific to MxDecRV9API
    @param pPictureHeader Pointer to the #GFMXDECRV9PICHDR.
    @retval GF_SUCCESS \a if it successfully decodes the Header
    @retval GF_ERROR   Some error occured
    GF_ERROR Return values for the above function
    <table>
    <tr><td>#GF_ERROR_RV9DECPICTUREHDR_DETECTED  </td>
    <td>There is a sequence header in the bit stream. 
        Application need to decide this sequence is an error or this 
        is intended to be in the bit stream.</td></tr>
    <tr><td>#GF_ERROR_RV9DECPICTUREHDR_END_OF_FILE  </td>
    <td>No more bit stream from application.</td></tr>
    <tr><td>#GF_ERROR_RV9DECPICTUREHDR_CORRUPTED  </td>
    <td>GFMxDecRV9DecPicture encounters an un-recoverable error 
        in the bit stream. Application should call GFMxDecRV9Resync 
        API to skip this picture.</td></tr>
    <tr><td>#GF_ERROR_RV9DECPICTUREHDR_NOT_ENOUGH_MEM   </td>
    <td>There is not enough memory.</td></tr>
    </table>

    @see GFMXDECRV9PICHDR
*/
    GF_RETTYPE (* MxDecRV9DecodePictureHeader)(GFMxDecRV9Handle hMxDecRV9, PGFMXDECRV9PICHDR pPictureHeader);  
     
    
    /** This function decodes one frame from the bitstream.
    @param hMxDecRV9 (GFMxDecRV9Handle) Handle specific to MxDecRV9API
    @param pFrame pointer to #PGFMXDECRV9FRAME
    @retval GF_SUCCESS \a if successful
    @retval #GF_MXDEC_RV9_FRAMEDEC_EOF_REACHED  \a No more bit streams from the application.
    
*/
    GF_RETTYPE (* MxDecRV9DecodeFrame)(GFMxDecRV9Handle hMxDecRV9, PGFMXDECRV9FRAME pFrame);
     
    
    
/** GFMxDecRV9Resync  re-synchronizes to a specific position of a bit stream..
    @param hMxDecRV9 (GFMxDecRV9Handle) Handle specific to MxDecRV9API
    @param ResyncOption  :
                          <table>
                            <tr><td>#GF_MXDEC_RV9_RESYNC_FORWARD_NEAREST_I_FRAME.</td>
                            <td>Resynchronize forward to the nearest I frame.</td></tr>
                            <tr><td>#GF_MXDEC_RV9_RESYNC_BACKWARD_NEAREST_I_FRAME.</td>
                            <td>Resynchronize backward to the nearest I frame.</td></tr>
                            <tr><td>#GF_MXDEC_RV9_RESYNC_BACKWARD_NEAREST_P_FRAME.</td>
                            <td>Resynchronize backward to the nearest P frame.<td><tr>
                          <table>
    @retval GF_SUCCESS \a if successful
    @retval GF_ERROR   Some error occured
    
*/
    GF_RETTYPE (* MxDecRV9Resync)(GFMxDecRV9Handle hMxDecRV9, NvU32 ResyncOption);
     
    
    
    
    GF_RETTYPE (* MxDecRV9InterruptControl)(GFMxDecRV9Handle hMxDecRV9,
                GF_MXDEC_RV9_INTERRUPT_TYPE IntType, GF_MXDEC_RV9_INTERRUPT_OPERATION_TYPE op,
                void * pData);
    
    
    
    /** This function provides component-level interrupt control for the
    MxDecRV9API. It is optional because an interrupt service thread (IST) at the
    application level can call the MxDecRV9API to complete the task.
    @param hMxDecRV9(GFMxDecRV9Handle)   Handle specific to MxDecRV9API
    @param IntType      MxDecRV9API interrupt type as defined in
                       “#GF_MXDEC_RV9_INTERRUPT_TYPE”
    @param pData        Pointer to data being passed in or out.
    @retval GF_SUCCESS \a if successful.
    @retval GF_ERROR   Some error occured.
    
*/
    GF_RETTYPE (* MxDecRV9InterruptHandler)(GFMxDecRV9Handle hMxDecRV9, 
                GF_MXDEC_RV9_INTERRUPT_TYPE IntType, void * pData); // Reserved.
    
} GFMXDECRV9TABLE, *PGFMXDECRV9TABLE;

// Typesafe functions for opening and closing this component
GF_RETTYPE GFMxDecRV9Open(GFRmHandle hRm, GFMxDecRV9Handle *phMxDecRV9,
                          GF_STATE_TYPE state, GFRmChHandle hCh);
void GFMxDecRV9Close(GFMxDecRV9Handle *phMxDecRV9);

#if NVCPU_IS_XTENSA
#define MXDRV9OFFSET sizeof(GFMXDECRV9TABLE)
#else
#define MXDRV9OFFSET 0
#endif


//ERROR return values for the GFMxDecRV9DecodePictureHeader()

/** ERROR return values for the GFMxDecRV9DecodePictureHeader() \n
    There is a sequence header in the bit stream. 
    Application need to decide this sequence is an error or this 
    is intended to be in the bit stream.
    @see GFMXDECRV9TABLE::MxDecRV9DecodePictureHeader
*/
#define GF_ERROR_RV9DECPICTUREHDR_DETECTED              0x00000001
        

/**ERROR return values for the GFMxDecRV9DecodePictureHeader() \n
   No more bit stream from application.
   @see GFMXDECRV9TABLE::MxDecRV9DecodePictureHeader
*/
#define GF_ERROR_RV9DECPICTUREHDR_END_OF_FILE           0x00000002
        

/** ERROR return values for the GFMxDecRV9DecodePictureHeader() \n
    GFMxDecRV9DecPicture encounters an un-recoverable error 
    in the bit stream. Application should call GFMxDecRV9Resync 
    API to skip this picture.
    @see GFMXDECRV9TABLE::MxDecRV9DecodePictureHeader
*/
#define GF_ERROR_RV9DECPICTUREHDR_CORRUPTED             0x00000003
 
/**ERROR return values for the GFMxDecRV9DecodePictureHeader() \n
   There is not enough memory.
*/
#define GF_ERROR_RV9DECPICTUREHDR_NOT_ENOUGH_MEM        0x00000004

//ERROR return values for MxDecRV9DecodeFrame()
/** ERROR return values for MxDecRV9DecodeFrame()\n
    API returns this error when End of file is reached,i.e No more bit stream from application.
    once this ERROR is returned, the application should provide more media files to decode or 
    exit gracefully.*/
#define GF_MXDEC_RV9_FRAMEDEC_EOF_REACHED               0x00000001

/* #### MxDecRV9API Helper macros.  Maybe useful for backward compatible API. #### */


/* #### MxDecRV9 Helper macros.  Maybe useful for backward compatible API. #### */
#define GFMxDecRV9GetProperty(hMxDecRV9, pMXProp) \
    ((PGFMXDECRV9TABLE)((NvU32)hMxDecRV9+MXDRV9OFFSET))->MxDecRV9GetProperty(hMxDecRV9, pMXProp)

#define GFMxDecRV9GetStatus(hMxDecRV9, pStatus) \
    ((PGFMXDECRV9TABLE)((NvU32)hMxDecRV9+MXDRV9OFFSET))->MxDecRV9GetStatus(hMxDecRV9, pStatus)

#define GFMxDecRV9DecodePictureHeader(hMxDecRV9, pPictureHeader)\
    ((PGFMXDECRV9TABLE)((NvU32)hMxDecRV9+MXDRV9OFFSET))->MxDecRV9DecodePictureHeader(hMxDecRV9, pPictureHeader)

#define GFMxDecRV9PostProcessing(hMxDecRV9, pP) \
    ((PGFMXDECRV9TABLE)((NvU32)hMxDecRV9+MXDRV9OFFSET))->MxDecRV9PostProcessing(hMxDecRV9, pP);

#define GFMxDecRV9SetAttribute(hMxDecRV9, uiFeature, pInfo) \
    ((PGFMXDECRV9TABLE)((NvU32)hMxDecRV9+MXDRV9OFFSET))->MxDecRV9SetAttribute(hMxDecRV9, uiFeature, pInfo)

#define GFMxDecRV9GetAttribute(hMxDecRV9, uiFeature, pInfo) \
    ((PGFMXDECRV9TABLE)((NvU32)hMxDecRV9+MXDRV9OFFSET))->MxDecRV9GetAttribute(hMxDecRV9, uiFeature, pInfo)

#define GFMxDecRV9Set(hMxDecRV9, uiFeature, pInfo) \
    ((PGFMXDECRV9TABLE)((NvU32)hMxDecRV9+MXDRV9OFFSET))->MxDecRV9Set(hMxDecRV9, uiFeature, pInfo)

#define GFMxDecRV9DecodeFrame(hMxDecRV9, pFrame) \
    ((PGFMXDECRV9TABLE)((NvU32)hMxDecRV9+MXDRV9OFFSET))->MxDecRV9DecodeFrame(hMxDecRV9, pFrame)

#define GFMxDecRV9Resync(hMxDecRV9, ResyncOption) \
    ((PGFMXDECRV9TABLE)((NvU32)hMxDecRV9+MXDRV9OFFSET))->MxDecRV9Resync(hMxDecRV9, ResyncOption)

#define GFMxDecRV9InterruptControl(hMxDecRV9, IntType, op, pData)\
    ((PGFMXDECRV9TABLE)((NvU32)hMxDecRV9+MXDRV9OFFSET))->MxDecRV9InterruptControl(hMxDecRV9, IntType, op, pData)

#define GFMxDecRV9InterruptHandler(hMxDecRV9, IntType, pData)\
    ((PGFMXDECRV9TABLE)((NvU32)hMxDecRV9+MXDRV9OFFSET))->MxDecRV9InterruptHandler(hMxDecRV9, IntType, pData)



/*@}*/
/*@}*/


/** @page pageMxDecRV9AppNotes MxDecRV9API Application Notes
    @section pageMxDecRV9AppNotes1 Programming Sequence

    The following procedure requires that GFRmOpen() is called first to start
    GFSDK usage.

    

    1. Call GFMxDecRV9Open() to obtain RV9Handle. This handle will be passed to different functions of MxDecRV9API.

    2. Call  GFMxDecRV9GetProperty()to querry the properties.Check whether this 
       MxDecRV9API version can support the desired RV9 profile and level.

    3. Set different attributes of RV9 decoder using GFMxDecRV9SetAttribute(),
        #GFMXDECRV9TABLE::MxDecRV9SetAttribute.

    4. Decode the picture header using GFMxDecRV9DecodePictureHeader(),
        #GFMXDECRV9TABLE::MxDecRV9DecodePictureHeader.

    5. call GFRmSurfaceAlloc() to allocate at least one reference surface and one 
       current surface for decoding purposes.

    6. If the postprocessing engine is needed, allocate one surface to hold the
       postprocessing results.

    7. For display purposes, the decoder application could call GFVxBlt() for
       the following two scenarios. Please refer to the latest GFVxAPI document
       for additional information. 
                            <tr><td>Performing color space conversion and then a stretch blit to the primary surface directly.</td>
                            <td>Blitting to the overlay surface.<td><tr>
   
    8. The decoder application should decode on frame by frame basis. Call GFMxDecRV9DecodeFrame() to decode each frame.
       once GF_MXDEC_RV9_FRAMEDEC_EOF_REACHED is returnd by API, application should exit gracefully.
        #GFMXDECRV9TABLE::MxDecRV9DecodeFrame

    9. If Post processing is enabled , call GFMxDecRV9PostProcessing().
       #GFMXDECRV9TABLE::MxDecRV9PostProcessing

    10. Before exiting the application, the decoder application should call
        GFRmSurfaceFree() to free the surfaces that have been allocated.

    11. Call GFMxDecRV9Close() with RV9Handle to release the resources of the decoder module.
              
*/


#ifdef __cplusplus
}  // only need to export C interface if
              // used by C++ source code
#endif

#endif