Miles Sound System SDK 7.2a

AIL_protect_timbre

The function AIL_protect_timbre prevents the timbre bank, patch from being discarded from the synthesizer memory or local timbre cache.

void AIL_protect_timbre(
  HMDIDRIVER mdi,
  S32 bank,
  S32 patch
);

In Parameters

mdi: indicates the driver for which timbre protection is to be enabled.
bank: specifies the XMIDI Patch Bank Select (controller 114) value associated with the desired timbre.
patch: specifies the MIDI Program Change value associated with the desired timbre.

Discussion

If the synthesizer memory or local timbre cache does not contain sufficient space for a timbre to be installed by AIL_init_sequence or AIL_install_timbre, one or more least-recently-used timbres (the timbres least recently used to play notes) may be discarded from the cache to make room. AIL_protect_timbre and AIL_unprotect_timbre provide a means of protecting a given timbre against deletion, and of removing such protection, respectively. (Neither function will have any immediate effect on the contents of the timbre cache.)

Timbres installed by AIL_init_sequence or AIL_install_timbre are "unprotected" by default. Timbre protection may be useful in cases where it is desirable to play little-used sound-effect or music sequences at widely varying intervals during the course of an application, while avoiding the delay associated with loading and transmitting their custom timbres. Excessive use of timbre protection may give rise to "logjams" in the timbre cache.

If both the bank and the patch parameters are equal to -1, the AIL_protect_timbre and AIL_unprotect_timbre functions will protect or unprotect all timbres in the cache.

The action of these functions is analogous to the Extended MIDI Control Change event 113 (Timbre Protect).

The current version of the Windows and MacOS system does not support custom MIDI instruments. The default MIDI instrument set used by the selected midiOut driver will be used instead.

Group: XMIDI Services
Related Sections: XMIDI Timbre Protect (113)
Related Functions: AIL_init_sequence, AIL_install_timbre, AIL_protect_timbre, AIL_timbre_status, AIL_unprotect_timbre
Related Basic Types: HMDIDRIVER, S32, void