シーン：基本再生

プログラム解説：基本再生

格納場所 /cri/cocos2dx/samples/criatom/AtomSamples/
主なソースコード Scenes/AtomBasicScene.cpp
AtomUtil.cpp
ADX2でよく使われる機能をまとめたサンプルプログラムです。
CRI Atom Craft を使ってデータをうまく作ると、プログラム側は再生開始の関数を呼ぶだけで様々な演出が実装できます。

lecocos_sample_adx2_basic.png


サンプル操作と内容

画面左側に縦に並んでいるのが再生ボタンです。ボタンの隣に書いてあるのがキュー名です。
画面右上に並んでいるのが停止ボタンです。
Stopボタンは最後に再生したキューを停止します。stopAllボタンは全ての再生を停止します。
画面中央下部の上矢印ボタンを押すと、シーン選択メニューに戻ります。

キューの試聴と効果の確認

再生ボタンをマウスでクリックするかタッチして再生します。
プログラムは各キューに再生開始の関数を呼び出すだけで、様々なサウンド演出が実現できているのが確認できます。
クロスフェード
music1 と music2 を交互に再生すると、音楽がクロスフェードして切り替わります。

ダッキング
music1 / music2 の再生中に voice_random / voice_effect を再生すると、セリフの再生中だけ音楽の音量が下がります。

ランダムトラック
voice_random は再生するたびに違うセリフが再生されます。

ランダムピッチ
kalimba は再生するたびにピッチの違う音が再生されます。

シーケンス
gunshot はひとつのキューを再生するだけで、タイミングの異なる２つの音（銃撃と薬莢）が再生されます。

発音数制御
bomb_limit は同時に３つまでしかならない設定をしています。bomb は何も制限をかけていません。
ボタンを連打すると連続で再生リクエストを発行しますが、bomb_limit の場合は画面上部のボイス数が一定までしか増えないのが確認できます。

DSPバスエフェクト
voice_effect はリバーブがかかった音声を再生します。

アクション機能
music2 の再生中 pitch_up_m2 / pitch_def_m2 を再生すると、音楽のピッチが変かします。
pitch_up_m2 を再生するとピッチが上がります。pitch_def_m2 で標準の音に戻ります。

汎用的なライブラリ初期化設定

ADX2は機能を制限することで初期化モジュールを減らすことが出来ますが、ここではよく使われるであろう機能に必要な初期化手順とパラメータについてまとめて紹介します。どんなデータを再生するかまだわからないような場合などもこの初期化内容を参考にしてください。
初期化パラメータの調整については、次のようなチェック項目で解説します。
  • 同時発音数がデフォルト設定よりも多い場合。
  • ストリーム再生を何本くらい同時に実行するか。
  • HCA-MXコーデックを再生するか。

サンプルコード

シンプルな初期化手順はクイックスタートの「 [ゲームへの組み込み]編 」で解説していますので参照してください。
本サンプルプログラムでは最大同時発音数やピッチ変更に対応するためにいくつかの初期化パラメータを変更しています。
ADX2はゲーム機用でメモリ使用量をギリギリまで節約できるように、機能や再生するデータ内容／データ数に応じてかなり細かく初期化パラメータを指定できるようになっています。
結果としてかなり初期化構造が複雑になっていますので、ひとまずは本サンプルの初期化コードをそのまま流用するぐらいの実装が簡単でしょう。
このサンプルコードの初期化では、最大16ボイス再生、最大ストリーム数も16、ピッチ変更可能、HCA-MXコーデック再生可能、インゲームプレビュー有効、という設定になっています。
本サンプルの初期化で行っているパラメータ変更については後述します。
criErr_SetCallback(&errorCallback);
criAtomEx_SetUserAllocator(&allocCallback, &freeCallback, NULL);

/* ADX2 初期化 */
CriFsConfig fs_config;
criFs_SetDefaultConfig(&fs_config);
fs_config.num_loaders = 32;     /* ざっくり多め。ストリーミング最大数＋ACB等の読み込みが使用 */

#if (CC_TARGET_PLATFORM == CC_PLATFORM_WIN32)
    /* PC用 */
    CriAtomExConfig_WASAPI atom_wasapi_config;
    criAtomEx_SetDefaultConfig_WASAPI(&atom_wasapi_config);
    atom_wasapi_config.atom_ex.fs_config = &fs_config;
    atom_wasapi_config.hca_mx.output_sampling_rate = sampling_rate_hcamx;
    criAtomEx_Initialize_WASAPI(&atom_wasapi_config, NULL, 0);

