midiOutCacheDrumPatches
The midiOutCacheDrumPatches function requests that an internal MIDI synthesizer device preload and cache a specified set of key-based percussion patches.
MMRESULT midiOutCacheDrumPatches(
HMIDIOUT hmo,
UINT wPatch,
WORD * lpKeyArray,
UINT wFlags
);
Parameters
hmo
Handle to the opened MIDI output device. This device should be an internal MIDI synthesizer. This parameter can also be the handle of a MIDI stream, cast to HMIDIOUT.
wPatch
Drum patch number that should be used. This parameter should be set to zero to cache the default drum patch.
lpKeyArray
Pointer to a KEYARRAY array indicating the key numbers of the specified percussion patches to be cached or uncached.
wFlags
Options for the cache operation. It can be one of the following flags.
| Value | Meaning |
| MIDI_CACHE_ALL | Caches all of the specified patches. If they cannot all be cached, it caches none, clears the KEYARRAY array, and returns MMSYSERR_NOMEM. |
| MIDI_CACHE_BESTFIT | Caches all of the specified patches. If they cannot all be cached, it caches as many patches as possible, changes the KEYARRAY array to reflect which patches were cached, and returns MMSYSERR_NOMEM. |
| MIDI_CACHE_QUERY | Changes the KEYARRAY array to indicate which patches are currently cached. |
| MIDI_UNCACHE | Uncaches the specified patches and clears the KEYARRAY array. |
Return Values
Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following.
| Value | Description |
| MMSYSERR_INVALFLAG | The flag specified by wFlags is invalid. |
| MMSYSERR_INVALHANDLE | The specified device handle is invalid. |
| MMSYSERR_INVALPARAM | The array pointed to by the lpKeyArray array is invalid. |
| MMSYSERR_NOMEM | The device does not have enough memory to cache all of the requested patches. |
| MMSYSERR_NOTSUPPORTED | The specified device does not support patch caching. |
Remarks
Some synthesizers are not capable of keeping all percussion patches loaded simultaneously. Caching patches ensures that the specified patches are available.
Each element of the KEYARRAY array represents one of the 128 key-based percussion patches and has bits set for each of the 16 MIDI channels that use the particular patch. The least-significant bit represents physical channel 0, and the most-significant bit represents physical channel 15. For example, if the patch on key number 60 is used by physical channels 9 and 15, element 60 would be set to 0x8200.
This function applies only to internal MIDI synthesizer devices. Not all internal synthesizers support patch caching. To see if a device supports patch caching, use the MIDICAPS_CACHE flag to test the dwSupport member of the MIDIOUTCAPS structure filled by the midiOutGetDevCaps function.
Requirements
** Windows NT/2000/XP:** Included in Windows NT 3.1 and later.
** Windows 95/98/Me:** Included in Windows 95 and later.
** Header:** Declared in Mmsystem.h; include Windows.h.
** Library:** Use Winmm.lib.
See Also
Musical Instrument Digital Interface (MIDI), MIDI Functions, KEYARRAY, MIDIOUTCAPS, midiOutGetDevCaps