Atomライブラリ初期化用コンフィグ構造体CRI Atomライブラリの動作仕様を指定するための構造体です。
criAtomEx_Initialize 関数の引数に指定します。

CRI Atomライブラリは、初期化時に本構造体で指定された設定に応じて、内部リソースを必要なだけ確保します。
ライブラリが必要とするワーク領域のサイズは、本構造体で指定されたパラメーターに応じて変化します。 [詳解]

#include <cri_atom_ex.h>

フィールド
CriAtomExThreadModel	thread_model
	スレッドモデル [詳解]

CriFloat32	server_frequency
	サーバー処理の実行頻度 [詳解]

CriSint32	parameter_update_interval
	パラメーター更新間隔 [詳解]

CriBool	enable_atom_sound_disabled_mode
	CRI Atom Library以外を使った音声出力を行うことを指定するフラグ [詳解]

CriSint32	max_virtual_voices
	最大バーチャルボイス数 [詳解]

CriSint32	max_parameter_blocks
	最大パラメーターブロック数 [詳解]

CriSint32	max_voice_limit_groups
	最大ボイスリミットグループ数 [詳解]

CriSint32	max_categories
	最大カテゴリ数 [詳解]

CriUint8	max_aisacs
	最大AISAC数 [詳解]

CriUint8	max_bus_sends
	最大バスセンド数 [詳解]

CriSint32	categories_per_playback
	再生単位でのカテゴリ参照数 [詳解]

CriSint32	max_sequences
	最大再生シーケンス数 [詳解]

CriUint32	max_tracks
	最大再生トラック数 [詳解]

CriUint32	max_track_items
	最大トラックアイテム数 [詳解]

CriUint32	max_aisac_auto_modulations
	最大AISACオートモジュレーション数（使用停止） [詳解]

CriFloat32	max_pitch
	ピッチ変更の上限値 [詳解]

CriUint32	max_faders
	最大フェーダー数 [詳解]

CriAtomExCoordinateSystem	coordinate_system
	3Dポジション計算を行う際の座標系 [詳解]

CriBool	enable_auto_matching_in_pan_type_auto
	パンタイプがオートの場合における、リスナーのオートマッチング機能の有効化 [詳解]

CriBool	enable_category_override_by_ex_player
	AtomExPlayerによるカテゴリの上書きの有効化 [詳解]

CriFloat32	sequence_prepare_ratio
	シーケンス先読み割合の指定 [詳解]

const CriAtomExRngInterface *	rng_if
	疑似乱数生成器インターフェース [詳解]

const CriFsConfig *	fs_config
	CRI File System の初期化パラメーターへのポインタ [詳解]

const CriAtomExAcfRegistrationInfo *	acf_info
	ACF情報へのポインタ [詳解]

void *	context
	プラットフォーム固有の初期化パラメーターへのポインタ [詳解]

CriUint32	version
	ライブラリバージョン番号 [詳解]

CriUint32	version_ex
	モジュールバージョン番号 [詳解]

const CriChar8 *	version_string
	ライブラリバージョン文字列 [詳解]

const CriChar8 *	version_ex_string
	モジュールバージョン文字列 [詳解]

詳解

Atomライブラリ初期化用コンフィグ構造体

CRI Atomライブラリの動作仕様を指定するための構造体です。
criAtomEx_Initialize 関数の引数に指定します。

CRI Atomライブラリは、初期化時に本構造体で指定された設定に応じて、内部リソースを必要なだけ確保します。
ライブラリが必要とするワーク領域のサイズは、本構造体で指定されたパラメーターに応じて変化します。

備考:: デフォルト設定を使用する場合、 criAtomEx_SetDefaultConfig マクロで構造体にデフォルトパラメーターをセットした後、 criAtomEx_Initialize 関数に構造体を指定してください。

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

参照: criAtomEx_Initialize, criAtomEx_SetDefaultConfig

フィールド詳解

◆ thread_model

