mirror of
https://github.com/ENSL/NS.git
synced 2024-11-30 00:10:57 +00:00
183 lines
9.4 KiB
HTML
183 lines
9.4 KiB
HTML
<HTML>
|
|
<HEAD>
|
|
<META NAME="GENERATOR" Content="SOURCEDOC.EXE">
|
|
<META HTTP-EQUIV="Content-Type" content="text/html; charset=iso-8859-1">
|
|
<TITLE>FSOUND_DSP_Create</TITLE>
|
|
<STYLE>
|
|
#flush {margin-left: -10p; margin-right: -0p}
|
|
#buttonbar {color: white}
|
|
</STYLE>
|
|
</HEAD>
|
|
<BODY TOPMARGIN=0 BGPROPERTIES="FIXED" BGCOLOR="white">
|
|
<FONT FACE="ARIAL">
|
|
<SPAN ID="flush">
|
|
<A NAME="SEE ALSO">
|
|
<TABLE WIDTH="100%" COLS=2 BORDER=0 BGCOLOR="#000000">
|
|
<TR ALIGN=RIGHT>
|
|
<TD ALIGN=LEFT>
|
|
<IMG SRC="banner03.gif" WIDTH="88" HEIGHT="31" BORDER=0>
|
|
</TD>
|
|
<TD ALIGN=RIGHT VALIGN=TOP>
|
|
<FONT FACE="ARIAL" SIZE="2">
|
|
<A ID=buttonbar HREF="FSOUND_DSP_ClearMixBuffer.html">
|
|
<IMG SRC="u_prev.gif" WIDTH="71" HEIGHT="16" BORDER=0 ALT="Previous Topic">
|
|
</A>
|
|
<A ID=buttonbar HREF="FSOUND.html">
|
|
<IMG SRC="u_index.gif" WIDTH="47" HEIGHT="16" BORDER=0 ALT="Index">
|
|
</A>
|
|
<A ID=buttonbar HREF="FSOUND_DSP_Free.html">
|
|
<IMG SRC="u_next.gif" WIDTH="48" HEIGHT="16" BORDER=0 ALT="Next Topic">
|
|
</A>
|
|
</FONT></TD><TD WIDTH=15></TD>
|
|
</TR>
|
|
</TABLE>
|
|
</A>
|
|
</SPAN>
|
|
<A HREF="FSOUND.html#Functions"><H5>[API function]</A></H5>
|
|
<H2><A NAME="FSOUND_DSP_Create">FSOUND_DSP_Create</A></H2>
|
|
Creates a DSP unit, and places it in the DSP chain position specified by the priority<BR>
|
|
parameter. Read the remarks section carefully for issues regarding DSP units.<BR>
|
|
DSP units are freed with FSOUND_DSP_Free.<BR>
|
|
<P>
|
|
<B>FSOUND_DSPUNIT *F_API </B><B> </B><B>FSOUND_DSP_Create</B><B>(</B><BR>
|
|
<B>FSOUND_DSPCALLBACK </B><B> </B><I>callback</I><B>,</B><BR>
|
|
<B>int </B><B> </B><I>priority</I><B>,</B><BR>
|
|
<B>void *</B><I>userdata</I><BR>
|
|
<B>);</B><BR>
|
|
<H3>Parameters</H3>
|
|
<TABLE>
|
|
<TR VALIGN=top><TD><I>callback</I></TD>
|
|
<TD>This is a pointer to your DSP Unit callback, of type FSOUND_DSPCALLBACK.<BR>
|
|
The prototype for a callback is declared in the following fashion.<BR>
|
|
Callbacks must return a pointer to the buffer you work on, so that<BR>
|
|
the next dsp unit can work on it. <BR>
|
|
Here is the simplest case:<BR>
|
|
void *callback(void *originalbuffer, void *newbuffer, int length, void *userdata)<BR>
|
|
{<BR>
|
|
// originalbuffer = fsounds original mixbuffer.<BR>
|
|
// newbuffer = the buffer passed from the previous DSP unit.<BR>
|
|
// length = length in samples at this mix time.<BR>
|
|
// param = user parameter passed through in FSOUND_DSP_Create.<BR>
|
|
//<BR>
|
|
// modify the buffer in some fashion<BR>
|
|
return newbuffer;<BR>
|
|
}<BR>
|
|
See the definition of FSOUND_DSPCALLBACK for more.<BR>
|
|
</TD><TR VALIGN=top><TD><I>priority</I></TD>
|
|
<TD>Order in the priority chain. Valid numbers are 0 to 1000, 0 being<BR>
|
|
highest priority (first), with 1000 being lowest priority (last).<BR>
|
|
Note that FSOUNDs soundeffects mixers and copy routines are considered<BR>
|
|
part of this DSP unit chain which you can play with.<BR>
|
|
</TD><TR VALIGN=top><TD><I>param</I></TD>
|
|
<TD>User defined parameter, this gets passed into the callback when it is<BR>
|
|
called. It is safe to leave this value 0.<BR>
|
|
</TD></TABLE>
|
|
<H3>Return Value</H3>
|
|
On success, a pointer to a new valid DSP unit is returned.<BR>
|
|
On failure, NULL is returned.<BR>
|
|
<H3>Remarks</H3>
|
|
A dsp unit is NOT ACTIVE by default. You have to activate it with FSOUND_DSP_SetActive<BR>
|
|
---------------------------------------------------------------------------------------<BR>
|
|
Priorities and default system units.<BR>
|
|
---------------------------------------------------------------------------------------<BR>
|
|
A note on priorities. FSOUND processes DSP units in order of priority. A 0 priority<BR>
|
|
unit gets processed first, a 1 priority unit gets processed next, and so on. <BR>
|
|
FSOUND actually uses these DSP units to mix its sound effects and music! Yes, you have<BR>
|
|
access to them (be careful!). It is possible to totally remove, replace or deactivate <BR>
|
|
all of FSOUND's system units so that it does nothing at all!<BR>
|
|
FSOUND has preinstalled default system units at the following priority locations:<BR>
|
|
FSOUND_DSP_DEFAULTPRIORITY_CLEARUNIT (priority 0) - Clear Unit. This unit clears out <BR>
|
|
the mixbuffer for the next units to mix into. You can disable this unit and replace<BR>
|
|
it with something other than a clearer, such as a scaler, which fades down the mix<BR>
|
|
buffer instead of clearing it, to produce a very rough echo effect.<BR>
|
|
FSOUND_DSP_DEFAULTPRIORITY_SFXUNIT (priority 100) - SFX Unit. This unit mixes sound <BR>
|
|
effect channels into the mix buffer, which was previously cleared with the Clear <BR>
|
|
Unit. <BR>
|
|
FSOUND_DSP_DEFAULTPRIORITY_MUSICUNIT (priority 200) - Music Unit. This unit mixes all <BR>
|
|
music channels into the mix buffer, which was previously mixed into with the SFX <BR>
|
|
Unit. <BR>
|
|
FSOUND_DSP_DEFAULTPRIORITY_CLIPANDCOPYUNIT (priority 1000) - Clip and Copy Unit. This <BR>
|
|
unit takes the finally mixed buffer, and clips it to the output stream size (if it<BR>
|
|
needs to), and then sends it off to the sound device. It is done last. If this is<BR>
|
|
disabled you will hear no sound.<BR>
|
|
---------------------------------------------------------------------------------------<BR>
|
|
Buffer Lengths.<BR>
|
|
---------------------------------------------------------------------------------------<BR>
|
|
The 'length' value of the DSP callback is roughly 20ms worth of data.<BR>
|
|
Use FSOUND_DSP_GetBufferLength to get the exact callback length.<BR>
|
|
---------------------------------------------------------------------------------------<BR>
|
|
Buffer Widths<BR>
|
|
---------------------------------------------------------------------------------------<BR>
|
|
Remember that FSOUND uses different buffer types depending on what type of mixer it is.<BR>
|
|
You will have to compensate for this by writing different routines depending on the <BR>
|
|
mixer type (ie mmx or non mmx), just like FSOUND does. <BR>
|
|
Currently there are the 3 types of mixers and their buffer sizes.<BR>
|
|
You can get the type of mixer being used by calling the FSOUND_GetMixer function.<BR>
|
|
You may want to check on this inside your callback, or set up a function pointer system,<BR>
|
|
whatever you think is suitable (it costs nothing to do a FSOUND_GetMixer every time).<BR>
|
|
- FSOUND_MIXER_BLENDMODE : This buffer is a stereo, signed 32bit buffer (8 bytes per <BR>
|
|
sample). The data is in integer format.<BR>
|
|
Data written to this buffer is not clipped and passed to the output stream until the <BR>
|
|
very end of the chain (the clip and copy unit). For this type of mixer, you dont <BR>
|
|
have to worry about clipping becuase FSOUND does this for you.<BR>
|
|
- FSOUND_MIXER_QUALITY_FPU / FSOUND_MIXER_QUALITY_FPU_VOLUMERAMP: This buffer is also a <BR>
|
|
stereo, signed 32bit buffer (8 bytes per sample). This data is in floating point <BR>
|
|
format.<BR>
|
|
The same clip and copy rules apply here as for the above mixer.<BR>
|
|
- Any MMX based mixer : This buffer is a stereo, signed 16bit buffer (4 bytes per sample).<BR>
|
|
When writing to this buffer, you must make sure the result does not overflow this <BR>
|
|
signed 16bit range.<BR>
|
|
If you add data into to this buffer, make sure it is clipped to a signed 16bit range<BR>
|
|
before writing it back. FSOUND only copies this data to the output stream, it does<BR>
|
|
not clip it.<BR>
|
|
---------------------------------------------------------------------------------------<BR>
|
|
Speed<BR>
|
|
---------------------------------------------------------------------------------------<BR>
|
|
DSP Units are processed then and there, inside the mixing routine. Remember to make<BR>
|
|
your process as FAST as possible, or the output device's play cursor will catch up to<BR>
|
|
FSOUND's write cursor while your routine takes its time to complete, and make it start <BR>
|
|
to break up. <BR>
|
|
So basically, if it isnt fast, then FSOUND will not be able to send the data to the<BR>
|
|
output device in time for the next mixer update, and the result will be corrupted sound.<BR>
|
|
FSOUND_DSP_MixBuffers is available now, so if you need to mix some raw data into the output <BR>
|
|
buffer quickly, you can use FSOUND's own optimized mixer directly to do it!<BR>
|
|
Finally, you can see how your routine affects cpu usage, by using FSOUND_GetCPUUsage.<BR>
|
|
The cpu usage returned by this function includes any time spent in DSP units as well.<BR>
|
|
(this function times everything). If you are really bored, you can see how much FSOUND's<BR>
|
|
system units take cpu-wise, by turning them on and off and seeing how they affect <BR>
|
|
performance.<BR>
|
|
___________________<BR>
|
|
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, GameCube<BR>
|
|
<H3>See Also</H3>
|
|
<A HREF="FSOUND_DSP_Create.html">FSOUND_DSP_Create</A>
|
|
,
|
|
<A HREF="FSOUND_DSP_Free.html">FSOUND_DSP_Free</A>
|
|
,
|
|
<A HREF="FSOUND_DSP_GetBufferLength.html">FSOUND_DSP_GetBufferLength</A>
|
|
,
|
|
<A HREF="FSOUND_DSP_GetBufferLengthTotal.html">FSOUND_DSP_GetBufferLengthTotal</A>
|
|
,
|
|
<A HREF="FSOUND_DSP_MixBuffers.html">FSOUND_DSP_MixBuffers</A>
|
|
,
|
|
<A HREF="FSOUND_DSP_PRIORITIES.html">FSOUND_DSP_PRIORITIES</A>
|
|
,
|
|
<A HREF="FSOUND_DSP_SetActive.html">FSOUND_DSP_SetActive</A>
|
|
,
|
|
<A HREF="FSOUND_DSP_SetPriority.html">FSOUND_DSP_SetPriority</A>
|
|
,
|
|
<A HREF="FSOUND_DSPCALLBACK.html">FSOUND_DSPCALLBACK</A>
|
|
,
|
|
<A HREF="FSOUND_GetCPUUsage.html">FSOUND_GetCPUUsage</A>
|
|
,
|
|
<A HREF="FSOUND_GetMixer.html">FSOUND_GetMixer</A>
|
|
,
|
|
<A HREF="FSOUND_MIXERTYPES.html">FSOUND_MIXERTYPES</A>
|
|
,
|
|
<A HREF="FSOUND_PlaySoundEx.html">FSOUND_PlaySoundEx</A>
|
|
,
|
|
<A HREF="FSOUND_Stream_CreateDSP.html">FSOUND_Stream_CreateDSP</A>
|
|
<HR><BR><FONT SIZE="-2">This document copyright ©Firelight Technologies, Pty, Ltd, 1999-2002. All rights reserved.</FONT><BR>
|
|
<FONT SIZE="-2">Generated Thu Dec 15 17:31:28 2005
|
|
by SourceDoc v0.10, the automated source code documenter.</FONT><BR>
|
|
</BODY>
|
|
</HTML>
|