#elif (CC_TARGET_PLATFORM == CC_PLATFORM_MAC)
    /* Mac用 */
    CriAtomExConfig_MACOSX atom_macosx_config;
    criAtomEx_SetDefaultConfig_MACOSX(&atom_macosx_config);
    atom_macosx_config.atom_ex.fs_config = &fs_config;
    atom_macosx_config.hca_mx.output_sampling_rate = sampling_rate_hcamx;
    criAtomEx_Initialize_MACOSX(&atom_macosx_config, NULL, 0);

#elif (CC_TARGET_PLATFORM == CC_PLATFORM_IOS)
    /* iOS用 */
    CriAtomExConfig_IOS atom_ios_config;
    criAtomEx_SetDefaultConfig_IOS(&atom_ios_config);
    atom_ios_config.atom_ex.fs_config = &fs_config;
    atom_ios_config.hca_mx.output_sampling_rate = sampling_rate_hcamx;
    criAtomEx_Initialize_IOS(&atom_ios_config, NULL, 0);

#elif (CC_TARGET_PLATFORM == CC_PLATFORM_ANDROID)
    /* Android用 */
    CriAtomExConfig_ANDROID atom_android_config;
    criAtomEx_SetDefaultConfig_ANDROID(&atom_android_config);
    atom_android_config.atom_ex.fs_config = &fs_config;
    atom_android_config.hca_mx.output_sampling_rate = sampling_rate_hcamx;
    criAtomEx_Initialize_ANDROID(&atom_android_config, NULL, 0);
#endif

#if (CC_TARGET_PLATFORM == CC_PLATFORM_ANDROID)
    /* ANDROIDの場合で必要な一手間。assetsフォルダへのアクセスを可能にする */
    /* まずはJniHelperでActivityのContextを取得 */
    cocos2d::JniMethodInfo methodInfo;
    cocos2d::JniHelper::getStaticMethodInfo(methodInfo,
                                            "org/cocos2dx/lib/Cocos2dxActivity",
                                            "getContext",
                                            "()Landroid/content/Context;");
     auto android_context_object = (jobject)methodInfo.env->CallStaticObjectMethod( methodInfo.classID, methodInfo.methodID );
     /* 有効化。assetsフォルダはCocosプロジェクトのResource相当なので、ほぼ必須と言って良い手順 */
     criFs_EnableAssetsAccess_ANDROID(cocos2d::JniHelper::getJavaVM(), android_context_object);
#endif

/* 全体設定(ACF)の登録 */
CriChar8 acf_path[256];
getResourcePath(acf_path, acf_file_name);
criAtomEx_RegisterAcfFile(NULL, acf_path, NULL, 0);

/* DSPバス設定の登録 */
/* MEMO: これをやらないとDSPバスエフェクト（リバーブ等）が効きません。 */
criAtomEx_AttachDspBusSetting(dsp_bus_setting_name, NULL, 0);

/* ボイスプール作成 */
CriAtomExStandardVoicePoolConfig vp_config;
/* ボイスプールの設定。まずはデフォルト設定にして、その上で必要な値へ書き換えていく */
criAtomExVoicePool_SetDefaultConfigForStandardVoicePool(&vp_config);
vp_config.num_voices                        = max_voice;
vp_config.player_config.streaming_flag      = CRI_TRUE;
vp_config.player_config.max_sampling_rate   = max_sampling_rate;
/* 上で作った設定オブジェクトを渡して、ボイスプールを作成 */
g_standard_voice_pool = criAtomExVoicePool_AllocateStandardVoicePool(&vp_config, NULL, 0);

/* HCA-MX再生用のボイスプール作成 */
CriAtomExHcaMxVoicePoolConfig hcamx_config;
criAtomExVoicePool_SetDefaultConfigForHcaMxVoicePool(&hcamx_config);
hcamx_config.num_voices                         = max_voice;
/* 一応ストリーミング再生可能で初期化しておく。メモリ再生のみなら不要。 */
hcamx_config.player_config.streaming_flag       = CRI_TRUE;
hcamx_config.player_config.max_sampling_rate    = sampling_rate_hcamx;
g_hcamx_voice_pool = criAtomExVoicePool_AllocateHcaMxVoicePool(&hcamx_config, NULL, 0);

