[ゲームへの組み込み]編
本章では、プログラム側でのADX2組み込み方法について基本的な流れを説明します。
具体的に動作するサンプルとして「シーン：基本再生 」および「サンプル共通事項 」の「サンプル用簡易ADX2ラッパ」も併せてご覧ください。

(1) データの準備

以降の説明では、サンプル「基本再生」用のサウンドデータを使って説明します。
サウンドデータのファイルパスと内容を説明します。
読み込むサウンドデータのパス
  * cri

  \ * cocos2dx

    \ * samples

      \ * criatom

        \ * programs

          \ * AtomSamples

            \ * Resources

              o * Basic.acb

              o * Basic.awb

              \ * ADX2_samples.acf

 

 

 

 

 

 

 

: キューシートバイナリ

: ストリーミングデータ

: 全体設定ファイル

 

最終的なアプリケーションに必要なデータは、ACFファイル、ACBファイル、AWBファイルです。
自作のサウンドデータを使ったり、ファイルの場所を変える場合はプログラムから読める場所にACF/ACB/AWBファイルをコピーして、サンプルコードのファイルパスやファイル名を適宜読み替えてください。

(2) プロジェクトの設定（機種別）

ADX2 LEのためのヘッダファイルのインクルードとライブラリのリンクを各機種で設定します。
詳細は機種別の説明を参照してください。
本項では各機種の開発環境やCocos2d-x自体のセットアップは完了しているものとして、ADX2 LEに関連する部分のみ説明します。

(3) ライブラリ初期化

以降はすべてプログラム側の実装方法の説明です。
まずADX2ライブラリを使用できるようにするためにいくつかの初期化処理を実行します。
再生したいデータ内容や使いたい機能によって必要な初期化処理は増減しますが、ここでは一般的に必要になるであろう機能はすべて使うという前提で説明します。
ヘッダファイルのインクルード
ADX2ライブラリの関数を呼び出すプログラム側では、次のようにインクルードを記述してください。
#include <cri_adx2le.h>


ADX2ライブラリのヘッダファイルは複数ありますが、 cri_adx2le.h だけをインクルードすれば各機種に必要なADX2のヘッダファイルが全て読み込まれます。

ADX2ライブラリ初期化と再生の準備
初期化処理には次のような手順があります。
まずはこれらの初期化はワンセットで実装してしまうのが、簡単です。
メモリ削減などが必要になった場合はそれから初期化内容やパラメータを調整するのが良いでしょう。
(1) エラーコールバック関数の登録
(2) メモリアロケータの登録
(3) ライブラリの初期化
(4) ストリーミング用バッファの作成
(5) 全体設定ファイル(ACF)の登録
(6) DSPバス設定の登録
(7) ボイスプールの作成
上記の初期化処理を簡単に実装したサンプルコードは次のようになります。
この初期化で同時に再生できるボイス数は８です。
同時最大ボイス数を増やしたり、ピッチ変更に対応したりすると初期化パラメータを細かく指定する必要が出てきます。
パラメータ変更の実践例は「 シーン：基本再生 」で解説していますので参照してください。
ライブラリ初期化 criAtomEx_Initialize_WASAPI の部分は各機種ごとに関数名が異なりますので必要な環境に合わせて呼び分けてください。
#include <cri_adx2le.h>

/* 全体設定ファイルのパス */
#define ACF_FILE   "../../../data/ADX2_samples.acf"

CriAtomExVoicePoolHn voice_pool;   /* ボイスプールハンドル */
CriAtomDbasId dbas;                /* D-BASハンドル */

/* エラーコールバック関数の登録 */
criErr_SetCallback(user_error_callback_func);

/* メモリアロケータの登録 */
criAtomEx_SetUserAllocator(user_alloc_func, user_free_func, NULL);

/* ライブラリ初期化 */
criAtomEx_Initialize_WASAPI(NULL, NULL, 0);

/* ストリーミング用バッファの作成 */
dbas = criAtomDbas_Create(NULL, NULL, 0);

