superbuild/modules/openal-soft/docs/env-vars.txt

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.

__ALSOFT_REVERB_IGNORES_SOUND_SPEED
Older versions of OpenAL Soft ignored the app-specified speed of sound when
calculating distance-related reverb decays and always assumed the default
343.3m/s. Now, both of the AL_SPEED_OF_SOUND and AL_METERS_PER_UNIT properties
are taken into account for speed of sound adjustments to have an appropriate
affect on the reverb decay. Consequently, applications that use reverb but
don't set these properties properly may find the reverb decay too strong.
Setting this to "true" or "1" will revert to the old behavior for those apps
and assume the default speed of sound for reverb.