Platform SDK: DirectX

DirectMusic ツール

DirectMusic におけるツールとは、メッセージを途中で取得して、何らかの方法で処理するオブジェクトを意味する。ツールはメッセージに変更を加えて次のツールに渡すか、メッセージを解放するか、元のメッセージ内の情報に基づいて新しいメッセージを送信するか、いずれかの方法で処理を行える。

DirectMusic には出力ツールがあり、通常はこのツールが最後にメッセージを受け取る。このツールは、パフォーマンス メッセージをスタンダード MIDI メッセージに変換し、シンセサイザへのストリームに入れる。ほかのツールは、アプリケーションによって実装するか、ライブラリから取得する。

[Visual Basic]

DirectX for Visual Basic では、アプリケーション定義のツール、またはサードパーティ製のツールはサポートされない。

[C++]

ツールを実装するには、IDirectMusicTool インターフェイスをサポートするオブジェクトを作成しなければならない。IDirectMusicTool メソッドのオブジェクト実装により、このツールがどのメッセージを取得するか、およびそのメッセージにどのような作業を行うかを決定する。

通常、出力ツール以外のすべてのツールはグラフに収集される。アプリケーションが、出力ツール以外に 1 つしかツールを使用していない場合でも、これを含めるための DirectMusicGraph を作成する。次に、そのグラフをセグメントかパフォーマンスに追加する。グラフは、ツール間でメッセージを転送する際に有効なメカニズムである。

パフォーマンス エンジンがセグメントを演奏するときに、セグメント グラフ内の各ツール、次いでパフォーマンス グラフ内の各ツールが、各メッセージを処理できる。あるツールがメッセージを処理した後、そのツールは IDirectMusicGraph::StampPMsg メソッドを呼び出し (DMUS_PMSG 構造体の pGraph メンバから IDirectMusicGraph ポインタを取得する)、次にそのメッセージを受け取るツールがある場合は、そのツールへのポインタをメッセージにスタンプする。次いで、このツールはメッセージをパイプラインへ返す。

ツールは、優先順位の高いスレッドでメッセージを処理する。ツールの IDirectMusicTool::ProcessPMsg メソッド内では、グラフィックスやファイル入出力などを行う時間のかかる関数を呼び出さないようにする。ツールがアクションをトリガする必要がある場合は、アプリケーションのメイン スレッドなどの別のスレッドに通知して実行する。

IDirectMusicTool のメソッドを実装するときに、親オブジェクトへの循環参照を作成しないように注意する。循環参照は、あるオブジェクトがほかのオブジェクトを作成したときに、子オブジェクトが親オブジェクトへの参照を維持している場合に発生する。たとえばツールが、IDirectMusicTool::Init メソッドに渡される、グラフへの新しい参照を作成する場合を考える。ツールがこの参照を解放できない場合、セグメントがグラフを解放しようとしたときに問題が発生する。ツールにはグラフへの参照が残っているため、グラフが完全に解放されない。また、グラフにはツールへの参照があるため、ツールも解放されない。

ツールの設定方法の詳細については、「チュートリアル 2 : ツールの使い方」を参照すること。