Miles Sound System SDK 7.2a

AIL_branch_index

The function AIL_branch_index moves a sequence's data pointers to the location of a specified XMIDI Sequence Branch Index controller.

void AIL_branch_index(
  HSEQUENCE S,
  U32 marker
);

In Parameters

S: indicates the sequence to branch.
marker: is the XMIDI Sequence Branch Index controller value which specifies the branch target.

Discussion

You can also use the AIL_set_sequence_ms_position function to adjust a sequence's playback position.

An XMIDI Sequence Branch Index event is defined by an Extended MIDI controller of type 120 (78h). As MIDI input files are converted into XMIDI sequence files, the location of every Sequence Index event in a special IFF "private chunk" is recorded for quick reference by the AIL_branch_index function.

Up to 128 Sequence Branch Index events, with controller values from 0 to 127, may appear in each XMIDI sequence. If a given Sequence Branch Index marker_number appears in more than one track in the original MIDI file, the conversion process will terminate with an error message.

When a sequence's pointers are adjusted by this function, any active Sustain (Hold1) controllers are not released. Therefore, "stuck notes" are a possibility unless care is taken to make sure all sustain controllers are released before or after this function is called. No controller values (volume, panpot, pitch, etc.) are affected, so it is advisable to follow each Sequence Branch Index event with MIDI events which reset all relevant MIDI controllers to reasonable values for that point in the sequence.

Normally, Sequence Branch Index events should be placed on beat or measure boundaries in the MIDI sequence, and the AIL_branch_index function should be called immediately after a new beat or measure begins (as reported by AIL_sequence_position ). Synchronizing branches in this way will ensure that future calls to AIL_sequence_position return meaningful values for sequences in which branches have been taken. Another way to ensure the accuracy of beat and measure count values is to embed an XMIDI Control Change event with a controller type of 118 (76h); see AIL_sequence_position for more information.

Group: XMIDI Services
Related Sections: XMIDI For Loop Controller (116), XMIDI Sequence Branch (109), XMIDI Sequence Branch Index (120)
Related Functions: AIL_branch_index, AIL_sequence_ms_position, AIL_sequence_position, AIL_set_sequence_ms_position
Related Basic Types: HSEQUENCE, MILES_PREFERENCES, U32, void