Miles Sound System SDK 7.2a

AIL_sequence_position

The function AIL_sequence_position returns the number of beats and measures elapsed since a given XMIDI sequence began playing.

void AIL_sequence_position(
  HSEQUENCE S,
  S32 *beat,
  S32 *measure
);

In Parameters

S: indicates the sequence for which position information is desired.

Out Parameters

beat: if not NULL, should point to a long integer into which will be stored the current sequence beat count.
measure: if not NULL, should point to a long integer into which will be stored the current sequence measure count.

Returns

The current beat and measure counts are stored in the variables pointed to by the parameters *beat and *measure.

Discussion

This function is used to let the application know when a new beat or measure has begun, for indexing, layering, or animation purposes. You can use the AIL_sequence_ms_position function to track a sequence's current position in milliseconds.

To allow an application extra time to respond to the beginning of a new beat or bar, the MDI_QUANT_ADVANCE preference may be set at any time to cause beat and measure counts to be reported a given number of XMIDI intervals (typically 1/120 second) "ahead" of their current position. MDI_QUANT_ADVANCE's default preference value is 1.

The beat and measure counters are constantly updated as long as the XMIDI sequence is playing, and are reset to 0 during a call to AIL_start_sequence. Generally, applications should watch for and pay attention to changes in the beat or measure count, rather than attempting to interpret their absolute values.

Both counters are reset to 0 when an MSS-specific XMIDI Control Change event of type 118 (76h) is encountered during playback of the sequence. This event may be embedded to ensure the validity of the beat and measure counters at critical junctures in the sequence, such as track index points.

During the XMIDI conversion process, a certain amount of MIDI timing precision is necessarily lost. Very rarely, a sequence with numerous meter map changes can cause the reported beat and measure count to temporarily lose "sync" with the actual beat and measure count as reported by the time display in the MIDI sequencer used to create the sequence. Applications which require near-perfect timing precision may be able to overcome this potential problem by increasing the XMIDI quantization rate in the MDI_SERVICE_RATE preference in the runtime system before calling AIL_MIDI_to_XMI, or, if all else fails, use XMIDI Callback Trigger controllers to inform the application of critical sequence points. It may also help to advance the sequence's MIDI events in each measure so that they begin a few ticks into the first beat of their measure.

Group: XMIDI Services
Related Sections: XMIDI Clear Beat-Bar Count (118)
Related Functions: AILBEATCB, AIL_MIDI_to_XMI, AIL_branch_index, AIL_register_beat_callback, AIL_sequence_ms_position, AIL_set_sequence_ms_position, AIL_start_sequence
Related Basic Types: HSEQUENCE, MILES_PREFERENCES, S32, void