View source for Sound Propagation: Part 1

{{Original_Reference|Ishtvan|3271}}

= Mapping and Sound Propagation: Part 1 =
Assumed knowledge: How to place [[Visportals]], doors and breakable windows.

== Portals and Caulking ==
First of all, all sound propagation (both TDM soundprop and the D3 sound engine) depends on visportals to define the apertures between rooms. It is therefore essential that your map be portalized and caulked correctly. Ideally, all concave rooms should be broken up into convex sections by visportals. This is a good rule for getting performance out of your maps in general (as long as you can't see too many separate portals from any given portal). Occasionally, you may have a concave room where breaking it up into two convex areas with a visportal isn't necessary for improving renderer performance, but is necessary for believable sound propagation.

Caulking is important, because the renderer uses it to distinguish separate portal areas. If you have any caulking leaks between areas that you intend to be separated, this will cause serious errors in soundprop, not to mention a decrease in performance from the D3 renderer.

Anything that can change the attenuation of sound going between two rooms needs to interface with soundprop.

=== Note ===
The sound propagation code works ideally for '''rectangles''' now. In case anyone's curious, this is the part of the code that finds the minimum path length for paths that are constrained to go thru certain portals. I.e., it calculates what points on the portal surfaces the sound path should pass through to get the least distance path.

If the visportal does not have four sides, sound is just passed through the center. This will be okay for smaller visportals, but the error (path difference from the minimal path) will get more noticeable the larger the visportal. '''The code also still assumes that when you do have four sides, they are perpendicular.''' If you have some non-90 degree angles between the sides, some wierdness may ensue.

== Doors & Openable Windows (atdm:mover_door) ==
A visportal must be placed within the door if you want the door to have any effect on sound propagation when it opens/closes.

Doors and Windows are the same as seen by the code. They are both covered by atdm:mover_door. It's probably easiest to list the relevant key/value pairs from the def file:

* '''loss_open'''    "Soundprop: Acoustical loss applied to sounds going thru the door when it is open (default 1 dB)"
* '''loss_closed'''    "Soundprop: Acoustical loss applied to sounds going thru the door when it is completely closed (default 10 dB)"
* '''loss_double_open'''    "Soundprop: Acoustical loss applied to sounds going thru a set of double doors when one is open and the other is closed (defaults to 1 dB)"

{{red|Rev 2.00:}}

Prior to Rev 2.00, these values affected the sound propagation to AI '''only'''.  Sound propagation to the player was not affected.

Starting with Rev 2.00, these values are also used in determining sound volume to the player. This aligns what AI hear with what the player hears. It also allows sound coming through the door to increase as the door opens, or decrease as the door closes, making for a more realistic experience.

== Breakable Windows (func_fracture) ==
Again, a visportal must be placed within a breakable window if you want its breaking to have any effect on sound propagation. (Actually, the sound of it breaking will still be propagated regardless of whether a visportal is inside. What I mean is, if you want it to block sound from going through at first, and then let sound through when it's broken, it must have a visportal placed within its bounds)

Relevant values in the def file:

* '''editor_var loss_unbroken'''    "soundprop: Acoustical loss experienced by sounds going through the unbroken fracture surface.  Must have visportal present to work."

NOTE: This number should probably be a bit higher than a loss for an ordinary door, because windows are usually more airtight than doors, which have spaces underneath and above.

* '''editor_var loss_broken'''    "soundprop: Acoustical loss experienced by sounds going through the surface after it's shattered.  Must have visportal present to work."

{{red|Rev 2.00:}}

Prior to Rev 2.00, these values affected the sound propagation to AI '''only'''.  Sound propagation to the player was not affected.

Starting with Rev 2.00, these values are also used in determining sound volume to the player.

== Solid, unbreakable windows (and portal attenuation in general) ==
Suppose you have a transparent window looking outside from a room, that for whatever reason is not a breakable, func_fracture window. Because it's transparent, the renderer and consequently soundprop will view it as connected with the outside area. You'll have to do two things to get soundprop to attenuate sounds when going through that unbreakable window.

# Place a visportal in the window (you'll probably want to do this for performance reasons anyway). At this stage, soundprop will think it is a hole in the wall. It doesn't know about the window there blocking the sound.
# Place an info_locationSeparator entity or info_portalSettings entity so that it's touching the visportal. Use the former if you're also marking a location zone boundary, and the latter if both sides of the portal belong to the same location zone.
# Set the portal attenuation value ('''sound_loss''', again in dB) on the info_locationseparator or info_portalSettings.

Soundprop can use these two entities to make sound incur a certain loss when going through the portal they're touching. The key/value pair is the following:

* '''sound_loss'''    "Soundprop: Loss in dB incurred when a sound travels through this portal. Cumulative with door loss if a door is present."

The loss must be a positive number, and negative numbers will automatically be converted to positive.

The info_locationseparator you place to set sound loss at a portal doesn't have to be simultaneously used to "properly" define a location, but it can be. In practice, you will probably be setting up some locations to take advantage of the ambient sounds and D3 EAX soundengine, and naturally you would have a different EAX environment for inside/outside areas, which requires different locations for these two places, so you would already want to put a visportal and location separator on transparent windows.

NOTE: Opaque windows don't need a visportal or any of this. They should already separate the inside and outside areas.

{{red|Rev. 2.00}}

The '''sound_loss''' value can affect the sound propagation to both the player and/or AI. Starting in Rev. 2.00, you can place the following spawnargs on both an info_locationSeparator and an info_portalSettings:

* '''apply_loss_to_AI'''    "Apply (1) or don't apply (0) sound loss to propagated sounds. Default is 1."
* '''apply_loss_to_Player'''    "Apply (1) or don't apply (0) sound loss to what the Player hears. Default is 1."

== Setting Portal Attenuation Directly with Scripting ==
If you know the handle of the portal (which you will need to use some D3 debug settings to find out), you can also set the portal attenuation directly, and get it, with these scriptfunctions called on the sys object.

 void    setPortSoundLoss( float handle, float value ) (Sets '''sound_loss''' for both AI and the Player)
 float   getPortSoundLoss( float handle ) (Gets '''sound_loss''')
 {{red|Rev. 2.00:}}
 void    setPortAISoundLoss( float handle, float value) (Sets AI-only '''sound_loss''' w/o affecting any Player-only '''sound_loss''')
 void    setPortPlayerSoundLoss( float handle, float value) (Sets Player-only '''sound_loss''' w/o affecting any AI-only '''sound_loss''')
 float   getPortAISoundLoss( float handle ) (Gets AI-only '''sound_loss''')
 float   getPortPlayerSoundLoss( float handle ) (Gets Player-only '''sound_loss''')

These can be used to dynamically alter the flow of sound in the map in cases where the door/window code is not sufficient (for example, pushing aside a large crate that was covering a sound-conducting passage to another room).

{{tutorial-sound}}
{{tutorial-scripting}}