au.streamcaching.ForceBlockForLoad

au.streamcaching.ForceBlockForLoad

#Overview

name: au.streamcaching.ForceBlockForLoad

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.ForceBlockForLoad is to control the behavior of audio chunk loading in Unreal Engine’s audio streaming system. Specifically, it determines whether the engine should block and wait for disk reads to complete when retrieving loaded audio chunks.

This setting variable is primarily used in the audio streaming subsystem of Unreal Engine, which is part of the Engine module. It’s referenced in the AudioStreamingCache.cpp file, indicating its relevance to the audio streaming cache functionality.

The value of this variable is set through the Unreal Engine Console Variable (CVar) system. It’s initialized to 0 by default but can be changed at runtime using console commands or through configuration files.

The associated variable ForceBlockForLoadCVar directly interacts with au.streamcaching.ForceBlockForLoad. They share the same value, with ForceBlockForLoadCVar being the actual integer variable used in the C++ code.

Developers must be aware that setting this variable to a non-zero value will cause the GetLoadedChunk function to block until the disk read is complete. This can potentially impact performance, especially in scenarios where quick, non-blocking audio streaming is desired.

Best practices when using this variable include:

  1. Keeping it at its default value (0) for most scenarios to allow for non-blocking audio streaming.
  2. Only setting it to a non-zero value when debugging or in specific situations where ensuring immediate audio chunk availability is critical.
  3. Monitoring performance impact when enabled, as it may introduce latency in audio streaming.
  4. Using it in conjunction with other audio streaming settings for optimal configuration.

Regarding the associated variable ForceBlockForLoadCVar:

The purpose of ForceBlockForLoadCVar is to serve as the actual integer storage for the au.streamcaching.ForceBlockForLoad setting. It’s used directly in the C++ code to control the blocking behavior of the GetLoadedChunk function.

This variable is part of the audio streaming system in the Engine module. It’s defined and used within the AudioStreamingCache.cpp file.

The value of ForceBlockForLoadCVar is set through the CVar system, mirroring the value of au.streamcaching.ForceBlockForLoad.

ForceBlockForLoadCVar interacts directly with the GetLoadedChunk function, influencing its blocking behavior based on its value.

Developers should be aware that modifying ForceBlockForLoadCVar directly in code is not recommended. Instead, they should use the CVar system to modify au.streamcaching.ForceBlockForLoad, which will automatically update ForceBlockForLoadCVar.

Best practices for ForceBlockForLoadCVar include:

  1. Treating it as a read-only variable in most code contexts.
  2. Relying on the CVar system for modifications rather than direct assignment.
  3. Using it for conditional logic in audio streaming-related functions, as demonstrated in the GetLoadedChunk function.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

static int32 ForceBlockForLoadCVar = 0;
FAutoConsoleVariableRef CVarForceBlockForLoad(
	TEXT("au.streamcaching.ForceBlockForLoad"),
	ForceBlockForLoadCVar,
	TEXT("When set to a nonzero value, blocks GetLoadedChunk until the disk read is complete.\n"),
	ECVF_Default);

static int32 TrimCacheWhenOverBudgetCVar = 1;
FAutoConsoleVariableRef CVarTrimCacheWhenOverBudget(

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

	ECVF_Default);

static int32 ForceBlockForLoadCVar = 0;
FAutoConsoleVariableRef CVarForceBlockForLoad(
	TEXT("au.streamcaching.ForceBlockForLoad"),
	ForceBlockForLoadCVar,
	TEXT("When set to a nonzero value, blocks GetLoadedChunk until the disk read is complete.\n"),
	ECVF_Default);

static int32 TrimCacheWhenOverBudgetCVar = 1;
FAutoConsoleVariableRef CVarTrimCacheWhenOverBudget(
	TEXT("au.streamcaching.TrimCacheWhenOverBudget"),

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

Scope (from outer to inner):

file
function     FAudioChunkHandle FCachedAudioStreamingManager::GetLoadedChunk

Source code excerpt:

{
	LLM_SCOPE(ELLMTag::AudioStreamCache);
	bBlockForLoad |= (ForceBlockForLoadCVar != 0);

	if (!ensure(SoundWave.IsValid()))
	{
		return {};
	}