CriAtomExThreadModel thread_model

スレッドモデル

説明:: CRI Atomライブラリのスレッドモデルを指定します。

参照: CriAtomExThreadModel

◆ server_frequency

CriFloat32 server_frequency

サーバー処理の実行頻度

説明:: サーバー処理を実行する頻度を指定します。
通常、アプリケーションのフレームレートと同じ値を指定します。

CRI Atomライブラリは、ファイル読み込みの管理や、音声データのデコード、音声の出力、ステータスの更新等、ライブラリ内部で行う処理のほとんどを1つの関数でまとめて行います。
CRIミドルウェアでは、こういったライブラリ内の処理を一括して行う関数のことを "サーバー処理"と呼んでいます。

スレッドモデルが CRIATOMEX_THREAD_MODEL_MULTI の場合、サーバー処理は CRI Atomライブラリが作成するスレッドで、定期的に実行されます。
スレッドモデルが CRIATOMEX_THREAD_MODEL_SINGLE や CRIATOMEX_THREAD_MODEL_USER_MULTI の場合、サーバー処理は criAtomEx_ExecuteMain 関数内で実行されます。

server_frequency には、サーバー処理を実行する頻度を指定します。
スレッドモデルが CRIATOMEX_THREAD_MODEL_MULTI の場合、CRI Atomライブラリは指定された頻度でサーバー処理が実行されるよう、サーバー処理の呼び出し間隔を調節します。
スレッドモデルが CRIATOMEX_THREAD_MODEL_SINGLE や CRIATOMEX_THREAD_MODEL_USER_MULTI の場合、ユーザは criAtomEx_ExecuteMain 関数を server_frequency で指定した頻度以上で実行する必要があります。

アプリケーションのフレームレートの変動が大きく、サーバー処理を実行する頻度にバラツキができてしまう場合には、最悪のフレームレートを想定して server_frequency の値を指定するか、またはスレッドモデルに CRIATOMEX_THREAD_MODEL_MULTI を指定してください。

備考:

Atomライブラリのサーバー処理では、以下のような処理が行われます。

発音リクエストの処理（ボイスの取得等）
パラメーターの更新（ボリュームやパン、ピッチ等の変更の適用）
音声データのデコードと出力

サーバー処理の実行頻度を多くすると、単位サーバー処理当たりの音声データデコード量が少なくなります。
その結果、単位サーバー当たりの処理負荷は小さくなります（負荷が分散されます）が、サーバー処理の実行に伴うオーバーヘッドは大きくなります。
（スレッドの起床回数やパラメーターの更新回数が多くなります。）

サーバー処理の実行頻度を少なくすると、スレッドの起床や発音リクエストの処理、パラメーターの更新処理の回数が減り、アプリケーション全体の処理負荷は下がります。
反面、データをリロードする頻度が下がるため、単位サーバー処理当たりデコード量は増え、デコード結果を保持するためのバッファーサイズが余分に必要になります。
また、発音リクエストを処理する頻度が下がるため、発音リクエストから音声出力開始までにかかる時間は長くなります。

注意: スレッドモデルに CRIATOMEX_THREAD_MODEL_SINGLE や CRIATOMEX_THREAD_MODEL_USER_MULTI を指定したにもかかわらず、 criAtomEx_ExecuteMain 関数が server_frequency で指定した値以下の頻度でしか実行されなかった場合、再生中の音が途切れる等の問題が発生する可能性がありますので、ご注意ください。

参照: criAtomEx_ExecuteMain

◆ parameter_update_interval

CriSint32 parameter_update_interval

パラメーター更新間隔

説明:: サーバー処理実行時にパラメーターの更新処理を行う間隔を指定します。
parameter_update_interval の値を変更することで、サーバー処理の実行回数を変えることなくパラメーター更新頻度を下げることが可能です。

例えば、 parameter_update_interval を 2 に設定すると、サーバー処理 2 回に対し、 1 回だけパラメーターの変更が行われます。
（パラメーターの更新頻度が 1/2 になります。）

