IDirectMusicCollection::GetInstrument

The IDirectMusicCollection::GetInstrument method retrieves an instrument from a collection by its patch number.

HRESULT GetInstrument(
  DWORD dwPatch,
  IDirectMusicInstrument** ppInstrument
);

Parameters

dwPatch
Instrument patch number.
ppInstrument
Address of a variable to receive a pointer to the IDirectMusicInstrument interface.

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:

DMUS_E_INVALIDPATCH
E_FAIL
E_OUTOFMEMORY
E_POINTER

Remarks

The patch number passed in dwPatch describes the full patch address, including the MIDI parameters for MSB and LSB bank select. MSB is shifted left 16 bits and LSB is shifted left 8 bits. For more information, see MIDI Channel Messages.

In addition, the high bit must be set (0x80000000) if the instrument is specifically a drum kit, intended to be played on MIDI channel 10. Note that this a special tag for DLS Level 1, which always puts drums on MIDI channel 10.

For an example of how this method is used, see 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.