/**
 * @brief           GVD API Header
 * @author          AXELL CORPORATION
 * @description     GVD API定義
 * @note            none
 * @history         2017_02_22  初版
 * @history         2017_10_26  Ver2.0
 * @history         2020_07_22  [SDK3.1] GVDの強制停止APIを追加 (#2964)
 * @history         2020_07_22  [SDK3.1] GVDが占有するメモリ領域を指定するAPIを追加 (#2965)
 */
/* DOM-IGNORE-BEGIN */
/*
 * This program was created by AXELL CORPORATION.
 * Copyright (C) 2017-2020 AXELL CORPORATION, all rights reserved.
 */

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

#include <stddef.h>
#include <stdint.h>
#include <stdbool.h>

#include "gvd_error.h"
#include "gvd_api_params.h"

#ifndef GVD_MAX_ENUM
#define GVD_MAX_ENUM 0x7FFFFFFF
#endif

/** 出力先選択 [GVD_SelectOutputModule] */
typedef enum {
    GVD_OUTMOD_NONE,	/** 出力先なし */
    GVD_OUTMOD_BMU,		/** 出力先=BMU */
    GVD_OUTMOD_VRAM,	/** 出力先=VRAM */
    GVD_OUTMOD_FORCE_SIZE            = GVD_MAX_ENUM /** sentinel */
} gvdOutMod;

/** コールバック関数の引数 [GVD_SetCallbackParams] */
typedef struct {
    void *commit_output_buffer;		/** フレーム出力通知 */
    void *discard_input_buffer;		/** 入力バッファ破棄通知 */
    void *discard_output_buffer;	/** 出力バッファ破棄通知 */
    void *notify_frame_size;		/** フレームサイズ更新通知 */
    void *notify_decode_error;		/** デコードエラー通知 */
    void *notify_stream_pos;		/** ストリーム位置取得通知 */
    void *decode_stream_end;		/** 再生完了通知 */
    void *rewind_done;				/** 早戻し完了通知 */
    void *seqparam_decode_done;		/** シーケンス情報デコード完了通知 */
} gvdCbParams;


/**
 * @brief           コールバック関数 [GVD_SetCallbackFunctions]
 * @description     GVDライブラリからの各種通知を GVD_SetCallbackFunctions で登録することができます.<p>
 *                  また, 使用しない通知は NULL を登録することで無効にすることができます.<p>
 *                  各コールバック関数の詳細は GVDコールバック関数一覧 を参照してください.
 */
typedef struct {
    gvdCbFunc connect_done;					/** 接続完了通知 */
    gvdCbFunc disconnect_done;				/** 切断完了通知 */
    gvdCbFunc put_input_buffer_done;		/** 入力バッファ受付通知 */
    gvdCbFunc put_output_buffer_done;		/** 出力バッファ受付通知 */
    gvdCbFunc discard_output_buffers_done;	/** 出力バッファ破棄受付通知 */
    gvdCbFunc commit_output_buffer;			/** フレーム出力通知 */
    gvdCbFunc discard_input_buffer;			/** 入力バッファ破棄通知 */
    gvdCbFunc discard_output_buffer;		/** 出力バッファ破棄通知 */
    gvdCbFunc notify_frame_size;			/** フレームサイズ更新通知 */
    gvdCbFunc notify_decode_error;			/** デコードエラー通知 */
    gvdCbFunc notify_stream_pos;			/** ストリーム位置取得通知 */
    gvdCbFunc decode_stream_end;			/** 再生完了通知 */
    gvdCbFunc seek_done;					/** シーク完了通知 */
    gvdCbFunc rewind_done;					/** 早戻し完了通知 */
    gvdCbFunc pause_done;					/** 一時停止完了通知 */
    gvdCbFunc play_accepted;				/** 再生受付完了通知 */
    gvdCbFunc get_timestamp_done;			/** タイムスタンプ取得通知 */
    gvdCbFunc rewind_accepted;				/** 早戻し受付通知 */
    gvdCbFunc forward_accepted;				/** 早送り受付通知 */
    gvdCbFunc seqparam_decode_done;			/** シーケンス情報デコード完了通知 */
} gvdCbFuncs;

/** コンテキスト状態 [GVD_GetStatus] */
typedef enum {
    GVD_APIFUNC_STATUS_CLOSE,	/** クローズ状態 */
    GVD_APIFUNC_STATUS_PAUSE,	/** 停止中 */
    GVD_APIFUNC_STATUS_PLAY,	/** 再生中 */
    GVD_APIFUNC_STATUS_REWIND,	/** 早戻し中 */
    GVD_APIFUNC_STATUS_FORWARD,	/** 早送り中 */
    GVD_APIFUNC_STATUS_UNKNOWN,	/** 不定状態 */
    GVD_APIFUNC_STATUS_FORCE_SIZE       = GVD_MAX_ENUM /** sentinel */
} gvdApiFuncStatus;

typedef struct gvdContext_s gvdContext;	/** GVDコンテキスト型 */

