ライブラリの初期化/終了処理について

本セクションでは、CRI Atomライブラリの初期化処理と終了処理について説明します。

初期化関数の種類について

CRI Atomライブラリは、ライブラリの動作に必要なリソースを初期化時に確保します。
そのため、CRI Atomライブラリの機能を利用するには、まず初めにライブラリの初期化を行う必要があります。
ライブラリの初期化関数は、大きく分けて以下の2通りのタイプがあります。
ユーザは上記2つのいずれかのタイプの初期化関数をアプリケーションで実行する必要があります。

各初期化関数の特徴は以下のとおりです。
機能に応じた初期化関数について

Atomライブラリの初期化処理は、機能に応じて以下の3つの初期化関数があります。
初期化関数 説明
criAtomEx_Initialize 関数 ライブラリの基本機能を初期化します。
ASR、HCA-MXを除く全ての機能が利用可能になります。
criAtomExAsr_Initialize 関数 「ASR」を初期化します。
ASRを使用しない場合は不要です。
criAtomExHcaMx_Initialize 関数 「HCA-MX」を初期化します。
HCA-MXを使用しない場合は不要です。


ASRやHCA-MXを使用しない場合、 criAtomEx_Initialize 関数だけを実行すると不要なモジュールがリンクされません。
機種ごとの専用初期化関数について

Atomライブラリは、各機種向けに最適な初期化処理を"機種固有初期化関数"として提供しています。
PCの場合、機種固有の初期化/終了関数は以下の関数です。
機種固有の初期化関数を実行すると、内部的に以下の3つの関数が実行されます。
機種固有の初期化関数を使用することで、ASRHCA-MXを含む全ての機能が初期化されるため、初期化の手順を簡略化することが可能です。
[備考]
チュートリアルやサンプルプログラムでは機種固有の初期化関数を使用しています。

ライブラリの初期化方法

ライブラリを初期化する際には、ライブラリの動作仕様を詳細に指定することが可能です。
以下に criAtomEx_Initialize 関数を使った場合の初期化方法の詳細を示します。
初期化関数は、引数としてライブラリ初期化用のコンフィグ構造体( criAtomEx_Initialize 関数の場合は CriAtomExConfig )とワークメモリを指定する必要があります。
ライブラリ初期化用コンフィグ構造体について

ライブラリ初期化用のコンフィグ構造体(CriAtomExConfig)は、ライブラリの動作仕様を指定するための構造体です。
コンフィグ構造体で指定可能な主なパラメーターは以下のとおりです。

(1) スレッドモデル(thread_model)について
CRI Atomライブラリは、この構造体で指定された仕様に基づき、スレッドフレームワークを構築します。
スレッドフレームワークの詳細については「 スレッドについて 」をご参照ください。
(2) サーバー処理の実行頻度(server_frequency)について
CRI Atomライブラリは、ファイル読み込みの管理や、音声データのデコード、音声の出力、 ステータスの更新等、ライブラリ内部で行う処理のほとんどを1つの関数でまとめて行います。
CRIミドルウェアでは、こういったライブラリ内の処理を一括して行う関数のことを「サーバー処理」と呼んでいます。
音声を途切れなく再生するため、CRI Atomライブラリはサーバー処理をスレッド上で一定間隔で定期的に実行しています。
その際、CRI Atomライブラリはサーバー処理をserver_frequencyで指定された頻度で実行します。
サーバー処理の実行頻度を多くすると、単位サーバー処理当たりの処理量(デコード量等)が少なくなります。
その結果、単位サーバー当たりの処理負荷は小さくなります(負荷が分散されます)が、 サーバー処理の実行に伴うオーバーヘッドは大きくなります。
(携帯ゲーム機等、CPUリソースが少ない環境でサーバー処理の実行頻度を多くしすぎた場合、 サーバー処理の実行に伴うオーバーヘッドが無視できなくなる可能性があります。)
サーバー処理の実行頻度を少なくすると、単位サーバー処理当たりの処理量が多くなります。
サーバー処理の実行に伴うオーバーヘッドは低減されますが、単位サーバー処理当たりの負荷が高くなるため、フレーム落ち等の問題が発生する恐れがあります。
[備考]
通常、server_frequencyにはアプリケーションのフレームレートと同じ値を指定します。

(3) 最大バーチャルボイス数(max_virtual_voices)について
アプリケーション中で同時に使用する「バーチャルボイス」の数を指定します。
バーチャルボイスは、ボイスを制御するためのインターフェースを提供する、仮想的なボイスオブジェクトです。
(ボイスと異なり、バーチャルボイス自身は発音用のリソースを持ちません。)

