Setting Reverb Data of Rooms (EAX)

Originally written by Ishtvan on http://forums.thedarkmod.com/topic/2071

This document will attempt to explain how to set the new EAX settings in your rooms when mapping. After installing the patch on a separate D3 install than the one you use for the mod:

The EAX info for maps is stored in Doom3/pak007.pk4 , the file extension is <mapname>.EFX . They're plain text files so you can open them up in your text editor of choice. I think these files go in the maps directory along with your other map files.

What an EFX file looks like

Lets take a look at mars_city1.EFX. The first thing you'll notice is that it consists of separate blocks, one for each "reverb zone." Lets take a look at one of these blocks:

// reverb maintenance
reverb "maintenance" {
 "environment" 26
 "environment size" 5.0670
 "environment diffusion" 0.6030
 "room" -411
 "room hf" -685
 "room lf" 0
 "decay time" 1.7360
 "decay hf ratio" 0.8030
 "decay lf ratio" 1.0000
 "reflections" 96
 "reflections delay" 0.0080
 "reflections pan" 0.0000 0.0000 0.0000
 "reverb" 27
 "reverb delay" 0.0050
 "reverb pan" 0.0000 0.0000 0.0000
 "echo time" 0.0750
 "echo depth" 1.0000
 "modulation time" 0.2500
 "modulation depth" 0.0000
 "air absorption hf" -5.0000
 "hf reference" 5000.0000
 "lf reference" 250.0000
 "room rolloff factor" 0.0000
 "flags" 56
}

What does all this mean?

There is a lot of sound design stuff that one could make guesses at if you've ever used a reverb plugin in any sort of sound editing program. hf = high frequency, lf = low frequency, etc. Then it looks like there are some engine-specific flags like in the line:

"flags" 56

Below, I included a brief explanation of some reverb sound design variables.

How to associate a sound environment in an EFX file with a location in your map

reverb "<name of the location area you want to apply this to>"
{
    //... 
}

In D3 maps you can put in "location" entities so that something like "Corridor 5" pops up in the HUD. I think the names are func_location to define the location name, and func_location_separator, that you must put at the visportals leading out of your location to define the location boundaries. See the Id maps for more info on how to define location areas. In the EFX file, you can apply reverb to an entire location (ie, everywhere where the HUD says "corridor 5" has the same reverb characteristics).

Sometimes, you may not want to make a new location for a small area with different reverb (like a bathroom). In this case, you can specify portal area number directly in the EFX file, to specify reverb for just this portal area (remember a portal area is a "room" defined by where you place portals). This brings up the question of how you find out what portal area number a given area has? I'm not sure what the answer is at this time. I know there is an SDK function to find out that I've used in soundprop, but I don't know what the best way is for mappers. There might be a cvar that will display the area number when you're walking around in the map; I'm not sure. Please post if you know a good way to find out. Maybe the editor also tells you?