/* 全体設定ファイルの登録 */
criAtomEx_RegisterAcfFile(NULL, ACF_FILE, NULL, 0);

/* DSPバス設定の登録 */
criAtomEx_AttachDspBusSetting("DspBusSetting_0", NULL, 0);

/* ボイスプールの作成（ストリーム再生対応） */
CriAtomExStandardVoicePoolConfig vpconfig;
criAtomExVoicePool_SetDefaultConfigForStandardVoicePool(&vpconfig);
vpconfig.player_config.streaming_flag = CRI_TRUE;
voice_pool = criAtomExVoicePool_AllocateStandardVoicePool(&vpconfig, NULL, 0);
/* MEMO: ストリーム再生無しなら、ボイスプールは構造体NULL指定で可 */


エラーコールバックやメモリアロケータの詳細についてはマニュアルの 基本事項 に項目ごとの説明がありますので参照してください。
サンプルコードでは引数のほとんどがNULL指定となっていますが、引数構造体を使うことで細かなパラメータ設定が可能になります。
ボイスプールは、ライブラリ終了時に破棄しなければいけないので記録しておいてください。

エラーコールバック関数やメモリアロケータの実装サンプルは次のようになります。
/* エラーコールバック関数のユーザ実装 */
static void user_error_callback_func(const CriChar8 *errid, CriUint32 p1, CriUint32 p2, CriUint32 *parray)
{
    const CriChar8 *errmsg;
    /* エラーコードからエラー文字列に変換してコンソール出力する */
    errmsg = criErr_ConvertIdToMessage(errid, p1, p2);
    CCLOG("%s\n", errmsg);
    return;
}
/* メモリ確保関数のユーザ実装 */
void *user_alloc_func(void *obj, CriUint32 size)
{
    void *ptr;
    ptr = malloc(size);
    return ptr;
}
/* メモリ解放関数のユーザ実装 */
void user_free_func(void *obj, void *ptr)
{
    free(ptr);
}


Android 固有の処理
Androidの場合、ADX2ライブラリ初期化の前にライブラリをロードする必要があります。
詳細は「 Android用ダイナミックライブラリのロード処理 」を参照してください。

(4) データの読み込み

サウンドデータのファイル(ACB, AWB)読み込みの実装を説明します。
全体設定ファイル(ACF)はアプリケーション全体で唯一の登録になりますが、サウンドデータは複数のACBを使うことが可能です。
データ内容にあわせて管理しやすいサイズでキューシートバイナリ(ACB)を分けて作るのが良いでしょう。
#include <cri_adx2le_pc.h>

/* サウンドデータファイルのパス */
#define ACB_FILE   "../../../data/Basic.acb"
#define AWB_FILE   "../../../data/Basic.awb"

CriAtomExAcbHn acb_hn;             /* ACBハンドル */

/* サウンドデータの読み込み */
acb_hn = criAtomExAcb_LoadAcbFile(NULL, ACB_FILE, AWB_FILE, NULL, NULL, 0);


サウンドデータを読み込むと、ACBハンドルが出来ます。再生するキュー指定やACBの解放処理に必要なのでACBハンドルは記録しておくようにしてください。
criAtomExAcb_LoadAcbFile() の第一引数は、NULLを指定してください。
第一引数はファイルマジックPROと組み合わせて使うためのパラメータですが、ADX2 LE では使用できません。
criAtomExAcb_LoadAcbFile() が終わると、ACBファイルがメインメモリに読み込まれて再生準備が整います。
AWBファイルはストリーム再生用のデータとしてファイルパスがACBハンドルに記録されます。

(5) 再生制御

プレーヤハンドルの作成
サウンド（キュー）の再生はプレーヤハンドルを使って行います。まずプレーヤハンドルを作成します。
本説明では簡略化のためにプレーヤハンドルはひとつだけ最初に作っていますが、複数作って使い分けることも可能です。
CriAtomExPlayerHn player;          /* プレーヤハンドル */
/* プレーヤハンドルの作成 */
player = criAtomExPlayer_Create(NULL, NULL, 0);


