--[[

    Copyright (C) 2012-2019 John-Paul Ownby
    All Rights Reserved

]]
--[[

    This file can be used to configure the capabilities and behavior
    of the audio hardware that IndirectSound emulates.

    There are two different ways that this file can be used:
      * Local
        * You can use a copy of this file to configure how
          IndirectSound behaves for a specific game
      * Global
        * You can use a copy of this file to configure how
          IndirectSound behaves for all games

    In order for IndirectSound to use a local copy of this file
    for a specific game you must:
      * Create a copy of this file in the same directory
        where dsound.dll is located for the specific game
      * Local copies of this file must be named:
          dsound.ini

    In order for IndirectSound to use a global copy of this file
    for all games you must:
      * Create a copy of this file in the directory of your choice
      * Create the following registry key:
          Computer\HKEY_CURRENT_USER\Software\IndirectSound
      * Create either a new String Value or a new Exandable String Value
        (REG_SZ or REG_EXPAND_SZ) and name it:
          GlobalSettingsPath
      * Assign the path of your global file as the new value's data
    A path assigned to a REG_SZ must be absolute. For example:
        C:\Users\John-Paul\Documents\IndirectSound\dsound.ini
    A path assigned to a REG_EXPAND_SZ may contain environment variables:
        %AppData%\IndirectSound\dsound.ini
    The local file must be named "dsound.ini",
    but the global file can be named anything that you wish.
    For example, the following would also be a valid filename:
        C:\Users\John-Paul\MyGlobalIndirectSoundFile.txt
    USE CAUTION WHEN CHANGING THE REGISTRY!
    Making invalid changes can cause your computer
    to not function correctly!

    It is possible to use local and global files simultaneously
    (IndirectSound will look for and use both if they exist).
    If both files configure the same setting
    the local file's value for that setting
    will override the global file's value.
    You could, for example, use a global file to configure
    IndirectSound to behave the way that you usually want it to
    and then use local files in those unusual cases when
    you want to override specific settings for specific games.
    (Note that neither the local nor global file is required
    to configure every available setting.
    You may choose to just configure what you care about
    and remove everything else from the file
    so that IndirectSound uses the default values.)

    This file only has an "ini" extension for convenience
    so that it can be opened by double-clicking it,
    but it is actually Lua (not a Microsoft INI file)
    and must contain valid Lua syntax.
      * To find out more about Lua, visit:
          www.lua.org
      * IndirectSound uses Lua 5.2.1

]]

--[[=========================================================================]]

-- hardwareBufferCount
--====================

--[[

    This setting determines how many hardware buffers will be emulated.
    Using hardware acceleration enables:
      * Multichannel 3D positional sound
      * Audio hardware extensions like EAX

    As a point of reference, the following list shows how many
    hardware accelerated buffers some real sound cards support:
      * Sound Blaster Live!: 32
      * Sound Blaster Audigy2: 64
      * Sound Blaster X-Fi: 128

    Emulated hardware buffers require more processing power
    than standard DirectSound software buffers;
    decrease the hardware buffer count if using
    IndirectSound causes games to run slowly on your machine.
    (You may also increase it if you wish to experiment.)

    Setting this number to 0 has the same effect as setting the
    "Hardware Acceleration" slider in the control panel to "Basic"
    on older versions of Windows.

]]

hardwareBufferCount = 128

--[[=========================================================================]]

-- EAX
--====

--[[

    EAX ("Environmental Audio Extensions") is not emulated by IndirectSound.

    IndirectSound can emulate EAX support, however.
    In other words, IndirectSound will pretend that EAX is supported
    so that games using IndirectSound will think that EAX is available.
    This is useful for some games that don't calculate
    3D positional audio unless EAX is supported.

    (Actual emulation of EAX is under development
    but is not yet ready to release.)

    There are two versions of EAX with emulated support:
      * EAX 1.0
      * EAX 2.0
    Support for later versions of EAX is not yet emulated.

    To emulate support for a specific EAX version
    set the corresponding value to "true" (with no quotes), e.g.:

      eax2 = true

    To disable emulated support set the value to false.

    Disabling EAX has the same effect as setting the
    "Hardware Acceleration" slider in the control panel to "Standard"
    on older versions of Windows.

]]

eax1 = false
eax2 = false

--[[=========================================================================]]

-- surroundPanning
--================

