/** *  @file jpeg_dec.h *  @brief The header file for Faraday JPEG Decoder API. * */#ifndef _JPEG_DEC_H_#define _JPEG_DEC_H_/** *  By using typedef to create a type name for DMA memory allocation function. *  And user can allocate memory on a specified alignment memory  *  by using the parameter align_size. * *  @param size is the bytes to allocate. *  @param align_size is the alignment value which must be power of 2. *  @param reserved_size is the specifed cache line. *  @param phy_ptr is used to return the physical address of allocated aligned memory block. *  @return return a void pointer to virtual address of the allocated memory block. *  @see FJPEG_DEC_PARAM *  @see DMA_FREE_PTR */typedef void *(* DMA_MALLOC_PTR)(unsigned int size,unsigned char align_size,unsigned char reserved_size, void ** phy_ptr);/** *  By using typedef to create a type name for DMA memory free function. *  And user can use this type of function to free a block of memory that *  was allocated by the DMA_MALLOC_PTR type of function. * *  @param virt_ptr is a pointer to the memory block with virtual address that was returned *                  previously by the type of DMA_MALLOC_PTR function. *  @param phy_ptr is a pointer to the memory block with physical address that was returned *                 previously by the type of DMA_MALLOC_PTR function. *  @return return void. *  @see FJPEG_DEC_PARAM *  @see DMA_MALLOC_PTR */typedef void (* DMA_FREE_PTR)(void * virt_ptr, void * phy_ptr);/// The Faraday JPEG Decoder Parameters Structure./** *  While creating jpeg decoder object by using FJpegDecCreate() operation, FJPEG_DEC_PARAM *  pointer is served as FJpegDecCreate()'s parameter to internally initialize related JPEG decoder *  object settings. The data member pu32BaseAddr and pu8BitstreamAddr must be set before *  invoking the FJpegDecCreate() operation.\n * *  This data structure is also used for FJpegDecDecode() operation where the data member *  u8NumComponents and pu8YUVAddr must be set before invoking the FJpegDecDecode() operation. *   * *  See  @ref jpeg_decoder_ops_grp \n *  @see FJpegDecCreate *   */typedef struct {  /// The base address of hardware core.  unsigned int  *pu32BaseAddr;    /**< User can use this variable to set the base                                   *   address of hardware core.                                   *                                   *   @see pu8BitstreamAddr                                   */                                     /// 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                                 */  /// The input bitstream buffer physical address while decoding the jpeg bitstream.  unsigned char *pu8BitstreamAddr;  /**< To set input bitstream buffer's physical address.\n                                     *   This bitstream buffer was provided by user and used for JPEG decoder while                                     *   decoding JPEG bitstream.\n                                     *   <B>N.B.</B> : the input bitstream buffer address must be <B>physical address</B> with <B>4-byte aligned</B>.                                     *                                     *  @see pu32BaseAddr                                     */    /// The number of components in the decoding YUV image.  unsigned char  u8NumComponents;  /**< This variable shows the number of components in the decoding                                    *   image, which is also extracted from 'SOF' marker directly.                                    *   The color space used for these components is <B>YCbCr</B>.                                    *   If only one component is used, the component will be <B>Y</B> only.                                    *                                    *   @see pu8YUVAddr                                    */  /// The base physical address for output YUV buffer.  unsigned char *pu8YUVAddr[3];  /**< To set input YUV frame buffer's base physical address.\n                                  *   <B>N.B.</B> : the address must be physical address with <B>8-byte aligned</B>.                                  *                                  *   @see u8NumComponents                                                                    */} FJPEG_DEC_PARAM;/// The Faraday JPEG Decoder Result Image Descriptor (YCbCr)./** *  After reading the jpeg header , some side informations about the decoded YUV image *  were generated and reflected within FJPEG_DEC_RESULT structure after  *  calling FJpegDecReadHeader() operation. \n  * *  @see FJpegDecReadHeader *   */typedef struct {  /// The image width in pixels.  unsigned int   u32ImageWidth;    /**< This member variable indicates the actual image width after                                     *   JPEG decoding, which is extracted from 'SOF' marker directly.                                    */  /// The image height in pixels.  unsigned int   u32ImageHeight;   /**< This member variable indicates the actual image height after                                    *   JPEG decoding, which is extracted from 'SOF' marker directly.                                    */  /// The number of components in the decoding image.  unsigned char  u8NumComponents;  /**< This variable shows the number of components in the decoding                                    *   image, which is also extracted from 'SOF' marker directly.                                    *   The color space used for these components is <B>YCbCr</B>.                                    *   If only one component is used, the component will be <B>Y</B> only.                                    */  /// The array of structures to describe each component information about decoded image.    struct {    /// The horizontal sampling frequency of this component.    unsigned char m_u8HSamplingFrequency;  /**< horizontal sampling frequency factor (1..4) for this component.*/    /// The vertical sampling frequency of this component.    unsigned char m_u8VSamplingFrequency;  /**< vertical sampling frequency factor (1..4) for this component.  */        // The address where this component is stored.    //unsigned char *m_pComponent;           /**< the address where this component is stored  */        /// This component's width in pixels.    unsigned int m_u32ComponentWidth;      /**< this component horizontal sample width in pixels */    /// This component's height in pixels.    unsigned int m_u32ComponentHeight;     /**< this component's vertical sample width in pixels */            /// This component's total size in bytes = (m_u32ComponentWidth * m_u32ComponentHeight).    unsigned int m_u32ComponentTotalSize;  /**< this component's total size in bytes , which is equal to (m_u32ComponentWidth * m_u32ComponentHeight) */      } rgComponentInfo[3];  /**<                          *  According to JFIF standard, the color space is restricted to one or three components. \n                          *  For three components, <B>YCbCr</B> is used. \n                          *  If only one component is used, the component will be <B>Y</B>. \n                          *  Thus, depending on the number of components (indicated by member vairable 'u8NumComponents'),                           *  the following array of component descriptor 'rgComponentInfo' structure are in the                           *  order <B>{ Y, Cb,Cr }</B> respectively.                          *                            *  @see u8NumComponents                          */  } FJPEG_DEC_RESULT; #ifndef JPEGDEC_EXPOPRT  #ifdef __cplusplus	  #define JPEGDEC_EXPOPRT extern "C"	#else	  #define JPEGDEC_EXPOPRT extern	#endif#endif/***************************************************************************** * JPEG Decoder entry point ****************************************************************************/ /// Faraday JPEG Decoder API Functions Reference./** *  * \defgroup jpeg_decoder_ops_grp Faraday JPEG Decoder API Reference * * The following section describes all the operations Faraday JPEG decoder can perform. * * @{ *//// To create an JPEG decoder object and return handle to user./**   * And the returned handle have to be used in the rest of JPEG decoder operations. * * @param ptParam is the structure containing necessary decoder object parameters * @return return an JPEG decoder handle (void pointer) * * @see FJPEG_DEC_PARAM * @see FJpegDecDecode * @see FJpegDecDestroy * */JPEGDEC_EXPOPRT void * FJpegDecCreate(FJPEG_DEC_PARAM * ptParam);/// To read header of JPEG bitstream and obtain related decoding information./**   * Obtain the informations wby reading the header of JPEG bitstream. * * @param dec_handle is the handle of JPEG decoder object. * @param pDecResult contains the header informations about decoded image. * @return return void. If there is error during reading the JPEG header, the program *                      will simply print error message to stderr and exit the program. * * @see FJPEG_DEC_PARAM * @see FJPEG_DEC_RESULT * @see FJpegDecDecode * @see FJpegDecDestroy * */JPEGDEC_EXPOPRT void FJpegDecReadHeader(void *dec_handle,FJPEG_DEC_RESULT *pDecResult);/// To begin to decode JPEG bitstream./** * After calling FJpegDecReadHeader() function , user can start to decode JPEG bitstream by  * calling this function. And pass the allocated YUV buffer image pointer through  * 'FJPEG_DEC_PARAM' structure. * * @param dec_handle is the handle of JPEG decoder object. * @param ptParam is the structure containing necessary decoder object parameters such as *        the allocated YUV buffer space pointer and the number of components. * @return return void. If there is error during decoding, the program *                      will simply print error message to stderr and exit the program. * * @see FJPEG_DEC_PARAM * @see FJPEG_DEC_RESULT * @see FJpegDecCreate * @see FJpegDecDestroy * */JPEGDEC_EXPOPRT void FJpegDecDecode(void *dec_handle,FJPEG_DEC_PARAM * ptParam);/// To destroy a JPEG decoder object/** * After decoding, we need to release the JPEG decoder object. * * @param dec_handle is the handle of JPEG decoder object. * @return return void. * @see FJpegDecCreate * */JPEGDEC_EXPOPRT void FJpegDecDestroy(void *dec_handle);/** * @} */#endif