au.streamcache.DisableRetaining

au.streamcache.DisableRetaining

#Overview

name: au.streamcache.DisableRetaining

The value of this variable can be defined or overridden in .ini config files. 1 .ini config file referencing this setting variable.

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

• type: Var
• help: When set to 1, USoundWaves will not retain chunks of their own audio.\n0: Don\'t disable retaining, 1: disable retaining.

It is referenced in 5 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of au.streamcache.DisableRetaining is to control whether USoundWaves retain chunks of their own audio in the audio streaming system. This setting variable is part of Unreal Engine’s audio system, specifically related to sound streaming and caching.

The Unreal Engine subsystem that relies on this setting variable is the audio streaming system, particularly within the Engine module. It’s used in the SoundWave.cpp file, which is part of the core audio functionality.

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

The associated variable DisableRetainingCVar interacts directly with au.streamcache.DisableRetaining. They share the same value, with DisableRetainingCVar being the C++ variable that’s used in the code to check the setting’s value.

Developers must be aware that:

1. When set to 1, USoundWaves will not retain chunks of their own audio.
2. This setting affects the behavior of sound loading and streaming, potentially impacting memory usage and audio performance.
3. It can be changed at runtime, which might affect already loaded sound assets.

Best practices when using this variable include:

1. Consider the memory and performance implications before changing the default value.
2. Test thoroughly when modifying this setting, as it can affect the entire audio streaming system.
3. Use it in conjunction with other audio streaming settings for optimal performance.

Regarding the associated variable DisableRetainingCVar:

• It’s the C++ representation of the console variable au.streamcache.DisableRetaining.
• It’s used in various parts of the SoundWave.cpp file to control audio chunk retention behavior.
• It affects the PostLoad() function of USoundWave, determining whether to retain or release compressed audio.
• It’s also used in the RetainCompressedAudio() function to decide whether to proceed with audio retention.

Developers should be aware that changes to DisableRetainingCVar will directly impact the behavior controlled by au.streamcache.DisableRetaining. They should use this variable when implementing custom audio streaming logic or when optimizing audio memory usage in their games.

#Setting Variables

#References In INI files

Location: <Workspace>/Projects/Lyra/Config/IOS/IOSEngine.ini:17, section: [ConsoleVariables]

• INI Section: ConsoleVariables
• Raw value: 1
• Is Array: False

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/SoundWave.cpp:56

Scope: file

Source code excerpt:

static int32 DisableRetainingCVar = 0;
FAutoConsoleVariableRef CVarDisableRetaining(
	TEXT("au.streamcache.DisableRetaining"),
	DisableRetainingCVar,
	TEXT("When set to 1, USoundWaves will not retain chunks of their own audio.\n")
	TEXT("0: Don't disable retaining, 1: disable retaining."),
	ECVF_Default);

static int32 BlockOnChunkLoadCompletionCVar = 0;

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/SoundWave.cpp:54

Scope: file

Source code excerpt:

	ECVF_Default);

static int32 DisableRetainingCVar = 0;
FAutoConsoleVariableRef CVarDisableRetaining(
	TEXT("au.streamcache.DisableRetaining"),
	DisableRetainingCVar,
	TEXT("When set to 1, USoundWaves will not retain chunks of their own audio.\n")
	TEXT("0: Don't disable retaining, 1: disable retaining."),
	ECVF_Default);

static int32 BlockOnChunkLoadCompletionCVar = 0;
FAutoConsoleVariableRef CVarBlockOnChunkLoadCompletion(

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/SoundWave.cpp:1994

Scope (from outer to inner):

file
function     void USoundWave::PostLoad

Source code excerpt:

		if (ShouldUseStreamCaching())
		{
			if (!GIsEditor && !DisableRetainingCVar && ActualLoadingBehavior == ESoundWaveLoadingBehavior::RetainOnLoad)
			{
				RetainCompressedAudio(false);
			}
			else
			{
				// if a sound class defined our loading behavior as something other than Retain and our cvar default is to retain, we need to release our handle.

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/SoundWave.cpp:2016

Scope (from outer to inner):

file
function     void USoundWave::PostLoad

Source code excerpt:

			}

			// If DisableRetainingCVar was set after this USoundWave was loaded by the ALT, release its compressed audio here.
			if (DisableRetainingCVar)
			{
				ReleaseCompressedAudio();
			}

			if (!GIsEditor)
			{

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/SoundWave.cpp:4220

Scope (from outer to inner):

file
function     void USoundWave::RetainCompressedAudio

Source code excerpt:

	// Since the zeroth chunk is always inlined and stored in memory,
	// early exit if we only have one chunk.
	if (GIsEditor || IsTemplate() || IsRunningDedicatedServer() || !IsStreaming() || !FApp::CanEverRenderAudio() || DisableRetainingCVar || GetNumChunks() <= 1)
	{
		return;
	}

	// If the first chunk is already loaded and being retained,
	// don't kick off another load.