MusicVillage Tutorial

 このドキュメントには MusicVillage の簡単な使い方が記されています。 このドキュメント通りにプログラミングすれば、誰でも MusicVillage の最小機能を使えるはずです。


1. 準備するもの

 このサンプルは、Microsoft Visual C++ 6.0 用に書かれています。 5.0以下、もしくは 2002 以上でも、プログラム上には差はありません。 また、他のコンパイラを使っている場合でも、 設定方法が多少異なるだけですので、平気かとは思います。
  1. サンプル用プロジェクト
    プロジェクト名はなんでも構いません。 ただし、次の関数のテンプレートは必ず作成しておいてください (この関数を呼ぶこととして説明をしていきます)。

    BOOL mvsampleOpenDevice();
    BOOL mvsampleCloseDevice();
    BOOL mvsamplePlayMusic(LPCSTR lpszFileName);

    また、『mmsystem.h』も忘れずにインクルードしておいてください。

  2. Midi デバイス
    ご使用のマシンに Midi アウトデバイスが無いと、 説明を続けられません。 外部音源と接続している場合は、準備をしておいてください。

  3. プロジェクトの設定
    プロジェクトを用意したら、『MVillage.h』をそのフォルダにコピーし、 必ずインクルードしてください。これを忘れると MusicVillage が使えません(当然ですが)。 それから、『MVillage.lib』もコピーし、プロジェクトに参加させてください。 面倒なら、共通のヘッダファイルか何かに

    #pragma comment(lib,"MVillage.lib")

    と追加してください。



簡単なサンプル

 いよいよ説明に入ります。 まずは、上記で用意した3つの関数に、必要なコードを書いていきます。
 mvsampleOpenDevice() 関数では、再生のためのデバイスをオープンします。 以下のコードを書きこんでください。

MVRESULT ret;

ret = MVOpenDevice(MIDI_MAPPER,NULL);
if(ret != MVERR_NOERROR) {
	//  An error occured
	return FALSE;
}

return TRUE;


ここで行っているのは、システムデフォルトの Midi デバイスをオープンするだけです。 MusicVillage を使うには、まずデバイスをオープンしなければなりません。 ここでの MVOpenDevice 関数がそれを行ってくれます。
第一引数には LONG 型のデバイス ID を指定します。 今回はシステムデフォルトという事で MIDI_MAPPER を指定します。
第二引数にはデバイスのオープンを通知するためのイベントハンドルを指定しますが、 今回は NULL を指定します。
成功すれば MVERR_NOERROR が、失敗すればその他のエラーコードが返ります。 MVRESULT は LONG 型を置き換えています。 これでデバイスはオープンできました。しかし、こういったシステムはあけっぱなしではいけません。 オープンしたデバイスはきちんとクローズしなければなりません。 それを処理するのが次の mvsampleCloseDevice 関数です。


MVRESULT ret;

ret = MVCloseDevice();
if(ret != MVERR_NOERROR) {
	//  An error occured
	return FALSE;
}

return TRUE;


 この関数も簡単ですね。MusicVillage にデバイスを閉じてくれと言っているだけです。 ただし、デバイスが開いていない時はそのことを伝えるエラーメッセージを返すだけなので、 あまり気にしなくても良いでしょう。 アプリケーション終了時にはこの関数を呼ぶ事をお勧めします。 MusicVillage はプログラムシャットダウン時にデバイスが開いていれば自動で閉じてくれますが、 こういうことはきちんとやっておいたほうが、ほかのところでも役に立ちます。

 では最後に、再生のための関数を実装します。


MVRESULT ret;

ret = MVStopMusic();

ret = MVLoadMusic(lpszFileName);
if(ret != MVERR_NOERROR) {
	//  Failed to load file.
	return FALSE;
}

ret = MVPlayMusic();
if(ret != MVERR_NOERROR) {
	//  An error occured.
	return FALSE;
}

return TRUE;


 ちょっとだけ長くなりましたが、やっている事はいたって簡単です。
 まず、最初に MVStopMsic 関数を呼んで強制的に演奏をストップさせます。 MVCloseDevice 同様、再生されていない場合はエラーを返すだけなので、 このように使っても問題ありません。
 そして次に、目的の Midi ファイルを読みこみます。 これには MVLoadMusic 関数を使います。 第一引数には読みこむファイルのファイル名へのポインタを渡します。 MusicVillage は UNICODE 環境では動作しないので注意してください。 また、この関数は演奏中だと失敗しますので、覚えておいてください。 今回は強制的に再生停止してあるのでそのような失敗は起きません。 ただし、他の理由(ファイルフォーマットがおかしい等)で、エラーコードを返す事もあります。
 やっと読みこみが終わったので、最後に MVPlayMusic 関数で曲を再生してから関数を抜けます。 MVPlayMusic 関数は読みこまれている曲データを再生します。引数はありません。

 さて、これで再生のための関数の準備は出来ましたので、あとは適所でこの関数を呼ぶだけです。 同梱のサンプルプログラムでは、ウィンドウを作成し終わった後、デバイスをオープンし、 プログラム終了直前にクローズしています。 また、マウス左クリックすると、ファイル名を指定して再生する事が出来ます。 その辺りはサンプルの『main.cpp』を参照してください。


3. その他の様々な機能

MusicVillage はただ再生するだけではなく、色々な工夫を施す事も出来ます。 詳しくは sdk.htm を参照してください。

(C) 2005 ドリームROM