.TH alCSeqPlayer 3P local "Silicon Graphics, Inc."

.SH NAME
.upperok
alCSeqPlayer \- Ultra 64 Compressed MIDI sequence player routines.

.SH SYNOPSIS
.nf
\f3
.Op c
#include <libaudio.h>
.sp .8v
void    alCSPNew(ALCSPlayer *seqp, ALSeqpConfig *config);
void    alCSPDelete(ALCSPlayer *seqp);
void    alCSPSetSeq(ALCSPlayer *seqp, ALCSeq *seq);
ALCSeq  *alCSPGetSeq(ALCSPlayer *seqp);
void    alCSPSetBank(ALCSPlayer *seqp, ALBank *b);
s32     alCSPGetState(ALCSPlayer *seqp);
void    alCSPPlay(ALCSPlayer *seqp);
void    alCSPStop(ALCSPlayer *seqp);
void    alCSPSetBank(ALCSPlayer *seqp, ALBank *b);
void    alCSPSetTempo(ALCSPlayer *seqp, s32 tempo);
s32     alCSPGetTempo(ALCSPlayer *seqp);
s16     alCSPGetVol(ALCSPlayer *seqp);
void    alCSPSetVol(ALCSPlayer *seqp, s16 vol);

void    alCSPSetChlProgram(ALCSPlayer *seqp, u8 chan, u8 prog);
s32     alCSPGetChlProgram(ALCSPlayer *seqp, u8 chan);
void    alCSPSetChlFXMix(ALCSPlayer *seqp, u8 chan, u8 fxmix);
u8      alCSPGetChlFXMix(ALCSPlayer *seqp, u8 chan);
void    alCSPSetChlPan(ALCSPlayer *seqp, u8 chan, ALPan pan);
ALPan   alCSPGetChlPan(ALCSPlayer *seqp, u8 chan);
void    alCSPSetChlVol(ALCSPlayer *seqp, u8 chan, u8 vol);
u8      alCSPGetChlVol(ALCSPlayer *seqp, u8 chan);
void    alCSPSetChlPriority(ALCSPlayer *seqp, u8 chan, u8 priority);
u8      alCSPGetChlPriority(ALCSPlayer *seqp, u8 chan);

void    alCSPSendMidi(ALCSPlayer *seqp, long ticks, u8 status,
                       u8 byte1, u8 byte2);
.Op
\f1
.fi
.SH DESCRIPTION
The Ultra 64 Audio Library supports playback of MIDI sequences using either
the Type 0 MIDI Sequence Player, whose routines start with 
.B alSeqp,
or the Compressed MIDI Sequence Player, whose routines start with 
.B alCSP. 
This man page details the Compressed MIDI Sequence Player. For details
of the Type 0 MIDI Sequence Player, see the man page for 
.B alSeqPlayer.
The principle differences between the two MIDI players are the handling of
loops, and the compression of data. Details are discussed in the Nintendo 64
Programming Manual's chapters, Audio Library and Audio Formats.
.PP
The sequence player handles the playback of the sequence, but
the actual sequence data is handled by a Sequence 
(see
.B alCSeq).
.PP
To use a Compressed Sequence Player, you must first initialize an ALCSPlayer
structure to represent it. This is accomplished with a call to 
.B alCSPNew.
.PP
After initializing the ALCSPlayer structure, you must set the bank and the 
sequence with calls to 
.B alCSPSetBank
and 
.B alCSPSetSeq
respectively. 
.PP
To start the sequence player playing, call
.B alCSPPlay.
To stop the sequence player, call
.B alCSPStop. 
The sequence player can only have one target sequence at a time. You must 
stop a sequence before setting and playing a new sequence. You should not 
attempt to switch banks while a sequence is playing. You can use
.B alCSPGetState
to determine if the sequence player is fully stopped. When you call 
.B alCSPStop,
all processing of the sequence will stop and all notes will be turned off.
.PP
When a sequence is stopped it will not "rewind" but will remain pointing to
its current location. This allows you to restart a sequence from where it
was stopped with a call to
.B alCSPPlay.
Sustained notes that were cut off by a call to
.B alCSPStop
will not be restarted, only new notes will be processed. 

.PP
If you want to rewind the sequence or relocate to another point in the
sequence, you can create an ALCSeqMarker at the desired location using the call 
.B alCSeqNewMarker,
and then call
.B alCSeqSetLoc
to rewind or relocate the sequence.  Note that these calls do not affect
the channel playback state so care should be taken to make sure that the
channel parameters (eg. program, vol, pan, etc.) are set to appropriate 
values for the given sequence location.

Channel parameters can be set with their individual calls or by sending the
appropriate midi data using
.B alCSPSendMidi.
Music can be created in realtime and played back with
.B alCSPSendMidi.

The compressed MIDI sequence player doesn't support loops created by API calls 
like the Type 0 MIDI sequence player does. To loop music using the compressed
MIDI sequence player the sequences must have loop points imbedded in them.
Details of how to imbed loop points are discussed in the Ultra 64 Programming
Guide's Audio Library section.


.SH SEE ALSO
alCSeq(3P),
alCSPNew(3P),
alCSPDelete(3P),
alCSPSetSeq(3P),
alCSPGetSeq(3P),
alCSPPlay(3P),
alCSPStop(3P),
alCSPSetBank(3P),
alCSPSetTempo(3P),
alCSPGetTempo(3P),
alCSPGetVol(3P),
alCSPSetVol(3P),
alCSPSetChlProgram(3P),
alCSPGetChlProgram(3P),
alCSPSetChlFXMix(3P),
alCSPGetChlFXMix(3P),
alCSPSetChlPan(3P),
alCSPGetChlPan(3P),
alCSPSetChlVol(3P),
alCSPGetChlVol(3P),
alCSPSetChlPriority(3P),
alCSPGetChlPriority(3P),
alCSPSendMidi(3P)