備考:: サーバー処理周波数（ server_frequency ）を下げると、サーバー処理の実行回数が減るため、アプリケーション全体の処理負荷は下がりますが、サーバー処理同士の間隔が開くため、バッファリングすべきデータの量が増加します。
その結果、バッファリングのために必要なメモリのサイズは増加します。

これに対し、サーバー処理周波数を変更せずにパラメーター更新間隔（ parameter_update_interval ）の値を上げた場合、メモリサイズを増加させずに負荷を下げることが可能となります。
ただし、サーバー処理の駆動に伴う処理のオーバーヘッド（スレッドの起床負荷等）は削減されないため、サーバー処理の回数を減らす場合に比べ、負荷削減の効果は薄いです。

注意:: parameter_update_interval の値を変更した場合、発音リクエストの処理頻度も少なくなります。
そのため、 parameter_update_interval の値を変更すると、発音リクエストから音声出力開始までにかかる時間が長くなります。

◆ enable_atom_sound_disabled_mode

CriBool enable_atom_sound_disabled_mode

CRI Atom Library以外を使った音声出力を行うことを指定するフラグ

説明:: CRI Atom Libraryを使用せずに音声出力する際にCRI_TRUEを指定します。
criAtomEx_SetDefaultConfig マクロでは、CRI Atom Libraryを指定するため、CRI_FALSEが指定されます。
CRI Atom Library以外の音声出力ライブラリを用いる場合は、本フラグにCRI_TRUEを指定してから、criAtomEx_Initializeを実行するようにしてください。

注意: 本フラグを切り替える際には、AtomライブラリをcriAtomEx_Finalizeで終了してから、フラグの内容を変更し、再度 criAtomEx_Initializeにて初期化処理を行うようにしてください。

◆ max_virtual_voices

CriSint32 max_virtual_voices

最大バーチャルボイス数

説明:: アプリケーションで同時に発音制御を行うボイスの数です。
Atomライブラリは、初期化時に max_virtual_voices で指定された数分だけ発音管理に必要なリソースを確保します。

備考:: max_virtual_voices で指定された数以上の音声を同時に発音することはできません。
また、 max_virtual_voices 分の発音リクエストを行ったとしても、実際に発音される音声の数は、必ずしも max_virtual_voices に一致するとは限りません。
実際に発音可能な音声の数は、ボイスプールで確保されたボイス数や、ターゲット機で利用可能なハードウェアボイスの数に依存します。

バーチャルボイス数の目安は、「最大同時発音数＋1V当たりの発音リクエスト数」です。
バーチャルボイス数が最大同時発音数より少ない場合や、発音数とリクエスト数の合計が最大バーチャルボイスを超える場合、エラーコールバック関数に警告が返される可能性があります。

CRIATOMEX_RETRY_VOICE_ALLOCATION を指定して AtomEx プレーヤーを作成する場合、上記よりもさらに多くのバーチャルボイスを必要とする可能性があります。

◆ max_parameter_blocks

CriSint32 max_parameter_blocks

最大パラメーターブロック数

説明:: 音声再生時にパラメーター管理を行うための領域の数です。
Atomライブラリは、初期化時に max_parameter_blocks で指定された数分だけパラメーター管理に必要なリソースを確保します。

備考:: 1つのキューを再生するのに必要なパラメーターブロック数は、再生するキューの内容によって変化します。
（操作するパラメーターの数に比例して必要なパラメーターブロック数は増加します。）

パラメーターブロック数が不足した場合、再生するキューに対して一部のパラメーターが設定されないことになります。
（ボリュームやピッチ、フィルター等が意図した値にならない可能性があります。）
アプリケーション実行中にパラメーターブロック数不足のエラーが発生した場合、 max_parameter_blocks の値を増やしてください。

◆ max_voice_limit_groups

CriSint32 max_voice_limit_groups

最大ボイスリミットグループ数

