MMRESULT midiOutCachePatches(hMidiOut, wBank, lpPatchArray, wFlags) | |||
HMIDIOUT hMidiOut; | |||
UINT wBank; | |||
LPWORD lpPatchArray; | |||
UINT wFlags; |
The midiOutCachePatches function requests that an internal MIDI synthesizer device preload a specified set of patches. Some synthesizers are not capable of keeping all patches loaded simultaneously and must load data from disk when they receive MIDI program change messages. Caching patches ensures specified patches are immediately available.
hMidiOut
Specifies a handle to the opened MIDI output device. This device must be an internal MIDI synthesizer.
wBank
Specifies which bank of patches should be used. This parameter should be set to zero to cache the default patch bank.
lpPatchArray
Specifies a pointer to a PATCHARRAY array indicating the 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 PATCHARRAY 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 PATCHARRAY array to reflect which patches were cached, and return MMSYSERR_NOMEM. | ||
MIDI_CACHE_QUERY | ||
Change the PATCHARRAY array to indicate which patches are currently cached. | ||
MIDI_UNCACHE | ||
Uncache the specified patches and clear the PATCHARRAY array. |
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. |
The PATCHARRAY data type is defined as:
typedef UINT PATCHARRAY[MIDIPATCHSIZE];
Each element of the array represents one of the 128 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 (0x0F). For example, if patch 0 is used by physical channels 0 and 8, element 0 would be set to 0x0101.
This function only applies 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.
midiOutCacheDrumPatches