IDirectMusicPerformance8::DownloadInstrument

DirectMusic

Microsoft DirectX 9.0 SDK Update (Summer 2004)

^{IDirectMusicPerformance8::DownloadInstrument}

The DownloadInstrument method downloads DLS instrument data to a port.

Syntax

HRESULT DownloadInstrument(
  IDirectMusicInstrument* pInst,
  DWORD dwPChannel,
  IDirectMusicDownloadedInstrument** ppDownInst,
  DMUS_NOTERANGE* pNoteRanges, 
  DWORD dwNumNoteRanges, 
  IDirectMusicPort** ppPort,
  DWORD* pdwGroup,
  DWORD* pdwMChannel
);

Parameters

pInst

Pointer to the IDirectMusicInstrument8 interface of the instrument to download.

dwPChannel

Performance channel to which the instrument is assigned.

ppDownInst

Address of a variable that receives an IDirectMusicDownloadedInstrument8 pointer to the downloaded instrument.

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 are downloaded.

ppPort

Address of a variable that receives a pointer to the port to which the instrument was downloaded.

pdwGroup

Address of a variable that receives the channel group to which the instrument was assigned.

pdwMChannel

Address of a variable that receives the MIDI channel to which the instrument was assigned.

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_INVALIDARG

E_POINTER

Remarks

Most applications do not need to use this method, because instrument downloading is normally handled by bands.

The method returns E_INVALIDARG if the performance channel is not assigned to a port.

To prevent loss of resources, unload the instrument by using the IDirectMusicPort8::UnloadInstrument method when the instrument is no longer needed.

Requirements

Header: Declared in dmusici.h.

See Also

previous page start next page