*       <li> == <B>NULL</B> : Use internally AC DC predictor buffer
                   *                             which is allocated by using installed @ref pfnDmaMalloc
                   *                             function.
                   *     </ul>
                   *   <B>N.B.</B> : the AC DC predictor buffer address must be <B>physical address</B> with <B>16-byte aligned</B>.
                   *
                   *   @see pfnDmaMalloc
                   *   @see pfnDmaFree
                   */
  
  /// The function pointer to user-defined DMA memory allocation function.
  DMA_MALLOC_PTR pfnDmaMalloc;  /**< This variable contains the function pointer to the user-defined 
                                 *   DMA malloc function since under OS environment, our hardware device
                                 *   may need the physical address instead of virtual address.
                                 *
                                 *   @see pfnDmaFree
                                 *   @see DMA_MALLOC_PTR
                                 *   @see DMA_FREE_PTR
                                 */
  /// The function pointer to user-defined DMA free allocation function.
  DMA_FREE_PTR   pfnDmaFree;    /**< This variable contains the function pointer to the user-defined 
                                 *   DMA free function since under OS environment, our hardware device
                                 *   may need the physical address instead of virtual address.
                                 *
                                 *   @see pfnDmaFree
                                 *   @see DMA_MALLOC_PTR
                                 *   @see DMA_FREE_PTR
                                 */
} FMP4_ENC_PARAM;

/**
 *  Denote INTER mode with 1MV.
 */
#define INTER_MODE		0
/**
 *  Denote INTER mode with 4MV.
 */
#define INTER4V_MODE	2
/**
 *  Denote INTRA mode.
 */
#define	INTRA_MODE		3

/// The Encoder Macroblock Information Structure.
/**
 *  This data structure is mainly used for FMpeg4EncGetMBInfo() operation which
 *  contains various kind of macroblock information such as motion vectors,
 *  quantization value and macroblock mode.\n
 *  
 */
typedef struct {
  int mode;  /**< This variable indicates the mode of macroblock.
              *   Possible values are :
              *   <ul>
              *     <li> == INTER_MODE   : Indicate that this macroblock is encoded in INTER mode
              *                                   with 1MV.
              *     <li> == INTER4V_MODE : Indicate that this macroblock is encoded in INTER mode
              *                                   with 4MV.
              *     <li> == INTRA_MODE   : Indicate that this macroblock is encoded in INTRA mode.
              *   </ul>
              *
              */
  int quant;  /**< This variable indicates the macroblock level quantization value (1 ~ 31)
               */               
  int mv16x_0; /**< The motion vector's x-component of block 0 within one macroblock.
                *   It is valid only when this macroblock is encoded in INTER mode
                *   with 4MV.
                */
  int mv16y_0; /**< The motion vector's y-component of block 0 within one macroblock.
                *   It is valid only when this macroblock is encoded in INTER mode
                *   with 4MV.
                */
  int mv16x_1; /**< The motion vector's x-component of block 1 within one macroblock.
                *   It is valid only when this macroblock is encoded in INTER mode
                *   with 4MV.
                */
  int mv16y_1; /**< The motion vector's y-component of block 1 within one macroblock.
                *   It is valid only when this macroblock is encoded in INTER mode
                *   with 4MV.
                */
  int mv16x_2; /**< The motion vector's x-component of block 2 within one macroblock.
                *   It is valid only when this macroblock is encoded in INTER mode
                *   with 4MV.
                */
  int mv16y_2; /**< The motion vector's y-component of block 2 within one macroblock.
                *   It is valid only when this macroblock is encoded in INTER mode
                *   with 4MV.
                */
  int mv16x_3; /**< When this macroblock is encoded in :
                *   - INTER mode with 1MV : this variable indicates the motion vector
                *                           of whole macroblock.
                *   - INTER mode with 4MV : this variable indicates the motion vector's
                *                           x-component of block 3 within one macroblock.                
                *   This variable is valid only when this macroblock is encoded in INTER mode
                *   with 1MV or 4MV.
                */
  int mv16y_3; /**< When this macroblock is encoded in :
                *   - INTER mode with 1MV : this variable indicates the motion vector
                *                           of whole macroblock.
                *   - INTER mode with 4MV : this variable indicates the motion vector's
                *                           y-component of block 3 within one macroblock.                
                *   This variable is valid only when this macroblock is encoded in INTER mode
                *   with 1MV or 4MV.
                */
} MACROBLOCK_INFO;

typedef struct {
	unsigned int u32KeyFrame;
	unsigned char *pu8BSptr_virt;
	unsigned int u32BSlength;
} FMP4_ENC_RESULT;

