キューポイント機能について説明します。

キューポイントとは

「キューポイント」とは、ムービーファイルにタイミング情報を埋め込む機能です。
機能全体のことを「キューポイント」、ひとつひとつのタイミング情報のことを「イベントポイント」と呼びます。
ムービーファイルにキューポイント情報を埋め込むには、エンコード時に「キューポイント情報ファイル」を指定してください。

タイミング情報の利用方法としては、例えば以下のようなものが考えられます。

ムービー内容にあわせて迫力のあるコントローラーの振動を実現する。
ポリゴンキャラをムービー内容にあわせて動かすデモシーン。
ムービーを途中から再生するための再生開始位置管理（キューポイントを使用したシーク位置の決定参照）

タイミング情報の取得

キューポイントで埋め込んだイベントポイント情報は次の２種類の方法で取得することができます。

(1) ヘッダー解析終了後、キューポイント情報取得関数で「全てのイベントポイント」の一覧を取得できます。
(2) 再生中に再生時刻がイベントポイントで指定した時刻になると呼び出されるコールバック関数を登録することができます。

キューポイント情報

CriManaPlayerHn のハンドル状態が CRIMANAPLAYER_STATUS_WAIT_PREP になったあと、 criManaPlayer_GetCuePointInfo() でキューポイント情報を取得できます。
キューポイント情報には、全イベントポイントの一覧とイベントポイント総数が含まれます。

イベントポイント

「イベントポイント」とは、個々のタイミング情報のことです。キューポイントは１個以上のイベントポイントから構成されます。
各イベントポイントには以下のパラメーターが存在します。

**イベントポイント情報のパラメーター一覧**
パラメーター	内容
名前文字列	アプリーケーションがイベントポイントを区別するための名前です。
時刻	ライブラリがキューポイントコールバック関数の呼び出し判定に使用します。
タイプ変数	任意の整数値です。アプリケーションがイベントポイントの種類を簡単に区別したい場合などに使用してください。
パラメーター文字列	任意の文字列です。特別なパラメーターを埋めたい場合は、パラメーター文字列に記述してアプリケーションで文字列を解釈してください。

「名前文字列」と「パラメーター文字列」のキャラクターコードはエンコード時に指定したキューポイント情報ファイルに従います。

キューポイントコールバック

キューポイントコールバック関数を登録すると、再生中に再生時刻がイベントポイントに到達した際にコールバック関数が呼び出されます。コールバック関数の引数には、イベントポイント情報が渡されます。

キューポイントコールバック関数は criManaPlayer_SetCuePointCallback() で登録します。
キューポイントコールバック型は次の通りです。

void(*) (void* obj, CriManaPlayerHn player, CriManaEventPoint *eventinfo);

キューポイントコールバック関数内では、Sofdec ライブラリの関数呼び出しは行わないでください。
コールバックをきっかけにして再生制御や情報取得を行いたい場合は、コールバック関数内で処理内容だけを記録し、実際のSofdecライブラリの関数呼び出しはメインスレッドから行うようにしてください。

キューポイントコールバックの呼び出し元

キューポイントコールバック関数の呼び出し判定は criMana_ExecuteMain() で行っています（Sofdecのフレームワークでは、アプリケーションはメインループで criMana_ExecuteMain() を毎回呼び出すようになっています）。

コールバック関数で記録したパラメーターに応じてメインスレッドで処理を行う場合は、 criMana_ExecuteMain() の後でアプリケーションの処理判定をすると遅延を最小限に抑えることが出来ます。

キューポイントを使用したシーク位置の決定

キューポイント情報からシーク位置（フレーム番号）を計算することができます。
シークしたいイベントポイントの時刻を使って、 criManaPlayer_CalcFrameNoFromTime() を呼び出してください。
なお、 criManaPlayer_CalcFrameNoFromTime() が有効なのはヘッダー解析終了後です。

また、時刻を指定してその前後のイベントポイントを検索する関数もあります。
これらの関数は検索対象とするタイプ変数を指定することができます。タイプ変数に-1を指定すると全イベントポイントが対象となります。

応用例：キューポイントを使用したチャプタースキップ再生

キューポイント情報からシーク位置を決定する方法を使った応用例として、チャプタースキップ再生を紹介します。

ムービーデータの作成
イベントポイントとして、各チャプターの先頭位置が埋め込んだムービーを作成します。
チャプター位置以外のイベントポイントも一緒に埋め込みたい場合は、タイプ変数の値を使って区別します（例えばタイプ変数０番はチャプター位置、タイプ変数１番は別目的にタイミング情報）。
次のチャプターへ進む
(1) 現在の再生時刻を取得します。
(2) criManaPlayer_SearchNextEventPointByTime() で現在時刻の次に出てくるイベントポイントを検索し、返り値で取得できるフレーム番号を記録します。
(3) ムービー再生を停止します。
(4) criManaPlayer_SetSeekPosition() で(2)で記録したフレーム番号を指定します。
(5) ムービー再生を開始します。
現在のチャプターの先頭へ戻る／前のチャプターへ戻る
(1) 現在の再生時刻を取得し、時刻を１秒減らします。１秒減らすことで、現在の再生位置が各チャプターの先頭１秒以内だった時にひとつ前のチャプターへ戻ることができます。
(2) criManaPlayer_SearchPrevEventPointByTime() で(1)で計算した時刻を指定してイベントポイントを検索し、返り値で取得できるフレーム番号を記録します。
(3) ムービー再生を停止します。
(4) criManaPlayer_SetSeekPosition() で(2)で記録したフレーム番号を指定します。
(5) ムービー再生を開始します。

キューポイントの制限事項

キューポイントが有効になるのは単純再生・ループ再生の場合のみです。
連結再生の場合は１個目のムービー再生のみ、キューポイントが有効です。