docs/env-vars.txt

   1 Useful Environment Variables
   2
   3 Below is a list of environment variables that can be set to aid with running or
   4 debugging apps that use OpenAL Soft. They should be set before the app is run.
   5
   6 *** Logging ***
   7
   8 ALSOFT_LOGLEVEL
   9 Specifies the amount of logging OpenAL Soft will write out:
  10 0 - Effectively disables all logging
  11 1 - Prints out errors only
  12 2 - Prints out warnings and errors
  13 3 - Prints out additional information, as well as warnings and errors
  14
  15 ALSOFT_LOGFILE
  16 Specifies a filename that logged output will be written to. Note that the file
  17 will be first cleared when logging is initialized.
  18
  19 *** Overrides ***
  20
  21 ALSOFT_CONF
  22 Specifies an additional configuration file to load settings from. These
  23 settings will take precedence over the global and user configs, but not other
  24 environment variable settings.
  25
  26 ALSOFT_DRIVERS
  27 Overrides the drivers config option. This specifies which backend drivers to
  28 consider or not consider for use. Please see the drivers option in
  29 alsoftrc.sample for a list of available drivers.
  30
  31 ALSOFT_DEFAULT_REVERB
  32 Specifies the default reverb preset to apply to sources. Please see the
  33 default-reverb option in alsoftrc.sample for additional information and a list
  34 of available presets.
  35
  36 ALSOFT_TRAP_AL_ERROR
  37 Set to "true" or "1" to force trapping AL errors. Like the trap-al-error config
  38 option, this will raise a SIGTRAP signal (or a breakpoint exception under
  39 Windows) when a context-level error is generated. Useful when run under a
  40 debugger as it will break execution right when the error occurs, making it
  41 easier to track the cause.
  42
  43 ALSOFT_TRAP_ALC_ERROR
  44 Set to "true" or "1" to force trapping ALC errors. Like the trap-alc-error
  45 config option, this will raise a SIGTRAP signal (or a breakpoint exception
  46 under Windows) when a device-level error is generated. Useful when run under a
  47 debugger as it will break execution right when the error occurs, making it
  48 easier to track the cause.
  49
  50 ALSOFT_TRAP_ERROR
  51 Set to "true" or "1" to force trapping both ALC and AL errors.
  52
  53 *** Compatibility ***
  54
  55 __ALSOFT_HALF_ANGLE_CONES
  56 Older versions of OpenAL Soft incorrectly calculated the cone angles to range
  57 between 0 and 180 degrees, instead of the expected range of 0 to 360 degrees.
  58 Setting this to "true" or "1" restores the old buggy behavior, for apps that
  59 were written to expect the incorrect range.
  60
  61 __ALSOFT_REVERSE_Z
  62 Applications that don't natively use OpenAL's coordinate system have to convert
  63 to it before passing in 3D coordinates. Depending on how exactly this is done,
  64 it can cause correct output for stereo but incorrect Z panning for surround
  65 sound (i.e., sounds that are supposed to be behind you sound like they're in
  66 front, and vice-versa). Setting this to "true" or "1" will negate the localized
  67 Z coordinate to flip front/back panning for 3D sources.
  68
  69 __ALSOFT_REVERSE_Y
  70 Same as for __ALSOFT_REVERSE_Z, but for Y (up/down) panning.
  71
  72 __ALSOFT_REVERSE_X
  73 Same as for __ALSOFT_REVERSE_Z, but for X (left/right) panning.
  74
  75 __ALSOFT_SUSPEND_CONTEXT
  76 Due to the OpenAL spec not being very clear about them, behavior of the
  77 alcSuspendContext and alcProcessContext methods has varied, and because of
  78 that, previous versions of OpenAL Soft had them no-op. Creative's hardware
  79 drivers and the Rapture3D driver, however, use these methods to batch changes,
  80 which some applications make use of to protect against partial updates. In an
  81 attempt to standardize on that behavior, OpenAL Soft has changed those methods
  82 accordingly. Setting this to "ignore" restores the previous no-op behavior for
  83 applications that interact poorly with the new behavior.