--[[

    IndirectSound supports the following algorithms for
    calculating what volume to play a 3D sound at in each speaker
    based on the configuration of your physical speakers and the
    sound's position in the game world relative to the listener:
      * "constantPower"
        * The power of a sound will be kept constant
          as it is blended between two adjacent speakers
        * This is sometimes referred to as -3 dB panning
        * This is the default and is how Sound Blaster hardware behaved
          on earlier Windows operating systems
      * "linear"
        * The amplitude of a sound will be kept constant
          as it is blended between two adjacent speakers
        * This can also be referred to as "constant amplitude"
          or -6 dB panning
        * This can result in a perceptual "hole in the middle"
          where a sound seems softer when it is between two speakers
          and louder when it is lined up with a single speaker
      * "compromise"
        * This is a compromise between constant power and linear panning
        * It is sometimes referred to as -4.5 dB panning

    To choose one of these algorithms set the option with quotes, e.g.:

      surroundPanning = "yourDesiredAlgorithm"

    Note that this setting only determines the behavior of
    the hardware buffers that IndirectSound emulates;
    DirectSound itself will control the behavior of
    any buffers played in software.

]]

surroundPanning = "constantPower"

--[[=========================================================================]]

-- speakerAngles
--==============

--[[

    In order to calculate what volume to play
    a 3D sound at in each individual speaker
    IndirectSound must know where your actual physical speakers are located.
    By default IndirectSound will behave the same way that
    Sound Blaster hardware did on earlier Windows operating systems
    based on your audio device's current speaker configuration,
    but the 3D positional audio effect can be improved by definining values
    that accurately describe your physical speaker's actual positions.

    An angle can be defined for each speaker. The possible angle names are:
        * speakerAngle_frontLeft
        * speakerAngle_frontCenter
        * speakerAngle_frontRight
        * speakerAngle_sideLeft
        * speakerAngle_sideRight
        * speakerAngle_rearLeft
        * speakerAngle_rearCenter
        * speakerAngle_rearRight
        * speakerAngle_frontLeftOfCenter
        * speakerAngle_frontRightOfCenter

    Angles should be specified in degrees (i.e. not radians)
    and define the horizontal angle between the
    direction your head faces and the center of a speaker.
    If you have a speaker that is directly in front of you
    its angle would be 0°.
    Speakers to your right (clockwise)
    should be defined with positive angles
    and speakers to your left (counterclockwise)
    should be defined with negative angles.
    If you have a speaker directly to your right
    its angle would be 90°,
    if you have a speaker directly to your left
    its angle would be -90°,
    and if you have a speaker that is directly behind you
    its angle could be either 180° or -180°.

    For example, the following is how you would define speaker angles
    using the default values that Sound Blaster hardware used
    for 5.1 speaker configurations on earlier Windows operating systems:

        speakerAngle_frontLeft = -30
        speakerAngle_frontCenter = 0
        speakerAngle_frontRight = 30
        speakerAngle_rearLeft = -120
        speakerAngle_rearRight = 120

    (If you have a 5.1 home theater speaker configuration
    you would define side speaker angles instead of rear speakers angles.
    You can look at the generated dsound.log file to verify
    that IndirectSound is actually using the values that you intend it to.)

    Note that this setting only determines the behavior of
    the hardware buffers that IndirectSound emulates;
    DirectSound itself will control the behavior of
    any buffers played in software.

]]

--[[=========================================================================]]

-- maxFrequencyRatio
--==================

--[[

    This setting determines how high
    the frequency (pitch) of a sound can be increased.
    Higher values increase memory usage.

    The "frequency ratio" is the ratio of the desired frequency
    to the frequency of the sound's original sample rate.
    For example, a frequency ratio of 2
    means that a sound will be played twice as fast
    (which will make it sound twice as high in pitch).

    If the application tries to use a frequency ratio
    that is greater than maxFrequencyRatio
    a message will be output in the dsound.log file
    telling you which value to use for maxFrequencyRatio
    for that particular game to hear the correct higher frequencies.

    For example, if the log file says that the application
    tried to set a frequency ratio of 2.45909 then you should
    change the maximum to something a bit larger:
        maxFrequencyRatio = 2.5

    Note that this setting only determines the behavior of
    the hardware buffers that IndirectSound emulates;
    DirectSound itself will control the behavior of
    any buffers played in software.

]]