/**
 * @brief           GVDライブラリパラメータ初期化
 * @param           initparam [in] ライブラリ初期化パラメータ
 * @return          GVDのエラーコード
 * @retval          GVD_ERR_SUCCESS 正常終了
 * @retval          GVD_ERR_BAD_PARAMETER 引数に不正なパラメータが与えられた
 * @description     ライブラリ初期化パラメータを初期化します.<p>
 *                  必ず本APIでパラメータの初期化を行ってください.<p>
 *                  本APIでパラメータ初期化後にGVD_GetRequiredMemorySize,
 *                  GVD_SetWorkMemory, GVD_Initializeを実行してください.
 * @note            本APIは同期処理されます.
 * @seealso         gvdInitializeParam
 */
gvdError GVD_InitInitializeParam(gvdInitializeParam *initparam);
/**
 * @brief           ワークメモリサイズ算出
 * @param           void
 * @return          ワークメモリサイズ [Byte]
 * @description     GVDが要求するワークメモリサイズを返します.<p>
 *                  GVD_InitInitializeParamで動作構成を初期化した後にコールしてください.
 * @note            本APIは同期処理されます.
 * @seealso         GVD_SetWorkMemory
 */
uint32_t GVD_GetRequiredMemorySize(void);
/**
 * @brief           ワークメモリ設定
 * @param           address [in] ワークメモリ領域先頭のアドレス
 * @param           size [in] ワークメモリサイズ [Byte]
 * @return          GVDのエラーコード
 * @retval          GVD_ERR_SUCCESS 正常終了
 * @retval          GVD_ERR_BAD_PARAMETER 引数に不正なパラメータが与えられた
 * @description     GVDがワークメモリとして使用するメモリ領域を設定します.<p>
 *                  GVD_GetRequiredMemorySizeで取得したサイズ以上のメモリを確保してください.<p>
 *                  ワークメモリの先頭アドレスは32kB境界にある必要があります.<p>
 *                  ワークメモリ領域の属性は, キャッシュ無し・共有としてください.
 * @note            本APIは同期処理されます.
 */
gvdError GVD_SetWorkMemory(void *address, size_t size);
/**
 * @brief           GVDライブラリ初期化
 * @param           void
 * @return          GVDのエラーコード
 * @retval          GVD_ERR_SUCCESS 正常終了
 * @retval          GVD_ERR_BAD_PARAMETER 引数に不正なパラメータが与えられた
 * @retval          GVD_FATALERR_MSVD_INIT_FAILURE ドライバ初期化失敗
 * @retval          GVD_ERR_RESOURCE_NOT_ENOUGH メモリ不足
 * @description     動画デコーダを初期化します.
 * @seealso         GVD_InitInitializeParam, GVD_SetWorkMemory
 * @note            本APIは同期処理されます.
 * @note            本APIのコールから, GVDライブラリはTIM7を占有します.
 */
gvdError GVD_Initialize(void);
/**
 * @brief           GVDライブラリ終了
 * @param           void
 * @return          GVDのエラーコード
 * @retval          GVD_ERR_SUCCESS 正常終了
 * @retval          GVD_ERR_INVALID_STATE 状態エラー（未初期化, 残存コンテキストあり）
 * @description     動画デコーダの終了処理を行います.<p>
 *                  全てのコンテキストの破棄してから本APIをコールしてください.<p>
 *                  本APIのコール以降は非同期処理はできません. GVD_Executeをコールしないでください.
 * @note            本APIは同期処理されます.
 */
gvdError GVD_Finalize(void);
/**
 * @brief           非同期処理の実行
 * @param           void
 * @return          GVDのエラーコード
 * @retval          GVD_ERR_SUCCESS 正常終了
 * @retval          GVD_ERR_INVALID_STATE 状態エラー（未初期化）
 * @description     非同期処理を実行します.<p>
 *                  GVDライブラリ初期化以降は本APIを定期的に実行してください.<p>
 *                  本APIの処理はGVDライブラリとハードウェア間の処理を含みます.<p>
 *                  著しくコール頻度が低下した場合, デコード性能に影響することがあります.
 * @note            本APIは同期処理されます.
 */
gvdError GVD_Execute(void);
/**
 * @brief           コンテキスト生成
 * @param           gvdctx [out] 生成したコンテキストのポインタ
 * @return          GVDのエラーコード
 * @retval          GVD_ERR_SUCCESS 正常終了
 * @retval          GVD_ERR_RESOURCE_NOT_ENOUGH メモリ不足
 * @retval          GVD_ERR_BAD_PARAMETER 引数に不正なパラメータが与えられた
 * @description     GVDのコンテキストを生成します.<p>
 *                  gvdContextは1つのストリームの内部状態を保持します.
 * @note            本APIは同期処理されます.
 * @seealso         gvdContext
 */
