構造体 CriAtomExConfigTag
[CriAtomEx API]

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

#include <cri_atom_ex.h>

すべてのメンバ一覧

Public 変数

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数
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 CriAtomExRngInterfacerng_if
 疑似乱数生成器インターフェース
const CriFsConfig * fs_config
 CRI File System の初期化パラメーターへのポインタ
const CriAtomExAcfRegistrationInfoacf_info
 ACF情報へのポインタ
void * context
 プラットフォーム固有の初期化パラメーターへのポインタ
CriUint32 version
 ライブラリバージョン番号
CriUint32 version_ex
 モジュールバージョン番号


説明

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

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

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

備考:
デフォルト設定を使用する場合、 criAtomEx_SetDefaultConfig マクロで構造体にデフォルト パラメーターをセットした後、 criAtomEx_Initialize 関数に構造体を指定してください。
注意:
将来的にメンバが増える可能性があるため、 criAtomEx_SetDefaultConfig マクロを使用しない 場合には、使用前に必ず構造体をゼロクリアしてください。
(構造体のメンバに不定値が入らないようご注意ください。)
参照:
criAtomEx_Initialize, criAtomEx_SetDefaultConfig


変数

CriAtomExThreadModel thread_model

スレッドモデル

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

CriFloat32 server_frequency

サーバー処理の実行頻度

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

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

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

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

アプリケーションのフレームレートの変動が大きく、サーバー処理を実行する頻度にバラツキ ができてしまう場合には、最悪のフレームレートを想定して server_frequency の値を指定 するか、またはスレッドモデルに CRIATOMEX_THREAD_MODEL_MULTI を指定してください。
備考:
Atomライブラリのサーバー処理では、以下のような処理が行われます。
  • 発音リクエストの処理(ボイスの取得等)
  • パラメーターの更新(ボリュームやパン、ピッチ等の変更の適用)
  • 音声データのデコードと出力
サーバー処理の実行頻度を多くすると、単位サーバー処理当たりの音声データデコード量が少なくなります。
その結果、単位サーバー当たりの処理負荷は小さくなります(負荷が分散されます)が、 サーバー処理の実行に伴うオーバーヘッドは大きくなります。
(スレッドの起床回数やパラメーターの更新回数が多くなります。)

サーバー処理の実行頻度を少なくすると、スレッドの起床や発音リクエストの処理、 パラメーターの更新処理の回数が減り、アプリケーション全体の処理負荷は下がります。
反面、データをリロードする頻度が下がるため、単位サーバー処理当たりデコード量は増え、 デコード結果を保持するためのバッファーサイズが余分に必要になります。
また、発音リクエストを処理する頻度が下がるため、 発音リクエストから音声出力開始までにかかる時間は長くなります。
注意:
スレッドモデルに CRIATOMEX_THREAD_MODEL_SINGLECRIATOMEX_THREAD_MODEL_USER_MULTI を指定したにもかかわらず、 criAtomEx_ExecuteMain 関数が server_frequency で 指定した値以下の頻度でしか実行されなかった場合、再生中の音が途切れる等の問題が 発生する可能性がありますので、ご注意ください。
参照:
criAtomEx_ExecuteMain

CriSint32 parameter_update_interval

パラメーター更新間隔

説明:
サーバー処理実行時にパラメーターの更新処理を行う間隔を指定します。
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 の値を変更すると、 発音リクエストから音声出力開始までにかかる時間が長くなります。

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にて初期化処理を行うようにしてください。

CriSint32 max_virtual_voices

最大バーチャルボイス数

説明:
アプリケーションで同時に発音制御を行うボイスの数です。
Atomライブラリは、初期化時に max_virtual_voices で指定された数分だけ 発音管理に必要なリソースを確保します。
備考:
max_virtual_voices で指定された数以上の音声を同時に発音することはできません。
また、 max_virtual_voices 分の発音リクエストを行ったとしても、実際に 発音される音声の数は、必ずしも max_virtual_voices に一致するとは限りません。
実際に発音可能な音声の数は、ボイスプールで確保されたボイス数や、 ターゲット機で利用可能なハードウェアボイスの数に依存します。

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

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

