プレーヤー作成用コンフィグ構造体 [詳解]

#include <cri_atom_ex.h>

フィールド
CriAtomExVoiceAllocationMethod	voice_allocation_method
	ボイス確保方式 [詳解]

CriSint32	max_path_strings
	最大パス文字列数 [詳解]

CriSint32	max_path
	最大パス長 [詳解]

CriUint8	max_aisacs
	最大AISAC数 [詳解]

CriBool	updates_time
	時刻更新の有無 [詳解]

CriBool	enable_audio_synced_timer
	音声同期時刻更新の有無 [詳解]

詳解

プレーヤー作成用コンフィグ構造体

説明:: AtomExプレーヤーを作成する際に、動作仕様を指定するための構造体です。
criAtomExPlayer_Create 関数の引数に指定します。

作成されるプレーヤーは、ハンドル作成時に本構造体で指定された設定に応じて、内部リソースを必要なだけ確保します。
プレーヤーが必要とするワーク領域のサイズは、本構造体で指定されたパラメーターに応じて変化します。

注意: 将来的にメンバが増える可能性があるため、 criAtomExPlayer_SetDefaultConfig マクロを使用しない場合には、使用前に必ず構造体をゼロクリアしてください。
（構造体のメンバに不定値が入らないようご注意ください。）

参照: criAtomExPlayer_Create, criAtomExPlayer_SetDefaultConfig

フィールド詳解

◆ voice_allocation_method

CriAtomExVoiceAllocationMethod voice_allocation_method

ボイス確保方式

説明:: AtomExプレーヤーがボイスを確保する際の方式を指定します。

voice_allocation_method に CRIATOMEX_ALLOCATE_VOICE_ONCE を指定した場合、 AtomExプレーヤーはボイスの確保を発音開始のタイミングでのみ行います。
再生開始時点でボイスを確保できなかった場合や、発音数制御により再生中にボイスが奪い取られた場合、発音に関連するリソースが解放されるため、その波形データはその時点で停止します。
（再生が始まらなかった波形データや、再生が途中で停止された波形データが、追加の再生リクエストなしに再生されることはありません。）

これに対し、 voice_allocation_method に CRIATOMEX_RETRY_VOICE_ALLOCATION を指定した場合、AtomExプレーヤーはボイスの確保を必要な限り何度も繰り返します。
ボイスが確保できない場合やボイスを奪い取られた場合でも、発音を管理するリソース（バーチャルボイス）は解放しないので、再度ボイスに空きができた時点で、発音処理が再開されます。

備考:: CRIATOMEX_RETRY_VOICE_ALLOCATION を指定した場合、発音中のボイスの処理に加え、発音を行っていないバーチャルボイスについても定期的にボイスの再取得処理等が行われるため、 CRIATOMEX_ALLOCATE_VOICE_ONCE を指定した場合に比べ、処理負荷が高くなる可能性があります。

CRIATOMEX_RETRY_VOICE_ALLOCATION 指定時、ボイスの再確保に成功すると、波形データは再生時刻を考慮した位置からシーク再生されます。

注意: CRIATOMEX_RETRY_VOICE_ALLOCATION を指定して AtomEx プレーヤーを作成した場合でも、 Atom ライブラリ初期化時に指定する max_virtual_voices の数を超える再生要求があった場合、発音は再開されなくなります。
（エラーコールバック関数に警告が返され、バーチャルボイスも削除されます。）
CRIATOMEX_RETRY_VOICE_ALLOCATION を指定する際には、初期化時に必要充分なバーチャルボイスを確保してください。
（ max_virtual_voices に大きめの値を指定してください。）

CRIATOMEX_RETRY_VOICE_ALLOCATION を指定した場合、再生されなかった波形データやボイスが奪い取られた波形データが、いつどこから再生再開されるか、厳密に制御することはできません。
（実行タイミングにより毎回異なった結果になる可能性があります。）

◆ max_path_strings

CriSint32 max_path_strings

最大パス文字列数

説明:: AtomExプレーヤーが保持するパス文字列の数です。

備考:: criAtomExPlayer_SetFile 関数を実行すると、指定したパス文字列がAtomExプレーヤー内に保持されます。
AtomExプレーヤーはデフォルト状態ではパス文字列を1つしか保持しません。
（メモリサイズ削減のため。）
プレーヤー作成時に指定する max_path_strings の数を増やせば、 AtomExプレーヤーは指定された数分のパス文字列を保存するようになります。
max_path_strings に2以上の値を指定することで、 1つのプレーヤーで複数のファイルを同時にパス指定で再生することが可能となります。
ただし、 max_path_strings の値に応じて必要なワーク領域のサイズは増加します。
（max_path_strings×max_pathバイトのメモリが必要となります。）

参照: criAtomExPlayer_SetDefaultConfig, criAtomExPlayer_SetFile

◆ max_path

CriSint32 max_path

最大パス長

説明:: AtomExプレーヤーに指定可能なファイルパスの最大長です。
ファイル名を指定して音声の再生を行う場合、使用するパスの最大長を max_path として指定する必要があります。

備考:: 本パラメーターは、パッキングされていない音声ファイルを、ファイル名を指定して再生する際にのみセットする必要があります。
ファイル名指定の再生を行わず、キューIDや波形データIDを指定して再生を行う場合、 max_path を 0 に設定することが可能です。

注意: criAtomExPlayer_SetDefaultConfig マクロで CriAtomExPlayerConfig 構造体にデフォルト値を設定した場合、 max_path には 0 がセットされます。
ファイル名を指定して再生を行う場合、 criAtomExPlayer_SetDefaultConfig マクロを使用しないか、または criAtomExPlayer_SetDefaultConfig マクロ実行後に再度パスの最大長をセットする必要があります。

参照: criAtomExPlayer_SetDefaultConfig, criAtomExPlayer_SetFile

◆ max_aisacs

CriUint8 max_aisacs

最大AISAC数

説明:: 一つのキューに紐づけることができるAISACの最大数です。
Atomライブラリは、初期化時と AtomExPlayer 作成時に max_aisacs で指定された数分のAISACを参照できるリソースを確保します。
max_aisacs に指定する値の上限は55です。

◆ updates_time

CriBool updates_time

時刻更新の有無

説明:: AtomExプレーヤーが時刻更新処理を行うかどうかを指定します。

備考:: updates_time に CRI_FALSE を指定した場合、作成されたAtomExプレーヤーは再生時刻の更新を行いません。
その結果、 criAtomExPlayer_GetTime 関数による再生時刻の取得は行えなくなりますが、音声再生時の処理負荷をわずかに下げることが可能となります。

参照: criAtomExPlayer_GetTime

◆ enable_audio_synced_timer

CriBool enable_audio_synced_timer

音声同期時刻更新の有無

説明:: AtomExプレーヤーが再生音声に同期した時刻更新処理を行うかどうかを指定します。

備考:: enable_audio_synced_timer に CRI_TRUE を指定した場合、作成されたAtomExプレーヤーを用いて再生された音声に対して、再生済みサンプル数に同期するように補正した再生時刻の更新を行うようになります。
補正された再生時刻は criAtomExPlayback_GetTimeSyncedWithAudio 関数によって取得できます。
音声再生時の処理負荷が上がるため、音声に同期した正確な再生時刻を取得したいプレーヤーの作成時のみ CRI_TRUE を指定するようにしてください。

注意: 本フラグを有効にした場合、AtomExプレーヤーに対するピッチ指定が行えなくなります。

参照: criAtomExPlayback_GetTimeSyncedWithAudio

この構造体詳解は次のファイルから抽出されました:

cri_atom_ex.h