maxFrequencyRatio = 2

--[[=========================================================================]]

-- monoSourceBehavior
--===================

--[[

    There are two ways that audio hardware can play
    a 2D sound with only one source channel ("mono"):
      * "center"
        * The sound will play out of the front center speaker
        * This is the default and is how DirectSound behaves
          on modern Windows operating systems
        * This could be considered Microsoft's reference/intended behavior,
          but may not represent the authentic behavior
          that an application's developer intended
      * "frontLeftAndRight"
        * The sound will play out of the front left and right speakers
        * This is how Sound Blaster hardware behaved
          on earlier Windows operating systems
        * This could be considered the more authentic behavior
          because it represents how an application's developer
          probably would have heard mono sounds

    To choose one of these modes set the option with quotes, e.g.:

      monoSourceBehavior = "yourDesiredMode"

    Note that this setting only determines the behavior of
    the hardware buffers that IndirectSound emulates;
    DirectSound itself will control the behavior of
    any buffers played in software.

    Also note that if a buffer's format has a dwChannelMask field
    then that will be respected and this setting will be ignored.

]]

monoSourceBehavior = "center"

--[[=========================================================================]]

-- disabled3dBehavior
--===================

--[[

    DirectSound allows every 3D sound to be assigned a mode
    that determines how the 3D will be calculated,
    and one of those possible modes is to disable 3D processing.
    The DirectSound documentation describes the effect of this mode as:

      "The sound seems to originate from the center of the listener's head."

    IndirectSound supports the following behaviors
    when 3D processing is disabled on a 3D sound:
      * "2D"
        * The sound will play exactly as it would if it were not a 3D sound
        * This is the default and is how Sound Blaster hardware behaved
          on earlier Windows operating systems
          * Note that in order to match Creative's implementation exactly
            the "monoSourceBehavior" option
            must also be set to "frontLeftAndRight"
        * This could be considered the more authentic behavior
          because it represents how an application's developer
          probably would have heard 3D sounds with disabled processing
      * "all"
        * The sound will play at full volume out of all speakers
          except the subwoofer LFE channel
          * Stereo sources will play both channels out of each speaker,
            which can make them sound much louder than they do
            under the default "2D" behavior
        * This is how DirectSound behaves
          on modern Windows operating systems
          (except that Windows also plays the sound at full volume
          out of the subwoofer, which is presumably a bug)
        * This could be considered Microsoft's reference/intended behavior,
          but may not represent the authentic behavior
          that an application's developer intended
      * "normalized"
        * Identical to "all" except that rather than playing at full volume
          a sound is attenuated based on the number of speakers.
        * This is how IndirectSound plays a 3D sound
          that is located exactly at the listener's head
      * "ambient"
        * The sound will play out of all speakers
          except the front center and subwoofer LFE channel
          * Stereo sources will maintain stereo separation
            in all left/right speaker pairs that exist

    To choose one of these behaviors set the option with quotes, e.g.:

      disabled3dBehavior = "yourDesiredBehavior"

    If you wish to choose different behaviors for mono and stereo sources
    you can do so with the following syntax:

      disabled3dBehavior =
      {
        mono = "yourDesiredBehaviorForMonoSources",
        stereo = "yourDesiredBehaviorForStereoSources"
      }

    Note that this setting only determines the behavior of
    the hardware buffers that IndirectSound emulates;
    DirectSound itself will control the behavior of
    any buffers played in software.

]]

disabled3dBehavior = "2D"

--[[=========================================================================]]

-- earlyStopFadeOutTime
--=====================

