au.SoundDistanceOptimizationLength

au.SoundDistanceOptimizationLength

#Overview

name: au.SoundDistanceOptimizationLength

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

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of au.SoundDistanceOptimizationLength is to optimize audio performance by culling short-duration sounds that are too far from the listener to be audible. This setting is part of the audio system in Unreal Engine 5.

This setting variable is primarily used in the Engine module, specifically within the AudioDevice subsystem. It’s referenced in the AudioDevice.cpp file, which is responsible for managing audio playback and processing in the engine.

The value of this variable is set using an FAutoConsoleVariableRef, which allows it to be modified at runtime through console commands. Its default value is 1.0f seconds.

The au.SoundDistanceOptimizationLength variable interacts directly with its associated variable SoundDistanceOptimizationLengthCVar. They share the same value, with SoundDistanceOptimizationLengthCVar being the actual storage for the setting.

Developers must be aware that this variable affects the culling of short-duration sounds. Sounds with a duration less than or equal to this value are candidates for distance-based culling. This means that if a sound’s duration is shorter than this threshold and it’s determined to be out of audible range, it won’t be played, potentially saving performance.

Best practices when using this variable include:

  1. Carefully consider the default value (1.0 seconds) and adjust it based on your game’s specific audio needs and performance requirements.
  2. Be mindful that increasing this value may result in more sounds being culled, which could improve performance but might also lead to important audio cues being missed if not carefully balanced.
  3. Test thoroughly with different values to find the optimal balance between performance and audio quality for your specific game.

Regarding the associated variable SoundDistanceOptimizationLengthCVar:

The purpose of SoundDistanceOptimizationLengthCVar is to store the actual value of the au.SoundDistanceOptimizationLength setting. It’s used directly in the code to perform the optimization checks.

This variable is used in the Engine module, specifically within the AudioDevice system. It’s defined and used in AudioDevice.cpp.

The value of SoundDistanceOptimizationLengthCVar is set when au.SoundDistanceOptimizationLength is modified, as they are linked through the FAutoConsoleVariableRef.

It interacts directly with au.SoundDistanceOptimizationLength and is used in sound culling logic within the FAudioDevice::AddNewActiveSoundInternal and FAudioDevice::CreateComponent functions.

Developers should be aware that modifying au.SoundDistanceOptimizationLength will directly affect SoundDistanceOptimizationLengthCVar, and thus the sound culling behavior.

Best practices include using the console variable au.SoundDistanceOptimizationLength to modify this value at runtime for testing, rather than changing the code directly. This allows for easier experimentation and tuning of the audio optimization system.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

static float SoundDistanceOptimizationLengthCVar = 1.0f;
FAutoConsoleVariableRef CVarSoundDistanceOptimizationLength(
	TEXT("au.SoundDistanceOptimizationLength"),
	SoundDistanceOptimizationLengthCVar,
	TEXT("The maximum duration a sound must be in order to be a candidate to be culled due to one-shot distance optimization.\n"),
	ECVF_Default);

static int32 EnableBinauralAudioForAllSpatialSoundsCVar = 0;
FAutoConsoleVariableRef CVarEnableBinauralAudioForAllSpatialSounds(

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

	ECVF_Default);

static float SoundDistanceOptimizationLengthCVar = 1.0f;
FAutoConsoleVariableRef CVarSoundDistanceOptimizationLength(
	TEXT("au.SoundDistanceOptimizationLength"),
	SoundDistanceOptimizationLengthCVar,
	TEXT("The maximum duration a sound must be in order to be a candidate to be culled due to one-shot distance optimization.\n"),
	ECVF_Default);

static int32 EnableBinauralAudioForAllSpatialSoundsCVar = 0;
FAutoConsoleVariableRef CVarEnableBinauralAudioForAllSpatialSounds(
	TEXT("au.EnableBinauralAudioForAllSpatialSounds"),

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

Scope (from outer to inner):

file
function     void FAudioDevice::AddNewActiveSoundInternal

Source code excerpt:

	}

	if (Sound->GetDuration() <= FMath::Max(0.0f, SoundDistanceOptimizationLengthCVar))
	{
		// TODO: Determine if this check has already been completed at AudioComponent level and skip if so. Also,
		// unify code paths determining if sound is audible.
		if (!SoundIsAudible(InNewActiveSound))
		{
			UE_LOG(LogAudio, Log, TEXT("New ActiveSound not created for out of range Sound %s"), *InNewActiveSound.Sound->GetName());

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

Scope (from outer to inner):

file
function     UAudioComponent* FAudioDevice::CreateComponent

Source code excerpt:

			bool bIsAudible = true;
			// If a sound is a long duration, the position might change before sound finishes so assume it's audible
			if (Params.bLocationSet && Sound->GetDuration() <= FMath::Max(0.0f, SoundDistanceOptimizationLengthCVar))
			{
				float MaxDistance = 0.0f;
				float FocusFactor = 0.0f;
				Params.AudioDevice->GetMaxDistanceAndFocusFactor(Sound, Params.World, Params.Location, AttenuationSettingsToApply, MaxDistance, FocusFactor);
				bIsAudible = Params.AudioDevice->SoundIsAudible(Sound, Params.World, Params.Location, AttenuationSettingsToApply, MaxDistance, FocusFactor);
			}