midiOutCacheDrumPatches

	MMRESULT midiOutCacheDrumPatches(hMidiOut, wPatch, lpKeyArray, wFlags)
	HMIDIOUT hMidiOut;
	UINT wPatch;
	LPWORD lpKeyArray;
	UINT wFlags;

The midiOutCacheDrumPatches function requests that an internal MIDI synthesizer device preload a specified set of key-based percussion patches. Some synthesizers are not capable of keeping all percussion patches loaded simultaneously. Caching patches ensures specified patches are available.

Parameters

hMidiOut

Specifies a handle to the opened MIDI output device. This device should be an internal MIDI synthesizer.

wPatch

Specifies which drum patch number should be used. This parameter should be set to zero to cache the default drum patch.

lpKeyArray

Specifies a pointer to a KEYARRAY array indicating the key numbers of the specified percussion patches to be cached or uncached.

wFlags

Specifies options for the cache operation. Only one of the following flags can be specified:

Value

Meaning

MIDI_CACHE_ALL
	Cache all of the specified patches. If they can't all be cached, cache none, clear the KEYARRAY array,and return MMSYSERR_NOMEM.
MIDI_CACHE_BESTFIT
	Cache all of the specified patches. If all patches can't be cached, cache as many patches as possible, change the KEYARRAY array to reflect which patches were cached, and return MMSYSERR_NOMEM.
MIDI_CACHE_QUERY
	Change the KEYARRAY array to indicate which patches are currently cached.
MIDI_UNCACHE
	Uncache the specified patches and clear the KEYARRAY array.

Return Value

Returns zero if the function was successful. Otherwise, it returns one of the following error codes:

Value

Meaning

MMSYSERR_INVALHANDLE	The specified device handle is invalid.
MMSYSERR_NOTSUPPORTED	The specified device does not support patch caching.
MMSYSERR_NOMEM	The device does not have enough memory to cache all of the requested patches.

Comments

The KEYARRAY data type is defined as:

typedef UINT KEYARRAY[MIDIPATCHSIZE];

Each element of the array represents one of the 128 key-based percussion patches and has bits set for each of the 16 MIDI channels that use that particular patch. The least-significant bit represents physical channel 0; 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. Use the MIDICAPS_CACHE flag to test the dwSupport field of the MIDIOUTCAPS structure filled by midiOutGetDevCaps to see if the device supports patch caching.