gvdError GVD_CreateContext(gvdContext **gvdctx);
/**
 * @brief           コンテキスト廃棄
 * @param           gvdctx [in] コンテキスト
 * @return          GVDのエラーコード
 * @retval          GVD_ERR_SUCCESS 正常終了
 * @retval          GVD_ERR_BAD_PARAMETER 引数に不正なパラメータが与えられた
 * @retval          GVD_ERR_INVALID_STATE 呼び出しが禁止されているステート
 * @description     GVDのコンテキストを破棄します.
 * @note            コンテキストの状態が CLOSE である必要があります.
 * @note            本APIは同期処理されます.
 */
gvdError GVD_DestroyContext(gvdContext *gvdctx);
/**
 * @brief           コンテキスト接続
 * @param           gvdctx [in] コンテキスト
 * @param           param_user [in] ユーザーパラメータ
 * @return          GVDのエラーコード
 * @retval          GVD_ERR_SUCCESS 正常終了
 * @retval          GVD_ERR_BAD_PARAMETER 引数に不正なパラメータが与えられた
 * @retval          GVD_ERR_INVALID_STATE 呼び出しが禁止されているステート
 * @description     gvdctxに渡されたコンテキストをデコーダに接続します.<p>
 *                  外部ファイルストリーマを使用する場合は, 本APIでコンテキストを接続します.<p>
 *                  本APIの処理によって, コンテキストの状態が PAUSE に遷移します.
 * @note            内蔵ファイルストリーマを使用する場合は, GVD_OpenFileを使用してください.
 * @note            コンテキストの状態が CLOSE である必要があります.
 * @note            本APIは非同期処理されます. 完了通知は gvdCbFuncs の connect_done を参照してください.
 */
gvdError GVD_Connect(gvdContext *gvdctx, void *param_user);
/**
 * @brief           コンテキスト切断
 * @param           gvdctx [in] コンテキスト
 * @param           param_user [in] ユーザーパラメータ
 * @return          GVDのエラーコード
 * @retval          GVD_ERR_SUCCESS 正常終了
 * @retval          GVD_ERR_BAD_PARAMETER 引数に不正なパラメータが与えられた
 * @retval          GVD_ERR_INVALID_STATE 呼び出しが禁止されているステート
 * @description     gvdctxに渡されたコンテキストをデコーダから切断します.<p>
 *                  GVD_Connectで接続したコンテキストを指定してください.<p>
 *                  本APIの処理によって, コンテキストの状態が CLOSE に遷移します.
 * @note            GVD_OpenFileで接続したコンテキストを本APIで切断することはできません.
 * @note            コンテキスト状態が PAUSE である必要があります.
 * @note            本APIは非同期処理されます. 完了通知は gvdCbFuncs の disconnect_done を参照してください.
 */
gvdError GVD_Disconnect(gvdContext *gvdctx, void *param_user);
/**
 * @brief           ストリームオープンとコンテキスト接続
 * @param           gvdctx [in] コンテキスト
 * @param           filename [in] 動画ファイル名
 * @param           param_user [in] ユーザーパラメータ
 * @return          GVDのエラーコード
 * @retval          GVD_ERR_SUCCESS 正常終了
 * @retval          GVD_ERR_BAD_PARAMETER 引数に不正なパラメータが与えられた
 * @retval          GVD_ERR_INVALID_STATE 呼び出しが禁止されているステート
 * @description     gvdctxに渡されたコンテキストをデコーダに接続します.<p>
 *                  さらに, filenameに指定されたストリームを内蔵ストリーマに割り当てます.<p>
 *                  本APIの処理によって, コンテキストの状態が PAUSE に遷移します.
 * @note            コンテキスト状態が CLOSE である必要があります.
 * @note            本APIは非同期処理されます. 完了通知は gvdCbFuncs の connect_done を参照してください.
 */
gvdError GVD_OpenFile(gvdContext *gvdctx, const char *filename, void *param_user);
/**
 * @brief           ストリームクローズとコンテキスト切断
 * @param           gvdctx [in] コンテキスト
 * @param           param_user [in] ユーザーパラメータ
 * @return          GVDのエラーコード
 * @retval          GVD_ERR_SUCCESS 正常終了
 * @retval          GVD_ERR_BAD_PARAMETER 引数に不正なパラメータが与えられた
 * @retval          GVD_ERR_INVALID_STATE 呼び出しが禁止されているステート
 * @retval          GVD_ERR_INVALID_CALL 不正な呼び出し（ファイルストリーマ未使用）
 * @description     gvdctxに渡されたコンテキストに割り当てられた内蔵ストリーマを停止し, ストリームをクローズします.<p>
 *                  さらに, コンテキストをデコーダから切断します.<p>
 *                  本APIの処理によって, コンテキストの状態が CLOSE に遷移します.
 * @note            コンテキスト状態が PAUSE である必要があります.
 * @note            本APIは非同期処理されます. 完了通知は gvdCbFuncs の disconnect_done を参照してください.
 */
