au.streamcaching.MinimumCacheUsage

au.streamcaching.MinimumCacheUsage

#Overview

name: au.streamcaching.MinimumCacheUsage

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.streamcaching.MinimumCacheUsage is to control the minimum potential usage of the audio stream cache in Unreal Engine 5. This setting variable is part of the audio streaming system and is used to manage the efficiency of disk I/O operations when dealing with multiple small sound files.

This setting variable is primarily used in the Engine module, specifically within the audio compression and streaming subsystems. The code referencing this variable is located in the AudioCompressionSettingsUtils.cpp file, which suggests it’s closely tied to audio compression and streaming functionality.

The value of this variable is set through a console variable (CVar) system, allowing it to be adjusted at runtime. It’s initialized with a default value of 0.9f but can be modified using the console command “au.streamcaching.MinimumCacheUsage”.

The associated variable MinimumCacheUsageCvar directly interacts with au.streamcaching.MinimumCacheUsage. They share the same value, with MinimumCacheUsageCvar being the actual float variable used in the code calculations.

Developers must be aware that this variable affects the balance between cache usage and the number of audio chunks. A lower value (closer to 0.0) will limit the number of chunks to (Cache Size / Max Chunk Size), while higher values (between 0.01 and 0.99) will increase the number of chunks to potentially reduce disk I/O when many small sounds are playing simultaneously.

Best practices when using this variable include:

  1. Carefully consider the trade-off between cache usage and disk I/O performance.
  2. Monitor performance metrics related to audio streaming when adjusting this value.
  3. Test thoroughly with various audio scenarios to find the optimal setting for your specific game.
  4. Be cautious when setting values close to 1.0, as it’s noted that a value of 1.0 is impossible (it would require an infinite number of chunks).

Regarding the associated variable MinimumCacheUsageCvar:

The purpose of MinimumCacheUsageCvar is to serve as the actual float variable that stores the value set by au.streamcaching.MinimumCacheUsage. It’s used in calculations within the audio streaming system to determine the number of audio chunks and manage cache usage.

This variable is used in the Engine module, specifically in the audio compression and streaming subsystems. It’s directly referenced in calculations that determine the minimum chunk size and the number of elements in the audio streaming manager.

The value of MinimumCacheUsageCvar is set through the au.streamcaching.MinimumCacheUsage console variable. It’s initialized with a default value of 0.9f.

MinimumCacheUsageCvar interacts directly with au.streamcaching.MinimumCacheUsage, as they share the same value. It’s also used in calculations involving other variables like MaxChunkSize and ChunkSlotNumScalarCvar.

Developers should be aware that this variable is clamped between 0.0 and (1.0f - UE_KINDA_SMALL_NUMBER) to prevent invalid values. It’s crucial in determining the balance between cache usage and the number of audio chunks.

Best practices for using MinimumCacheUsageCvar include:

  1. Treat it as read-only in most cases, modifying it through the au.streamcaching.MinimumCacheUsage console variable instead.
  2. Consider its impact on memory usage and disk I/O performance when adjusting related audio streaming settings.
  3. Monitor its effects in conjunction with other audio streaming parameters for optimal performance.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/AudioCompressionSettingsUtils.cpp:37

Scope: file

Source code excerpt:

static float MinimumCacheUsageCvar = 0.9f;
FAutoConsoleVariableRef CVarMinimumCacheUsage(
	TEXT("au.streamcaching.MinimumCacheUsage"),
	MinimumCacheUsageCvar,
	TEXT("This value is the minimum potential usage of the stream cache we feasibly want to support. Setting this to 0.25, for example, cause us to potentially be using 25% of our cache size when we start evicting chunks, worst cast scenario.\n")
	TEXT("0.0: limit the number of chunks to our (Cache Size / Max Chunk Size) [0.01-0.99]: Increase our number of chunks to limit disk IO when we have lots of small sounds playing."),
	ECVF_Default);

static float ChunkSlotNumScalarCvar = 1.0f;

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/AudioCompressionSettingsUtils.cpp:35

Scope: file

Source code excerpt:

 * A minimum cache usage of 1.0f is impossible, because it would require an infinite amount of chunks.
 */
static float MinimumCacheUsageCvar = 0.9f;
FAutoConsoleVariableRef CVarMinimumCacheUsage(
	TEXT("au.streamcaching.MinimumCacheUsage"),
	MinimumCacheUsageCvar,
	TEXT("This value is the minimum potential usage of the stream cache we feasibly want to support. Setting this to 0.25, for example, cause us to potentially be using 25% of our cache size when we start evicting chunks, worst cast scenario.\n")
	TEXT("0.0: limit the number of chunks to our (Cache Size / Max Chunk Size) [0.01-0.99]: Increase our number of chunks to limit disk IO when we have lots of small sounds playing."),
	ECVF_Default);

static float ChunkSlotNumScalarCvar = 1.0f;
FAutoConsoleVariableRef CVarChunkSlotNumScalar(

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/AudioCompressionSettingsUtils.cpp:348

Scope (from outer to inner):

file
function     FCachedAudioStreamingManagerParams FPlatformCompressionUtilities::BuildCachedStreamingManagerParams

Source code excerpt:


	// Our number of elements is tweakable based on the minimum cache usage we want to support.
	const float MinimumCacheUsage = FMath::Clamp(MinimumCacheUsageCvar, 0.0f, (1.0f - UE_KINDA_SMALL_NUMBER));
	int32 MinChunkSize = (1.0f - MinimumCacheUsage) * MaxChunkSize;
	
	uint64 TempNumElements = ((CacheSettings.CacheSizeKB * 1024) / MinChunkSize) * FMath::Max(ChunkSlotNumScalarCvar, 1.0f);
	int32 NumElements = FMath::Min(TempNumElements, static_cast<uint64>(TNumericLimits< int32 >::Max()));

	FCachedAudioStreamingManagerParams Params;