au.DisableAutomaticPrecache

au.DisableAutomaticPrecache

#Overview

name: au.DisableAutomaticPrecache

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.DisableAutomaticPrecache is to control the automatic precaching behavior of audio assets in Unreal Engine 5. It is primarily used in the audio system to manage how and when audio data is loaded and prepared for playback.

This setting variable is utilized by the Unreal Engine’s audio subsystem, specifically within the FAudioDevice class. It’s part of the Engine module, as evidenced by its location in the AudioDevice.cpp file within the Engine/Source/Runtime/Engine/Private directory.

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 configuration files.

The au.DisableAutomaticPrecache variable interacts directly with the DisableAutomaticPrecacheCvar variable. They share the same value, with DisableAutomaticPrecacheCvar being the actual integer storage and au.DisableAutomaticPrecache being the console-accessible name.

Developers must be aware that setting this variable to 1 will disable all automatic precaching of audio, except for synchronous calls. This can significantly affect audio loading behavior and performance, especially during game startup or level loading.

Best practices when using this variable include:

  1. Leaving it at the default value (0) unless there’s a specific need to disable automatic precaching.
  2. If disabling automatic precaching, ensure that all necessary audio assets are manually precached to avoid performance issues during gameplay.
  3. Use this setting judiciously in shipping builds, as it can affect the player’s experience if audio isn’t properly loaded.

Regarding the associated variable DisableAutomaticPrecacheCvar:

The purpose of DisableAutomaticPrecacheCvar is to store the actual integer value that controls the precaching behavior. It’s the backend storage for the au.DisableAutomaticPrecache console variable.

This variable is used directly in the FAudioDevice class to determine whether to perform automatic precaching. It’s checked in methods like PrecacheStartupSounds() and Precache().

The value of DisableAutomaticPrecacheCvar is set through the FAutoConsoleVariableRef system, which links it to the au.DisableAutomaticPrecache console variable.

DisableAutomaticPrecacheCvar interacts primarily with the au.DisableAutomaticPrecache console variable, and it’s used in conditional statements to control precaching behavior.

Developers should be aware that this variable is the actual storage used in the code logic, while au.DisableAutomaticPrecache is the external interface for changing its value.

Best practices for DisableAutomaticPrecacheCvar include:

  1. Not modifying this variable directly in code, but instead using the au.DisableAutomaticPrecache console variable to change its value.
  2. Being aware of its usage in audio-related functions when debugging or profiling audio performance.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

static int32 DisableAutomaticPrecacheCvar = 0;
FAutoConsoleVariableRef CVarDisableAutomaticPrecache(
	TEXT("au.DisableAutomaticPrecache"),
	DisableAutomaticPrecacheCvar,
	TEXT("When set to 1, this disables precaching on load or startup, it will only precache synchronously when playing.\n")
	TEXT("0: Use normal precaching logic, 1: disables all precaching except for synchronous calls."),
	ECVF_Default);

static float DecompressionThresholdCvar = 0.0f;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

	ECVF_Default);

static int32 DisableAutomaticPrecacheCvar = 0;
FAutoConsoleVariableRef CVarDisableAutomaticPrecache(
	TEXT("au.DisableAutomaticPrecache"),
	DisableAutomaticPrecacheCvar,
	TEXT("When set to 1, this disables precaching on load or startup, it will only precache synchronously when playing.\n")
	TEXT("0: Use normal precaching logic, 1: disables all precaching except for synchronous calls."),
	ECVF_Default);

static float DecompressionThresholdCvar = 0.0f;
FAutoConsoleVariableRef CVarDecompressionThreshold(

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

Scope (from outer to inner):

file
function     void FAudioDevice::PrecacheStartupSounds

Source code excerpt:

{
	// Iterate over all already loaded sounds and precache them. This relies on Super::Init in derived classes to be called last.
	if (!GIsEditor && GEngine && GEngine->UseSound() && DisableAutomaticPrecacheCvar == 0)
	{
		for (TObjectIterator<USoundWave> It; It; ++It)
		{
			USoundWave* SoundWave = *It;
			Precache(SoundWave);
		}

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

Scope (from outer to inner):

file
function     void FAudioDevice::Precache

Source code excerpt:

	if (!bSynchronous && SoundWave->GetPrecacheState() == ESoundWavePrecacheState::NotStarted)
	{
		if (!bForceFullDecompression && DisableAutomaticPrecacheCvar == 1)
		{
			// Don't schedule a precache for a normal async request because it is currently disabled
			return;
		}

		if (IsInGameThread())