FSOUND_PlaySoundEx

Extended featured version of FSOUND_PlaySound.
New functionality includes the ability to start the sound paused.
This allows attributes of a channel to be set freely before the sound actually starts playing, until FSOUND_SetPaused(FALSE) is used.
Also added is the ability to associate the channel to a specified DSP unit. This allows the user to 'group' channels into seperate DSP units, which allows effects to be inserted between these 'groups', and allow various things like having one group affected by reverb (wet mix) and another group of channels unaffected (dry).
This is useful to seperate things like music from being affected by DSP effects, while other sound effects are.

int F_API FSOUND_PlaySoundEx(
int channel,
FSOUND_SAMPLE *sptr,
FSOUND_DSPUNIT *dspunit,
signed char startpaused
);

Parameters

channel	0+ The absolute channel number in the channel pool. Remember software channels come first, followed by hardware channels. You cannot play a software sample on a hardware channel and vice versa. FSOUND_FREE Chooses a free channel to play in. If all channels are used then it selects a channel with a sample playing that has an EQUAL or LOWER priority than the sample to be played. FSOUND_ALL Plays the sound on all channels.
sptr	Pointer to the sample to be played.
dspunit	Optional. NULL by default. Pointer to a dsp unit to attach the channel to for channel grouping. Only attach a sound to a user created DSP unit, and not a system DSP unit.
paused	Start the sound paused or not. Pausing the sound allows attributes to be set before the sound starts.

Return Value

On success, the channel handle that was selected is returned.
On failure, -1 is returned.

Remarks

FSOUND_ALL is supported. Passing this will cause ALL channels to play. (note this could make things VERY noisy!)
If FSOUND_ALL is used the last channel success flag will be returned. This return value is not useful in most circumstances.
----------
The channel handle :
The return value is reference counted. This stops the user from updating a stolen channel.
This means the only sound you can change the attributes (ie volume/pan/frequency/3d position) for are the
one you specifically called playsound for. If another sound steals that channel, and you keep trying to
change its attributes (ie volume/pan/frequency/3d position), it will do nothing.
This is great if you have sounds being updated from tasks and you just forget about it.
You can keep updating the sound attributes and if another task steals that channel, your original task
wont change the attributes of the new sound!!!
The lower 12 bits contain the channel number. (yes this means a 4096 channel limit for FMOD :)
The upper 19 bits contain the reference count.
The top 1 bit is the sign bit.
ie
S RRRRRRRRRRRRRRRRRRR CCCCCCCCCCCC
----------
Remember if not using FSOUND_FREE, then the channel pool is split up into software and hardware channels.
Software channels occupy the first n indicies specified by the value passed into FSOUND_Init.
Hardware channels occupy the next n indicies after this, and can be a variable amount, depending on the hardware.
Use FSOUND_GetNumHardwareChannels to query how many channels are available in hardware.
----------
If you attach a sound to a DSP unit (for grouping purposes), the callback for the DSP unit will be overwritten with fmod's internal mixer callback, so the callback the user supplied is rendered obsolete and is not called.
Also, do not attach sounds to system DSP units, the assignment will be ignored if you do.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

[API function]