キューの指定と再生開始
キューの指定はプレーヤハンドルに対して行い、指定するときにそのキューを含むACBハンドルを指定します。
/* キューの指定 */
criAtomExPlayer_SetCueId(player, acb_hn, 0);
/* キューの再生開始 */
criAtomExPlayer_Start(player);


キューの指定には、ID指定、キュー名指定などが利用できます。
ID指定の場合は、ツールから出力されたヘッダファイルにキュー名を使ったマクロが定義されていますのでそれを利用可能です。
キュー名指定の場合は、ツールで指定したキュー名の文字列がそのまま使えます。
ひとつのプレーヤハンドルで複数のキューを再生することが可能です。キューの指定と再生開始を繰り返してください。
プレーヤに対して再生停止やボリューム設定を行うと、そのプレーヤで再生している全てのキューに対して適用されます。
プレーヤハンドルを複数作る場合は、音楽用、キャラボイス用、SE用などと用途をわけることで、種類ごとに音量変更などが簡単に実装できます。
また、3Dポジショニング機能を使う場合はひとつのプレーヤでひとつの音源となるように実装してください。
再生中のサウンド制御
特定のキューだけを再生停止したいとか、再生時刻や再生終了状態を調べたいという場合は、再生開始時に生成される CriAtomExPlayback のIDを使って実行が可能です。
CriAtomExPlaybackId playback_id;

/* キュー再生とプレイバックIDの記録 */
criAtomExPlayer_SetCueId(player, acb_hn, 0);
playback_id = criAtomExPlayer_Start(player);

....

/* 再生時刻の取得 */
msec = criAtomExPlayback_GetTime(playback_id);

/* 再生終了の判定 */
if (criAtomExPlayback_GetStatus(playback_id) == CRIATOMEXPLAYBACK_STATUS_REMOVED) {
     /* 再生終了 */
}


パラメータの更新
音量の変更等のパラメータ更新をアプリケーションから行った場合、設定関数を読んだだけではパラメータは適用されません。
設定したパラメータは、 criAtomExPlayer_UpdateAll() または criAtomExPlayer_Update() を呼び出すとプレーヤに適用されます。
criAtomExPlayer_SetVolume(player, 0.5f);
criAtomExPlayer_UpdateAll(player);



(6) メインループの定期処理

ADX2ライブラリの使用中はアプリケーションのメインループに相当するタイミングで定期的に criAtomEx_ExecuteMain 関数を呼び出してください。
criAtomEx_ExecuteMain 関数は、ライブラリ内部のパラメータ更新や再生制御などを定期的に行うための関数です。
Cocos2d-x の場合はシーンの定期所にから criAtomEx_ExecuteMain を呼び出してください。
void SampleScene::update()
{
    /* ADX2の定期処理 */
    criAtomEx_ExecuteMain();
}



(7) ライブラリ終了

ここまででライブラリ初期化から再生制御までの説明を行いましたので、最後に終了処理についてまとめます。
まとめて紹介しますが、プログラムの終了時でなくても、プレーヤハンドルを生成／破棄したり、ACBファイルを読み込み／解放したりすることは可能ですので適宜それぞれの機能に対応する終了処理を呼び出してください。
/* 再生中のサウンド停止 */
....

/* プレーヤハンドルの破棄 */
criAtomExPlayer_Destroy(player);

/* ACBハンドルの解放 */
criAtomExAcb_Release(acb_hn);

/* ボイスプールの解放 */
criAtomExVoicePool_Free(voice_pool);

/* 全体設定ファイルの登録解除 */
criAtomEx_UnregisterAcf();

/* ライブラリの終了 */
criAtomEx_Finalize_WASAPI();


(8) 追加の機種固有処理

スマートフォンアプリのサスペンド／レジューム対策など、機種固有の追加処理があります。
詳細はライブラリの機種固有情報ページを参照してください。


CRI Middleware logo Copyright (c) 2012-2018 CRI Middleware Co., Ltd. CRI ADX2 LE マニュアル (for Cocos2d-x) SDKVer.2.10版