IDirectMusicPort8::DownloadInstrument
The DownloadInstrument method downloads an instrument to the DLS device. Downloading an instrument means handing the data that makes up the instrument to the DLS device. This includes articulation data and all waveforms needed by the instrument. To conserve resources, only waveforms and articulation required for a range are downloaded. The method returns an IDirectMusicDownloadedInstrument8 interface pointer, which is later used to unload the instrument.
Syntax
HRESULT DownloadInstrument(
IDirectMusicInstrument* pInstrument,
IDirectMusicDownloadedInstrument** ppDownloadedInstrument,
DMUS_NOTERANGE* pNoteRanges,
DWORD dwNumNoteRanges;
);
Parameters
pInstrument
Pointer to the IDirectMusicInstrument8 interface of the instrument whose data is downloaded.
ppDownloadedInstrument
Address of a variable that receives a pointer to the IDirectMusicDownloadedInstrument8 interface.
pNoteRanges
Address of an 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 is 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 waveform data for the instrument are downloaded.
Return Values
If the method succeeds, the return value is S_OK.
If it fails, the method can return one of the error values shown in the following table.
| Return code |
| E_POINTER |
| E_OUTOFMEMORY |
| E_NOTIMPL |
Remarks
To prevent memory loss, the instrument must be unloaded by calling both IDirectMusicPort8::UnloadInstrument and IDirectMusicDownloadedInstrument8::Release when it is no longer needed.
Requirements
** Header:** Dmusicc.h
See Also