au.streamcache.BlockOnChunkLoadCompletion

au.streamcache.BlockOnChunkLoadCompletion

#Overview

name: au.streamcache.BlockOnChunkLoadCompletion

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.streamcache.BlockOnChunkLoadCompletion is to control the behavior of audio chunk loading in Unreal Engine 5’s audio streaming system. Specifically, it determines whether the engine should attempt to synchronously load a chunk after a USoundWave request has finished.

This setting variable is primarily used in the audio streaming subsystem of Unreal Engine 5, particularly within the Engine module. It affects how SoundWave objects handle chunk loading requests.

The value of this variable is set through the console variable system. It’s initialized to 0 by default, but can be changed at runtime using console commands or through configuration files.

The associated variable BlockOnChunkLoadCompletionCVar directly interacts with au.streamcache.BlockOnChunkLoadCompletion. They share the same value, with BlockOnChunkLoadCompletionCVar being the C++ variable that actually holds the value.

Developers must be aware that setting this variable to 1 will cause the engine to always attempt synchronous loading of audio chunks after a USoundWave request has finished. This can potentially impact performance, especially if used extensively, as synchronous loading can cause frame rate hitches.

Best practices when using this variable include:

  1. Leaving it at the default value (0) unless there’s a specific need for synchronous loading.
  2. If enabled, use it sparingly and only for critical audio that must be loaded immediately.
  3. Consider the performance implications, especially on slower storage devices.
  4. Use in conjunction with proper audio streaming and caching strategies to minimize potential performance impacts.

Regarding the associated variable BlockOnChunkLoadCompletionCVar:

The purpose of BlockOnChunkLoadCompletionCVar is to serve as the actual C++ variable that holds the value of the au.streamcache.BlockOnChunkLoadCompletion console variable.

It’s used within the Engine module, specifically in the audio streaming system, to determine whether to block on chunk load completion.

The value of this variable is set through the FAutoConsoleVariableRef system, which links it to the console variable au.streamcache.BlockOnChunkLoadCompletion.

It directly interacts with au.streamcache.BlockOnChunkLoadCompletion, serving as its C++ representation.

Developers should be aware that this variable is used in conditional statements to determine the behavior of chunk loading. For example, in the GetHandleForChunkOfAudio function, it’s used to decide whether to force synchronous loading of a chunk.

Best practices for this variable are the same as for au.streamcache.BlockOnChunkLoadCompletion, as they are essentially two representations of the same setting.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

static int32 BlockOnChunkLoadCompletionCVar = 0;
FAutoConsoleVariableRef CVarBlockOnChunkLoadCompletion(
	TEXT("au.streamcache.BlockOnChunkLoadCompletion"),
	BlockOnChunkLoadCompletionCVar,
	TEXT("When set to 1, USoundWaves we will always attempt to synchronously load a chunk after a USoundWave request has finished.\n")
	TEXT("0: Don't try to block after a SoundWave has completed loading a chunk, 1: Block after a USoundWave's chunk request has completed."),
	ECVF_Default);

static int32 DispatchToGameThreadOnChunkRequestCVar = 1;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

	ECVF_Default);

static int32 BlockOnChunkLoadCompletionCVar = 0;
FAutoConsoleVariableRef CVarBlockOnChunkLoadCompletion(
	TEXT("au.streamcache.BlockOnChunkLoadCompletion"),
	BlockOnChunkLoadCompletionCVar,
	TEXT("When set to 1, USoundWaves we will always attempt to synchronously load a chunk after a USoundWave request has finished.\n")
	TEXT("0: Don't try to block after a SoundWave has completed loading a chunk, 1: Block after a USoundWave's chunk request has completed."),
	ECVF_Default);

static int32 DispatchToGameThreadOnChunkRequestCVar = 1;
FAutoConsoleVariableRef CVarDispatchToGameThreadOnChunkRequest(

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

Scope (from outer to inner):

file
function     void USoundWave::GetHandleForChunkOfAudio
lambda-function

Source code excerpt:

			{
				USoundWave* ThisSoundWave = WeakThis.Get();
				FAudioChunkHandle ChunkHandle = IStreamingManager::Get().GetAudioStreamingManager().GetLoadedChunk(ThisSoundWave->Proxy, ChunkIndex, (BlockOnChunkLoadCompletionCVar != 0));

				// If we hit this, something went wrong in GetLoadedChunk.
				if (!ChunkHandle.IsValid())
				{
					UE_LOG(LogAudio, Display, TEXT("Failed to retrieve chunk %d from sound %s after successfully requesting it!"), ChunkIndex, *(WeakThis->GetName()));
				}