demagogue:  While there still may be a cvar to find it, one (inconvenient) way to find 
it is that the portal-area number is listed in the .proc file, which is created in the 
dmap process, in the format of _area# (where # is the portal area number, e.g., _area15.)
The mapper would need to open the .proc file with something like notepad.  One way to 
find the right area is to put a unique texture on one outer "wall" of the portal area, 
dmap, then search the .proc for that texture name (or some other distinguishing part 
of the mode { } entry you might see, like the wall's x y z coordinate), then search *up* 
for "area", and it will give you the portal _area# where that texture is used. 
(Be warned that the number may change in later dmaps and have to be updated in 
the EAX file, however.)  

All this said, since EAX can also be defined by location-name, currently it's probably 
easier for the mapper to just create a new location, name it, then define the EAX by that 
location's name.  So a mapper can do that and never have to worry about finding the portal 
area number.  It's just worth knowing that it's possible, and I can imagine situations 
where a mapper might want to use the portal number rather than the location name.  But as a 
general matter, especially for a beginner, it's safe to say that a mapper can get by just 
fine using the location name method and make life easier for himself.  The possibility that 
someone finds an easier way to find the portal area number and set EAX to it is still open, 
though. 

Anyway, to put in reverb for a given area number, just put the portal number after the reverb line in the EFX file, like so.

reverb "<portal area number>"
{
   //...
}

Finally, there is a "default" reverb environment which is used for any area in the map which does not have reverb information specified by either location area or portal area number. The order that the sound system checks for reverb data is: area number -> location name -> default. Brian says it again here:

"The sound system looks for the specific area number first (36) if it can't find that, it searches for the area name "Security Checkpoint", if it can't find that, it uses "default". In general I would recommend against using the area numbers. We only had to do that because there were some areas with the same name and we didn't want to change the map file."

Environment Properties

This information is from the official EAX 2.0 documentation. Although some properties may have changed in scope and focus from EAX 2.0 to EAX 4.0, one can assume that the properties serve the same general purpose and that each property's value bounds are approximately the same.

• environment - Unknown. Likely sets the room to one of an unknown number of environment presets.
• environment size - The Environment Size property sets the apparent size of the surrounding “room.” The value of Environment Size can be considered a characteristic dimension of the room expressed in meters. Scaling Environment Size is equivalent to scaling all dimensions of the room by the same factor. Value type is FLOAT; value range is 1.0 to 100.0, expressed in linear meters.
• environment diffusion - The Environment Diffusion property controls the echo density in the reverberation decay. Reducing diffusion gives the reverberation a more “grainy” character that is especially noticeable with percussive sound sources. If you set a diffusion value of 0.0, the later reverberation sounds like a succession of distinct echoes. Value type is FLOAT; value range is 0.0 to 1.0, expressed in a linear multiplier value.
• room - The Room property is the master volume control for the reflected sound (both early reflections and reverberation) that EAX adds to all sound sources. It sets the maximum amount of reflections and reverberation added to the sound mix in the primary buffer (the listener). Value is LONG; value range is -10000 to 0, expressed in hundredths of one decibel (-100 dB to 0 dB).
• room hf - The Room HF property further tweaks reflected sound by attenuating it at high frequencies. It controls a low-pass filter that applies globally to the reflected sound of all sound sources. The exact qualities of this low-pass filter -- its frequency and its bandwidth (Q) -- are unknown. Value type is LONG; value range is -10000 to 0, expressed in hundredths of one decibel (-100 dB to 0 dB).
• room lf - Undocumented. Assumably, the Room LF property applies a high-pass to reflected sound in much the same way as Room HF applies low-pass. The value type and range is unknown, but is likely LONG, must be between -10000 and 0 and is expressed in hundredths of one decibel.
• decay time - The Decay Time property sets the reverberation decay time, or the time in which reverberation is diminished. It ranges from 0.1 (typically a small room with very dead surfaces) to 20.0 (typically a large room with very live surfaces). Value is FLOAT; value range is 0.1 to 20.0, expressed in seconds.
• decay hf ratio - The Decay HF Ratio property sets the spectral quality of the Decay Time parameter. It is the ratio of high-frequency decay time relative to the time set by Decay Time. The Decay HF Ratio value 1.0 is neutral: the decay time is equal for all frequencies. As Decay HF Ratio increases above 1.0, the high-frequency decay time increases so it’s longer than the decay time at low frequencies. You hear a more brilliant reverberation with a longer decay at high frequencies. As the Decay HF Ratio value decreases below 1.0, the high-frequency decay time decreases so it’s shorter than the decay time of the low frequencies. You hear a more natural reverberation. Value is FLOAT; value range is 0.1 to 20.0, expressed in a linear multiplier variable.
• decay lf ratio - Undocumented. It's likely best to leave the value at 1.0, though the value's type and range is probably the same as the Decay HF Ratio property.
• reflections - The Reflections property controls the overall amount of initial reflections relative to the Room property. The value of Reflections ranges from a maximum of 10 dB to a minimum of -100 dB (no initial reflections at all), and is corrected by the value of the Room property. The Reflections property does not affect the subsequent reverberation decay. You can increase the amount of initial reflections to simulate a more narrow space or closer walls, especially effective if you associate the initial reflections increase with a reduction in reflections delays by lowering the value of the Reflection Delay property. To simulate open or semi-open environments, you can maintain the amount of early reflections while reducing the value of the Reverb property, which controls later reflections. Value type is LONG; value range is -10000 to 1000, expressed in hundredths of one decibel (-100 dB to -10 dB).
• reflections delay - The Reflections Delay property is the amount of delay between the arrival time of the direct path from the source to the first reflection from the source. It ranges from 0 to 300 milliseconds. You can reduce or increase Reflections Delay to simulate closer or more distant reflective surfaces—and therefore control the perceived size of the room. Value is FLOAT; value range is 0.0 to 0.3, expressed in seconds (0 to 300 milliseconds).
• reflections pan - Undocumented. Three values are specified which may correspond to a generic "front", "side" and "back/rear" configuration to control the directivity of early reflections in a 7.1 surround matrix. Value type and range is unknown.
• reverb - The Reverb property controls the overall amount of later reverberation relative to the Room property. (The Room property sets the overall amount of both initial reflections and later reverberation.) The value of Reverb ranges from a maximum of 20 dB to a minimum of -100 dB (no late reverberation at all). Value is LONG; value range is -10000 to 2000, expressed in hundredths of a decibel (-100 dB to 20 dB).
• reverb delay - The Reverb Delay property defines the begin time of the late reverberation relative to the time of the initial reflection (the first of the early reflections). It ranges from 0 to 100 milliseconds. Reducing or increasing Reverb Delay is useful for simulating a smaller or larger room. Value is FLOAT; value range is 0.0 to 0.1, expressed in seconds (0 to 100 milliseconds).
• reverb pan - Undocumented. Three values are specified which may correspond to a generic "front", "side" and "back/rear" configuration to control the directivity of reverberation in a 7.1 surround matrix. Value type and range is unknown.
• echo time - Undocumented. Likely controls the decay time of echoes, or late reflections. A value of 1.0 likely presents a natural amount of echo, while increasing the value likely causes a "Grand Canyon" effect. Value type is likely FLOAT; value range is likely between 0.0 and 20.0, expressed in seconds.
• echo depth - Undocumented. May control directionality or tonal qualities of echoes arriving at the listener. Probably best to leave at 1.0. Value type and range is unknown.
• modulation time - Undocumented. Unknown purpose. Value type and range is unknown.
• modulation depth - Undocumented. Unknown purpose. Value type and range is unknown.
• air absorption hf - The Air Absorption HF property controls the distance-dependent attenuation at high frequencies caused by the propagation medium. It applies to both the direct path and reflected sound. You can use Air Absorption HF to simulate sound transmission through foggy air, dry air, smoky atmosphere, and so on. The default value is -0.05 dB per meter, which roughly corresponds to typical condition of atmospheric humidity, temperature, and so on. Lowering the value simulates a more absorbent medium (more humidity in the air, for example); raising the value simulates a less absorbent medium (dry desert air, for example). Value is FLOAT; value range is -100.0 to 0.0, expressed in hundredths of one decibel per meter (-1 dB to 0 dB). Default value is -5.0, which corresponds to -0.05 dB per meter attenuation.
• hf reference - Likely defines the frequency used for low-pass filters. Value is likely LONG; value range is likely between 0.0 and 20000.0, expressed in Hz. This value is probably best left at 5000.0.
• lf reference - Likely defines the frequency used for high-pass filters. Value is likely LONG; value range is likely between 0.0 and 20000.0, expressed in Hz. This value is probably best left at 250.0.
• room rolloff factor - The Room Rolloff property is one of two methods available in EAX to attenuate the reflected sound (containing both reflections, reverberation and echoes) according to source-listener distance. Value type is FLOAT; value range is 0.0 to 10.0, expressed in a linear multiplier value. It's recommended that users use 0.0, as id Software did not deviate from this value with Doom 3.
• flags - The Flags property is intended to control the relationship of high-level EAX properties to low-level properties. If certain EAX flags are set by setting the Flags property to a particular value, the setting of high-level properties is supposed to control the values of low-level properties based upon a defined scale, overriding specified values. In EAX 2.0, the value type is DWORD, whereas in Doom 3, it appears to be INT or some other type commonly used to store numeric values. In Doom 3, common values are 0, 2, 15, 31, 32, 56 and 63, but no documentation details what these values correspond to. If users wish to experiment with the Flags property, it is recommended that they choose from one of the above values. For reference, here is a table with the counts for each flag value as used in Doom 3:

Flag decimal	Flag binary	Count
0	00000000	497
2	00000010	6
14	00001110	15
15	00001111	94
31	00011111	511
32	00100000	247
56	00111000	59
63	00111111	168

The Variables

In terms of the actual sound design for the values you put into these variables, here is a general tutorial on reverb from FruityLoops (NOTE: This is for a music production plugin, some of these don't apply, it's just to give a general idea on what certain variables do):

• Low Cut Adjusts the low cutoff frequency. Use this to remove low frequencies from the input signal before reverb is added. For example, if you are adding reverb to, say a drum track, you might want to remove some of the 'rumble' from the bass drum by attenuating the bass frequencies. Setting this parameter to the minimum value will bypass the Low Cut filter, displaying OFF in the value field.
• High Cut - Similar to the Low Cut, this adjusts the high cutoff frequency. Use this to remove high frequencies from the input signal.
• Predelay - Controls the delay time between the direct input signal and the first reverb reflection. This should be set to modest values for small rooms, and can be increased in relation to increases in room size. Predelay creates a slap-back echo effect that can both add atmosphere and muffle the signal, so use it wisely.
• Room Size - Use this to set the size of the virtual room where the reverb is created. The Room Size should be adjusted according to the decay time. Small rooms sound better with a short decay time, large rooms sound better with longer reverb times.
• Diffusion - Controls the density of the reflections bouncing off the walls of the virtual room. A low diffusion setting makes the reflections sound more distinct, like closely spaced echoes. A high diffusion setting creates reflections so close they sound more like noise, where no echoes can be distinguished.
• Color - The Color parameter is used for adjusting the decay time of the bass frequencies of the signal. This allows you to change the overall perceived mood or 'sound' of the virtual room. A bright room has a low bass response, while warm rooms have a higher bass response. In a flat room, the response of the bass is equal to the general frequency response. Color has five settings: Brighter, Bright, Flat, Warm, Warmer.
• Decay - Controls the decay time of the reverb, the time it takes for the signal to decay to -60dB (1/1000 of the maximum amplitude). Use low decay times for small rooms or boxes, and long decay times for large rooms, halls or churches. You should also make sure that the Room Size parameter has an appropriate value.
• High Damping - This parameter allows you to adjust damping of the high frequencies in the reverb signal over time. Damping refers to the high frequencies being attenuated and dying out. This causes the sound to become gradually muffled and warm like it is being absorbed in the room. Setting this parameter to the maximum value will bypass the High Damping, displaying OFF in the value field.
• Dry - Sets the relative dry output level.
• Reverb - Sets the relative reverb (wet) signal level.

See Also

A demonstration map of Environmental Audio Extensions (EAX) in TDM is included here.