Manually Downloading Bands

You can manually download a band in one of the following ways:

• Call IDirectMusicSegment8::Download to download the bands and waves in a segment to either an audiopath or a performance.
• Obtain an IDirectMusicBand8 interface from a loaded object, and call the IDirectMusicBand8::Download method.
• Call the IDirectMusicSegment8::SetParam method with the GUID_Download or GUID_DownloadToAudioPath parameter to download the band in the segment's first band track. You can also use IDirectMusicPerformance8::SetParam to set this parameter on the primary segment, or IDirectMusicTrack8::SetParamEx to set it directly on a band track. See Setting and Retrieving Track Parameters.

If your application creates audiopaths that use more than one synthesizer, or port, you must download bands to the individual audiopaths, not to the performance. However, most applications use only a single synthesizer, and it is safe to download all instrument data to the performance.

Multiple audiopaths usually share the same synthesizer. When a band is downloaded to an audiopath, the instrument data is downloaded to the port on that audiopath and is then available to any audiopath using the same port. The data does not have to be downloaded to each audiopath.

For example, suppose you have a segment that uses a DLS instrument for the sound of a car engine in a race game. To manipulate the 3-D parameters independently for each car in the race, you play the sound on multiple audiopaths. The instrument has to be downloaded only once.

There is no danger in downloading the same instrument multiple times. If an instrument appears in one band multiple times or if it appears in multiple bands that are all opened and downloaded at the same time, only one copy of the instrument is sent to the synthesizer.

The following function loads a band from disk and downloads it to the performance:

HRESULT myDownloadBand(
  IDirectMusicLoader8 *pILoader,  // Loader interface.
  IDirectMusicBand8 **ppBand,   // To retrieve pointer.
  IDirectMusicPerformance8 *pPerf,  // Performance to use band.
  WCHAR *pwszFile)        // File to load.
{
  HRESULT hr;
  DMUS_OBJECTDESC Desc;
 
  // Start by initializing Desc with the file name 
  // and GUID for the band object.
 
  wcscpy(Desc.wszFileName,pwszFile);
  Desc.dwSize = sizeof(Desc);
  Desc.guidClass = CLSID_DirectMusicBand; 
  Desc.dwValidData = DMUS_OBJ_CLASS | 
    DMUS_OBJ_FILENAME | DMUS_OBJ_FULLPATH;
 
  hr = pILoader->GetObject(&Desc, IID_IDirectMusicBand8,
    (void **) ppBand);
  if (SUCCEEDED(hr))
  {
    hr = (*ppBand)->Download(pPerf);
  }
  return hr;
}