AtomExプレーヤに対して音声データの再生を指示すると、Atomライブラリはバーチャルボイスを確保し、バーチャルボイスに対して発音リクエストを行います。
バーチャルボイスは、発音リクエストに応じて必要なボイスをボイスプールから確保し、発音を行おうとします。
この際、ボイスが確保できた場合は発音処理が行われますが、ボイスが確保できなかった場合には発音処理が行われません。
(バーチャルボイス数分の音声が必ず発音されるとは限りません。)

ハードウェアボイスと異なり、バーチャルボイスはライブラリ内でメモリが許す限り作成が可能です。
そのため、発音可能な音声の数がハードウェア的に制限された環境であっても、一時的に発音上限数を超える数の音声を制御することが可能になります。
アプリケーション中で使用するボイスの数は、ボイスプール作成時に決定されますが、バーチャルボイスの数はライブラリ初期化時に指定します。
バーチャルボイス数を多くすることで、同時にコントロール可能な音声の数は増えますが、必要なメモリは多くなります。
注意:
バーチャルボイス数には、総ボイス数(全ボイスプールで確保するボイスの合計値)以上の値を設定する必要があります。
ボイスプールで確保するボイスの総数がバーチャルボイス数を超える場合、ボイスプールの作成に失敗します。

バーチャルボイスが、実際に発音を行っているボイスの管理だけでなく、発音リクエストの管理にも使用される点にご注意ください。
(criAtomExPlayer_Start関数実行後、サーバー処理が動作するまでの間、発音すべき音声データの情報を保持する役割も持っています。)

バーチャルボイスが不足すると、エラーコールバックが返され、発音に失敗します。
(リクエスト自体が行われず終了するため、ボイスプライオリティ等の評価が行われることなく、必ず発音に失敗します。)
バーチャルボイス数が不足することがないよう、アプリケーション初期化時には max_virtual_voices に実ボイス数よりも充分大きな値を設定してください。
(バーチャルボイス数の目安は、「最大同時発音数+1V当たりの発音リクエスト数」です。)
(4) CRI File Systemライブラリの初期化パラメーター(fs_config)について
CRI Atomライブラリは、ファイルの読み込みにCRI File Systemライブラリを使用します。
そのため、criAtomEx_Initialize関数を実行した場合、関数内でCRI File Systemライブラリの初期化が行われます。
fs_configにNULLを指定した場合、CRI AtomライブラリはCRI File Systemライブラリをデフォルト設定で初期化します。
デフォルト以外の設定でCRI File Systemライブラリを初期化したい場合には、fs_configにCriFsConfig構造体をセットし、CRI Atomライブラリの初期化を行う必要があります。
[備考]
ライブラリ初期化時に指定可能なパラメーターは、上記以外にもいくつか存在します。
設定可能なパラメーターの詳細については「 CriAtomExConfigTag 」の項目をご参照ください。
criAtomEx_Initialize 関数を実行する時点で、既に CRI File System ライブラリが初期化済みである場合、 criAtomEx_Initialize 関数内では CRI File System ライブラリの初期化は行われません。
CRI File Systemライブラリの初期化については、CRI File System「ファイルマジックPRO」マニュアルをご参照ください。

コンフィグ構造体の省略について

初期化時に行うコンフィグ構造体の指定は、省略が可能です。
具体的には、以下のようにcriAtomEx_Initialize関数の引数にNULLを指定することが可能です。
main()
{
        :
    /* コンフィグ構造体を指定せずに初期化を行う */
    criAtomEx_Initialize(NULL, NULL, 0);
        :
}


コンフィグ構造体を省略した場合、CRI Atomライブラリは以下の設定でライブラリの初期化を行います。
上記と同じ設定でライブラリを初期化する際には、コンフィグ構造体の指定を省略することが可能です。
ワークメモリの指定について

以上のパラメーターの他、ライブラリを初期化時する際には、ライブラリを動作させるのに必要なワークメモリを合わせて指定する必要があります。
ワークメモリの指定方法については「 ワークメモリについて 」をご参照ください。

ライブラリの終了方法

アプリケーションを終了する際には、ライブラリの終了処理を行う必要があります。
criAtomEx_Initialize 関数でライブラリを初期化した場合、ライブラリの終了処理には、criAtomEx_Finalize関数を使用します。
ライブラリの終了処理を行うことで、初期化時にセットしたワークメモリを解放したり、他の用途に転用することが可能になります。
Next:スレッドについて

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