Miles Sound System SDK 7.2a

AIL_register_prefix_callback

The function AIL_register_prefix_callback registers an application function to be called whenever an XMIDI Callback Prefix controller (108) is encountered in a playing XMIDI sequence.

AILPREFIXCB AIL_register_prefix_callback(
  HSEQUENCE S,
  AILPREFIXCB callback
);

In Parameters

S

indicates the sequence with which the Callback Prefix function is to be associated.

callback

should be set to the address of an application function which is prototyped as follows:

S32 AILCALLBACK foo(HSEQUENCE sequence, S32 channel, S32 value)

where sequence and channel will indicate the sequence handle and logical channel number in which the XMIDI Callback Prefix controller appeared; and value will receive the Callback Prefix controller's value as it appeared in the XMIDI sequence. The callback function should return a value from 0 to 127, which is used instead of the value for the next MIDI or XMIDI controller event which occurs in the same sequence and MIDI channel.

Returns

The address of the previously-installed Callback Prefix function handler.

Discussion

The XMIDI Callback Prefix controller can help implement an almost infinite variety of interactive MIDI music effects. Its use is similar to the XMIDI Indirect Controller Prefix controller (115). However, instead of overriding the value of the next MIDI/XMIDI controller with an entry from the Indirect Controller Array table, the Callback Prefix controller invokes a user callback function, passing its own sequence, channel number, and controller value to the application. The callback function may take any action permitted to interrupt-based callback function handlers, including calling most XMIDI API functions. The user function's return value replaces the value of the next MIDI/XMIDI controller event occurring in its channel.

It is possible to use the value returned from the Callback Prefix function to override the values of XMIDI controllers such as Sequence Branch (109) or For...Next/Break (116/117). More conventional MIDI controllers such as Part Volume (7), Panpot (10), or Reverb (91) can also be altered interactively.

Most MSS functions can be safely invoked from within callback functions. Exceptions include driver-installation or driver-shutdown functions and any other functions which may perform DOS or BIOS calls, such as AIL_init_sequence. These exceptions are noted in the descriptions of the functions involved. If in doubt about whether a particular action may safely be performed from within a callback function, contact RAD Game Tools for assistance.

Group: XMIDI Services
Related Sections: XMIDI Callback Prefix (108)
Related Functions: AILPREFIXCB, AIL_init_sequence, AIL_register_beat_callback, AIL_register_event_callback, AIL_register_sequence_callback, AIL_register_timbre_callback, AIL_register_trigger_callback
Related Basic Types: HSEQUENCE
Related FAQs: What's the deal with callbacks - are they threads, interrupts, system timers, or what?