説明:: アプリケーションで作成するボイスリミットグループの数です。
Atomライブラリは、初期化時に max_voice_limit_groups で指定された数分のボイスリミットグループを作成できるリソースを確保します。

注意: max_voice_limit_groups で指定された数以上のボイスリミットグループを作成することはできません。
オーサリングツール上で作成したボイスリミットグループの数が max_voice_limit_groups を超える場合、ACFファイルのロードに失敗します。

◆ max_categories

CriSint32 max_categories

最大カテゴリ数

説明:: アプリケーションで作成するカテゴリの数です。
Atomライブラリは、初期化時に max_categories で指定された数分のカテゴリを作成できるリソースを確保します。

注意: max_categories で指定された数以上のカテゴリを作成することはできません。
オーサリングツール上で作成したカテゴリの数が max_categories を超える場合、ACFファイルのロードに失敗します。

◆ max_aisacs

CriUint8 max_aisacs

最大AISAC数

説明:: 一つのキューに紐づけることができるAISACの最大数です。
Atomライブラリは、初期化時と AtomExPlayer 作成時に max_aisacs で指定された数分のAISACを参照できるリソースを確保します。
max_aisacs に指定する値の上限は55です。
キュー、トラック、カテゴリの AISAC が対象となります。ミキサー AISAC は本設定値の対象ではありません。

◆ max_bus_sends

CriUint8 max_bus_sends

最大バスセンド数

説明:: 一つのボイスが同時にセンドすることができるバス数の最大数です。
max_bus_sends に指定する値の上限は32です。

◆ categories_per_playback

CriSint32 categories_per_playback

再生単位でのカテゴリ参照数

説明:: 再生単位で参照可能なカテゴリの数です。
Atomライブラリは、初期化時に categories_per_playback で指定された数分のカテゴリを参照できるリソースを確保します。
指定可能な最大値は CRIATOMEXCATEGORY_MAX_CATEGORIES_PER_PLAYBACK です。

注意: categories_per_playback で指定された数以上のカテゴリをキューやプレーヤーから参照することはできません。
オーサリングツール上で作成したキューの参照カテゴリ数が categories_per_playback を超える場合、ACFファイルのロードに失敗します。

◆ max_sequences

CriSint32 max_sequences

最大再生シーケンス数

説明:: アプリケーションで同時に再生するシーケンスの数です。
Atomライブラリは、初期化時に max_sequences で指定された数と max_virtual_voices で指定された数の総和分のシーケンスを再生できるリソースを確保します。

注意: Ver.2.00以降のライブラリでは全てのキューがシーケンスとして再生されるため、 max_sequences に加えて max_virtual_voices 数分のリソースが確保されます。
max_sequences で指定された数以上のシーケンスを再生することはできません。
エラーコールバックが発生した場合、この値を大きくしてください。

◆ max_tracks

CriUint32 max_tracks

最大再生トラック数

説明:: アプリケーションで同時再生するシーケンス内のトラック総数です。
Atomライブラリは、初期化時に max_tracks で指定された数と max_virtual_voices で指定された数の総和分のトラックを再生できるリソースを確保します。

注意: Ver.2.00以降のライブラリでは全てのキューがシーケンスとして再生されるため、 max_tracks に加えて max_virtual_voices 数分のリソースが確保されます。
max_tracks で指定された数以上のトラックを再生することはできません。
エラーコールバックが発生した場合、この値を大きくしてください。

◆ max_track_items

CriUint32 max_track_items

最大トラックアイテム数

説明:: アプリケーションで同時再生するシーケンス内のイベントの総数です。
Atomライブラリは、初期化時に max_track_items で指定された数と max_virtual_voices で指定された数の総和分のトラックアイテムを作成できるリソースを確保します。

注意: Ver.2.00以降のライブラリでは全てのキューがシーケンスとして再生されるため、 max_track_items に加えて max_virtual_voices 数分のリソースが確保されます。
max_track_items で指定された数以上のトラックアイテムを作成することはできません。
トラックアイテムは波形や、ループイベント等のシーケンストラック再生時に管理が必要なイベントです。
エラーコールバックが発生した場合、この値を大きくしてください。

