1 files changed, 81 insertions, 0 deletions
diff --git a/docs/env-vars.txt b/docs/env-vars.txt
new file mode 100644
index 00000000..b2268643
--- /dev/null
+++ b/docs/env-vars.txt
@@ -0,0 +1,81 @@
+Useful Environment Variables
+
+Below is a list of environment variables that can be set to aid with running or
+debugging apps that use OpenAL Soft. They should be set before the app is run.
+
+*** Logging ***
+
+ALSOFT_LOGLEVEL
+Specifies the amount of logging OpenAL Soft will write out:
+0 - Effectively disables all logging
+1 - Prints out errors only
+2 - Prints out warnings and errors
+3 - Prints out additional information, as well as warnings and errors
+4 - Same as 3, but also device and context reference count changes. This will
+    print out *a lot* of info, and is generally not useful unless you're trying
+    to track a reference leak within the library.
+
+ALSOFT_LOGFILE
+Specifies a filename that logged output will be written to. Note that the file
+will be first cleared when logging is initialized.
+
+*** Overrides ***
+
+ALSOFT_CONF
+Specifies an additional configuration file to load settings from. These
+settings will take precedence over the global and user configs, but not other
+environment variable settings.
+
+ALSOFT_DRIVERS
+Overrides the drivers config option. This specifies which backend drivers to
+consider or not consider for use. Please see the drivers option in
+alsoftrc.sample for a list of available drivers.
+
+ALSOFT_DEFAULT_REVERB
+Specifies the default reverb preset to apply to sources. Please see the
+default-reverb option in alsoftrc.sample for additional information and a list
+of available presets.
+
+ALSOFT_TRAP_AL_ERROR
+Set to "true" or "1" to force trapping AL errors. Like the trap-al-error config
+option, this will raise a SIGTRAP signal (or a breakpoint exception under
+Windows) when a context-level error is generated. Useful when run under a
+debugger as it will break execution right when the error occurs, making it
+easier to track the cause.
+
+ALSOFT_TRAP_ALC_ERROR
+Set to "true" or "1" to force trapping ALC errors. Like the trap-alc-error
+config option, this will raise a SIGTRAP signal (or a breakpoint exception
+under Windows) when a device-level error is generated. Useful when run under a
+debugger as it will break execution right when the error occurs, making it
+easier to track the cause.
+
+ALSOFT_TRAP_ERROR
+Set to "true" or "1" to force trapping both ALC and AL errors.
+
+*** Compatibility ***
+
+__ALSOFT_HALF_ANGLE_CONES
+Older versions of OpenAL Soft incorrectly calculated the cone angles to range
+between 0 and 180 degrees, instead of the expected range of 0 to 360 degrees.
+Setting this to "true" or "1" restores the old buggy behavior, for apps that
+were written to expect the incorrect range.
+
+__ALSOFT_REVERSE_Z
+Applications that don't natively use OpenAL's coordinate system have to convert
+to it before passing in 3D coordinates. Depending on how exactly this is done,
+it can cause correct output for stereo but incorrect Z panning for surround
+sound (i.e., sounds that are supposed to be behind you sound like they're in
+front, and vice-versa). Setting this to "true" or "1" will negate the localized
+Z coordinate to attempt to fix output for apps that have incorrect front/back
+panning.
+
+__ALSOFT_SUSPEND_CONTEXT
+Due to the OpenAL spec not being very clear about them, behavior of the
+alcSuspendContext and alcProcessContext methods has varied, and because of
+that, previous versions of OpenAL Soft had them no-op. Creative's hardware
+drivers and the Rapture3D driver, however, use these methods to batch changes,
+which some applications make use of to protect against partial updates. In an
+attempt to standardize on that behavior, OpenAL Soft has changed those methods
+accordingly. Setting this to "ignore" restores the previous no-op behavior for
+applications that interact poorly with the new behavior.