--[[

    This setting can fade out a sound that is stopped before it is finished
    rather than halting playback immediately.

    By default IndirectSound will stop playing a sound
    as soon as an application requests it.
    This can result in digital noise (e.g. pops, clicks, or scratches)
    if the application stops a sound's playback while it is audible.

    When this value is greater than zero IndirectSound will
    fade sounds out rather than stopping them immediately
    in order to prevent unpleasant digital noise.

    The value of this setting is the duration of the fade in seconds.
    For example, the following specifies a fade out time of 1 millisecond:

      earlyStopFadeOutTime = 0.001

    You should choose short fade out times.
    0.001 (1 ms) is a good initial value to try, and you should probably
    not use a value greater than 0.01 (10 ms).
    Not only will longer durations change the behavior of an application
    (sounds won't stop when they should),
    but you may also start to hear artifacts with streaming sounds repeating
    that are worse than the problem this setting is intended to solve.

    Note that there are some situations where this setting won't work
    (e.g. if an application destroys a sound buffer then
    playback will stop immediately even if the sound isn't fully faded out).

]]

earlyStopFadeOutTime = 0

--[[=========================================================================]]

-- nearDistanceToStartNormalizing
--===============================

--[[

    This setting determines the behavior of
    a 3D sound when it is close to the listener in the game world.

    Starting at nearDistanceToStartNormalizing,
    as a 3D sound gets closer to the listener
    it will gradually be played more and more in all speakers
    (rather than in a specific direction)
    until it becomes coincident with the listener,
    at which point it will play in all speakers equally
    (i.e. it is "normalized").

    Some older games rely on this behavior
    and play 3D sounds that are intended to be heard in all speakers
    even though they are located slightly offset from the listener
    (footsteps and weapon sounds are two common examples).

    The strange default value has no known physical meaning;
    it was discovered by observing Sound Blaster hardware behavior
    on earlier Windows operating systems.

    Normalization can be prevented
    by setting nearDistanceToStartNormalizing to 0.

    Note that this setting only determines the behavior of
    the hardware buffers that IndirectSound emulates;
    DirectSound itself will control the behavior of
    any buffers played in software.

]]

nearDistanceToStartNormalizing = 0.083

--[[=========================================================================]]

-- speedOfSound
--=============

--[[

    This setting determines the speed of sound that
    IndirectSound uses to calculate Doppler shift.
    It should be specified in meters per second.

    The default is 343.5 m/s, and is what DirectSound uses
    on modern Windows operating systems.
    The speed of sound at 20 °C ("room temperature")
    under normal atmospheric conditions at sea level
    is 343.21 m/s, according to Wikipedia.

    Note that this setting only determines the behavior of
    the hardware buffers that IndirectSound emulates;
    DirectSound itself will control the behavior of
    any buffers played in software.

]]

speedOfSound = 343.5

--[[=========================================================================]]

-- milesCompatibility
--===================

--[[

    The Miles Sound System middleware is used by many games.
    Partial lists can be found at the following two sites:
      www.radgametools.com/mssgames.htm
      http://satsun.org/audio/

    This setting should be false
    if you are playing a game that does not use Miles.
    When playing a game that does use Miles
    you may prefer the 3D audio behavior when this setting is true.

    Many versions of Miles expect a 5.1 rear speaker configuration
    and may not work with properly with other speaker configurations
    (e.g. the side speakers in a 7.1 configuration may not be used
    or no surround will be output for 5.1 or 7.1 home theater configurations).

    When this setting is true the behavior of IndirectSound changes:
      * If an application asks what speaker configuration your computer has
        IndirectSound will always report 5.1 with rear speakers
      * The mixing that Miles calculates internally is converted into
        the appropriate volumes for your actual speaker configuration

    Even if you have a 5.1 rear speaker configuration
    you may consider enabling this setting because
    IndirectSound will use your specified speakerAngles for
    greater positional accuracty than the default Miles behavior.

    Note that some games by Valve have a built-in option to do this.
    If you have changed snd_legacy_surround to 1 in the game's console
    then this setting should be false.
    If snd_legacy_surround is 0 (the default)
    then it is appropriate to change this setting to true.
    (If you have specified speakerAngles then 3D positioning may be
    more accurate if snd_legacy_surround is 0 and this setting is true.)

]]

milesCompatibility = false

--[[=========================================================================]]

--[[

    You can verify that IndirectSound is finding this file
    and that it really is using the values that you want it to
    by looking at the log file "dsound.log".
    IndirectSound will generate a new dsound.log in the same directory where
    dsound.dll is located every time that it is loaded by an application.
    If the dsound.log file isn't generated consult the
    readme.txt file for troubleshooting tips.

    Look in the dsound.log file for the following line:
        Initializing User Settings
    Immediately after that line there will be a message for each
    user settings file (global and local) that IndirectSound loads,
    and additional messages if a user settings file can't be loaded.

    Next the log file will display a message for each setting
    that can possibly be configured in this file
    and report the value that IndirectSound actually used.
    (It will also indicate if a default value is being used,
    either because no overriding value was found in a user settings file
    or because an override was found but was invalid.)

]]