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_ENABLE_SUB_DATA_EXT
  62 The more widely used AL_EXT_SOURCE_RADIUS extension is incompatible with the
  63 now-defunct AL_SOFT_buffer_sub_data extension. Setting this to "true" or "1"
  64 restores the AL_SOFT_buffer_sub_data extension for apps that require it,
  65 disabling AL_EXT_SOURCE_RADIUS.
  66
  67 __ALSOFT_REVERSE_Z
  68 Applications that don't natively use OpenAL's coordinate system have to convert
  69 to it before passing in 3D coordinates. Depending on how exactly this is done,
  70 it can cause correct output for stereo but incorrect Z panning for surround
  71 sound (i.e., sounds that are supposed to be behind you sound like they're in
  72 front, and vice-versa). Setting this to "true" or "1" will negate the localized
  73 Z coordinate to flip front/back panning for 3D sources.
  74
  75 __ALSOFT_REVERSE_Y
  76 Same as for __ALSOFT_REVERSE_Z, but for Y (up/down) panning.
  77
  78 __ALSOFT_REVERSE_X
  79 Same as for __ALSOFT_REVERSE_Z, but for X (left/right) panning.
  80
  81 __ALSOFT_VENDOR_OVERRIDE
  82 Overrides the value returned by alGetString(AL_VENDOR), for apps that misbehave
  83 without particular values.
  84
  85 __ALSOFT_VERSION_OVERRIDE
  86 Overrides the value returned by alGetString(AL_VERSION), for apps that
  87 misbehave without particular values.
  88
  89 __ALSOFT_RENDERER_OVERRIDE
  90 Overrides the value returned by alGetString(AL_RENDERER), for apps that
  91 misbehave without particular values.
  92
  93 __ALSOFT_DEFAULT_ERROR
  94 Applications that erroneously call alGetError prior to setting a context as
  95 current may not like that OpenAL Soft returns 0xA004 (AL_INVALID_OPERATION),
  96 indicating that the call could not be executed as there's no context to get the
  97 error value from. This can be set to 0 (AL_NO_ERROR) to let such apps pass the
  98 check despite the problem. Other applications, however, may see AL_NO_ERROR
  99 returned and assume any previous AL calls succeeded when they actually failed,
 100 so this should only be set when necessary.
 101
 102 __ALSOFT_SUSPEND_CONTEXT
 103 Due to the OpenAL spec not being very clear about them, behavior of the
 104 alcSuspendContext and alcProcessContext methods has varied, and because of
 105 that, previous versions of OpenAL Soft had them no-op. Creative's hardware
 106 drivers and the Rapture3D driver, however, use these methods to batch changes,
 107 which some applications make use of to protect against partial updates. In an
 108 attempt to standardize on that behavior, OpenAL Soft has changed those methods
 109 accordingly. Setting this to "ignore" restores the previous no-op behavior for
 110 applications that interact poorly with the new behavior.