Microsoft DirectX 8.0 (C++) |
ツールとは、メッセージを途中で取得して、何らかの方法で処理するオブジェクトを意味する。ツールはメッセージに変更を加えて次のツールに渡すか、メッセージを解放するか、元のメッセージ内の情報に基づいて新しいメッセージを送信するか、いずれかの方法で処理を行うことができる。
DirectMusic には出力ツールがあり、通常はこのツールが最後にメッセージを受け取る。このツールは、パフォーマンス メッセージをスタンダード MIDI メッセージに変換し、シンセサイザへのストリームに入れる。ほかのツールは、アプリケーションによって実装するか、ライブラリから取得する。
ツールを実装するには、IDirectMusicTool8 インターフェイスをサポートするオブジェクトを作成しなければならない。IDirectMusicTool8 メソッドのオブジェクト実装により、このツールがどのメッセージを取得するか、およびそのメッセージにどのような作業を行うかを決定する。
出力ツール以外のすべてのツールは、ツールグラフにまとめられる。アプリケーションがほかのツールを 1 つしか使わない場合でも、そのツールを含むツールグラフを作成しなければならない。次に、そのツールグラフをセグメントかパフォーマンスに追加する。ツールグラフは、ツール間でメッセージを転送する際に有効なメカニズムである。
パフォーマンス エンジンがセグメントを演奏するときに、セグメント ツールグラフ内の各ツール、次いでパフォーマンス ツールグラフ内の各ツールが、各メッセージを処理できる。あるツールがメッセージを処理した後、そのツールは DMUS_PMSG 構造体の pGraph メンバから IDirectMusicGraph8 ポインタを取得し、次にそのメッセージを受け取るツールがある場合は、IDirectMusicGraph8::StampPMsg メソッドを呼び出してそのツールへのポインタをメッセージにスタンプする。
ツールは、優先順位の高いスレッドでメッセージを処理する。ツールの IDirectMusicTool8::ProcessPMsg メソッド内では、グラフィックスやファイル入出力などを行う時間のかかる関数を呼び出さないようにする。ツールがアクションをトリガする必要がある場合は、アプリケーションのメイン スレッドなどの別のスレッドに通知して実行する。
IDirectMusicTool8 のメソッドを実装するときに、親オブジェクトへの循環参照を作成しないように注意する。循環参照は、あるオブジェクトがほかのオブジェクトを作成したときに、子オブジェクトが親オブジェクトへの参照を維持している場合に発生する。たとえば、ツールが、IDirectMusicTool8::Init メソッドに渡される、ツールグラフへの新しい参照を作成する場合を考える。ツールがこの参照を解放できない場合、セグメントがツールグラフを解放しようとしたときに問題が発生する。ツールにはツールグラフへの参照が残っているため、ツールグラフが完全に解放されない。また、ツールグラフにはツールへの参照があるため、ツールも解放されない。
ツールの実装方法の例については、「MusicTool サンプル アプリケーション」を参照すること。