Loading and Downloading Collections

Collections are loaded like other objects. To load the standard Roland 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.

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

HRESULT myGetGMCollection(
    IDirectMusicLoader8 *pLoader, 
    IDirectMusicCollection8 **ppCollection)
{
  HRESULT hr;
  DMUS_OBJECTDESC desc;
 
  if ((NULL == pLoader) || (NULL == ppCollection)) return E_INVALIDARG;
  desc.dwSize = sizeof(DMUS_OBJECTDESC);
  desc.guidClass = CLSID_DirectMusicCollection;
  desc.guidObject = GUID_DefaultGMCollection;
  desc.dwValidData = (DMUS_OBJ_CLASS | DMUS_OBJ_OBJECT);
  hr = pLoader->GetObject(&desc, IID_IDirectMusicCollection8,
          (void **) ppCollection);
  return hr;
}

When 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 Also

• Loading Audio Data
• Using Bands