FSOUND_PlaySound

Plays a sample in a specified channel, using the sample's default frequency, volume
and pan settings.

int F_API FSOUND_PlaySound(
int channel,
FSOUND_SAMPLE *sptr
);

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
Passing this will cause ALL channels to play. (note this will make things
VERY noisy!)
If FSOUND_ALL is used the last channel success flag will be returned.

sptr

Pointer to the sample to be played.

Return Value

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

Remarks

If you play a FSOUND_HW3D declared sample with this function, then the position and velocity
are set to those of the listener. Other attributes such as volume, frequency and pan are taken
from the sample's default volume, frequency, pan etc.
----------
The channel handle :
The return value is reference counted. This stops the user from updating a stolen channel.
Basically it 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.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

[API function]