Previous Topic Index Next Topic
[API function]

FSOUND_Reverb_SetEnvironment

Allows you to set a global reverb environment using EAX or A3D reverb.

signed char F_API FSOUND_Reverb_SetEnvironment(
int env,
float vol,
float decay,
float damp
);

Parameters

env Sets an environment type. see FSOUND_REVERB_ENVIRONMENTS for types. Setting this resets all other parameters to default!!!
This value can be FSOUND_REVERB_IGNOREPARAM to ignore it.
vol Linear volume of global reverb mix, from 0 to 1 default: varies depending on environment
This value can be FSOUND_REVERB_IGNOREPARAM to ignore it.
decay Decay value for reverb , in seconds from 0 to 20 default: varies depending on environment
This value can be FSOUND_REVERB_IGNOREPARAM to ignore it.
damp Room effect level at low frequencies from 0 to 2 default: varies depending on environment
This value can be FSOUND_REVERB_IGNOREPARAM to ignore it.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

You must be using FSOUND_OUTPUT_DSOUND or FSOUND_OUTPUT_A3D as the output mode for this to work.
In dsound, the reverb will only work if you have an EAX compatible soundcard such as the SBLive,
and your sample was created with the FSOUND_HW3D flag.
----------------
Note that EAX and A3D reverb sound different. If you are fussy you may want to tweak for
both by doing this.
if (FSOUND_GetOutput() == FSOUND_OUTPUT_A3D)
FSOUND_Reverb_SetEnvironment(one set of settings);
else
FSOUND_Reverb_SetEnvironment(another set of settings);
---------------------------
From the EAX 1.0 documentation.
---------------------------
Volume:
The Volume property is the master volume control for the reverb added to all
sound sources; it sets the maximum volume of all reverb added to the sound
mix in the primary buffer (the listener). Sound sources mixed into the primary
buffer may have reverb volumes that vary relative to each other. (The reverb
for each source is set by its wet/dry ratio as described in the Reverb Mix sound-source
property.) As the master reverb volume goes up and down, controlled
by Volume, the reverb for each sound source goes up or down in proportion.
The Reverb Volume property value is a linear amplitude value, not a linear
decibel value. The maximum value of 1.0 turns overall reverb up to its fullest
possible volume. Each time you halve the value, you halve the volume and
therefore drop it by 6 dB. For example, turning the volume down from 1.0 to
0.5 drops the volume by 6 dB. Turning it down from 1.0 to 0.25 drops 12 dB;
from 1.0 to 0.125 18 dB; and so on. Setting the volume to 0.0 turns off all
reverb completely.
----------------------------
Decay:
Reverb decay is caused when a room’s surfaces absorb acoustic energy. Each
time an echo bounces off a surface, it decreases in volume until there is no
echo. If room surfaces are acoustically "live," they absorb very little acoustic
energy, echoes diminish only gradually each time they bounce, and the reverb
(a mixture of all the echoes) takes a long time to decay. If room surfaces are
acoustically "dead", reverb decays very quickly as acoustic energy is absorbed.
The Decay Time property effectively sets the acoustic properties of the virtual
room’s surfaces by setting the time in seconds it takes the reverb to diminish by
60 dB. When set to the maximum value (20 seconds), it simulates very live
surfaces; when set to the minimum value (0.1 seconds), it simulates very dead
surfaces with almost no reverb at all.
----------------------------
Damping:
The acoustic reflectivity of a room surface is not always even across all
frequencies. Some surfaces reflect more low and middle frequencies while
absorbing high frequencies. This high-frequency roll-off is called damping.
The Damping property sets the amount of damping applied to an environment.
Damping affects the decay time of the reverb as set by the property Decay
Time. The damping value 1.0 is neutral: the decay time is equal for high
frequencies and for low and middle frequencies. As the damping value
increases above 1.0, the high-frequency decay time increases so it’s longer than
the decay time of the middle and low frequencies. You hear a more brilliant
reverb. As the damping value decreases below 1.0, high-frequency decay time
decreases so it’s shorter than the decay time of the middle and low frequencies.
You hear a more muffled reverb.
---------------------------
For more advanced control use FSOUND_Reverb_SetEnvironmentAdvanced, but note, this
only works under A3D 3.0 or EAX2 compatible hardware.
-----------------
FSOUND_REVERB_IGNOREPARAM is handy if the parameter list is overwhelming. It allows you to only adjust a certain value in the environment without
having to worry about setting the rest.

See Also

FSOUND_GetOutput , FSOUND_REVERB_ENVIRONMENTS , FSOUND_Reverb_GetEnvironment , FSOUND_Reverb_GetEnvironmentAdvanced , FSOUND_REVERB_IGNOREPARAM , FSOUND_REVERB_PRESETS , FSOUND_Reverb_SetEnvironment , FSOUND_Reverb_SetEnvironmentAdvanced

This document copyright ©Firelight Multimedia, 1999-2001. All rights reserved.
Generated Thu Sep 13 00:18:09 2001 by SourceDoc v0.10, the automated source code documenter.