alSynAllocVoice.3p 1.75 KB
.TH alSynAllocVoice 3P local "Silicon Graphics, Inc."

.SH NAME 
.upperok 
alSynAllocVoice \- allocate a synthesizer voice.

.SH SYNOPSIS
.nf
\f3
.Op c
#include <libaudio.h>
.sp .8v
s32	 alSynAllocVoice(ALSynth *drvr, ALVoice *voice, ALVoiceConfig *vc);
.Op
\f1
.fi
.SH PARAMETERS
.TP 10
.I drvr
pointer to the synthesizer driver.
.TP
.I voice
pointer to a virtual voice to be initialized and allocated a physical voice.
.TP
.I vc
pointer to a voice configuration structure.
.SH DESCRIPTION
Initialize the virtual voice using the parameters specified in the voice
configuration structure and allocate a physical voice to it. If there are
no physical voices available, alSynAllocVoice will attempt to steal a
physical voice from another virtual voice. To do this alSynAllocVoice,
will search the list of voices and steal the physical voice with the
lowest priority voice that is equal to or lower than the priority specified
in the configuration structure. If no physical voice is found with an equal
or lower priority or an error occurs, alSynAllocVoice will return 0 to
indicate failure.  If a physical voice is allocated and no errors occur,
alSynAllocVoice will return 1 to indicate success. Note that voice stealing
only occurs when there are more virtual voices than physical voices.

.PP
The parameters in the ALVoiceConfig structure are as follows:
.TP 15
.I priority
the voice's playback priority.
.TP
.I fxBus
the auxilliary effect bus to which the voice is assigned.
Currently there is only one auxilliary bus.
.TP
.I unityPitch
a flag which when set, specifies that this voice is to be played at a pitch of 1.0.
.SH WARNING
alSynAllocVoice should only be called from within an ALVoiceHandler.
.SH SEE ALSO
.IR alSynFreeVoice (3P),
.IR alSynStartVoice (3P),
.IR alSynStopVoice (3P)