gvdError GVD_CloseFile(gvdContext *gvdctx, void *param_user);
/**
 * @brief           ストリームバッファの供給
 * @param           gvdctx [in] コンテキスト
 * @param           ibufinf [in] 入力データ情報
 * @param           param_user [in] ユーザーパラメータ
 * @return          GVDのエラーコード
 * @retval          GVD_ERR_SUCCESS 正常終了
 * @retval          GVD_ERR_BAD_PARAMETER 引数に不正なパラメータが与えられた
 * @retval          GVD_ERR_INVALID_STATE 呼び出しが禁止されているステート
 * @retval          GVD_ERR_INVALID_CALL 不正なAPI 関数の呼び出し
 * @description     ストリーム入力用のバッファをGVDライブラリへ供給します.<p>
 *                  外部ストリーマを使用する場合は, ストリームを本APIでデコーダへ供給します.<p>
 *                  ibufinfにはストリームデータ以外にも各種パラメータがセットできます.<p>
 *                  詳細はgvdInBufInfoを参照してください.
 * @note            コンテキスト状態が CLOSE 以外である必要があります.
 * @note            本APIは非同期処理されます. 返却通知は gvdCbFuncs の discard_input_buffer を参照してください.
 */
gvdError GVD_PutInputBuffer(gvdContext *gvdctx, gvdInBufInfo *bufinf, void *param_user);
/**
 * @brief           出力バッファ供給
 * @param           gvdctx [in] コンテキスト
 * @param           obufinf [in] 出力バッファ情報
 * @param           param_user [in] ユーザーパラメータ
 * @return          GVDのエラーコード
 * @retval          GVD_ERR_SUCCESS 正常終了
 * @retval          GVD_ERR_BAD_PARAMETER 引数に不正なパラメータが与えられた
 * @retval          GVD_ERR_INVALID_STATE 呼び出しが禁止されているステート
 * @retval          GVD_ERR_INVALID_CALL 不正なAPI 関数の呼び出し
 * @description     デコード画像出力用のバッファをGVDライブラリへ供給します.<p>
 *                  出力先にVRAMを使用する場合は, 出力バッファを本APIでデコーダへ供給します.<p>
 *                  obufinfにはフレームデータ以外にも各種パラメータがセットされています.<p>
 *                  詳細はgvdOutBufInfoを参照してください.
 * @note            コンテキストの出力先が VRAM である必要があります.
 * @note            コンテキスト状態が CLOSE 以外である必要があります.
 * @note            本APIは非同期処理されます. 返却通知は gvdCbFuncs の discard_output_buffer を参照してください.
 */
gvdError GVD_PutOutputBuffer(gvdContext *gvdctx, gvdOutBufInfo *obufinf, void *param_user);
/**
 * @brief           出力バッファ破棄
 * @param           gvdctx [in] コンテキスト
 * @param           param_user [in] ユーザーパラメータ
 * @return          GVDのエラーコード
 * @retval          GVD_ERR_SUCCESS 正常終了
 * @retval          GVD_ERR_BAD_PARAMETER 引数に不正なパラメータが与えられた
 * @description     gvdctxに渡されたコンテキストに供給されている出力バッファの返却を要求します.<p>
 *                  GVD_PutOutputBufferで供給していて, discard_output_bufferのコールバックで返却されていないバッファの返却要求を発行します.<p>
 * @note            コンテキスト状態が CLOSE 以外である必要があります.
 * @note            本APIは非同期処理されます. 返却通知は gvdCbFuncs の discard_output_buffer を参照してください.
 */
gvdError GVD_DiscardOutputBuffers(gvdContext *gvdctx, void *param_user);
/**
 * @brief           コールバック設定パラメータ初期化
 * @param           cbfuncs [in] GVD_SetCallbackFunctionsに与える構造体
 * @param           cbparams [in] GVD_SetCallbackParamsに与える構造体
 * @return          GVDのエラーコード
 * @retval          GVD_ERR_SUCCESS 正常終了
 * @description     GVD_SetCallbackParamsとGVD_SetCallbackFunctionsに渡す構造体の初期化を行います.<p>
 *                  どちらか一方のみを初期化したい場合はもう一方にNULLを指定してください.
 * @note            本APIは同期処理されます.
 */
gvdError GVD_InitCallbackInfo(gvdCbFuncs *cbfuncs, gvdCbParams *cbparams);
/**
 * @brief           コールバック関数の引数設定
 * @param           gvdctx [in] コンテキスト
 * @param           cbparams [in] コールバック関数引数
 * @return          GVDのエラーコード
 * @retval          GVD_ERR_SUCCESS 正常終了
 * @retval          GVD_ERR_BAD_PARAMETER 引数に不正なパラメータが与えられた
 * @retval          GVD_ERR_INVALID_STATE 呼び出しが禁止されているステート
 * @description     一部のコールバック関数の引数を設定します.<p>
 *                  設定値については, gvdCbParams を参照してください.
 * @note            コンテキスト状態が CLOSE である必要があります.
 * @note            本APIは同期処理されます.
 */
