au.MaxWorldDistance

au.MaxWorldDistance

#Overview

name: au.MaxWorldDistance

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

It is referenced in 8 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of au.MaxWorldDistance is to set the maximum world distance used in audio-related calculations, such as attenuation. This setting variable is primarily used for the audio system in Unreal Engine 5.

The Unreal Engine subsystem that relies on this setting variable is the Audio Device, as evidenced by its usage in the FAudioDevice class within the Engine module.

The value of this variable is set through a console variable (CVar) using the FAutoConsoleVariableRef system. It is initialized with the value of UE_OLD_WORLD_MAX.

The associated variable MaxWorldDistanceCVar interacts directly with au.MaxWorldDistance. They share the same value, with MaxWorldDistanceCVar being the C++ variable that stores the console variable’s value.

Developers must be aware that this variable affects various audio calculations, particularly those involving distance-based effects like attenuation. It acts as a upper limit for distance calculations in the audio system.

Best practices when using this variable include:

  1. Consider the scale of your game world when adjusting this value.
  2. Be aware that setting it too low might cut off audio prematurely in large environments.
  3. Setting it too high might impact performance, as it could lead to unnecessary audio calculations for distant sounds.

Regarding the associated variable MaxWorldDistanceCVar:

The purpose of MaxWorldDistanceCVar is to store the value of au.MaxWorldDistance in the C++ code for easy access and use within the audio system.

This variable is used within the FAudioDevice class in the Engine module, specifically in methods related to determining audible locations and calculating distances to listeners.

The value of MaxWorldDistanceCVar is set by the au.MaxWorldDistance console variable.

MaxWorldDistanceCVar interacts directly with au.MaxWorldDistance and is used in various audio-related calculations throughout the FAudioDevice class.

Developers should be aware that modifying MaxWorldDistanceCVar directly in code is not recommended, as its value is controlled by the au.MaxWorldDistance console variable.

Best practices for MaxWorldDistanceCVar include:

  1. Use it for read-only operations within the audio system code.
  2. If changes are needed, modify the au.MaxWorldDistance console variable instead of MaxWorldDistanceCVar directly.
  3. Be cautious when comparing distances against this value, as it represents the maximum possible distance for audio calculations.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

static float MaxWorldDistanceCVar = UE_OLD_WORLD_MAX;
FAutoConsoleVariableRef CVarSetAudioMaxDistance(
	TEXT("au.MaxWorldDistance"),
	MaxWorldDistanceCVar,
	TEXT("Maximum world distance used in audio-related calculations (eg. attenuation).\n"),
	ECVF_Default);

static FAutoConsoleCommandWithWorld GListAvailableSpatialPluginsCommand(
	TEXT("au.spatialization.ListAvailableSpatialPlugins"),

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

	ECVF_Default);

static float MaxWorldDistanceCVar = UE_OLD_WORLD_MAX;
FAutoConsoleVariableRef CVarSetAudioMaxDistance(
	TEXT("au.MaxWorldDistance"),
	MaxWorldDistanceCVar,
	TEXT("Maximum world distance used in audio-related calculations (eg. attenuation).\n"),
	ECVF_Default);

static FAutoConsoleCommandWithWorld GListAvailableSpatialPluginsCommand(
	TEXT("au.spatialization.ListAvailableSpatialPlugins"),
	TEXT("This will output a list of currently available/active spatialization plugins"),

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

Scope (from outer to inner):

file
function     bool FAudioDevice::LocationIsAudible

Source code excerpt:

bool FAudioDevice::LocationIsAudible(const FVector& Location, const float MaxDistance) const
{
	if (MaxDistance >= MaxWorldDistanceCVar)
	{
		return true;
	}

	const bool bInAudioThread = IsInAudioThread();
	const bool bInGameThread = IsInGameThread();

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

Scope (from outer to inner):

file
function     bool FAudioDevice::LocationIsAudible

Source code excerpt:

	// To check if a location is audible by any listener, use FAudioDevice::LocationIsAudible that takes a location and max distance.
	// To check if a location is audible by a specific listener, use FAudioDevice::LocationIsAudible that additionally takes a listener index. 
	if (MaxDistance >= MaxWorldDistanceCVar)
	{
		return true;
	}

	FVector ListenerTranslation;
	const bool bAllowOverride = true;

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

Scope (from outer to inner):

file
function     bool FAudioDevice::LocationIsAudible

Source code excerpt:

bool FAudioDevice::LocationIsAudible(const FVector& Location, int32 ListenerIndex, float MaxDistance) const
{
	if (MaxDistance >= MaxWorldDistanceCVar)
	{
		return true;
	}
	
	FVector ListenerTranslation;
	const bool bAllowOverride = true;

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

Scope (from outer to inner):

file
function     float FAudioDevice::GetDistanceToNearestListener

Source code excerpt:

	}

	return MaxWorldDistanceCVar;
}

float FAudioDevice::GetSquaredDistanceToListener(const FVector& Location, const FTransform& ListenerTransform) const
{
	// This function is deprecated as it does not take into account listener attenuation override position
	FVector ListenerTranslation = ListenerTransform.GetTranslation();

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

Scope (from outer to inner):

file
function     bool FAudioDevice::GetDistanceSquaredToNearestListener

Source code excerpt:

	if (FindClosestListenerIndex(Location, DistSquared, bAllowAttenuationOverrides) == INDEX_NONE)
	{
		OutSqDistance = MaxWorldDistanceCVar;
		return false;
	}

	OutSqDistance = DistSquared;
	return true;
}

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

Scope (from outer to inner):

file
function     float FAudioDevice::GetMaxWorldDistance

Source code excerpt:

float FAudioDevice::GetMaxWorldDistance()
{
	return MaxWorldDistanceCVar;
}

bool FAudioDevice::GetListenerPosition(int32 ListenerIndex, FVector& OutPosition, bool bAllowOverride) const
{
	OutPosition = FVector::ZeroVector;
	if (ListenerIndex == INDEX_NONE)