au.streamcaching.EnableTrimmingRetainedAudio

au.streamcaching.EnableTrimmingRetainedAudio

#Overview

name: au.streamcaching.EnableTrimmingRetainedAudio

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

• type: Var
• help: When set > 0, we will trim retained audio when the stream cache goes over the memory limit.\n0: never trims retained audio, >0: will trim retained audio.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of au.streamcaching.EnableTrimmingRetainedAudio is to control the trimming of retained audio in the audio streaming cache system when the cache exceeds its memory limit.

This setting variable is primarily used in the audio streaming subsystem of Unreal Engine 5. It’s part of the Engine module, specifically within the audio streaming cache functionality.

The value of this variable is set through a console variable (CVar) system. It’s initialized with a default value of 1 in the C++ code, but can be changed at runtime through console commands or configuration files.

The variable interacts directly with its associated variable EnableTrimmingRetainedAudioCVar. They share the same value, with the CVar system providing an interface for runtime modification.

Developers should be aware that:

1. When set to 0, the system will never trim retained audio.
2. When set to a value greater than 0, the system will trim retained audio when the stream cache exceeds the memory limit.
3. This variable works in conjunction with other memory management settings in the audio streaming cache system.

Best practices for using this variable include:

1. Consider the target platform’s memory constraints when deciding whether to enable or disable this feature.
2. Monitor audio performance and memory usage to determine the optimal setting.
3. Use in conjunction with other audio streaming cache settings for comprehensive memory management.

Regarding the associated variable EnableTrimmingRetainedAudioCVar:

1. It’s an integer variable that directly reflects the value of au.streamcaching.EnableTrimmingRetainedAudio.
2. It’s used in the TrimMemory function of the FAudioChunkCache class to determine whether to trim retained audio chunks.
3. Developers should not modify this variable directly, but instead use the CVar system to change au.streamcaching.EnableTrimmingRetainedAudio.
4. The variable is checked in performance-critical code, so changing its value could have immediate effects on audio streaming behavior.

When using this variable, developers should consider the trade-off between memory usage and audio quality/performance. Enabling trimming can help manage memory more aggressively but may impact audio playback in some scenarios.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

static int32 EnableTrimmingRetainedAudioCVar = 1;
FAutoConsoleVariableRef CVarEnableTrimmingRetainedAudio(
	TEXT("au.streamcaching.EnableTrimmingRetainedAudio"),
	EnableTrimmingRetainedAudioCVar,
	TEXT("When set > 0, we will trim retained audio when the stream cache goes over the memory limit.\n")
	TEXT("0: never trims retained audio, >0: will trim retained audio."),
	ECVF_Default);
	
static float MemoryLimitTrimPercentageCVar = 0.1f;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

	ECVF_Default);

static int32 EnableTrimmingRetainedAudioCVar = 1;
FAutoConsoleVariableRef CVarEnableTrimmingRetainedAudio(
	TEXT("au.streamcaching.EnableTrimmingRetainedAudio"),
	EnableTrimmingRetainedAudioCVar,
	TEXT("When set > 0, we will trim retained audio when the stream cache goes over the memory limit.\n")
	TEXT("0: never trims retained audio, >0: will trim retained audio."),
	ECVF_Default);
	
static float MemoryLimitTrimPercentageCVar = 0.1f;
FAutoConsoleVariableRef CVarMemoryLimitTrimPercentage(

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

Scope (from outer to inner):

file
function     uint64 FAudioChunkCache::TrimMemory

Source code excerpt:

	uint32 NumRetainedElementsEvicted = 0;
	// If we have run out of non-retained and in-flight load audio chunks to trim, eat into the 
	if (bInAllowRetainedChunkTrimming && EnableTrimmingRetainedAudioCVar > 0 && BytesFreed < BytesToFree)
	{
		UE_LOG(LogAudioStreamCaching, Verbose, TEXT("TrimMemory: Num Non-Retained Elements Evicted: %d. Non-Retained Bytes Freed: %d"), NumElementsEvicted, BytesFreed);

		CurrentElement = LeastRecentElement;
		ElementToStopAt = MostRecentElement->LessRecentElement;
		while (CurrentElement != ElementToStopAt && BytesFreed < BytesToFree)