gvdError GVD_SetCallbackParams(gvdContext *gvdctx, gvdCbParams *cbparams);
/**
 * @brief           コールバック関数設定
 * @param           gvdctx [in] コンテキスト
 * @param           cbfuncs [in] コールバック関数
 * @return          GVDのエラーコード
 * @retval          GVD_ERR_SUCCESS 正常終了
 * @retval          GVD_ERR_BAD_PARAMETER 引数に不正なパラメータが与えられた
 * @retval          GVD_ERR_INVALID_STATE API 関数の呼び出しが禁止されているステート
 * @description     コールバック関数を設定します.<p>
 *                  設定値については, gvdCbFuncs を参照してください.
 * @note            コンテキスト状態が CLOSE である必要があります.
 * @note            本APIは同期処理されます.
 */
gvdError GVD_SetCallbackFunctions(gvdContext *gvdctx, gvdCbFuncs *cbfuncs);
/**
 * @brief           出力先選択
 * @param           gvdctx [in] コンテキスト
 * @param           omod [in] 出力先
 * @return          GVDのエラーコード
 * @retval          GVD_ERR_SUCCESS 正常終了
 * @retval          GVD_ERR_BAD_PARAMETER 引数に不正なパラメータが与えられた
 * @retval          GVD_ERR_RESOURCE_NOT_ENOUGH BMU出力数超過
 * @retval          GVD_ERR_INVALID_STATE 接続状態での呼び出し
 * @description     コンテキストの出力先を設定します.<p>
 * @note            出力先がBMUのコンテキストは, 最大4つ定義できます.
 * @note            コンテキスト状態が CLOSE である必要があります.
 * @note            本APIは同期処理されます.
 */
gvdError GVD_SelectOutputModule(gvdContext *gvdctx, gvdOutMod omod);
/**
 * @brief           BMU ID取得
 * @param           gvdctx [in] コンテキスト
 * @param           bmuid [out] BMUのID格納先
 * @return          GVDのエラーコード
 * @retval          GVD_ERR_SUCCESS 正常終了
 * @retval          GVD_ERR_BAD_PARAMETER 引数に不正なパラメータが与えられた
 * @retval          GVD_ERR_INVALID_STATE 呼び出しが禁止されているステート
 * @description     割り当てられたBMUのIDを取得します.
 * @note            コンテキストの出力先がBMUである必要があります.
 * @note            本APIは同期処理されます.
 */
gvdError GVD_GetBMUId(gvdContext *gvdctx, int32_t *bmuid);
/**
 * @brief           BMU出力先アドレス設定
 * @param           gvdctx [in] コンテキスト
 * @param           addr [in] 出力先アドレス
 * @return          GVDのエラーコード
 * @retval          GVD_ERR_SUCCESS 正常終了
 * @retval          GVD_ERR_BAD_PARAMETER 引数に不正なパラメータが与えられた
 * @description     BMU出力先アドレスを設定します.<p>
 *                  確保したBMUのテクスチャに対するアドレスの取得方法は関連リンクを参照してください.
 * @seealso         AG903_BMUMgrGetBMUSrcAddress
 * @note            コンテキストの出力先がBMUである必要があります.
 * @note            本APIは同期処理されます.
 */
gvdError GVD_SetBMUAddr(gvdContext *gvdctx, void *addr);
/**
 * @brief           サーチレンジ設定
 * @param           gvdctx [in] コンテキスト
 * @param           range [in] サーチレンジ設定値 [Byte]
 * @return          GVDのエラーコード
 * @retval          GVD_ERR_BAD_PARAMETER 引数に不正なパラメータが与えられた
 * @retval          GVD_ERR_SUCCESS 正常終了
 * @description     デコーダに設定するサーチレンジを指定します.<p>
 *                  ストリーム入力時, デコード開始地点の検出を行う上限サイズ(Byte)です.<p>
 *                  サーチレンジに "0" を設定した場合は, 上限なしとなります.
 * @note            コンテキスト状態が CLOSE である必要があります.
 * @note            本APIは同期処理されます.
 */
gvdError GVD_SetSearchRange(gvdContext *gvdctx, uint32_t range);
/**
 * @brief           サーチレンジ設定値取得
 * @param           gvdctx [in] コンテキスト
 * @param           range [out] サーチレンジ設定値 [Byte]
 * @return          GVDのエラーコード
 * @retval          GVD_ERR_SUCCESS 正常終了
 * @retval          GVD_ERR_BAD_PARAMETER 引数に不正なパラメータが与えられた
 * @description     設定されているサーチレンジの値を取得します.
 * @note            本APIは同期処理されます.
 */
