au.streamcache.priming.BypassRetainFromSoundCues

au.streamcache.priming.BypassRetainFromSoundCues

#Overview

name: au.streamcache.priming.BypassRetainFromSoundCues

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.streamcache.priming.BypassRetainFromSoundCues is to control the loading behavior of sound classes set on Sound Cues directly in Unreal Engine’s audio system.

This setting variable is primarily used in the audio streaming and caching subsystem of Unreal Engine. It’s specifically related to the Sound Cue and Sound Node functionality within the Engine module.

The value of this variable is set through the Unreal Engine’s console variable system. It’s defined as a static integer and initialized to 0 by default. The FAutoConsoleVariableRef class is used to expose it as a console variable that can be changed at runtime.

This variable interacts closely with another variable named BypassRetainInSoundNodesCVar. They share the same value, with BypassRetainInSoundNodesCVar being the actual storage for the setting.

Developers must be aware that when this variable is set to 1, it ignores the loading behavior of sound classes set on a Sound Cue directly. This can significantly affect how audio is loaded and streamed in the game.

Best practices when using this variable include:

  1. Only modify it if you fully understand the implications on your game’s audio performance.
  2. Use it in conjunction with profiling tools to measure the impact on audio loading times and memory usage.
  3. Consider the trade-offs between immediate audio availability and memory usage when deciding to bypass retain behavior.

Regarding the associated variable BypassRetainInSoundNodesCVar:

The purpose of BypassRetainInSoundNodesCVar is to provide a C++ accessible storage for the au.streamcache.priming.BypassRetainFromSoundCues setting.

This variable is used directly in the Engine module, specifically in the SoundNode.cpp file. It’s part of the audio system’s implementation.

The value of this variable is set indirectly through the console variable system, mirroring the value of au.streamcache.priming.BypassRetainFromSoundCues.

It interacts with ManuallyPrimeChildNodesCVar in determining the behavior of child node priming and wave player loading.

Developers should be aware that this variable directly affects the behavior of functions like PrimeChildWavePlayers and OverrideLoadingBehaviorOnChildWaves.

Best practices include:

  1. Treat this variable as read-only in most cases, modifying it through the console variable system instead.
  2. Consider its value when debugging audio loading issues, especially those related to Sound Cues and child nodes.
  3. Be cautious about changing its value during runtime, as it can have immediate effects on audio loading behavior.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/SoundNode.cpp:14

Scope: file

Source code excerpt:

static int32 BypassRetainInSoundNodesCVar = 0;
FAutoConsoleVariableRef CVarBypassRetainInSoundNodes(
	TEXT("au.streamcache.priming.BypassRetainFromSoundCues"),
	BypassRetainInSoundNodesCVar,
	TEXT("When set to 1, we ignore the loading behavior of sound classes set on a Sound Cue directly.\n"),
	ECVF_Default);

static int32 ManuallyPrimeChildNodesCVar = 1;
FAutoConsoleVariableRef CVarManuallyPrimeChildNodes(

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/SoundNode.cpp:12

Scope: file

Source code excerpt:

#include UE_INLINE_GENERATED_CPP_BY_NAME(SoundNode)

static int32 BypassRetainInSoundNodesCVar = 0;
FAutoConsoleVariableRef CVarBypassRetainInSoundNodes(
	TEXT("au.streamcache.priming.BypassRetainFromSoundCues"),
	BypassRetainInSoundNodesCVar,
	TEXT("When set to 1, we ignore the loading behavior of sound classes set on a Sound Cue directly.\n"),
	ECVF_Default);

static int32 ManuallyPrimeChildNodesCVar = 1;
FAutoConsoleVariableRef CVarManuallyPrimeChildNodes(			
	TEXT("au.streamcache.priming.ManuallyPrimeChildNodes"),

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/SoundNode.cpp:119

Scope (from outer to inner):

file
function     void USoundNode::PrimeChildWavePlayers

Source code excerpt:

	// any pending async loads to complete, which will never happen if WE are the (non)"async loading thread"
	// for now, in the synchronous loading case, we fallback to the old behavior.
	if(!BypassRetainInSoundNodesCVar && ManuallyPrimeChildNodesCVar && IsAsyncLoadingMultithreaded())
	{	
		// Search child nodes for wave players, then prime each soundwave
		IAudioStreamingManager &Mgr = IStreamingManager::Get().GetAudioStreamingManager();
		for (USoundNode* ChildNode : ChildNodes)
		{
			if (ChildNode)

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/SoundNode.cpp:159

Scope (from outer to inner):

file
function     void USoundNode::OverrideLoadingBehaviorOnChildWaves

Source code excerpt:

void USoundNode::OverrideLoadingBehaviorOnChildWaves(const bool bRecurse, const ESoundWaveLoadingBehavior InLoadingBehavior)
{
	if (!BypassRetainInSoundNodesCVar && FPlatformCompressionUtilities::IsCurrentPlatformUsingStreamCaching())
	{
		// Search child nodes for wave players, then override their waves' loading behavior.
		for (USoundNode* ChildNode : ChildNodes)
		{
			if (ChildNode)
			{