au.streamcache.priming.ManuallyPrimeChildNodes

au.streamcache.priming.ManuallyPrimeChildNodes

#Overview

name: au.streamcache.priming.ManuallyPrimeChildNodes

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

• type: Var
• help: When set to 1, we ignore the loading behavior of sound classes set on a Sound Cue directly.\n

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of au.streamcache.priming.ManuallyPrimeChildNodes is to control the loading behavior of sound classes in Sound Cues within Unreal Engine’s audio system.

This setting variable is primarily used by the audio subsystem of Unreal Engine, specifically in the context of sound node management and streaming.

The value of this variable is set using an FAutoConsoleVariableRef in the SoundNode.cpp file. It’s initialized with a default value of 1.

The associated variable ManuallyPrimeChildNodesCVar interacts directly with au.streamcache.priming.ManuallyPrimeChildNodes. They share the same value and are used interchangeably in the code.

Developers must be aware that when this variable is set to 1, it ignores the loading behavior of sound classes set directly on a Sound Cue. This can have significant implications for how audio content is loaded and managed in the engine.

Best practices when using this variable include:

1. Carefully consider the impact on audio loading performance before modifying its value.
2. Test thoroughly after changing this setting, as it may affect the behavior of Sound Cues throughout the project.
3. Document any changes to this variable in the project, as it can have wide-reaching effects on audio behavior.

Regarding the associated variable ManuallyPrimeChildNodesCVar:

The purpose of ManuallyPrimeChildNodesCVar is to serve as the actual storage for the au.streamcache.priming.ManuallyPrimeChildNodes setting within the C++ code.

This variable is used directly in the USoundNode::PrimeChildWavePlayers function to determine whether to manually prime child wave players. It’s checked alongside other conditions to decide on the priming behavior.

The value of ManuallyPrimeChildNodesCVar is set through the FAutoConsoleVariableRef mechanism, which links it to the console variable au.streamcache.priming.ManuallyPrimeChildNodes.

ManuallyPrimeChildNodesCVar interacts with other variables in the priming logic, such as BypassRetainInSoundNodesCVar and the result of IsAsyncLoadingMultithreaded().

Developers should be aware that this variable directly affects the behavior of the PrimeChildWavePlayers function, which is crucial for audio streaming and performance.

Best practices for ManuallyPrimeChildNodesCVar include:

1. Treat it as read-only within the code, as its value is managed by the console variable system.
2. When debugging audio loading issues, check the value of this variable to understand the current priming behavior.
3. Consider the implications of this variable when optimizing audio streaming performance in the engine.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

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

/*-----------------------------------------------------------------------------
	USoundNode implementation.

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

	ECVF_Default);

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

/*-----------------------------------------------------------------------------
	USoundNode implementation.
-----------------------------------------------------------------------------*/

#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)