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:

Constant	Effect
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

Property	Type	Default	Minmum	Maximum
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

Property	Type	Default	Minmum	Maximum	Description
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

Property	Type	Default	Minmum	Maximum
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