au.EnableOcclusionFilterScale

au.EnableOcclusionFilterScale

#Overview

name: au.EnableOcclusionFilterScale

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.EnableOcclusionFilterScale is to control the scaling of occlusion in the audio system of Unreal Engine 5. Specifically, it determines whether to apply a 0.25 scale factor to compensate for changes in filter cutoff frequencies in the audio mixer.

This setting variable is primarily used in the audio subsystem of Unreal Engine. Based on the callsites, it’s implemented in the Engine module, specifically in the Audio.cpp file.

The value of this variable is set through a console variable (CVar) system. It’s initialized to 0 and can be changed at runtime using console commands or through code.

The au.EnableOcclusionFilterScale variable interacts directly with the OcclusionFilterScaleEnabledCVar. They share the same value, with OcclusionFilterScaleEnabledCVar being the actual integer variable used in the code logic.

Developers must be aware that this variable is a boolean flag (0 for disabled, 1 for enabled). When enabled, it applies a 0.25 scale factor to the occlusion filter frequency, which can significantly affect the audio output.

Best practices when using this variable include:

  1. Understanding the impact on audio quality before enabling or disabling it.
  2. Testing the audio with both settings to determine which provides the best results for your specific use case.
  3. Documenting any changes to this setting in your project, as it can affect the overall audio experience.

Regarding the associated variable OcclusionFilterScaleEnabledCVar:

The purpose of OcclusionFilterScaleEnabledCVar is to serve as the actual integer storage for the au.EnableOcclusionFilterScale setting. It’s used directly in the code logic to determine whether to apply the occlusion filter scale.

This variable is used in the FSoundSource::SetFilterFrequency function to determine if the occlusion filter scale should be applied. When enabled (value is 1), and the WaveInstance’s OcclusionFilterFrequency is not nearly equal to MAX_FILTER_FREQUENCY, a scale factor of 0.25 is applied to the OcclusionFilterFrequency.

The value of OcclusionFilterScaleEnabledCVar is set through the CVar system, initialized to 0, and can be changed at runtime.

It doesn’t directly interact with other variables, but it affects the calculation of the LPFFrequency (Low Pass Filter Frequency) in the audio processing pipeline.

Developers should be aware that changes to this variable will directly impact the audio processing, potentially affecting the perceived quality of occlusion effects in the game.

Best practices for using OcclusionFilterScaleEnabledCVar include:

  1. Ensuring that any code that modifies this variable also updates the corresponding CVar (au.EnableOcclusionFilterScale) to maintain consistency.
  2. Using the CVar system to modify this value rather than directly changing the variable, to ensure proper synchronization with the engine’s console variable system.
  3. Considering the performance implications of enabling this feature, especially on lower-end hardware.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

static int32 OcclusionFilterScaleEnabledCVar = 0;
FAutoConsoleVariableRef CVarOcclusionFilterScaleEnabled(
	TEXT("au.EnableOcclusionFilterScale"),
	OcclusionFilterScaleEnabledCVar,
	TEXT("Whether or not we scale occlusion by 0.25f to compensate for change in filter cutoff frequencies in audio mixer. \n")
	TEXT("0: Not Enabled, 1: Enabled"),
	ECVF_Default);

static int32 BypassPlayWhenSilentCVar = 0;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

	ECVF_Default);

static int32 OcclusionFilterScaleEnabledCVar = 0;
FAutoConsoleVariableRef CVarOcclusionFilterScaleEnabled(
	TEXT("au.EnableOcclusionFilterScale"),
	OcclusionFilterScaleEnabledCVar,
	TEXT("Whether or not we scale occlusion by 0.25f to compensate for change in filter cutoff frequencies in audio mixer. \n")
	TEXT("0: Not Enabled, 1: Enabled"),
	ECVF_Default);

static int32 BypassPlayWhenSilentCVar = 0;
FAutoConsoleVariableRef CVarBypassPlayWhenSilent(

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

Scope (from outer to inner):

file
function     void FSoundSource::SetFilterFrequency

Source code excerpt:

			// compensate for filter coefficient calculation error for occlusion
			float OcclusionFilterScale = 1.0f;
			if (OcclusionFilterScaleEnabledCVar == 1 && !FMath::IsNearlyEqual(WaveInstance->OcclusionFilterFrequency, MAX_FILTER_FREQUENCY))
			{
				OcclusionFilterScale = 0.25f;
			}

			// Set the LPFFrequency to lowest provided value
			LPFFrequency = WaveInstance->OcclusionFilterFrequency * OcclusionFilterScale;