au.streamcaching.TrimCacheWhenOverBudget

au.streamcaching.TrimCacheWhenOverBudget

#Overview

name: au.streamcaching.TrimCacheWhenOverBudget

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.streamcaching.TrimCacheWhenOverBudget is to control the behavior of the audio streaming cache system in Unreal Engine 5, specifically to manage memory usage by trimming the cache when it exceeds the allocated budget.

This setting variable is primarily used in the audio streaming subsystem of Unreal Engine 5, as evidenced by its implementation in the AudioStreamingCache.cpp file.

The value of this variable is set through a console variable (CVar) system. It is initialized with a default value of 1, which means the cache trimming feature is enabled by default.

The associated variable TrimCacheWhenOverBudgetCVar directly interacts with au.streamcaching.TrimCacheWhenOverBudget. They share the same value, with TrimCacheWhenOverBudgetCVar being the actual variable used in the code logic.

Developers must be aware that when this variable is set to a non-zero value, the TrimMemory function will be called in the AddOrTouchChunk method to ensure the audio streaming cache never goes over budget. This affects the memory management of audio streaming, potentially impacting performance and audio quality.

Best practices when using this variable include:

  1. Monitoring its impact on audio performance and quality.
  2. Adjusting it based on the specific needs of the project and target hardware capabilities.
  3. Considering the trade-off between memory usage and potential audio loading times or quality.

Regarding the associated variable TrimCacheWhenOverBudgetCVar:

Its purpose is to serve as the actual implementation variable for the au.streamcaching.TrimCacheWhenOverBudget setting.

It is used in the FAudioChunkCache class, specifically in methods like AddOrTouchChunk, AddForceInlineSoundWave, and AddMemoryCountedFeature.

The value of TrimCacheWhenOverBudgetCVar is set through the console variable system, mirroring au.streamcaching.TrimCacheWhenOverBudget.

It directly controls the behavior of cache trimming when memory usage exceeds the limit.

Developers should be aware that changing the value of au.streamcaching.TrimCacheWhenOverBudget will directly affect TrimCacheWhenOverBudgetCVar and thus the cache trimming behavior.

Best practices include carefully considering the implications of disabling this feature (setting it to 0) on memory usage and overall audio system performance.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/AudioStreamingCache.cpp:41

Scope: file

Source code excerpt:

static int32 TrimCacheWhenOverBudgetCVar = 1;
FAutoConsoleVariableRef CVarTrimCacheWhenOverBudget(
	TEXT("au.streamcaching.TrimCacheWhenOverBudget"),
	TrimCacheWhenOverBudgetCVar,
	TEXT("When set to a nonzero value, TrimMemory will be called in AddOrTouchChunk to ensure we never go over budget.\n"),
	ECVF_Default);
	
static int32 AlwaysLogCacheMissesCVar = 0;
FAutoConsoleVariableRef CVarAlwaysLogCacheMisses(

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/AudioStreamingCache.cpp:39

Scope: file

Source code excerpt:

	ECVF_Default);

static int32 TrimCacheWhenOverBudgetCVar = 1;
FAutoConsoleVariableRef CVarTrimCacheWhenOverBudget(
	TEXT("au.streamcaching.TrimCacheWhenOverBudget"),
	TrimCacheWhenOverBudgetCVar,
	TEXT("When set to a nonzero value, TrimMemory will be called in AddOrTouchChunk to ensure we never go over budget.\n"),
	ECVF_Default);
	
static int32 AlwaysLogCacheMissesCVar = 0;
FAutoConsoleVariableRef CVarAlwaysLogCacheMisses(
	TEXT("au.streamcaching.AlwaysLogCacheMisses"),

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/AudioStreamingCache.cpp:823

Scope (from outer to inner):

file
function     uint64 FAudioChunkCache::AddOrTouchChunk

Source code excerpt:


			const uint64 MemoryUsageBytes = GetCurrentMemoryUsageBytes() + ChunkDataSize;
			if (TrimCacheWhenOverBudgetCVar != 0 && MemoryUsageBytes > MemoryLimitBytes)
			{
				uint64 MemoryToTrim = 0;
				if (MemoryLimitTrimPercentageCVar > 0.0f)
				{
					MemoryToTrim = MemoryLimitBytes * FMath::Min(MemoryLimitTrimPercentageCVar, 1.0f);
				}

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/AudioStreamingCache.cpp:1053

Scope (from outer to inner):

file
function     void FAudioChunkCache::AddForceInlineSoundWave

Source code excerpt:

		ForceInlineMemoryCounterBytes += MemoryCount;
		const uint64 MemoryUsageBytes = GetCurrentMemoryUsageBytes();
		if (TrimCacheWhenOverBudgetCVar != 0 && MemoryUsageBytes > MemoryLimitBytes)
		{
			uint64 MemoryToTrim = 0;
			if (MemoryLimitTrimPercentageCVar > 0.0f)
			{
				MemoryToTrim = MemoryLimitBytes * FMath::Min(MemoryLimitTrimPercentageCVar, 1.0f);
			}

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/AudioStreamingCache.cpp:1112

Scope (from outer to inner):

file
function     void FAudioChunkCache::AddMemoryCountedFeature

Source code excerpt:

	UE_LOG(LogAudioStreamCaching, Log, TEXT("Total Memory Usage for all features: %d -> %d bytes"), (int32)OldMemoryCount, (int32)FeatureMemoryCounterBytes.Load());
	const uint64 MemoryUsageBytes = GetCurrentMemoryUsageBytes();
	if (TrimCacheWhenOverBudgetCVar != 0 && MemoryUsageBytes > MemoryLimitBytes)
	{
		uint64 MemoryToTrim = 0;
		if (MemoryLimitTrimPercentageCVar > 0.0f)
		{
			MemoryToTrim = MemoryLimitBytes * FMath::Min(MemoryLimitTrimPercentageCVar, 1.0f);
		}