gvdError GVD_GetSearchRange(gvdContext *gvdctx, uint32_t *range);
/**
 * @brief           デコード用ヒープ領域設定
 * @param           gvdctx [in] コンテキスト
 * @param           heap [in] ヒープ領域のアドレス
 * @param           size [in] ヒープ領域のサイズ [Byte]
 * @return          GVDのエラーコード
 * @retval          GVD_ERR_BAD_PARAMETER 引数に不正なパラメータが与えられた
 * @retval          GVD_ERR_SUCCESS 正常終了
 * @description     デコーダが使用するヒープ領域を設定します.<p>
 *                  ヒープ領域の必要サイズはストリームに依存しますが, 以下の式で概算値を求めることができます.<p>
 *                  HEAP(approx.)[Byte] = 2.5 * Width[px] * Height[px] * (Refs + 1)<p>
 *                  Width:フレーム幅, Height:フレーム高さ, Refs:参照フレーム数
 * @note            設定するアドレスは 2048バイト境界 にある必要があります.
 *                  ヒープ領域の属性は, キャッシュ無し・共有としてください.
 * @note            コンテキスト状態が CLOSE である必要があります.
 * @note            本APIは同期処理されます.
 */
gvdError GVD_SetOutputHeap(gvdContext *gvdctx, void *heap, size_t size);
/**
 * @brief           位置情報バッファ設定
 * @param           gvdctx [in] コンテキスト
 * @param           buffer [in] 位置情報バッファのアドレス
 * @param           size [in] 位置情報バッファのサイズ（登録数）
 * @return          GVDのエラーコード
 * @retval          GVD_ERR_SUCCESS 正常終了
 * @retval          GVD_ERR_BAD_PARAMETER 引数に不正なパラメータが与えられた
 * @retval          GVD_ERR_INVALID_STATE 呼び出しが禁止されているステート
 * @note            コンテキスト状態が CLOSE である必要があります.
 * @note            本APIは同期処理されます.
 */
gvdError GVD_SetPositionBuffer(gvdContext *gvdctx, void *buffer, size_t size);
/**
 * @brief           コンテキスト状態取得
 * @param           gvdctx [in] コンテキスト
 * @param           status [out] コンテキスト状態
 * @return          GVDのエラーコード
 * @retval          GVD_ERR_SUCCESS 正常終了
 * @retval          GVD_ERR_BAD_PARAMETER 引数に不正なパラメータが与えられた
 * @description     gvdctxに渡されたコンテキストの状態を取得します.<p>
 *                  各状態の説明は gvdApiFuncStatus 型を参照してください.
 * @note            本APIは同期処理されます.
 * @seealso         gvdApiFuncStatus
 */
gvdError GVD_GetStatus(gvdContext *gvd, gvdApiFuncStatus *status);
/**
 * @brief           タイムスタンプ取得
 * @param           gvdctx [in] コンテキスト
 * @param           param_user [in] ユーザーパラメータ
 * @return          GVDのエラーコード
 * @retval          GVD_ERR_SUCCESS 正常終了
 * @retval          GVD_ERR_BAD_PARAMETER 引数に不正なパラメータが与えられた
 * @retval          GVD_ERR_INVALID_STATE 呼び出しが禁止されているステート
 * @description     最新のタイムスタンプ情報の通知を要求します.<p>
 *                  通知される情報については, gvdTimeStamp を参照してください.
 * @note            コンテキスト状態が CLOSE 以外である必要があります.
 * @note            本APIは非同期処理されます. 完了通知は gvdCbFuncs の get_timestamp_done を参照してください.
 */
gvdError GVD_GetTimeStamp(gvdContext *gvd, void *param_user);
/**
 * @brief           再生開始要求
 * @param           gvdctx [in] コンテキスト
 * @param           param_user [in] ユーザーパラメータ
 * @return          GVDのエラーコード
 * @retval          GVD_ERR_SUCCESS 正常終了
 * @retval          GVD_ERR_BAD_PARAMETER 引数に不正なパラメータが与えられた
 * @retval          GVD_ERR_INVALID_STATE 呼び出しが禁止されているステート
 * @description     gvdctxに渡されたコンテキストに再生要求を発行します.<p>
 *                  再生要求が処理されると, コンテキスト状態が PLAY に遷移します.
 * @note            コンテキスト状態が CLOSE 以外である必要があります.
 * @note            本APIは非同期処理されます. 完了通知は gvdCbFuncs の play_accepted を参照してください.
 */
gvdError GVD_Play(gvdContext *gvdctx, void *param_user);
/**
 * @brief           一時停止要求
 * @param           gvdctx [in] コンテキスト
 * @param           param_user [in] ユーザーパラメータ
 * @return          GVDのエラーコード
 * @retval          GVD_ERR_SUCCESS 正常終了
 * @retval          GVD_ERR_BAD_PARAMETER 引数に不正なパラメータが与えられた
 * @retval          GVD_ERR_INVALID_STATE 呼び出しが禁止されているステート
 * @description     gvdctxに渡されたコンテキストに一時停止要求を発行します.<p>
 *                  一時停止要求が処理されると, コンテキスト状態が PAUSE に遷移します.
 * @note            コンテキスト状態が CLOSE 以外である必要があります.
 * @note            本APIは非同期処理されます. 完了通知は gvdCbFuncs の pause_done を参照してください.
 */
