Platform SDK: DirectX |
ファイルからコレクションをロードする最も簡単な方法は、IDirectMusicLoader インターフェイスを使うことである (詳細については、「ファイルからのオブジェクトのロード」を参照すること)。IDirectMusicCollection インターフェイスへのポインタを取得すると、コレクション内のすべての音色にアクセスできる。ただし、この時点では、実際には音色はポートにダウンロードされていない。音色データは、必要になるまでメモリにロードされない。
コレクションは、IDirectMusicCollection、IDirectMusicObject、IPersistStream の各インターフェイスをサポートする COM オブジェクトである。IPersistStream は、標準的な COM インターフェイスであり、記憶の目的で単純なシリアル ストリームを使って、オブジェクトの保存とロードを行うメソッドを提供する。
IPersistStream::Load を呼び出した時点では、IDirectMusicCollection はコレクション全体をロードすることはない。通常、IPersistStream をサポートするオブジェクトは永続的なデータすべてをストリームにロードし、Load メソッドの外部で IStream ポインタを使わない。しかし、IDirectMusicCollection 内でこの方法により IPersistStream::Load をサポートすると、コレクション内のただ 1 つの音色を使う場合でも、DLS コレクション全体をメモリにロードしなければならない。代わりに、IDirectMusicCollection は IStream ポインタを保存し、後でそのポインタを使って、DirectMusic のポートにダウンロードすべき音色のデータをロードする。IDirectMusicCollection は、IPersistStream インターフェイス経由で提供されるデータ ストリームが DLS ファイル形式であると想定している。
次のコード例では、IDirectMusicLoader::GetObject メソッドが自動的に実行する処理を、手作業で行っている。コレクション オブジェクトを作成し、ストリームをそのオブジェクトにロードする。
HRESULT myLoadCollectionFromStream( IStream *pIStream, // ファイルから作成したストリーム IDirectMusicCollection **ppICollection ) { HRESULT hr; hr = CoCreateInstance(CLSID_DirectMusicCollection, NULL, CLSCTX_INPROC, IID_IDirectMusicCollection, (void **)ppICollection); if (SUCCEEDED(hr)) { IPersistStream* pIPersistStream; hr = *ppICollection->QueryInterface( IID_IPersistStream, (void**)&pIPersistStream); if (SUCCEEDED(hr)) { hr = pIPersistStream->Load(pIStream); pIPersistStream->Release(); } } return hr; }
次のコード例では、DirectMusicLoader を使って、ファイル名を指定してコレクションをロードしている。
HRESULT myLoadCollectionByName( IDirectMusicLoader *pILoader, char *pszFileName, IDirectMusicCollection **ppICollection) { HRESULT hr; DMUS_OBJECTDESC Desc; // ディスクリプタ // 最初にファイル名とコレクション オブジェクトの GUID を // 指定して、Desc を初期化する。 // ファイル名は最初、char 文字列になっているので、 // Unicode に変換する。 mbstowcs(Desc.wszFileName,pszFileName,DMUS_MAX_FILENAME); Desc.dwSize = sizeof(DMUS_OBJECTDESC); Desc.guidClass = CLSID_DirectMusicCollection; Desc.dwValidData = DMUS_OBJ_CLASS | DMUS_OBJ_FILENAME | DMUS_OBJ_FULLPATH; hr = pILoader->GetObject(&Desc, IID_IDirectMusicCollection, (void **) ppICollection); return hr; }
標準的な GM/GS セットをロードするために、DMUS_OBJECTDESC 構造体の guidObject メンバに、ローダーへのパス GUID_DefaultGMCollection を設定する。ローダーを使ってこのオブジェクトに何度もアクセスする場合は、キャッシングが有効になっていることを確認し (デフォルトの設定)、GM コレクションを要求するたびにコピーが 1 つ作成されることを防止する。
注 : GM/GS Sound Set を変更することはできない。詳細については、「法的情報」の「著作権に関する注意」を参照すること。
次のコード例は、GUID によって識別されるコレクションをロードする方法を示している。
HRESULT myGetGMCollection( IDirectMusicLoader *pILoader, IDirectMusicCollection **ppICollection) { HRESULT hr; DMUS_OBJECTDESC desc; desc.dwSize = sizeof(DMUS_OBJECTDESC); desc.guidClass = CLSID_DirectMusicCollection; desc.guidObject = GUID_DefaultGMCollection; desc.dwValidData = (DMUS_OBJ_CLASS | DMUS_OBJ_OBJECT); hr = pILoader->GetObject(&desc, IID_IDirectMusicCollection, (void **) ppICollection); return hr; }
音色コレクションをロードするには、DirectMusicLoader.LoadCollection または DirectMusicLoader.LoadCollectionFromResource メソッドを呼び出す。これらのメソッドは、DirectMusicCollection オブジェクトを返す。このオブジェクトにはメソッドがなく、DirectMusicSegment.ConnectToCollection へのパラメータとしてのみ機能する。このメソッドを呼び出してコレクションをセグメントに関連付けた後、DirectMusicSegment.Download を呼び出して音色をダウンロードする。
これらの手順は、デフォルト以外のコレクションを使用する場合にのみ必要となる。セグメントにカスタム コレクションが含まれていない場合、またはセグメントが MIDI ファイルの場合、通常は DirectMusicSegment.Download を呼び出すときに、セグメント中にオーサリングされたデフォルト コレクションの音色、またはGeneral MIDI セットの音色がポートにダウンロードされる。バンドをダウンロードするときに、そのバンドの音色で必要なすべての DLS データがダウンロードされる。「バンドの使い方」を参照すること。