/* DBASの作成（ストリーミング再生に必要） */
g_dbas_id = criAtomDbas_Create(NULL, NULL, 0);

/* インゲームプレビュー機能の初期化 */
CriAtomExAsrBusAnalyzerConfig analyze_config;
CriSint32 bus_no;
criAtomExMonitor_Initialize(NULL, NULL, 0);
/* レベル測定機能を追加 */
criAtomExAsr_SetDefaultConfigForBusAnalyzer(&analyze_config);
for ( bus_no=0;bus_no<8;bus_no++) {
    criAtomExAsr_AttachBusAnalyzer(bus_no, &analyze_config);
}


パラメータ調整：最大同時発音数を増やす

全てのモジュールをデフォルト初期化(NULL指定)した場合、最大同時発音数は８になります。
TIPS：「同時発音」とは再生中のキューの数ではなく、再生中の波形の数でカウントします。 シーケンスやマルチトラックを使うとキューの数よりも多い発音数になる可能性があります。
最大同時発音数を増やすためには、ボイスプールの初期化パラメータと、ライブラリの初期化パラメータを調整する必要があります。
  • CriAtomExStandardVoicePoolConfig の num_voices は「最大同時発音数」そのものの数値を指定します。
  • CriAtomExConfig_WASAPI の atom_ex.max_virtual_voices は作成するボイスプールの合計の「最大同時発音数」よりも大きい値を指定してください。
    また、ボイスプールをストリーム再生可能で作成すると、最大同時発音数に等しい数のストリーム読み込みが発生する可能性があることになるため、読み込みハンドル数も増やす必要があります。
  • CriAtomExConfig_WASAPI の crifs->num_loaders は、ボイスプールの合計の「最大同時発音数」よりも大きい値を指定してください。
TIPS: ボイス数は複数作ることが出来ますので、ストリーム用とメモリ用で２つにわけることも可能です。
この場合は読み込みハンドル数に影響するのは、ストリーム用最大発音数だけです。

パラメータ調整：同時ストリーム数について

全てのモジュールをデフォルト初期化(NULL指定)した場合、ストリーム再生は出来ません。
ストリーム再生を行う場合は、ボイスプールの初期化パラメータ CriAtomExStandardVoicePoolConfig の player_config.streaming_flag を true にしてください。
ストリーム有効のボイスプールは読み込みハンドル数にも影響します。「最大同時発音数」を増やすための説明も参照してください。

パラメータ調整：ピッチ変更に対応する

全てのモジュールをデフォルト初期化(NULL指定)した場合、データ設定やプログラムからの設定でピッチを上げる事が出来ません。

データ側でランダムピッチを使ったり、プログラムからピッチを上げる可能性がある場合は、ボイスプールの初期化パラメータ CriAtomExStandardVoicePoolConfig の player_config.max_sampling_rate を増やしてください。
ボイスプールのピッチ上限を超えたデータを再生しようとした場合、エラーコールバックで警告が発生します。

パラメータ調整：HCA-MXコーデックを使用する場合

HCA-MX コーデックのデータを再生する場合は、標準ボイスプールとは別に HCA-MX用ボイスプールを作成してください。
専用関数 criAtomExVoicePool_SetDefaultConfigForHcaMxVoicePool() があります。
同時発音数、同時ストリーム数、ピッチ変更などの設定は HCA-MX のボイスプールにも関係しますので注意してください。
また、HCA-MXコーデックを使う場合、CRI Atomライブラリ初期化時に HCA-MXコーデックのサンプリングレートを指定する必要があります。
データで使っている値を同じになるように設定してください。
HCA-MX についての詳細は「 HCA-MXコーデックの再生について 」も参照してください。


プレーヤハンドルの扱い

本サンプルプログラムでは、AtomUtil.cpp でプレーヤハンドル( CriAtomExPlayerHn )をひとつだけ作成して全てのキューを再生しています。
プレーヤハンドルを複数作って使い分けるかどうかはプログラムの設計によります。簡単に特徴をまとめます。

ひとつのプレーヤで複数のキューを再生する場合

＜メリット＞
  • プレーヤで再生中の全てのキューに対してパラメータ変更が可能。ボリューム変更や、ポーズのON/OFFなど。
    ＜デメリット＞
  • キュー単位でのパラメータ設定や情報取得には少し手間がかかる。
  • 3Dポジショニングはプレーヤ単位で音源位置を指定するので、位置の違う音は一緒に鳴らせません。