gvdError GVD_Pause(gvdContext *gvd, void *param_user);
/**
 * @brief           早送り要求
 * @param           gvdctx [in] コンテキスト
 * @param           n_speed [in] 早送り速度(1以上)
 * @param           param_user [in] ユーザーパラメータ
 * @return          GVDのエラーコード
 * @retval          GVD_ERR_SUCCESS 正常終了
 * @retval          GVD_ERR_BAD_PARAMETER 引数に不正なパラメータが与えられた
 * @retval          GVD_ERR_INVALID_STATE 呼び出しが禁止されているステート
 * @description     gvdctxに渡されたコンテキストに早送り要求を発行します.<p>
 *                  早送り要求が処理されると, コンテキスト状態が FORWARD に遷移します.
 * @note            早送りの速度(n_speed)は1以上である必要があります.
 * @note            コンテキスト状態が CLOSE 以外である必要があります.
 * @note            本APIは非同期処理されます. 完了通知は gvdCbFuncs の forward_accepted を参照してください.
 */
gvdError GVD_Forward(gvdContext *gvd, uint32_t n_speed, void *param_user);
/**
 * @brief           早戻し要求
 * @param           gvdctx [in] コンテキスト
 * @param           n_speed [in] 早戻し速度(1以上)
 * @param           param_user [in] ユーザーパラメータ
 * @return          GVDのエラーコード
 * @retval          GVD_ERR_SUCCESS 正常終了
 * @retval          GVD_ERR_BAD_PARAMETER 引数に不正なパラメータが与えられた
 * @retval          GVD_ERR_INVALID_STATE 呼び出しが禁止されているステート
 * @description     gvdctxに渡されたコンテキストに早戻し要求を発行します.<p>
 *                  早戻し要求が処理されると, コンテキスト状態が REWIND に遷移します.
 * @note            早戻しの速度(n_speed)は1以上である必要があります.
 * @note            位置情報バッファが登録されている必要があります.
 * @note            コンテキスト状態が CLOSE 以外である必要があります.
 * @note            本APIは非同期処理されます. 完了通知は gvdCbFuncs の rewind_accepted を参照してください.
 */
gvdError GVD_Rewind(gvdContext *gvd, uint32_t n_speed, void *param_user);
/**
 * @brief           シーク
 * @param           gvdctx [in] コンテキスト
 * @param           seekparam [in] シークパラメータ
 * @param           param_user [in] ユーザーパラメータ
 * @return          GVDのエラーコード
 * @retval          GVD_ERR_SUCCESS 正常終了
 * @retval          GVD_ERR_BAD_PARAMETER 引数に不正なパラメータが与えられた
 * @retval          GVD_ERR_INVALID_STATE 呼び出しが禁止されているステート
 * @description     seekparamの内容に従って再生位置を変更します.<p>
 *                  位置情報バッファの絶対/相対位置と, ストリームのバイト位置の3通りから指定できます.
 * @note            位置情報バッファの位置を指定する場合は, 位置情報バッファが登録されている必要があります.
 * @note            コンテキスト状態が PAUSE である必要があります.
 * @note            本APIは非同期処理されます. 完了通知は gvdCbFuncs の seek_done を参照してください.
 */
gvdError GVD_Seek(gvdContext *gvd, gvdSeekParam *seekparam, void *param_user);
/**
 * @brief           FatalError要因取得
 * @param           fatalerror [out] FatalError要因
 * @return          GVDのエラーコード
 * @description     FatalErrorの発生したコンテキストとその要因を取得します.
 * @note            本APIは同期処理されます.
 * @seealso         gvdFatalErrorInfo
 */
void GVD_GetFatalError(gvdFatalErrorInfo *fatalerror);
/**
 * @brief           入力バッファ数上限設定
 * @param           gvdctx [in] コンテキスト
 * @param           max_num_inputbuffers [in] 入力可能なバッファの最大数
 * @return          GVDのエラーコード
 * @retval          GVD_ERR_SUCCESS 正常終了
 * @retval          GVD_ERR_BAD_PARAMETER 引数に不正なパラメータが与えられた
 * @description     gvdctxに渡されたコンテキストに供給できる入力バッファの上限数を設定します.<p>
 *                  本APIで設定した数以上の入力バッファは供給できなくなります(関連APIはエラーを返します).<p>
 *                  マルチストリーム再生時, 入力バッファを使用する数をコンテキスト間で調節することができます.
 * @note            全てのコンテキストの入力バッファ数の総和は, GVD初期化時に設定した入力バッファの数を超えることはできません.
 */
gvdError GVD_SetMaxNumInputBuffers(gvdContext *gvdctx, size_t max_num_inputbuffers);
/**
 * @brief           入力バッファ数上限取得
 * @param           gvdctx [in] コンテキスト
 * @param           max_num_inputbuffers [out] 入力可能なバッファの最大数
 * @return          GVDのエラーコード
 * @retval          GVD_ERR_SUCCESS 正常終了
 * @retval          GVD_ERR_BAD_PARAMETER 引数に不正なパラメータが与えられた
 * @description     gvdctxに渡されたコンテキストに供給できる入力バッファの上限数を取得します.
 */
