IDirectMusicPort::DownloadInstrument

The IDirectMusicPort::DownloadInstrument method is used to download an instrument to the DLS device. Downloading an instrument is the process of handing to the DLS device the data that makes up the instrument. This includes articulation data and all waves needed by the instrument. To economize on wave space, only waves and articulation required for a range are downloaded. The method returns an IDirectMusicDownloadedInstrument interface pointer, which is later used to unload the instrument.

HRESULT DownloadInstrument(
  IDirectMusicInstrument *pInstrument,
  IDirectMusicDownloadedInstrument **ppDownloadedInstrument,
  DMUS_NOTERANGE *pNoteRanges,
  DWORD dwNumNoteRanges;
  );
 

Parameters

pInstrument

Pointer to the instrument from which the method extracts the data to be downloaded.

ppDownloadedInstrument

Address of a variable to receive a pointer to the IDirectMusicDownloadedInstrument interface.

pNoteRanges

Array of DMUS_NOTERANGE structures. Each entry in the array specifies a contiguous range of MIDI note messages to which the instrument must respond. An instrument region will be downloaded only if at least one note in that region is specified in the DMUS_NOTERANGE structures.

dwNumNoteRanges

Number of DMUS_NOTERANGE structures in the array pointed to by pNoteRanges. If this value is set to 0, the pNoteRanges parameter is ignored and all regions and wave data for the instrument are downloaded.

Return Values

If the method succeeds, the return value is S_OK.

If it fails, the method may return one of the following error values:

Remarks

To prevent memory loss, the instrument must be unloaded by calling both IDirectMusicPort::UnloadInstrument and IDirectMusicDownloadedInstrument::Release when it is no longer needed.

See Also

IDirectMusicPort::Compact, Working with Instruments

QuickInfo

  Windows NT/2000: Requires Windows 2000.
  Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
  Header: Declared in dmusicc.h.