Microsoft DirectX 8.0 (C++) |
コレクション オブジェクトを作成したり、コレクション ファイルやリソースからロードした場合、音色は特定のポートにバインドされない。異なる音色を異なるポートにダウンロードすることも、1 つの音色を複数のポートにダウンロードすることもできる。
IDirectMusicCollection8::EnumInstrument メソッドを使って、利用可能なすべての音色のパッチ番号および名前を取得できる。
次のサンプル コードは、コレクション内のすべての音色を列挙し、その名前とパッチ番号を表示している。
void myListInstruments( IDirectMusicCollection8 *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("Patch %lx is %S\n",dwPatch,wszName); } } }
IDirectMusicCollection8::GetInstrument メソッドに特定の音色のパッチ番号を渡して、特定の音色へのポインタを取得する。
音色を取得した後、IDirectMusicInstrument8::SetPatch メソッドを使ってパッチ番号を変更できる。
単一の音色をポートにダウンロードするには、IDirectMusicInstrument8 インターフェイス ポインタを IDirectMusicPort8::DownloadInstrument または IDirectMusicPerformance8::DownloadInstrument メソッドに渡す。この呼び出しは、ポートで DLS データを利用可能にする。音色を特定のパフォーマンスやオーディオパスに関連付けることはない。
メモリを節約するために、指定されたノートの範囲で必要なウェーブとアーティキュレーションだけがダウンロードされる。たとえば、バスーンを使う場合、低音の C から中間の B までのノート範囲に相当するデータだけをダウンロードするよう指定することがある。この範囲以外のリージョンのデータはダウンロードされない。
次のサンプル コードでは、指定されたコレクション、パッチ番号、ポート、およびノート範囲に対して、コレクションから音色を取得し、その音色をダウンロードしている。この関数は、1 つの DMUS_NOTERANGE 構造体から成る配列を作成し、この配列を IDirectMusicPort8::DownloadInstrument メソッドに渡す。一般的には、ノートの 1 つの範囲だけを指定するが、複数の範囲を指定することもできる。配列の代わりに NULL を渡すと、すべての範囲のデータがダウンロードされる。
HRESULT myDownload( IDirectMusicCollection8 *pCollection, // DLS コレクション IDirectMusicPort8 *pPort, // 転送先ポート IDirectMusicDownloadedInstrument8 **ppDLInstrument, DWORD dwPatch, // 要求された音色 DWORD dwLowNote, // 範囲内の低いノート DWORD dwHighNote) // 範囲内の高いノート { HRESULT hr; IDirectMusicInstrument8* 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; }
DownloadInstrument メソッドは、IDirectMusicDownloadedInstrument8 インターフェイスへのポインタを返す。このポインタの目的は、それ以降に IDirectMusicPort8::UnloadInstrument メソッドを呼び出すときに音色を識別することだけであり、このメソッドは特定のポートから音色インスタンスをアンロードする。
次の関数では、音色をダウンロードした後、アンロードしている。この例は、IDirectMusicDownloadedInstrument8 ポインタの使用方法を示すだけのものである。
HRESULT myFickleDownload( IDirectMusicInstrument8* pInstrument, IDirectMusicPort8 *pPort, DWORD dwPatch) { HRESULT hr; IDirectMusicDownloadedInstrument * pDLInstrument; hr = pPort->DownloadInstrument( pInstrument, &pDLInstrument, NULL, 0); if (SUCCEEDED(hr)) { pPort->UnloadInstrument(pDLInstrument); pDLInstrument->Release(); } return hr; }