◆ max_aisac_auto_modulations

CriUint32 max_aisac_auto_modulations

最大AISACオートモジュレーション数（使用停止）

説明:: Ver.2.00.00以降のライブラリでは使用停止となりました。ライブラリ内部での本メンバへの参照は行われません。

◆ max_pitch

CriFloat32 max_pitch

ピッチ変更の上限値

説明:: Atomライブラリ内で適用されるピッチ変更の上限値を設定します。
max_pitchに設定された値以上のピッチ変更が、ライブラリ内でクリップされます。

ピッチはセント単位で指定します。
1セントは1オクターブの1/1200です。半音は100セントです。

例えば、 max_pitch に 1200.0f を設定した場合、 1200セントを超えるピッチが設定されたキューを再生したとしても、ピッチが1200セントに抑えられて再生されます。

備考:: キューに設定されたピッチに、AISACによるピッチ変更やドップラー効果が追加適用された場合、予期せぬレベルまでピッチが上がる恐れがあります。
（ピッチに比例して単位時間当たりのデコード量が増加するため、ピッチが高すぎる音を大量に鳴らした場合、処理負荷が急増する恐れがあります。）

本パラメーターであらかじめピッチ上限を設定しておくことで、想定外の負荷変動を回避することが可能となります。
例えば、 max_pitch に 1200.0f を設定した場合、アプリケーション中でどのような操作を行ったとしてもピッチが1200セント（＝2倍速再生）までに抑えられるため、単位時間あたりのデコード量は最大でも通常時の2倍までに制限されます。

注意:: max_pitchには 0.0f 以上の値を設定する必要があります。
（ 0.0f を指定した場合、ピッチの変更は一切行われなくなります。）

◆ max_faders

CriUint32 max_faders

最大フェーダー数

説明:: Atomライブラリ内で使用するフェーダーの上限値を設定します。
ここで設定し、初期化時に確保したフェーダーはTrackTransitionBySelectorデータ再生時にライブラリ内部で使用します。

◆ coordinate_system

CriAtomExCoordinateSystem coordinate_system

3Dポジション計算を行う際の座標系

説明:: Atomライブラリが3Dポジション計算を行う際、どの座標系を使用するかを設定します。

◆ enable_auto_matching_in_pan_type_auto

CriBool enable_auto_matching_in_pan_type_auto

パンタイプがオートの場合における、リスナーのオートマッチング機能の有効化

説明:: パンタイプがオートの場合、リスナーのオートマッチング機能を有効化するかを設定します。

備考：: パンタイプが3Dポジショニングの場合はリスナーのオートマッチング機能は常に有効です。

◆ enable_category_override_by_ex_player

CriBool enable_category_override_by_ex_player

AtomExPlayerによるカテゴリの上書きの有効化

説明:: AtomExPlayerに::criAtomExPlayer_SetCategoryById関数や::criAtomExPlayer_SetCategoryByName関数を用いてカテゴリをセットした場合にキューのカテゴリ設定を上書きする機能を有効化します。

備考：: CRI Atom Ver.2.20.31未満のライブラリは、プレーヤーに対してカテゴリ設定を行うと、キューに設定されていたカテゴリが上書きにより無効になっていました。 Ver.2.20.31未満の挙動に戻す必要がある場合には本フラグにCRI_FALSEを設定してください。

◆ sequence_prepare_ratio

CriFloat32 sequence_prepare_ratio

シーケンス先読み割合の指定

説明:: シーケンサーが1サーバー処理で読み込む量の割合を指定します。 1.5fを指定すると次のサーバー処理が行われる予想時刻からさらに0.5サーバー分を先読みします。最大で3.0f、最小で1.1fが指定可能です。範囲を超える場合はクリップされます。

