jpeg_dec.h

基于Linux的ffmepg decoder

/**
 *  @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