Sound modifiers

Usage

A number of different sound modifiers can be attached to sounds. Sound modifiers are accessed via script by passing a prop list defining them to the Sound script functions. Sample prop lists are already defined in the Ambience definition in Objects.ocd. If Objects.ocd is loaded, you can for example play the "Ding" sound with a reverb-effect:
Sound("Ding",,,,,,,Ambience.CaveModifier);
Custom modifiers may also be created using the prototype classes provided in the ambience object:
// Play "Ding" sound with an extra-long reverb modifier
long_reverb_modifier = new Ambience.SoundModifier {
	Type = C4SMT_Reverb,
	Reverb_Decay_Time = 10000,
};
Sound("Ding",,,,,,,long_reverb_modifier);
modifier->Release();
Sound modifiers are lazy-initialized, that is the filters are computed when the first sound with that effect is played. The engine also holds filters of any used modifiers attached to the used prop list in memory until released by the Release()-call provided by the ambience library, which wraps ChangeSoundModifier with appropriate parameters.
Since filter creation may cost some performance, it is recommended to create filter prop lists at round start and keep them for any effects. Please note that modifier lookup happens by prop list pointer only, not by its contents. Recreating and failing to release sound modifier prop lists therefore constitutes a memory-leak.
If sound modifiers are released, they are kept active until the last sound using them finishes. Note that for modifiers such as echo, this could still cut off sounds because the modifier outlasts the original sound (potentially forever for echo without decay).
Some existing modifiers may also be updated and updates reflected to the sounds played, even with those currently playing, by using the Update()-call such as in this example scenario script:
static reverb_modifier;

func Initialize()
{
	// Play "Ding" sound repeatedly and modify reverb
	reverb_modifier = new Ambience.SoundModifier {
		Type = C4SMT_Echo,
		Echo_Feedback = 1000,
	};
	Sound("Ding",,,,1,,,reverb_modifier);
	ScheduleCall(nil, this.Timer, 30, 99999);
	return true;
}

func Timer()
{
	// Update effect every 30 frames
	reverb_modifier.Echo_Feedback = Random(2) * 500;
	reverb_modifier->Update();
	return true;
}
Note that runtime updating does not work for the reverb modifier in the openal-soft library.

Global modifiers

Global modifiers can be set using the SetGlobalSoundModifier (see function documentation for example). These modifiers are applied to all sounds played in the viewport of a player or all players that do not have a modifier yet. Please note that it is not possible to combine multiple modifiers on a single sound.

Property reference

The effect is selected from the Type-property, which may have the following values:
Konstante Effekt
C4SMT_Reverb Reverb effect caused by sound bouncing off walls in enclosed spaces.
C4SMT_Echo Sound repeat as caused by loud sounds reflected in very large spaces.
C4SMT_Equalizer Custom amplification of up to four definable frequency bands. Note: When running with OpenAL soft, only supported with version 1.16 or above (not shipped by default).
Each modifier has a number of parameters. These consult to standard parameters for the OpenAL EFX library by dividing all given integer values by 1000 to yield float values.

Reverb modifier

Eigenschaft Typ Default Minmum Maximum Anmerkungen
Reverb_Density int 1000 0 1000
Reverb_Diffusion int 1000 0 1000
Reverb_Gain int 316 0 1000
Reverb_GainHF int 1000 0 1000
Reverb_Decay_Time int 2910 100 20000
Reverb_Decay_HFRatio int 1300 100 20000
Reverb_Reflections_Gain int 500 0 3160
Reverb_Reflections_Delay int 15 0 300
Reverb_Late_Reverb_Gain int 706 0 10000
Reverb_Late_Reverb_Delay int 22 0 100
Reverb_Air_Absorption_GainHF int 994 892 1000
Reverb_Room_Rolloff_Factor int 0 0 10000
Reverb_Decay_HFLimit bool true

Echo modifier

Eigenschaft Typ Default Minmum Maximum Beschreibung
Echo_Delay int 100 0 207 Time delay for first, centered echo.
Echo_LRDelay int 100 0 404 Time delay for secondary, panning echo.
Echo_Damping int 500 0 990 Amount of high-frequency damping.
Echo_Feedback int 500 0 1000 Amount of original signal fed into the echo. A value of 1000 would lead to an infinite echo.
Echo_Spread int -1000 -1000 +1000 Controls the amount of panning left and right, with the sign determining if the first jump is left or right. A value of zero means no echo panning.

Equalizer modifier

Eigenschaft Typ Default Minmum Maximum Anmerkungen
Equalizer_Low_Gain int 1000 126 7943
Equalizer_Low_Cutoff int 200000 50000 800000
Equalizer_Mid1_Gain int 1000 126 7943
Equalizer_Mid1_Center int 500000 200000 3000000
Equalizer_Mid1_Width int 1000 10 1000
Equalizer_Mid2_Gain int 1000 126 7943
Equalizer_Mid2_Center int 3000000 1000000 8000000
Equalizer_Mid2_Width int 1000 10 1000
Equalizer_High_Gain int 1000 126 7943
Equalizer_High_Cutoff int 6000000 4000000 16000000
Sven2, 2015-07