au.DisableBinauralSpatialization

au.DisableBinauralSpatialization

#Overview

name: au.DisableBinauralSpatialization

The value of this variable can be defined or overridden in .ini config files. 1 .ini config file referencing this setting variable.

This variable is created as a Console Variable (cvar).

• type: Var
• help: Disables binaural spatialization.\n

It is referenced in 6 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of au.DisableBinauralSpatialization is to control the enabling or disabling of binaural spatialization in Unreal Engine’s audio system. Binaural spatialization is a technique used to create a more immersive 3D audio experience, particularly for headphone users.

This setting variable is primarily used by the audio subsystem of Unreal Engine. It is referenced in the Engine’s AudioDevice.cpp file, indicating its core importance to the audio rendering process. Additionally, it is utilized in the Lyra project’s settings management, suggesting that it can be exposed to end-users for configuration.

The value of this variable is set through the console variable system. It’s initialized with a default value of 0 (enabled) and can be modified at runtime through console commands or game settings.

The associated variable DisableBinauralSpatializationCVar directly interacts with au.DisableBinauralSpatialization. They share the same value, with DisableBinauralSpatializationCVar being the actual int32 variable that the engine checks when determining if binaural spatialization should be disabled.

Developers must be aware that:

1. This variable affects the entire audio system’s binaural spatialization capabilities.
2. It can be overridden by game settings, as seen in the Lyra project’s implementation.
3. Some platforms may have restrictions on modifying this setting, as indicated by the CanModifyHeadphoneModeEnabled() function in the Lyra project.

Best practices when using this variable include:

1. Providing user-facing options to toggle this setting when appropriate for your game.
2. Checking platform compatibility before allowing modifications to this setting.
3. Understanding the performance implications of enabling or disabling binaural spatialization for your specific use case.

Regarding the associated variable DisableBinauralSpatializationCVar:

• Its purpose is to provide a quick, thread-safe way to check the state of binaural spatialization within the engine’s code.
• It is used directly in the FAudioDevice::IsHRTFDisabled function to determine if HRTF (Head-Related Transfer Function) should be applied.
• The value is set automatically when au.DisableBinauralSpatialization is modified.
• Developers should generally interact with au.DisableBinauralSpatialization rather than DisableBinauralSpatializationCVar directly, as the console variable system provides additional functionality and thread-safety.

#Setting Variables

#References In INI files

Location: <Workspace>/Projects/Lyra/Config/Android/AndroidEngine.ini:19, section: [ConsoleVariables]

• INI Section: ConsoleVariables
• Raw value: 1
• Is Array: False

#References in C++ code

#Callsites

This variable is referenced in the following C++ source code:

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/AudioDevice.cpp:149

Scope: file

Source code excerpt:

static int32 DisableBinauralSpatializationCVar = 0;
FAutoConsoleVariableRef CVarDisableBinauralSpatialization(
	TEXT("au.DisableBinauralSpatialization"),
	DisableBinauralSpatializationCVar,
	TEXT("Disables binaural spatialization.\n"),
	ECVF_Default);

static int32 FlushAudioRenderThreadOnGCCVar = 0;
FAutoConsoleVariableRef CVarFlushAudioRenderThreadOnGC(

#Loc: <Workspace>/Projects/Lyra/Source/LyraGame/Settings/LyraSettingsLocal.cpp:844

Scope (from outer to inner):

file
function     void ULyraSettingsLocal::SetHeadphoneModeEnabled

Source code excerpt:

	if (CanModifyHeadphoneModeEnabled())
	{
		static IConsoleVariable* BinauralSpatializationDisabledCVar = IConsoleManager::Get().FindConsoleVariable(TEXT("au.DisableBinauralSpatialization"));
		if (BinauralSpatializationDisabledCVar)
		{
			BinauralSpatializationDisabledCVar->Set(!bEnabled, ECVF_SetByGameSetting);

			// Only save settings if the setting actually changed
			if (bUseHeadphoneMode != bEnabled)

#Loc: <Workspace>/Projects/Lyra/Source/LyraGame/Settings/LyraSettingsLocal.cpp:866

Scope (from outer to inner):

file
function     bool ULyraSettingsLocal::CanModifyHeadphoneModeEnabled

Source code excerpt:

bool ULyraSettingsLocal::CanModifyHeadphoneModeEnabled() const
{
	static IConsoleVariable* BinauralSpatializationDisabledCVar = IConsoleManager::Get().FindConsoleVariable(TEXT("au.DisableBinauralSpatialization"));
	const bool bHRTFOptionAvailable = BinauralSpatializationDisabledCVar && ((BinauralSpatializationDisabledCVar->GetFlags() & EConsoleVariableFlags::ECVF_SetByMask) <= EConsoleVariableFlags::ECVF_SetByGameSetting);

	const bool bBinauralSettingControlledByOS = LyraSettingsHelpers::HasPlatformTrait(TAG_Platform_Trait_BinauralSettingControlledByOS);

	return bHRTFOptionAvailable && !bBinauralSettingControlledByOS;
}

#Loc: <Workspace>/Projects/Lyra/Source/LyraGame/Settings/LyraSettingsLocal.h:234

Scope: file

Source code excerpt:

	bool IsHeadphoneModeEnabled() const;

	/** Enables or disables headphone mode (HRTF) - NOTE this setting will be overruled if au.DisableBinauralSpatialization is set */
	UFUNCTION()
	void SetHeadphoneModeEnabled(bool bEnabled);

	/** Returns if we can enable/disable headphone mode (i.e., if it's not forced on or off by the platform) */
	UFUNCTION()
	bool CanModifyHeadphoneModeEnabled() const;

#Associated Variable and Callsites

This variable is associated with another variable named DisableBinauralSpatializationCVar. They share the same value. See the following C++ source code.

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/AudioDevice.cpp:147

Scope: file

Source code excerpt:

	ECVF_Default);

static int32 DisableBinauralSpatializationCVar = 0;
FAutoConsoleVariableRef CVarDisableBinauralSpatialization(
	TEXT("au.DisableBinauralSpatialization"),
	DisableBinauralSpatializationCVar,
	TEXT("Disables binaural spatialization.\n"),
	ECVF_Default);

static int32 FlushAudioRenderThreadOnGCCVar = 0;
FAutoConsoleVariableRef CVarFlushAudioRenderThreadOnGC(
	TEXT("au.FlushAudioRenderThreadOnGC"),

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/AudioDevice.cpp:2208

Scope (from outer to inner):

file
function     bool FAudioDevice::IsHRTFDisabled

Source code excerpt:

	if (IsInAudioThread())
	{
		return (bHRTFDisabled || DisableBinauralSpatializationCVar == 1);
	}

	check(IsInGameThread());
	return (bHRTFDisabled_OnGameThread || DisableBinauralSpatializationCVar == 1);
}

void FAudioDevice::SetMixDebugState(EDebugState InDebugState)
{
	if (!IsInAudioThread())
	{