gvdError GVD_GetMaxNumInputBuffers(gvdContext *gvdctx, size_t *max_num_inputbuffers);
/**
 * @brief           出力バッファ数上限設定
 * @param           gvdctx [in] コンテキスト
 * @param           max_num_outputbuffers [in] 出力用バッファの最大数
 * @return          GVDのエラーコード
 * @retval          GVD_ERR_SUCCESS 正常終了
 * @retval          GVD_ERR_BAD_PARAMETER 引数に不正なパラメータが与えられた
 * @description     gvdctxに渡されたコンテキストに供給できる出力バッファの上限数を設定します.
 */
gvdError GVD_SetMaxNumOutputBuffers(gvdContext *gvdctx, size_t max_num_outputbuffers);
/**
 * @brief           出力バッファ数上限取得
 * @param           gvdctx [in] コンテキスト
 * @param           max_num_outputbuffers [out] 出力用バッファの最大数
 * @return          GVDのエラーコード
 * @retval          GVD_ERR_SUCCESS 正常終了
 * @retval          GVD_ERR_BAD_PARAMETER 引数に不正なパラメータが与えられた
 * @description     gvdctxに渡されたコンテキストに供給できる出力バッファの上限数を取得します.
 */
gvdError GVD_GetMaxNumOutputBuffers(gvdContext *gvdctx, size_t *max_num_outputbuffers);
/**
 * @brief           I/P変換設定
 * @param           gvdctx [in] コンテキスト
 * @param           enable [in] IP変換設定(有効:true,無効:false)
 * @return          GVDのエラーコード
 * @retval          GVD_ERR_SUCCESS 正常終了
 * @retval          GVD_ERR_BAD_PARAMETER 引数に不正なパラメータが与えられた
 * @description     gvdctxに渡されたコンテキストのI/P変換回路の動作設定をします.
 */
gvdError GVD_SetIPConv(gvdContext *gvdctx, _Bool enable);
/**
 * @brief           I/P変換設定取得
 * @param           gvdctx [in] コンテキスト
 * @param           enable [out] IP変換設定
 * @return          GVDのエラーコード
 * @retval          GVD_ERR_SUCCESS 正常終了
 * @retval          GVD_ERR_BAD_PARAMETER 引数に不正なパラメータが与えられた
 * @retval          GVD_ERR_INVALID_STATE 呼び出しが禁止されているステート
 * @description     gvdctxに渡されたコンテキストのI/P変換回路の動作設定を取得します.
 */
gvdError GVD_GetIPConv(gvdContext *gvdctx, _Bool *enable);
/**
 * @brief           致命的エラー管理アドレス設定
 * @param           address [in] 先頭アドレス
 * @return          GVDのエラーコード
 * @retval          GVD_ERR_SUCCESS 正常終了
 * @retval          GVD_ERR_BAD_PARAMETER 引数に不正なパラメータが与えられた
 * @retval          GVD_ERR_INVALID_STATE 呼び出しが禁止されているステート
 * @description     addressに指定されたアドレスで致命的エラー状態の管理を行います.<p>
 *                  致命的エラー管理領域のサイズは 4[Byte] です.<p>
 *                  本APIはGVD_Initializeの前にコールしてください.
 */
gvdError GVD_SetFatalErrorAddress(void *address);
/**
 * @brief           GVD占有メモリ先頭アドレス設定
 * @param           address [in] 先頭アドレス
 * @return          GVDのエラーコード
 * @retval          GVD_ERR_SUCCESS 正常終了
 * @retval          GVD_ERR_BAD_PARAMETER 引数に不正なパラメータが与えられた
 * @retval          GVD_ERR_INVALID_STATE 呼び出しが禁止されているステート
 * @description     GVDライブラリが占有するメモリ領域の先頭アドレスを設定します.<p>
 *                  占有するメモリサイズは 16[KiB] です.<p>
 *                  addressに設定するアドレスは 4[KB] 境界である必要があります.<p>
 *                  指定するメモリ領域はキャッシュ無効である必要があります.<p>
 *                  本APIはGVD_Initializeの前にコールしてください.
 */
gvdError GVD_SetOccupyMemoryAddress(void *address);
/**
 * @brief           GVDの強制停止
 * @return          GVDのエラーコード
 * @param           gvdctx [in] コンテキスト
 * @retval          GVD_ERR_SUCCESS 正常終了
 * @retval          GVD_ERR_INVALID_STATE 呼び出しが禁止されているステート
 * @description     GVDを強制的に停止します。<p>
 *                  本APIによる強制停止の完了は, 致命的エラーのコールバックで通知されます.<p>
 *                  強制停止からの復帰については, リセットまたは致命的エラーからの復帰手順が必要となります.<p>
 *                  引数にNULLを渡すと、ID=0として処理を行います.
 */
gvdError GVD_ForcedShutdown(gvdContext *gvdctx);

#endif /* GVD_H */