CriSint32 max_parameter_blocks

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

説明:
音声再生時にパラメーター管理を行うための領域の数です。
Atomライブラリは、初期化時に max_parameter_blocks で指定された数分だけ パラメーター管理に必要なリソースを確保します。
備考:
1つのキューを再生するのに必要なパラメーターブロック数は、 再生するキューの内容によって変化します。
(操作するパラメーターの数に比例して必要なパラメーターブロック数は増加します。)

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

CriSint32 max_voice_limit_groups

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

説明:
アプリケーションで作成するボイスリミットグループの数です。
Atomライブラリは、初期化時に max_voice_limit_groups で指定された数分 のボイスリミットグループを作成できるリソースを確保します。
注意:
max_voice_limit_groups で指定された数以上のボイスリミットグループを 作成することはできません。
オーサリングツール上で作成したボイスリミットグループの数が max_voice_limit_groups を超える場合、ACFファイルのロードに失敗します。

CriSint32 max_categories

最大カテゴリ数

説明:
アプリケーションで作成するカテゴリの数です。
Atomライブラリは、初期化時に max_categories で指定された数分 のカテゴリを作成できるリソースを確保します。
注意:
max_categories で指定された数以上のカテゴリを作成することはできません。
オーサリングツール上で作成したカテゴリの数が max_categories を超える場合、ACFファイルのロードに失敗します。

CriUint8 max_aisacs

最大AISAC数

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

CriSint32 categories_per_playback

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

説明:
再生単位で参照可能なカテゴリの数です。
Atomライブラリは、初期化時に categories_per_playback で指定された数分 のカテゴリを参照できるリソースを確保します。
指定可能な最大値は CRIATOMEXCATEGORY_MAX_CATEGORIES_PER_PLAYBACK です。
注意:
categories_per_playback で指定された数以上のカテゴリをキューやプレーヤーから参照することはできません。
オーサリングツール上で作成したキューの参照カテゴリ数が categories_per_playback を超える場合、ACFファイルのロードに失敗します。

CriSint32 max_sequences

最大再生シーケンス数

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

CriUint32 max_tracks

最大再生トラック数

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

CriUint32 max_track_items

最大トラックアイテム数

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

CriUint32 max_aisac_auto_modulations

最大AISACオートモジュレーション数(仕様停止)

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

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 を指定した場合、ピッチの変更は一切行われなくなります。)

CriUint32 max_faders

最大フェーダー数

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

CriAtomExCoordinateSystem coordinate_system

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

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

CriBool enable_auto_matching_in_pan_type_auto

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

説明:
パンタイプがオートの場合、リスナーのオートマッチング機能を有効化するかを設定します。
備考:
パンタイプが3Dポジショニングの場合はリスナーのオートマッチング機能は常に有効です。

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を設定してください。

CriFloat32 sequence_prepare_ratio

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

説明:
シーケンサーが1サーバー処理で読み込む量の割合を指定します。 1.5fを指定すると次のサーバー処理が行われる予想時刻からさらに0.5サーバー分を先読みします。 最大で3.0f、最小で1.1fが指定可能です。範囲を超える場合はクリップされます。
備考:
サーバー周期の揺れによって発生する発音タイミングのずれが発生しづらくなります。

const CriAtomExRngInterface* rng_if

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

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

const CriFsConfig* fs_config

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

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

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

void* context

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

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

CriUint32 version

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

説明:
CRI Atomライブラリのバージョン番号です。
criAtomEx_SetDefaultConfig マクロにより、cri_atom.hヘッダーに定義されているバージョン番号が設定されます。
注意:
アプリケーションでは、この値を変更しないでください。

CriUint32 version_ex

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

説明:
CRI Atom Exのバージョン番号です。
criAtomEx_SetDefaultConfig マクロにより、本ヘッダーに定義されているバージョン番号が設定されます。
注意:
アプリケーションでは、この値を変更しないでください。


CRI Middleware logo Copyright (c) 2006-2018 CRI Middleware Co., Ltd.