備考:: サーバー周期の揺れによって発生する発音タイミングのずれが発生しづらくなります。

◆ rng_if

const CriAtomExRngInterface* rng_if

疑似乱数生成器インターフェース

説明:: CRI Atomライブラリで使用する疑似乱数生成器インターフェースを指定します。
NULLを指定した場合は、デフォルトの疑似乱数生成器を使用します。

◆ fs_config

const CriFsConfig* fs_config

CRI File System の初期化パラメーターへのポインタ

説明:: CRI File Systemの初期化パラメーターへのポインタを指定します。 NULLを指定した場合、デフォルトパラメーターでCRI File Systemを初期化します。

参照: criAtomEx_Initialize

◆ acf_info

const CriAtomExAcfRegistrationInfo* acf_info

ACF情報へのポインタ

説明:: 初期化時にACFの登録を行う際にACF情報へのポインタを指定します。 NULLを指定した場合、初期化時にACFの登録は行われません。本メンバを設定して初期化処理内でACFの登録を行う場合、 CriAtomExConfig 構造体の max_voice_limit_groups, max_categories, categories_per_playbackの各メンバ値は ACF設定値と比較して大きい方の値が初期化用設定値として使用されます。 CriAtomEx初期化時にACFの登録を行った場合、環境によっては CriAtomExAsr, CriAtomExHcaMx 等のモジュール初期化にも一部ACF内の設定値が使用されます。
ACF内の設定値を使用せずにこれらのモジュールを初期化したい場合は、本メンバを使用せずにライブラリの初期化を行い、その後ACFの登録を行ってください。

注意: 本メンバを設定する場合、初期化処理内でのACFデータの登録とACFデータを元に初期化に必要なワークを動的に確保するため、初期化関数呼び出し前にメモリアロケーター関数の登録とエラーコールバック関数の登録が必要になります。
本メンバを使用する場合、ワーク領域の確保は登録されたメモリアロケーター関数を使用して行います。取得済みメモリ領域を使用しての初期化は行えません。

参照: criAtomEx_Initialize, criAtomEx_SetUserAllocator

◆ context

void* context

プラットフォーム固有の初期化パラメーターへのポインタ

説明:: CRI Atomライブラリを動作させるために必要な、プラットフォーム固有の初期化パラメーターへのポインタを指定します。 NULLを指定した場合、デフォルトパラメーターでプラットフォーム毎に必要な初期化を行います。
パラメーター構造体は各プラットフォーム固有ヘッダーに定義されています。パラメーター構造体が定義されていないプラットフォームでは、常にNULLを指定してください。

参照: criAtomEx_Initialize

◆ version

CriUint32 version

ライブラリバージョン番号

説明:: CRI Atom ライブラリのバージョン番号です。
criAtomEx_SetDefaultConfig マクロにより、 cri_atom.h ヘッダーに定義されているバージョン番号が設定されます。

注意: アプリケーションでは、この値を変更しないでください。

◆ version_ex

CriUint32 version_ex

モジュールバージョン番号

説明:: CRI Atom Ex のバージョン番号です。
criAtomEx_SetDefaultConfig マクロにより、本ヘッダーに定義されているバージョン番号が設定されます。

注意: アプリケーションでは、この値を変更しないでください。

◆ version_string

const CriChar8* version_string

ライブラリバージョン文字列

説明:: CRI Atom ライブラリのバージョン文字列です。
criAtomEx_SetDefaultConfig マクロにより、 cri_atom.h ヘッダーに定義されているバージョン文字列が設定されます。

注意: アプリケーションでは、この値を変更しないでください。

◆ version_ex_string

const CriChar8* version_ex_string

モジュールバージョン文字列

説明:: CRI Atom Ex のバージョン文字列です。
criAtomEx_SetDefaultConfig マクロにより、本ヘッダーに定義されているバージョン文字列が設定されます。

注意: アプリケーションでは、この値を変更しないでください。

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

cri_atom_ex.h