#ifndef MP4VENC_EXPOPRT
  #ifdef __cplusplus
	  #define MP4VENC_EXPOPRT extern "C"
	#else
	  #define MP4VENC_EXPOPRT extern
	#endif
#endif

/*****************************************************************************
 * Encoder entry point
 ****************************************************************************/
 
/// Faraday MPEG4 Encoder API Functions Reference.
/**
 * 
 * \defgroup encoder_ops_grp Faraday MPEG4 Encoder API Reference
 *
 * The following section describes all the operations Faraday MPEG4 encoder can perform.
 *
 * @{
 */

/// To create an encoder object and return handle to user.
/**  
 * And the returned handle must be used in the rest of encoder operations.
 *
 * @param ptParam is the structure containing necessary encoding parameters
 * @return return an encoder handle (void pointer)
 * @see FMP4_ENC_PARAM
 * @see FMpeg4EncDestroy
 *
 */
MP4VENC_EXPOPRT void * FMpeg4EncCreate(FMP4_ENC_PARAM * ptParam);
/// To set YUV frame buffer address.
/**
 * This operation was used to set the frame buffer address for each Y frame, U frame,
 * and V frame respectively before calling FMpeg4EncOneFrame() function.
 * User must prepare the YUV frame data and store them in the specified Y,U and V address.\n
 * Encoder will fetch the YUV data from the specified frame buffer address to
 * perform encoding procedure.
 *
 * Note that :
 *   <ul>
 *     <li> The YUV data stored in the frame buffer for encoding must be arranged as <B>2D YUV format</B>
 *          for hardware's convenience.
 *     <li> The parameters yaddr, uaddr and vaddr must be an <B>8-byte aligned</B> <I><B>(64-bit alignment)</B></I> address.
 *     <li> The parameters yaddr, uaddr and vaddr provided by user must be physical address.
 *   </ul>
 * @param enc_handle is the structure containing necessary encoding parameters
 * @param yaddr is the address where the Y frame is stored. 
 *              The address must be pyhsical address and <B>8-byte aligned</B> <I><B>(64-bit alignment)</B></I>.
 * @param uaddr is the address where the U frame is stored.
 *              The address must be pyhsical address and <B>8-byte aligned</B> <I><B>(64-bit alignment)</B></I>.
 * @param vaddr is the address where the V frame is stored.
 *              The address must be pyhsical address and <B>8-byte aligned</B> <I><B>(64-bit alignment)</B></I>.
 * @return return void.
 * @see FMpeg4EncOneFrame
 * @see FMpeg4EncGetBitsLength
 *
 */
MP4VENC_EXPOPRT void FMpeg4EncSetYUVAddr(void *enc_handle,unsigned char *yaddr,unsigned char *uaddr,unsigned char *vaddr);
/// To encode one frame
/**
 * After each Y,U and V frame buffer address is set by using FMpeg4EncSetYUVAddr() function , user can 
 * start to encode one frame by calling this function.
 *
 * @param enc_handle is the handle of encoder object.
 * @return return 1 if the encoding is successful.
 * @see FMpeg4EncSetYUVAddr
 * @see FMpeg4EncGetBitsLength
 *
 */
MP4VENC_EXPOPRT int FMpeg4EncOneFrame(void *enc_handle,int *key_frame);
/// To get encoded bitstream length
/**
 * After one frame is encoded, user is able to obtain the encoded bitstream length of last encoded
 * frame by using this function.
 *
 * @param enc_handle is the handle of encoder object.
 * @return return the encoded bitstream length of last encoded frame.
 *
 */
MP4VENC_EXPOPRT unsigned int FMpeg4EncGetBitsLength(void *enc_handle);
/// To obtain related macroblock information of current encoded image
/**
 * This function will return a pointer to an array of MACROBLOCK_INFO
 * structure which contains various kind of information about encoded
 * macroblock such as macroblock mode, macroblock level quantization value 
 * and motion vectors for 4MV and 1MV.\n
 * The length of this returned array of MACROBLOCK_INFO structure is depending on
 * the total number of macroblocks in one image. Take QCIF format image as an example,
 * the returned array will consists of 99 MACROBLOCK_INFO structure elements.
 *
 * @param enc_handle is the handle of encoder object.
 * @return return a pointer to an array of MACROBLOCK_INFO strcutre.
 *
 */
MP4VENC_EXPOPRT MACROBLOCK_INFO *FMpeg4EncGetMBInfo(void *enc_handle);
/// To destroy encoder object
/**
 * To destroy the encoder object.
 *
 * @param enc_handle is the handle of encoder object.
 * @return return 1 if the encoder object is released successfully.
 * @see FMpeg4EncCreate
 *
 */
MP4VENC_EXPOPRT int FMpeg4EncDestroy(void *enc_handle);
/**
 * @}
 */
#endif