au.DisableStereoSpread

au.DisableStereoSpread

#Overview

name: au.DisableStereoSpread

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

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of au.DisableStereoSpread is to control the stereo spread feature in Unreal Engine’s audio system. It allows developers to disable the 3D Stereo Spread property in attenuation settings, causing audio to be rendered from a singular point instead of using spatial audio techniques.

This setting variable is primarily used by the audio subsystem within Unreal Engine. Specifically, it affects the audio rendering process in the Engine module.

The value of this variable is set through a console variable (CVar) system. It’s initialized to 0 by default, meaning the stereo spread feature is enabled. Developers can change this value at runtime or through configuration files.

The au.DisableStereoSpread variable interacts directly with the DisableStereoSpreadCvar variable. They share the same value, with DisableStereoSpreadCvar being the actual integer storage for the setting.

Developers must be aware that setting this variable to 1 will override any 3D Stereo Spread settings in audio attenuation, potentially changing the perceived audio experience significantly. This could be particularly noticeable in games or applications that rely heavily on spatial audio for immersion or gameplay mechanics.

Best practices when using this variable include:

  1. Using it for debugging or performance optimization purposes.
  2. Ensuring that disabling stereo spread doesn’t negatively impact the intended audio experience.
  3. Documenting its use clearly, especially if it’s changed from the default value in shipping builds.

Regarding the associated variable DisableStereoSpreadCvar:

The purpose of DisableStereoSpreadCvar is to serve as the actual storage for the au.DisableStereoSpread setting. It’s an integer variable that directly controls whether stereo spread is disabled or not.

This variable is used within the Engine module, specifically in the audio rendering code.

The value of DisableStereoSpreadCvar is set through the CVar system, mirroring the value of au.DisableStereoSpread.

DisableStereoSpreadCvar interacts directly with the au.DisableStereoSpread console variable. It’s also used in the UpdateStereoEmitterPositions function to determine whether to apply stereo spread calculations.

Developers should be aware that this variable is the actual control point for the stereo spread feature. Changing its value directly (though not recommended) would have the same effect as changing au.DisableStereoSpread.

Best practices for DisableStereoSpreadCvar include:

  1. Avoiding direct manipulation of this variable; instead, use the au.DisableStereoSpread console variable.
  2. Being aware of its existence when debugging audio-related issues, as it directly influences the audio rendering process.
  3. Understanding that a value of 0 means stereo spread is enabled, while a value of 1 means it’s disabled.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Audio.cpp:64

Scope: file

Source code excerpt:

static int32 DisableStereoSpreadCvar = 0;
FAutoConsoleVariableRef CVarDisableStereoSpread(
	TEXT("au.DisableStereoSpread"),
	DisableStereoSpreadCvar,
	TEXT("When set to 1, ignores the 3D Stereo Spread property in attenuation settings and instead renders audio from a singular point.\n")
	TEXT("0: Not Disabled, 1: Disabled"),
	ECVF_Default);

static int32 AllowAudioSpatializationCVar = 1;

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Audio.cpp:62

Scope: file

Source code excerpt:


/** CVars */
static int32 DisableStereoSpreadCvar = 0;
FAutoConsoleVariableRef CVarDisableStereoSpread(
	TEXT("au.DisableStereoSpread"),
	DisableStereoSpreadCvar,
	TEXT("When set to 1, ignores the 3D Stereo Spread property in attenuation settings and instead renders audio from a singular point.\n")
	TEXT("0: Not Disabled, 1: Disabled"),
	ECVF_Default);

static int32 AllowAudioSpatializationCVar = 1;
FAutoConsoleVariableRef CVarAllowAudioSpatializationCVar(

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Audio.cpp:435

Scope (from outer to inner):

file
function     void FSoundSource::UpdateStereoEmitterPositions

Source code excerpt:

	check(Buffer->NumChannels == 2);

	if (!DisableStereoSpreadCvar && WaveInstance->StereoSpread > 0.0f)
	{
		// We need to compute the stereo left/right channel positions using the audio component position and the spread
		FVector ListenerPosition;

		const bool bAllowAttenuationOverride = false;
		const int32 ListenerIndex = WaveInstance->ActiveSound ? WaveInstance->ActiveSound->GetClosestListenerIndex() : 0;