Platform SDK: DirectX |
ここでは、C++ でのアプリケーション開発について説明する。DirectX for Visual Basic では、アプリケーションがコレクションの個々の音色を操作することはできない。
DirectMusicCollection を作成してコレクション ファイルからロードした後、IDirectMusicCollection::EnumInstrument メソッドを使って、利用可能なすべての音色のパッチ番号と名前を取り出せる。
次のコード例では、コレクション内のすべての音色を列挙し、その名前とパッチ番号を表示している。
void myListInstruments( IDirectMusicCollection *pCollection) { HRESULT hr = S_OK; DWORD dwPatch; WCHAR wszName[MAX_PATH]; DWORD dwIndex; for (dwIndex = 0; hr == S_OK; dwIndex++) { hr = pCollection->EnumInstrument( dwIndex, &dwPatch, wszName, MAX_PATH); if (hr == S_OK) { printf("パッチ %lx は、%S。\n",dwPatch,wszName); } } }
IDirectMusicCollection::GetInstrument メソッドに特定の音色のパッチ番号を渡すことにより、その音色へのポインタを取得できる。
音色を取得した後、IDirectMusicInstrument::SetPatch メソッドを使ってパッチ番号を変更できる。
コレクションをロードし、音色を取り出す作業は、音色を利用可能にするための最初のステップに過ぎない。次に、これらの音色をポートにダウンロードしなければならない。
音色をポートにダウンロードするには、IDirectMusicInstrument インターフェイス ポインタを IDirectMusicPort::DownloadInstrument メソッドに渡す。このメソッドは、ポートで DLS データを利用可能にする。音色を特定のパフォーマンスに関連付けることはない。
IDirectMusicPerformance::DownloadInstrument メソッドを使って、音色をダウンロードすることもできる。DLS データのダウンロードに加えて、このメソッドは音色を特定のパフォーマンス チャンネルに割り当てる。
メモリを節約するために、指定された音符の範囲で必要なウェーブとアーティキュレーションだけがダウンロードされる。たとえば、バスーンを使う場合、低音の C から中間の B までの音符範囲に相当するデータだけをダウンロードするよう指定することがある。その範囲内のリージョン のデータだけをダウンロードすべきである。
次のコード例では、指定されたコレクション、パッチ番号、ポート、および音符範囲に対して、コレクションから音色を取り出し、その音色をダウンロードしている。この関数は、1 つの DMUS_NOTERANGE 構造体からなる配列を作成し、この配列を IDirectMusicPort::DownloadInstrument メソッドに渡す。一般的には、音符の 1 つの範囲だけを指定するが、複数の範囲を指定することもできる。配列へのポインタの代わりに NULL を渡すと、すべての範囲のデータがダウンロードされる。
HRESULT myDownload( IDirectMusicCollection *pCollection, // DLS コレクション IDirectMusicPort *pPort, // ダウンロード先ポート IDirectMusicDownloadedInstrument **ppDLInstrument, DWORD dwPatch, // 要求された音色 DWORD dwLowNote, // 音符範囲の下限の音符 DWORD dwHighNote) // 音符範囲の上限の音符 { HRESULT hr; IDirectMusicInstrument* pInstrument; hr = pCollection->GetInstrument(dwPatch, &pInstrument); if (SUCCEEDED(hr)) { DMUS_NOTERANGE NoteRange[1]; // オプションの音符範囲 NoteRange[0].dwLowNote = dwLowNote; NoteRange[0].dwHighNote = dwHighNote; hr = pPort->DownloadInstrument(pInstrument, ppDLInstrument, NoteRange, // 範囲の配列 1); // 配列内の要素数 pInstrument->Release(); } return hr; }
Download メソッドは、IDirectMusicDownloadedInstrument インターフェイスへのポインタを返す。このポインタの目的は、それ以降に IDirectMusicPort::UnloadInstrument メソッドを呼び出すときに音色を識別することだけであり、このメソッドは特定のポートから音色インスタンスをアンロードする (DirectMusicCollection は、特定のポートにバインドされない。異なる音色を異なるポートにダウンロードすることも、1 つの音色を複数のポートにダウンロードすることもできる)。
次のコード例では、音色をダウンロードした後、アンロードしている。この例は、IDirectMusicDownloadedInstrument ポインタの使用方法を示している。
HRESULT myFickleDownload( IDirectMusicInstrument* pInstrument, IDirectMusicPort *pPort, DWORD dwPatch) { HRESULT hr; IDirectMusicDownloadedInstrument * pDLInstrument; hr = pPort->DownloadInstrument( pInstrument, &pDLInstrument, NULL, 0); if (SUCCEEDED(hr)) { pPort->UnloadInstrument(pDLInstrument); pDLInstrument->Release(); } return hr; }
IDirectMusicBand::Download メソッドは、バンド内のすべての音色を自動的にダウンロードする。開発者がパフォーマンスへのポインタを渡すだけで、このメソッドはそのパフォーマンスに付加された適切なポートに各音色をダウンロードする。