au.VirtualLoops.ForceUpdateListenerMoveDistance

au.VirtualLoops.ForceUpdateListenerMoveDistance

#Overview

name: au.VirtualLoops.ForceUpdateListenerMoveDistance

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.VirtualLoops.ForceUpdateListenerMoveDistance is to set a distance threshold for forcing an update on virtualized sounds when the listener moves a significant distance in a single frame. This setting is used in the audio system of Unreal Engine 5, specifically for managing virtual audio loops.

This setting variable is primarily used in the Engine module, particularly in the audio subsystem dealing with virtual loops. The code referencing this variable is located in the AudioVirtualLoop.cpp file, which is part of the Engine’s runtime.

The value of this variable is set through the Unreal Engine’s console variable (CVar) system. It’s initialized with a default value of 2500.0f and can be modified at runtime using console commands or through configuration files.

The variable interacts directly with its associated C++ variable VirtualLoopsForceUpdateListenerMoveDistanceCVar. They share the same value, with the console variable providing an interface for runtime modification.

Developers should be aware that this variable affects the performance and accuracy of virtual audio loops. A lower value will cause more frequent updates, potentially improving accuracy but at the cost of performance. Conversely, a higher value may improve performance but could lead to less accurate audio positioning for virtual loops.

Best practices when using this variable include:

  1. Adjusting the value based on the scale and requirements of your game world.
  2. Testing different values to find the right balance between performance and audio accuracy.
  3. Considering the typical movement speed of the listener (usually the player) when setting this value.

Regarding the associated variable VirtualLoopsForceUpdateListenerMoveDistanceCVar:

This is the actual C++ variable that stores the value set by the console variable. It’s used in the FAudioVirtualLoop::ShouldListenerMoveForceUpdate function to determine if an update should be forced based on listener movement.

The purpose of this variable is to provide a quick access point for the threshold value within the C++ code, without needing to query the console variable system each time.

Developers should be aware that modifying this variable directly in code will not persist changes across sessions or be reflected in the console variable system. Always use the console variable (au.VirtualLoops.ForceUpdateListenerMoveDistance) to make persistent changes.

Best practices for this associated variable include:

  1. Treating it as read-only within the C++ code, unless there’s a specific need for temporary runtime modification.
  2. Using it efficiently in performance-critical code sections, as it’s a simple float value that doesn’t require additional lookup.
  3. Ensuring that any code using this variable can handle potential runtime changes to its value.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/AudioVirtualLoop.cpp:22

Scope: file

Source code excerpt:

static float VirtualLoopsForceUpdateListenerMoveDistanceCVar = 2500.0f;
FAutoConsoleVariableRef CVarVirtualLoopsForceUpdateListenerMoveDistance(
	TEXT("au.VirtualLoops.ForceUpdateListenerMoveDistance"),
	VirtualLoopsForceUpdateListenerMoveDistanceCVar,
	TEXT("Sets distance threshold required to force an update on virtualized sounds to check for if listener moves in a single frame over the given distance.\n"),
	ECVF_Default);

static float VirtualLoopsUpdateRateMinCVar = 0.1f;
FAutoConsoleVariableRef CVarVirtualLoopsUpdateRateMin(

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/AudioVirtualLoop.cpp:20

Scope: file

Source code excerpt:

	ECVF_Default);

static float VirtualLoopsForceUpdateListenerMoveDistanceCVar = 2500.0f;
FAutoConsoleVariableRef CVarVirtualLoopsForceUpdateListenerMoveDistance(
	TEXT("au.VirtualLoops.ForceUpdateListenerMoveDistance"),
	VirtualLoopsForceUpdateListenerMoveDistanceCVar,
	TEXT("Sets distance threshold required to force an update on virtualized sounds to check for if listener moves in a single frame over the given distance.\n"),
	ECVF_Default);

static float VirtualLoopsUpdateRateMinCVar = 0.1f;
FAutoConsoleVariableRef CVarVirtualLoopsUpdateRateMin(
	TEXT("au.VirtualLoops.UpdateRate.Min"),

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/AudioVirtualLoop.cpp:346

Scope (from outer to inner):

file
function     bool FAudioVirtualLoop::ShouldListenerMoveForceUpdate

Source code excerpt:

{
	const float DistanceSq = FVector::DistSquared(LastTransform.GetTranslation(), CurrentTransform.GetTranslation());
	const float ForceUpdateDistSq = VirtualLoopsForceUpdateListenerMoveDistanceCVar * VirtualLoopsForceUpdateListenerMoveDistanceCVar;
	return DistanceSq > ForceUpdateDistSq;
}