ひとつのプレーヤでひとつのキューのみ再生する場合

＜メリット＞
  • パラメータ設定や情報取得が簡単。
  • 3Dポジショニングは基本的にこの使い方。 ＜デメリット＞
  • プレーヤの数が増えると、ポーズON/OFFやボリューム調整に手間がかかる。

プレーヤの使い分け例

音楽用、キャラボイス用、SE用などいくつかのプレーヤを作って用途別に使い分けるという例もあります。
こうすると、データ側でカテゴリ設定がない場合でも種類ごとに音量を変えたりポーズをかけたりできます。

キュー単位での再生情報取得

ひとつのプレーヤで複数のキューを再生している場合、特定のキューに対して再生時刻や再生状態を調べるにはプレイバックID( CriAtomExPlaybackId )を使います。
プレイバックIDは再生開始時に criAtomExPlayer_Start() の返り値として取得できます。
CriAtomExPlaybackId plyaback_id;
/* 再生開始＆プレイバックIDの取得 */
playback_id = criAtomExPlayer_Start(player);
....
/* キューの再生状態取得 */
CriAtomExPlaybackStatus playback_state;
playback_state = criAtomExPlayback_GetStatus(playback_id);
/* キューの再生時刻の取得 */
CriSint64 playback_time;
playback_time = criAtomExPlayback_GetTime(playback_id);
....
/* キュー指定の再生停止 */
criAtomExPlayback_Stop(playback_id);
サンプルプログラムでは、最後に再生したキューについてだけプレイバックIDを保存して情報表示および再生停止を行っています。

プログラムからの再生パラメータ変更

音量やピッチなどのパラメータは、CRI Atom Craft でデータ側に設定するのが基本ですが、プログラムから動的に設定することも可能です。
プログラム側から設定したパラメータがどう扱われるかは、パラメータの種類によって異なります。
例えば音量の場合は、データ側設定と掛け算で計算されますし、ピッチの場合は足し算で計算されます。

再生開始前のパラメータ変更

再生開始前にパラメータを変更しておくと、設定したパラメータが初期値として再生を開始できます。
他のキューを同じプレーヤで再生する可能性がある場合は、再生開始後に設定値をもとに戻しておかないと別の再生にも影響を与えてしまうので注意してください。
再生開始後にパラメータを戻しても、再生中のサウンドには影響しません。
/* パラメータ設定 */
criAtomExPlayer_SetPitch(player, 0.5f);
/* 再生開始 */
criAtomExPlayer_Start(player);
/* このプレーヤで他のキューも再生する可能性がある場合は、パラメータをもとに戻す */
criAtomExPlayer_SetPitch(player, 0.0f);


再生中のパラメータ変更

再生開始した後にパラメータを変更する場合は、プレイバックIDを使用します。
パラメータを設定したあと、プレイバックIDを指定してパラメータ更新関数 criAtomExPlayer_Update() を呼び出してください。

/* 再生開始 */
playback_id = criAtomExPlayer_Start(player);
....
/* 再生中に音量変更 */
criAtomExPlayer_SetVolume(player, 0.2f);
/* 変更した音量を適用 */
criAtomExPlayer_Update(player, playback_id);


criAtomExPlayer_Update() の代わりに criAtomExPlayer_UpdateAll() を使用すると、再生中の全てのキューに適用されます。

発音数制御

最大発音数を制限するためには、ライブラリの初期化およびボイスプール作成時の最大ボイス数指定がポイントになります。
初期化のサンプルコード自体は「 汎用的なライブラリ初期化設定 」を参照してください。
プログラムは再生開始を行う際に、最大発音数を超えるかどうかを気にする必要はありません。
最大発音数を超えた場合は、データ側で設定されたサウンド優先度に従って再生するサウンドが選択されます。
使用中のボイス数は criAtomExVoicePool_GetNumUsedVoices() でボイスプール単位で取得できます。
また、ボイスプールをメモリ再生用とストリーム再生用で分けた場合は、それぞれ独立に再生数が管理されます。
ボイスプールによる発音数制御と、データ側のキューリミット等での発音数制御は再生時に全て適用されます。
ボイスプールに余裕があってもキューリミットにかかれば発音は制限されますし、その逆もしかりです。
CRI Middleware logo Copyright (c) 2012-2018 CRI Middleware Co., Ltd. CRI ADX2 LE マニュアル (for Cocos2d-x) SDKVer.2.10版