# FSOUND FX API

Introduction

The FSOUND_FX api allows you to do special effects processing per channel through Direct X 8 only.
You can do such effects as chorus, compression, distortion, echo, flange, gargle, reverb, and EQ through a simple API.

Limitations

Before using the FSOUND_FX api, there are a few limitations that must be known about because of the DirectX API.
- FX enabled samples can only be played once at a time, not multiple times at once.
- Samples or streams have to be created with FSOUND_HW2D or FSOUND_HW3D, and FSOUND_ENABLEFX for this to work.
- If you are using DirectX 8, FSOUND_SetFrequency will not work any more for that sound, you cannot change the pitch of a FX enabled sound. This is a DirectX limitation. Direct X 9 does not have this limitation.
- FSOUND_FX_Enable cannot be called if the sound is playing or locked.
- If FSOUND_FX_Disable is not called effects will build up on top of each other every time FSOUND_FX_Enable is called.
  Once these are taken into account, you can go for it!

Using it

You have to use the pause feature of FSOUND_PlaySoundEx for this API to work.
The reason for this is DirectX needs a channel resource in hardware to be allocated, and so actually PLAYED (but paused) before the FX functions can succeed.
Once you have it played but paused, you can enable multiple effects on one channel, and even the same effect multiple times on the same channel, then unpause it to hear what happens, but at this point you cannot enable more effects. It has to be paused or restarted.
You can update the parameters of effects while they are playing or while it is paused.
Here is an example

int channel, echoid, echoid2;
channel = FSOUND_PlaySoundEx(FSOUND_FREE, samp2, DrySFXUnit, TRUE);
echoid = FSOUND_FX_Enable(channel, FSOUND_FX_ECHO); // enable echo and get the first echo handle
echoid2 = FSOUND_FX_Enable(channel, FSOUND_FX_ECHO); // enable echo again and get the second echo handle
FSOUND_FX_Enable(channel, FSOUND_FX_FLANGER); // enable the flange effect, don't bother with the handle, we'll just use the default parameters<
FSOUND_SetPaused(channel, FALSE); // now start the sound playing
FSOUND_FX_SetEcho(echoid, 80.0f, 70.0f, 100.0f, 100.0f, TRUE); // Alter the parameters of the first echo for the channel it was enabled on. This handle is unique to this effect and this channel. The 2nd echo we enabled will be unaffected

This process must be repeated as when a sound is restarted, all FX information is reset, so effects must be enabled each time.

FX on the 'output' channel.

This is a special feature which allows you to enable effects on the output result of the software mixed channels!
If you specify FSOUND_INIT_ENABLESYSTEMCHANNELFXX in the flags field of FSOUND_Init.
The channel ID to use for altering the output result is FSOUND_SYSTEMCHANNEL. Call FSOUND_SetPaused on this to enable effects. This will stop all software mixed sound effects.

FSOUND_FX + Spectrum and DSP?.

To use the FSOUND_FX api to do fx on channels requires FSOUND_HW2D or FSOUND_HW3D (and FSOUND_ENABLEFX) flags to work.
You may notice if you do this, you will lose the ability to do FSOUND_DSP_GetSpectrum or any DSP unit will not register, because FSOUND_FX channels play in hardware, and don't run through the FMOD DSP Engine.
There is a way to do this though. Instead of performing EQ on a channel by channel basis, perform it on the global software mix output.
This means you can't have per channel control, but if you are just looking for a way to do EQ on your audio for example, then use the following method.
- Call FSOUND_SetBufferSize(100); When you call FSOUND_Init with FSOUND_INIT_ENABLESYSTEMCHANNELFX (see step 2) you will need a big enough software engine buffer to allow FX to be processed. FMOD defaults to 50 which is too small. This is a limitation of DirectSound and needs to be taken care of.
- Use FSOUND_INIT_ENABLESYSTEMCHANNELFXin FSOUND_Init. This will ready the software engine output to have the FX api used on it.
- Pause the software engine. You always need to pause the source when using FSOUND_FX_Enable (see step 3), so call FSOUND_SetPaused(FSOUND_SYSTEMCHANNEL, TRUE);
- Call FSOUND_FX_Enable to create all your FX handles (EQ, distortion whatever).
- Unpause the software engine. FSOUND_SetPaused(FSOUND_SYSTEMCHANNEL, FALSE);
- Now you are ready! Create streams and sounds in software mode (FSOUND_NORMAL - don't use FSOUND_HW2D or FSOUND_HW3D)
  Now that all your sounds and streams are in software, you get spectrum analysis back, and also you can use the DSP engine for your own software processing or oscilliscope plotting - with the added benefit of FSOUND_FX processing!