FSOUND_DSP_Create

Creates a DSP unit, and places it in the DSP chain position specified by the priority
parameter. Read the remarks section carefully for issues regarding DSP units.
DSP units are freed with FSOUND_DSP_Free.

FSOUND_DSPUNIT *F_API FSOUND_DSP_Create(
FSOUND_DSPCALLBACK callback,
int priority,
void *userdata
);

Parameters

callback	This is a pointer to your DSP Unit callback, of type FSOUND_DSPCALLBACK. The prototype for a callback is declared in the following fashion. Callbacks must return a pointer to the buffer you work on, so that the next dsp unit can work on it. Here is the simplest case: void callback(void originalbuffer, void newbuffer, int length, void userdata) { // originalbuffer = fsounds original mixbuffer. // newbuffer = the buffer passed from the previous DSP unit. // length = length in samples at this mix time. // param = user parameter passed through in FSOUND_DSP_Create. // // modify the buffer in some fashion return newbuffer; } See the definition of FSOUND_DSPCALLBACK for more.
priority	Order in the priority chain. Valid numbers are 0 to 1000, 0 being highest priority (first), with 1000 being lowest priority (last). Note that FSOUNDs soundeffects mixers and copy routines are considered part of this DSP unit chain which you can play with.
param	User defined parameter, this gets passed into the callback when it is called. It is safe to leave this value 0.

Return Value

On success, a pointer to a new valid DSP unit is returned.
On failure, NULL is returned.

Remarks

A dsp unit is NOT ACTIVE by default. You have to activate it with FSOUND_DSP_SetActive
---------------------------------------------------------------------------------------
Priorities and default system units.
---------------------------------------------------------------------------------------
A note on priorities. FSOUND processes DSP units in order of priority. A 0 priority
unit gets processed first, a 1 priority unit gets processed next, and so on.
FSOUND actually uses these DSP units to mix its sound effects and music! Yes, you have
access to them (be careful!). It is possible to totally remove, replace or deactivate
all of FSOUND's system units so that it does nothing at all!
FSOUND has preinstalled default system units at the following priority locations:
FSOUND_DSP_DEFAULTPRIORITY_CLEARUNIT (priority 0) - Clear Unit. This unit clears out
the mixbuffer for the next units to mix into. You can disable this unit and replace
it with something other than a clearer, such as a scaler, which fades down the mix
buffer instead of clearing it, to produce a very rough echo effect.
FSOUND_DSP_DEFAULTPRIORITY_SFXUNIT (priority 100) - SFX Unit. This unit mixes sound
effect channels into the mix buffer, which was previously cleared with the Clear
Unit.
FSOUND_DSP_DEFAULTPRIORITY_MUSICUNIT (priority 200) - Music Unit. This unit mixes all
music channels into the mix buffer, which was previously mixed into with the SFX
Unit.
FSOUND_DSP_DEFAULTPRIORITY_CLIPANDCOPYUNIT (priority 1000) - Clip and Copy Unit. This
unit takes the finally mixed buffer, and clips it to the output stream size (if it
needs to), and then sends it off to the sound device. It is done last. If this is
disabled you will hear no sound.
---------------------------------------------------------------------------------------
Buffer Lengths.
---------------------------------------------------------------------------------------
The 'length' value of the DSP callback is roughly 20ms worth of data.
Use FSOUND_DSP_GetBufferLength to get the exact callback length.
---------------------------------------------------------------------------------------
Buffer Widths
---------------------------------------------------------------------------------------
Remember that FSOUND uses different buffer types depending on what type of mixer it is.
You will have to compensate for this by writing different routines depending on the
mixer type (ie mmx or non mmx), just like FSOUND does.
Currently there are the 3 types of mixers and their buffer sizes.
You can get the type of mixer being used by calling the FSOUND_GetMixer function.
You may want to check on this inside your callback, or set up a function pointer system,
whatever you think is suitable (it costs nothing to do a FSOUND_GetMixer every time).
- FSOUND_MIXER_BLENDMODE : This buffer is a stereo, signed 32bit buffer (8 bytes per
sample). The data is in integer format.
Data written to this buffer is not clipped and passed to the output stream until the
very end of the chain (the clip and copy unit). For this type of mixer, you dont
have to worry about clipping becuase FSOUND does this for you.
- FSOUND_MIXER_QUALITY_FPU / FSOUND_MIXER_QUALITY_FPU_VOLUMERAMP: This buffer is also a
stereo, signed 32bit buffer (8 bytes per sample). This data is in floating point
format.
The same clip and copy rules apply here as for the above mixer.
- Any MMX based mixer : This buffer is a stereo, signed 16bit buffer (4 bytes per sample).
When writing to this buffer, you must make sure the result does not overflow this
signed 16bit range.
If you add data into to this buffer, make sure it is clipped to a signed 16bit range
before writing it back. FSOUND only copies this data to the output stream, it does
not clip it.
---------------------------------------------------------------------------------------
Speed
---------------------------------------------------------------------------------------
DSP Units are processed then and there, inside the mixing routine. Remember to make
your process as FAST as possible, or the output device's play cursor will catch up to
FSOUND's write cursor while your routine takes its time to complete, and make it start
to break up.
So basically, if it isnt fast, then FSOUND will not be able to send the data to the
output device in time for the next mixer update, and the result will be corrupted sound.
FSOUND_DSP_MixBuffers is available now, so if you need to mix some raw data into the output
buffer quickly, you can use FSOUND's own optimized mixer directly to do it!
Finally, you can see how your routine affects cpu usage, by using FSOUND_GetCPUUsage.
The cpu usage returned by this function includes any time spent in DSP units as well.
(this function times everything). If you are really bored, you can see how much FSOUND's
system units take cpu-wise, by turning them on and off and seeing how they affect
performance.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, GameCube

[API function]