/**
 * @brief           JPG Manager Header
 * @author          AXELL CORPORATION
 * @description     JPG Manager提供ヘッダ。<p>JPG Manager使用時にincludeして下さい。
 * @note            none
 * @history         2017_02_22  初版
 * @history         2017_05_01  [#1303]JPGライブラリの変更
 * @history         2017_10_26  Ver2.0
 * @history         2018_01_24  Ver2.1
 *                  [#1781] 品質設定API "AG903_JPGSetQScale" を追加
 * @history         2021_06_30  [SDK3.3] 異常なJPEGデータのデコードが終了しなくなる不具合を修正 (#3255)
*/
/* DOM-IGNORE-BEGIN */
/*
 * This program was created by AXELL CORPORATION.
 * Copyright (C) 2017-2021 AXELL CORPORATION, all rights reserved.
 */

#ifndef __JPGMGR_H__
#define __JPGMGR_H__
/* DOM-IGNORE-END */

#ifdef __cplusplus
extern "C" {
#endif

/** コーデックモード */
enum AG903_JPG_ENDEC_ENUM{
	AG903_JPG_ENDEC_DECODE					= 0	,	/** Decode operation */
	AG903_JPG_ENDEC_ENCODE						,	/** Encode operation */
};

/** カラーコンポーネント */
enum AG903_JPG_CCOMP_ENUM{
	AG903_JPG_CCOMP_YUV420					= 0	,	/** YUV420 mode */
	AG903_JPG_CCOMP_YUV422						,	/** YUV422 mode */
};

/** フック要因 */
enum AG903_JPG_HOOK_ENUM{
	AG903_JPG_HOOK_CMP						= 0	,	/** バス転送完了 */
	AG903_JPG_HOOK_STRE							,	/** ストリームデータ転送エラー */
	AG903_JPG_HOOK_IMGE							,	/** 画像データ転送エラー */
	AG903_JPG_HOOK_CAPE							,	/** キャプチャーオーバーフロー */
	AG903_JPG_HOOK_ESTE							,	/** エンコード開始エラー */
	AG903_JPG_HOOK_EOI							,	/** EOI検出 */
	AG903_JPG_HOOK_SOI							,	/** SOI/Pictureヘッダ検出 */
	AG903_JPG_HOOK_EOP							,	/** CODEC完了 */
	AG903_JPG_HOOK_SOP							,	/** CODEC開始 */
	AG903_JPG_HOOK_NG							,	/** コーデックエラー */
	AG903_JPG_HOOK_SOS							,	/** SOS検出 */
	AG903_JPG_HOOK_DCTRI						,	/** DCT読み込み */
	AG903_JPG_HOOK_INITF						,	/** CODEC初期化完了 */
	AG903_JPG_HOOK_SRSTF						,	/** CODECソフトリセット完了	*/

	AG903_JPG_HOOK_MAX								/** フック要因数 */
};

/** JPGハンドル */
typedef uint32_t	AG903_JPGHandle;

/** コーデック制御パラメータ<p>
    interval はRestartマーカーのインターバルの設定です。<p>
	operation は右から指定します。 AG903_JPG_ENDEC_DECODE , AG903_JPG_ENDEC_ENCODE<p>
    color_cmpnt は右から指定します。 AG903_JPG_CCOMP_YUV420 , AG903_JPG_CCOMP_YUV422<p>
    EOImarker は true=マーカーON、false=マーカーOFF です。<p>
    RSTmarker は true=マーカーON、false=マーカーOFF です。<p>
    SOImarker は true=マーカーON、false=マーカーOFF です。<p>
    marker は true=マーカーON、false=マーカーOFF です。<p>
    SOSstop は true=デコード停止、false=通常動作 です。*/
typedef struct _AG903_JPGCtrlParam {
	uint16_t	interval;		/** Restartマーカー インターバル */
	uint8_t		operation;		/** Codec Operation Decode/Encode */
	uint8_t		color_cmpnt;	/** Color Component YUV420/YUV422 (Encode時のみ) */
	uint8_t		EOImarker;		/** EOIマーカー On/Off (Encode時のみ) */
	uint8_t		RSTmarker;		/** RSTマーカー On/Off (Encode時のみ) */
	uint8_t		SOImarker;		/** SOIマーカー On/Off (Encode時のみ) */
	uint8_t		marker;			/** DQT/SOF/DHT/SOSマーカー On/Off (Encode時のみ) */
	uint8_t		SOSstop;		/** SOS検出Stop (Decode時のみ) */
	uint8_t		reserve[3];		/** 予約 */
}	AG903_JPGCtrlParam;

/** コーデック設定パラメータ<p>
    in_buf は4バイトアラインされたアドレスを指定して下さい。
    またデコード時はデータの末尾に0xXXを4バイト以上余分に付加して下さい。<p>
    out_buf は4バイトアラインされたアドレスを指定して下さい。
    またエンコード時はサイズを見積もれませんので十分なサイズを確保して下さい。<p>
    strm_size は in_buf に余分に付加したデータを含めたサイズを設定して下さい。<p>
    stride は ストライドのバイトサイズを設定して下さい。
	また設定値は8ピクセルの倍数（16バイト）単位にする必要があります。<p>
	capture は true=キャプチャ回路から取り込み、false=VRAMから取り込み です。<p>
    buf_flow は true=有効、false=無効 です。（BMU使用時はtrueを指定して下さい）<p>
    flame_skip は true=次のSOIマーカーまでフレームをスキップする、false=スキップなし です。*/
typedef struct _AG903_JPGCodecParam {
	void*		in_buf;		/** 入力バッファ (capture OFF時のみ) */
	void*		out_buf;	/** 出力バッファ */
	uint32_t	h_size;		/** 水平サイズ[pixel] (Encode時のみ) */
	uint32_t	v_size;		/** 垂直サイズ[pixel] (Encode時のみ) */
	uint32_t	strm_size;	/** ストリームサイズ (Decode時のみ)  */
	uint16_t	stride;		/** ストライドサイズ (capture OFF時のみ)  */
	uint8_t		capture;	/** capture ON/OFF */
	uint8_t		buf_flow;	/** バッファ管理フロー制御 ON/OFF */
	uint8_t		flame_skip;	/** Search next SOI automatically ON/OFF */
	uint8_t		reserve[3];	/** 予約 */
}	AG903_JPGCodecParam;

/** コールバック関数型<p>
    handle はJPGハンドル、param は AG903_JPGSetHooks で設定したパラメータです。*/
typedef void (*AG903_JPGClbk)(AG903_JPGHandle *handle, uint32_t param);

/** フックリスト構造体<p>
    コールバック不要な場合は clbk にNULLを設定して下さい。<p>
    param はコールバック関数に引数として渡されます。*/
typedef struct _AG903_JPGHooks {
	AG903_JPGClbk	clbk;	/** コールバック関数ポインタ */
	uint32_t			param;	/** 任意のパラメータ */
}	AG903_JPGHooks;

/*************************************************************************************
 * プロトタイプ定義
 ************************************************************************************/

/**
 * @brief           JPGモジュール初期化
 * @param           none
 * @return          初期化結果
 * @retval          AG903_ENONE  正常終了
 * @description     内部状態の初期化を行います。システム起動時にCALLして下さい。
*/
int32_t AG903_JPGInit(void);

/**
 * @brief           JPGハンドル取得
 * @param           handle [out] JPGハンドル
 * @return          ハンドル取得結果
 * @retval          AG903_ENONE    正常終了
 * @retval          -AG903_EINVAL  引数異常
 * @retval          -AG903_EBUSY   ハンドル使用中
 * @retval          -AG903_EFAULT  処理失敗（割込みハンドラ登録失敗）
 * @description     JPGのハンドルを取得します。
 * @note            内部状態は、取得時に初期化されます。
 * @note	        以下のINTManager APIを使用します。
 * @note              ・AG903_INTMgrSetHandler
 * @note              ・AG903_INTMgrEnableInt
*/
int32_t AG903_JPGGetHandle(AG903_JPGHandle **handle);

/**
 * @brief           JPGハンドル解放
 * @param           handle [in] JPGハンドル
 * @return          ハンドル解放結果
 * @retval          AG903_ENONE    正常終了
 * @retval          -AG903_EINVAL  引数異常
 * @retval          -AG903_EBUSY   ハンドル使用中
 * @description     ハンドルを解放します。<p>動作中にハンドルが解放された場合はエラーを返します。 
 * @note            処理中は、ハンドルの解放は行わないでください。
*/
int32_t AG903_JPGReleaseHandle(AG903_JPGHandle *handle);

/**
 * @brief           ストリームサイズ取得
 * @param           handle [in] JPGハンドル
 * @param           size [out] ストリームサイズ [バイト]
 * @return          ストリームサイズ取得結果
 * @retval          AG903_ENONE    正常終了
 * @retval          -AG903_EINVAL  引数異常
 * @description     ストリームサイズを取得します。（エンコード後にデータサイズを取得することができます。）
*/
int32_t AG903_JPGGetStreamSize(AG903_JPGHandle *handle, uint32_t *size);

/**
 * @brief           イメージサイズ取得
 * @param           handle [in] JPGハンドル
 * @param           xlen [out] 横幅 [pixel]
 * @param           ylen [out] 縦幅 [pixel]
 * @return          イメージサイズ取得結果
 * @retval          AG903_ENONE    正常終了
 * @retval          -AG903_EINVAL  引数異常
 * @description     イメージサイズを取得します。（デコード後にデコードした画像のサイズを取得することができます。）
*/
int32_t AG903_JPGGetImageSize(AG903_JPGHandle *handle, uint32_t *xlen, uint32_t *ylen);

/**
 * @brief           カラーコンポーネント取得
 * @param           handle [in] JPGハンドル
 * @param           ccomp [out] カラーコンポーネント [0:YUV420,1:YUV422]
 * @return          カラーコンポーネント取得結果
 * @retval          AG903_ENONE    正常終了
 * @retval          -AG903_EINVAL  引数異常
 * @description     カラーコンポーネントを取得します。（デコード後にJPEGフレームヘッダからカラーコンポーネントを取得することができます。）
*/
int32_t AG903_JPGGetColorComponent(AG903_JPGHandle *handle, uint8_t *ccomp);

/**
 * @brief           コーデック初期化
 * @param           handle [in] JPGハンドル
 * @param           param [out] 制御パラメータ
 * @return          コーデック初期化結果
 * @retval          AG903_ENONE    正常終了
 * @retval          -AG903_EINVAL  引数異常
 * @retval          -AG903_EBUSY   ハンドル使用中（処理中）
 * @description     コーデックを初期化します。 
 * @note            デコード処理からエンコード処理への切り替え、またはその逆の切り替えを行う場合、コーデック終了処理(AG903_JPGEndCodec)<p>
 *                  で現在の処理を終了させた後、当関数をコールしてください。<p>
 *                  同一処理を行う場合は、コーデック終了処理は不要です。
 * @note            処理中に発生したエラーはAG903_JPGSetHooksでコールバックを登録して検出してください。
*/
int32_t AG903_JPGInitCodec(AG903_JPGHandle *handle, AG903_JPGCtrlParam *param);

/**
 * @brief           コーデック開始処理
 * @param           handle [in] JPG ハンドル
 * @param           param [in] コーデックパラメータ
 * @return          コーデック開始結果
 * @retval          AG903_ENONE    正常終了
 * @retval          -AG903_EINVAL  引数異常
 * @retval          -AG903_EILSEQ  状態異常（未初期化/処理中）
 * @description     コーデックの動作を開始します。
 * @note            デコード時は、4Byte以上のダミーデータを付加してください。<p>
 *                  ダミーデータを付加しない場合、データ転送が終了しない恐れがあります。<p>
 *                  エンコード時は、エンコードデータ出力先バッファの先頭4Byteに、エンコードデータのサイズが格納されます。エンコードデータは、先頭4Byte後から格納されます。
 * @note            処理中に発生したエラーはAG903_JPGSetHooksでコールバックを登録して検出してください。
*/
int32_t AG903_JPGStartCodec(AG903_JPGHandle *handle, AG903_JPGCodecParam *param);

/**
 * @brief           コーデック終了処理
 * @param           handle [in] JPGハンドル
 * @return          コーデック終了結果
 * @retval          AG903_ENONE    正常終了
 * @retval          -AG903_EINVAL  引数異常
 * @description     コーデックの処理を終了します。
*/
int32_t AG903_JPGEndCodec(AG903_JPGHandle *handle);

/**
 * @brief           コールバック登録
 * @param           handle [in] JPGハンドル
 * @param           hook [in] フックリスト
 * @return          コールバック登録結果
 * @retval          AG903_ENONE    正常終了
 * @retval          -AG903_EINVAL  引数異常
 * @description     コールバックを登録します。<p>
 *                  hookには以下を配列とし、必要なコールバックを登録して下さい。<p>
 *                  <table>
 *                  <tr><th>hook</th><th>コールバック条件</th></tr>
 *                  <tr><td>AG903_JPG_HOOK_CMP</td><td>バス転送完了</td></tr>
 *                  <tr><td>AG903_JPG_HOOK_STRE</td><td>ストリームデータ転送エラー</td></tr>
 *                  <tr><td>AG903_JPG_HOOK_IMGE</td><td>画像データ転送エラー</td></tr>
 *                  <tr><td>AG903_JPG_HOOK_CAPE</td><td>キャプチャーオーバーフロー</td></tr>
 *                  <tr><td>AG903_JPG_HOOK_ESTE</td><td>エンコード開始エラー</td></tr>
 *                  <tr><td>AG903_JPG_HOOK_EOI</td><td>EOI検出</td></tr>
 *                  <tr><td>AG903_JPG_HOOK_SOI</td><td>SOI/Pictureヘッダ検出</td></tr>
 *                  <tr><td>AG903_JPG_HOOK_EOP</td><td>CODEC完了</td></tr>
 *                  <tr><td>AG903_JPG_HOOK_SOP</td><td>CODEC開始</td></tr>
 *                  <tr><td>AG903_JPG_HOOK_NG</td><td>コーデックエラー</td></tr>
 *                  <tr><td>AG903_JPG_HOOK_SOS</td><td>SOS検出</td></tr>
 *                  <tr><td>AG903_JPG_HOOK_DCTRI</td><td>DCT読み込み</td></tr>
 *                  <tr><td>AG903_JPG_HOOK_INITF</td><td>CODEC初期化完了</td></tr>
 *                  <tr><td>AG903_JPG_HOOK_SRSTF</td><td>CODECソフトリセット完了</td></tr>
 *                  </table>
 * @note            コールバック不要な場合は clbk に NULL を設定して下さい。
 * @note            コーデックの処理完了は「AG903_JPG_HOOK_EOP」ではなく「AG903_JPG_HOOK_CMP」で判断して下さい。
 * @note            AG903_JPG_HOOK_NGのとき入力しているデータが不正である可能性があります。
 * @note            AG903_JPG_HOOK_NGのときはコールバックを抜けた後AG903_JPGEndCodecで終了し、
 *                  AG903_JPGInitで初期化して下さい。
*/
int32_t AG903_JPGSetHooks(AG903_JPGHandle *handle, AG903_JPGHooks *hook);

/**
 * @brief           品質値を設定
 * @param           scale [in] 品質値
 * @return          品質値設定結果
 * @retval          AG903_ENONE    正常終了
 * @retval          -AG903_EINVAL  引数異常
 * @description     画像の品質値を指定します。指定範囲は、0：低品質（高圧縮率）から100：高品質（低圧縮率）の間で指定してください。<p>
 *                  また、本関数で設定した品質値は、JPGモジュール初期化関数「AG903_JPGInit」を実行する事で適用します。<p>
 *                  デフォルト値は75です。
*/
int32_t AG903_JPGSetQScale(uint8_t scale);


#ifdef __cplusplus
}
#endif

#endif/* __JPGMGR_H__ */
