Loading and Downloading Collections

Collections are loaded like other objects. For more information, see Loading Audio Data.

To load the standard GM/GS set, pass GUID_DefaultGMCollection to the loader in the guidObject member of the DMUS_OBJECTDESC structure. If you intend to use the loader to access this object more than once, make sure that caching is enabled (as it is by default) so that you don't create another copy of the GM collection each time you request it.

Note   The GM/GS Sound Set cannot be altered. For more information, see the Legal Information at the beginning of this Help.

The following code example illustrates how to load a collection identified by its GUID:

HRESULT myGetGMCollection(
    IDirectMusicLoader8 *pILoader, 
    IDirectMusicCollection8 **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_IDirectMusicCollection8,
    (void **) ppICollection);
  return hr;
}

Once you have obtained a pointer to the IDirectMusicCollection8 interface, you have access to all the instruments in the collection. At this point, though, none of them have been downloaded to a port.

To download an entire collection at once, you must associate the collection with a segment and then call the IDirectMusicSegment8::Download method. For an example, see Playing a MIDI File with Custom Instruments.

These steps are necessary only when you want to use a collection other than the default one. Normally, when you call IDirectMusicSegment8::Download, the instruments downloaded to the port are from the default collection authored into the segment, or from the General MIDI set if the segment does not reference a collection. When you download a band, all DLS data needed by the instruments in that band is downloaded. See Using Bands.