Miles Sound System SDK 7.2a

AIL_install_timbre

The function AIL_install_timbre forces the driver to install a single timbre (synthesizer instrument), allowing it to be used for performance in a channel of an Extended MIDI (XMIDI) sequence which contains an XMIDI Patch Bank Select controller (114) with the value bank followed by a MIDI Program Change (Patch) message with the value patch.

S32 AIL_install_timbre(
  HMDIDRIVER mdi,
  S32 bank,
  S32 patch
);

In Parameters

mdi: indicates the driver for whose device the timbre is to be installed.
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.

Returns

0 if the specified timbre was not found in the library or could not be installed; otherwise, 1.

Discussion

This function causes the driver to search its Global Timbre Library (GTL) file or a proprietary instrument file for the desired timbre, and load it into the synthesizer's memory or a local timbre cache if it is not already installed.

By default, MSS 2.X-compatible Global Timbre Library files are loaded by the driver from the current working directory at the time AIL_init_sequence or AIL_install_timbre is called. If this is undesirable, the AIL_set_redist_directory function may be used to specify a DOS directory path to be used as part of the timbre filename prefix string.

Assuming a timbre in a given bank has been uploaded through the use of this function, subsequent MIDI Program Change messages for the specified patch will "call up" the timbre which was installed for the patch number patch and current XMIDI Patch Bank Select controller (114) bank.

Synthesizers with built-in (ROM) General MIDI instruments, such as the Roland Sound Canvas, will select their built-in timbre for the specified patch when attempting to install an external timbre in bank 0. This is because the 128 possible timbres in bank 0 are always mapped directly to the synthesizer's built-in instrument timbres, and cannot be externally installed. Bank 127 is unusable by the Roland driver for a similar reason; this bank is used only on the Ad Lib and other synthesizers to map rhythm key numbers to custom timbre "patches."

Most application programs will not need to call AIL_install_timbre.

Under DOS, this function must not be invoked from an interrupt-based callback function.

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: DDK Function: 503H Install Timbre Set
Related Functions: AIL_init_sequence, AIL_install_timbre, AIL_protect_timbre, AIL_set_GTL_filename_prefix, AIL_set_redist_directory, AIL_timbre_status, AIL_unprotect_timbre
Related Basic Types: HMDIDRIVER, S32