au.itd.SetHeadWidth

au.itd.SetHeadWidth

#Overview

name: au.itd.SetHeadWidth

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

It is referenced in 5 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of au.itd.SetHeadWidth is to set the listener’s head width from ear to ear in centimeters for the spatialization system in Unreal Engine 5. This setting is crucial for accurate spatial audio rendering, particularly for interaural time difference (ITD) calculations.

This setting variable is primarily used by the Spatialization plugin, which is part of Unreal Engine’s audio system. Specifically, it is utilized in the ITDSpatializer module, responsible for creating realistic 3D audio experiences.

The value of this variable is set through a console variable (CVar) system. It is initialized with a default value of 34.0f centimeters and can be modified at runtime.

The au.itd.SetHeadWidth variable interacts directly with HeadWidthCVar. They share the same value, with HeadWidthCVar being the actual variable used in calculations throughout the code.

Developers must be aware that this variable significantly impacts the spatial audio experience. Changing its value will affect how sound is perceived to come from different directions, particularly in terms of left-right positioning.

Best practices when using this variable include:

  1. Using realistic values based on average human head widths (around 34 cm is typical).
  2. Considering the target audience and adjusting if necessary (e.g., for games targeting children).
  3. Testing thoroughly with different values to ensure the desired audio experience.

Regarding the associated variable HeadWidthCVar:

The purpose of HeadWidthCVar is to store and provide access to the head width value within the ITDSpatializer implementation. It’s the internal representation of the au.itd.SetHeadWidth console variable.

HeadWidthCVar is used in various calculations within the FSourceSpatializer class, which is part of the spatialization system. It’s used to calculate things like the head radius, distances to each ear, and gain factors for spatial audio rendering.

The value of HeadWidthCVar is set through the console variable system, mirroring au.itd.SetHeadWidth.

HeadWidthCVar interacts with several other variables and calculations in the spatialization system, including distance factors, pan values, and delay calculations.

Developers should be aware that HeadWidthCVar is used in centimeters in some calculations and converted to meters in others. Care should be taken to use the correct units when working with this variable.

Best practices for HeadWidthCVar include ensuring it’s always positive and non-zero, and considering its impact on performance, as it’s used in potentially frequent calculations during audio processing.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Plugins/Runtime/Spatialization/Source/Spatialization/Private/ITDSpatializer.cpp:19

Scope: file

Source code excerpt:

static float HeadWidthCVar = 34.0f;
FAutoConsoleVariableRef CVarHeadWidth(
	TEXT("au.itd.SetHeadWidth"),
	HeadWidthCVar,
	TEXT("Sets the listener's head width from ear to ear, in centimeters.\n")
	TEXT("Value: The listener's head width from ear to ear, in centimeters."),
	ECVF_Default);

static float InterpolationTauCVar = 0.1f;

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Plugins/Runtime/Spatialization/Source/Spatialization/Private/ITDSpatializer.cpp:17

Scope: file

Source code excerpt:

	ECVF_Default);

static float HeadWidthCVar = 34.0f;
FAutoConsoleVariableRef CVarHeadWidth(
	TEXT("au.itd.SetHeadWidth"),
	HeadWidthCVar,
	TEXT("Sets the listener's head width from ear to ear, in centimeters.\n")
	TEXT("Value: The listener's head width from ear to ear, in centimeters."),
	ECVF_Default);

static float InterpolationTauCVar = 0.1f;
FAutoConsoleVariableRef CVarInterpolationTime(

#Loc: <Workspace>/Engine/Plugins/Runtime/Spatialization/Source/Spatialization/Private/ITDSpatializer.cpp:49

Scope (from outer to inner):

file
function     FSourceSpatializer::FSourceSpatializer

Source code excerpt:

{
	// Max delay line length will be the maximum distance audio will need to travel divided by the speed of sound:
	const float MaxDelay = 0.5f; //HeadWidthCVar / 1000.0f / SpeedOfSoundCVar;
	const float EaseFactor = Audio::FExponentialEase::GetFactorForTau(InterpolationTauCVar, InSampleRate);

	LeftDelays.Reset();
	LeftDelays.AddDefaulted(2);

	RightDelays.Reset();

#Loc: <Workspace>/Engine/Plugins/Runtime/Spatialization/Source/Spatialization/Private/ITDSpatializer.cpp:151

Scope (from outer to inner):

file
function     void FSourceSpatializer::EvaluateGainDestinations

Source code excerpt:

	const float DistanceFactor = FMath::Clamp<float>(InRichCurve->Eval(InputData.SpatializationParams->Distance, 0.0f), 0.0f, 1.0f);

	const float HeadRadius = (HeadWidthCVar / 100.0f) * 0.5f;

	// PanValue value normalized [0, 1]:
	const float NormalizedPanValue = (FMath::Clamp<float>(InputData.SpatializationParams->EmitterPosition.Y, -1.0f * HeadRadius, HeadRadius) / HeadRadius + 1.0f) * 0.5f;
	const float GainDelta = 0.5f * NormalizedPanValue * DistanceFactor;

	// LeftGain.SetValue(2.0f - GainDelta - DistanceFactor);

#Loc: <Workspace>/Engine/Plugins/Runtime/Spatialization/Source/Spatialization/Private/ITDSpatializer.cpp:179

Scope (from outer to inner):

file
function     void FSourceSpatializer::EvaluateDelayDestinationForInputChannel

Source code excerpt:

void FSourceSpatializer::EvaluateDelayDestinationForInputChannel(int32 ChannelIndex, float X, float Y)
{
	const float HeadRadius = (HeadWidthCVar / 100.0f) * 0.5f;

	const float DistanceToLeftEar = FMath::Sqrt((X * X) + FMath::Square(HeadRadius + Y));
	const float DistanceToRightEar = FMath::Sqrt((X * X) + FMath::Square(HeadRadius - Y));

	const float DeltaInSeconds = (DistanceToLeftEar - DistanceToRightEar) / SpeedOfSoundCVar;