fmod APIを使用したプログラムについて解説します。
今回から具体的なAPIを使用したプログラミングに入ります。
Win32のプロジェクトなので要点以外のコードがとても多かったり、先にソースを読んでおいて解説と並行したいという方もいると思います。
ということで出来上がったものをこちらにあらかじめ用意しました。
# 料理講座っぽく言ってみたかっただけです
このプロジェクトでは、次の処理を行っています。
- fmodシステムの初期化(InitMusicStream関数)
- BGMとして使用するオーディオファイルの読み込み(PlayMusicStream関数)
- fmodシステムの終了処理(ReleaseMusicStream関数)
これらの処理は、それぞれ関数化してWinMain.cppで呼び出すようにしています。
カッコ内の関数名はfmodTest.cpp内で定義されています。
fmodTest.cpp内の解説に移ります。
このソースファイルには、3個のグローバル変数があります。
FMOD_SYSTEM* fmodsystem = NULL;
FMOD_SOUND* fmodsound = NULL;
FMOD_CHANNEL* fmodchannel = NULL;
このFMOD_SYSTEM、FMOD_SOUND、FMOD_CHANNELはそれぞれオーディオシステム全体、再生する楽曲/効果音データ、データ再生時チャンネルのハンドルです。
ヘッダファイル(fmod.h)内では、それぞれ構造体として定義されていますが、メンバまでは記述されていません。
現時点ではこれらの情報を追求する必要はないので｢こういうもの｣という程度にとどめておいてください。
次にInitMusicStream関数内で呼び出しているAPIの解説です。
| API名 | FMOD_System_Create |
| 構文 | FMOD_RESULT FMOD_System_Create( FMOD_SYSTEM* system ); |
| 引数 | | system | FMOD_SYSTEMのポインタです。
処理が成功した場合、生成されたFMODシステムのアドレスが返されます。 | |
| 返り値 | FMOD_RESULT(FMOD_OKであれば成功、それ以外は各種エラーコード) |
| 解説 | FMOD_SYSTEMオブジェクトを生成します。
FMOD_SYSTEMオブジェクトは、生成しただけでは使用できないので返されたsystemをFMOD_System_Initに渡し、初期設定を行う必要があります。 |
| API名 | FMOD_System_Init |
| 構文 | FMOD_RESULT FMOD_System_Init( FMOD_SYSTEM* system, int maxchannels, FMOD_INITFLAGS flags, void* extradriverdata ); |
| 引数 | | system | FMOD_SYSTEMのポインタです。
FMOD_System_Createで生成したものを使います。 | | maxchannels | FMODで使用されるチャンネルの最大数です。
通常は100もあれば困ることはありません。 | | flags | 拡張機能を合わせて初期化するためのフラグです。
特に必要がなければFMOD_INIT_NORMALだけを指定します。
FMOD_INIT_NORMAL以外のFMOD_INITFLAGS定数については、ヘッダファイルもしくはリファレンスマニュアルを参照してください。 | | extradriverdata | サウンドデバイスのドライバに渡すデータがある場合に使用する引数です。
渡すデータがない場合は、NULLを渡します。 | |
| 返り値 | FMOD_RESULT(FMOD_OKであれば成功、それ以外は各種エラーコード) |
| 解説 | systemで指定したFMOD_SYSTEMオブジェクトの初期設定を行います。
設定できる内容はmaxchannelsとflagsの解説を参照してください。 |
| API名 | FMOD_System_CreateStream |
| 構文 | FMOD_RESULT FMOD_System_CreateStream( FMOD_SYSTEM* system, const char* name_or_data, FMOD_MODE mode, FMOD_CREATESOUNDEXINFO* exinfo, FMOD_SOUND** sound ); |
| 引数 | | system | FMOD_SYSTEMのポインタです。
FMOD_System_Createで生成したものを使います。 | | name_or_data | 再生するオーディオデータのパスもしくはURLです。
音楽CDを再生する場合はドライブレターを指定します(例、Eドライブの場合は"E:")。
ファイルパスはマルチバイト文字列で指定します。UNICODEビルドをした場合でもワイド文字列は使用できません。 | | mode | ファイルを開く際に指定する条件のフラグです。
特に必要がなければFMOD_DEFAULTだけを指定します。FMOD_DEFAULT以外のFMOD_MODE定数については、ヘッダファイルもしくはリファレンスマニュアルを参照してください。 | | exinfo | 開いたファイルに関する情報(FMOD_CREATESOUNDEXINFO構造体)です。
取得できる情報については、ヘッダファイルもしくはリファレンスマニュアルを参照してください。 | | sound | FMOD_SOUNDのポインタをアドレスで渡します(形式上ダブルポインタになる)。
ここで返される値は、FMOD_Sound_* APIを呼び出す際に必要になります。 | |
| 返り値 | FMOD_RESULT(FMOD_OKであれば成功、それ以外は各種エラーコード) |
| 解説 | name_of_dateで指定したパスやファイルを開きます。
オンライン上のURLや音楽CDのドライブを指定することもできます。
このAPIでは指定したパスをストリーム再生(再生をする際に必要なデータを逐次読み込んでいく)する形式で読み込みます。
パスやファイルを開くことができた場合、soundにそのデータのアドレスが返されます。 |
リファレンスがたくさん出てきましたが、初期化処理で指定する値は特殊環境でなければデフォルト推奨値でよいと思います。
FMOD_System_CreateとFMOD_System_InitがFMODシステムの生成と初期化処理で、次にFMOD_System_CreateStreamでBGMに使用するファイルを開きます。
ここまでが初期化処理(とファイルオープン処理)になります。
次にPlayMusicStream関数内で呼び出されているAPIの説明です。
| API名 | FMOD_System_PlaySound |
| 構文 | FMOD_RESULT FMOD_System_PlaySound( FMOD_SYSTEM* system, FMOD_CHANNELINDEX channelid, FMOD_SOUND* sound, FMOD_BOOL paused, FMOD_CHANNEL** channel ); |
| 引数 | | system | FMOD_SYSTEMのポインタです。
FMOD_System_Createで生成したものを使います。 | | channelid | 再生の際に使用するチャンネルを指定します。
FMOD_CHANNEL_FREE(-1)を指定すると空いているチャンネルに自動割り当てされます。
特定のチャンネルを指定する場合は、ゼロ以上の値を指定します。 | | sound | 再生するデータのFMOD_SOUNDのポインタ。
FMOD_System_CreateStreamで作成したものを使います。 | | paused | API呼び出し直後に再生を進めるかを指定します。
TRUEを指定した場合、一時停止状態になります。
一時停止の解除は、FMOD_Channel_SetPaused APIを使用します。
(このエントリでは解説しません) | | channel | 再生を行うチャンネル(FMOD_CHANNEL)のポインタです。
再生中のBGMや効果音に対する操作/設定をするAPIで必要になります。 | |
| 返り値 | FMOD_RESULT(FMOD_OKであれば成功、それ以外は各種エラーコード) |
| 解説 | soundに指定したFMOD_SOUNDを再生します。
呼び出しが成功した場合、channelに再生チャンネルのハンドルが返され、再生が始まります(ただし、pausedによる一時停止設定など例外もあります)。 |
PlayMusicStream関数が呼び出され、FMOD_System_PlaySound APIが呼び出されれば、演奏が始まります。
最後に、プログラム終了時に行うFMODシステムの終了処理のAPIを解説します。
| API名 | FMOD_Channel_Stop |
| 構文 | FMOD_RESULT FMOD_Channel_Stop( FMOD_CHANNEL* channel ); |
| 引数 | | channel | データ再生をしているチャンネルのハンドルです。
FMOD_System_PlaySound等の呼び出しで取得したものを指定します。 | |
| 返り値 | FMOD_RESULT(FMOD_OKであれば成功、それ以外は各種エラーコード) |
| 解説 | channelで指定したチャンネルの演奏を停止します。 |
| API名 | FMOD_Sound_Release |
| 構文 | FMOD_RESULT FMOD_Sound_Release( FMOD_SOUND* sound ); |
| 引数 | | sound | 再生のためにオープン(ストリーム)もしくは読み込んでいるデータのハンドルです。
FMOD_System_CreateStream等で取得したものを使用します。 | |
| 返り値 | FMOD_RESULT(FMOD_OKであれば成功、それ以外は各種エラーコード) |
| 解説 | soundで指定したデータを開放します。 |
| API名 | FMOD_System_Close |
| 構文 | FMOD_RESULT FMOD_System_Close( FMOD_SYSTEM* system ); |
| 引数 | | system | FMOD_SYSTEMのポインタです。
FMOD_System_Createで生成したものを使います。 | |
| 返り値 | FMOD_RESULT(FMOD_OKであれば成功、それ以外は各種エラーコード) |
| 解説 | systemで指定したFMODシステムを使用できないようにします。
このAPIを呼び出す前にFMODシステムに関連するリソースは開放するようにしてください。 |
| API名 | FMOD_System_Release |
| 構文 | FMOD_RESULT FMOD_System_Release( FMOD_SYSTEM* system ); |
| 引数 | | system | FMOD_SYSTEMのポインタです。
FMOD_System_Createで生成したものを使います。 | |
| 返り値 | FMOD_RESULT(FMOD_OKであれば成功、それ以外は各種エラーコード) |
| 解説 | systemで指定したFMODシステムを開放します。
このAPIでシステムを開放する場合、事前にFMOD_System_Closeを呼ぶ必要はありません。 |
リファレンスによれば、FMOD_System_ReleaseすればFMOD_System_Closeは省いてよいようですが、念のためサンプルではClose→Releaseと呼び出しています。
以上が、fmod APIの初期化/終了の処理と最低限のBGM再生を行うための解説です。
ここまでの処理ができれば、後は素材を揃えてAPIで遊ぶことができます。
最後に、サンプルを動かすための注意をいくつか。
- fmodex.dllをコピーしてください。
このサンプルはfmodex.dllが読み込めないと動作しません。
SDKをインストールしたフォルダの｢./api｣フォルダにfmodex.dllというファイルがあります。
これをサンプルのプロジェクトファイルがあるフォルダにコピーしてください。
また、VisualStudio上から実行した場合と、ビルドしてできたexeファイルを直接呼び出す場合では、dllの配置場所を変えないといけません。
VisualStudioから実行する場合は、プロジェクトファイルがあるフォルダに置いてください。
exeファイルを直接実行する場合は、exeファイルと同じ場所に置いてください。 - music.oggを用意してください。
このサンプルでは、music.oggというファイルを読み込んで再生しています。
オーディオファイルは、mp3やwavでもよいのですが、サンプルで指定しているものと名前が一致するようにしてください。
fmodのSDKには、サンプルとしていくつかのoggファイルがインストールの時点で作成されます。
インストールフォルダ配下の｢.\fmoddesignerapi\examples\media\music｣からファイルをコピーして名前を変更して使うこともできます。
music.oggはサンプルに同梱していません。
# excited.oggやrelaxed.oggは演奏時間が長いです
以上が、fmod APIを使った簡単なサンプルになります。