alSeqpLoop.3p 2.13 KB
.TH alSeqpLoop 3P local "Silicon Graphics, Inc."

.SH NAME 
.upperok 
alSeqpLoop \- sets sequence loop points

.SH SYNOPSIS
.nf
\f3
.Op c
#include <libaudio.h>
.sp .8v
void alSeqpLoop(ALSeqPlayer *seqp, ALSeqMarker *start, ALSeqMarker *end, 
                int count);
.Op
\f1
.fi
.SH PARAMETERS
.TP 10
.I seqp
pointer to the sequence player. 
.TP
.I start
loop start marker.
.TP
.I end
loop end marker.
.TP
.I count
number of times to loop. A value of -1 means loop forever.
.SH DESCRIPTION 
alSeqpLoop sets sequence loop points to the locations specified by the
.I start
and 
.I end
markers.  These markers must have been previously initialized with
.I alSeqNewMarker.

In order to use loops effectively, several important points
concerning the behavior of loops and markers must be understood.
Firstly, markers always get positioned at sequence event locations,
so if you create a new marker at a tick location that does not
correspond to a sequence event,
.I alSeqNewMarker
will "snap" the marker to the event previous to the tick time.
Secondly, loops are inclusive of the start marker's event and 
exclusive of the end marker's event. That is, the loop is defined
as [start, end).  Thirdly, loops should always contain an equal
number of note on and note off events.  This is very important since
if the end marker is positioned on a note off event it will not
be part of the loop and the corresponding note on's voice will
never get released.  So each time through the loop a voice will
get used up until the maximum number of allocated voices has been
reached.  Therefore, be very careful to place the end marker so that
all note ons are matched with a note off, even if this means placing
a dummy event at the end loop marker.

Overall, alSeqpLoop is intended for looping over the entire sequence
or over well-defined sections of a sequence.  For more comprehensive
loops that are on a track by track basis, see the compact sequence
player which embeds loop points in the sequence stream.
.SH WARNING
The loop markers must remain allocated for the entire duration of the
loop since the sequence player stores references to these markers.
.SH SEE ALSO 
.IR alSeqNewMarker (3P)