au.streamcache.DispatchToGameThreadOnChunkRequest

au.streamcache.DispatchToGameThreadOnChunkRequest

#Overview

name: au.streamcache.DispatchToGameThreadOnChunkRequest

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.DispatchToGameThreadOnChunkRequest is to control how audio chunk requests are handled in Unreal Engine’s audio streaming system. Specifically, it determines whether callbacks for completed USoundWave requests should be dispatched to the game thread or handled immediately on the loading thread.

This setting variable is primarily used in the audio streaming subsystem of Unreal Engine. It affects how audio chunks are loaded and processed, which is part of the Engine’s audio module.

The value of this variable is set through the console variable system. It’s initialized to 1 by default, as seen in the source code excerpt.

The associated variable DispatchToGameThreadOnChunkRequestCVar directly interacts with au.streamcache.DispatchToGameThreadOnChunkRequest. They share the same value, with DispatchToGameThreadOnChunkRequestCVar being the actual integer variable used in the code logic.

Developers must be aware that setting this variable to 1 (default) may cause audio chunks to be evicted from memory by the time they are needed. This is because dispatching to the game thread introduces a delay between when the chunk is loaded and when it’s processed.

Best practices when using this variable:

  1. Keep it at the default value (1) unless you’re experiencing specific issues with audio streaming.
  2. If you’re noticing audio chunks being evicted before they can be used, consider setting it to 0 to process chunks immediately upon loading.
  3. Be cautious when changing this value, as it can affect audio performance and behavior across the entire game.

Regarding the associated variable DispatchToGameThreadOnChunkRequestCVar:

The purpose of DispatchToGameThreadOnChunkRequestCVar is to serve as the actual integer variable that stores the value of the au.streamcache.DispatchToGameThreadOnChunkRequest setting.

This variable is used directly in the audio streaming system of Unreal Engine, specifically in the USoundWave class, which is part of the Engine’s audio module.

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

It interacts directly with the au.streamcache.DispatchToGameThreadOnChunkRequest console variable, serving as its in-code representation.

Developers should be aware that this variable directly affects the behavior of audio chunk loading and processing. When non-zero, it causes callbacks to be dispatched to the game thread, which can introduce delays in audio processing.

Best practices for using this variable:

  1. Avoid modifying it directly in code; instead, use the console variable system to change its value.
  2. When debugging audio streaming issues, monitor this variable’s value to understand how audio chunk requests are being handled.
  3. Consider the performance implications of its value, especially on different platforms or with varying audio workloads.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

static int32 DispatchToGameThreadOnChunkRequestCVar = 1;
FAutoConsoleVariableRef CVarDispatchToGameThreadOnChunkRequest(
	TEXT("au.streamcache.DispatchToGameThreadOnChunkRequest"),
	DispatchToGameThreadOnChunkRequestCVar,
	TEXT("When set to 1, we will always dispatch a callback to the game thread whenever a USoundWave request has finished. This may cause chunks of audio to be evicted by the time we need them.\n")
	TEXT("0: as soon as the chunk is loaded, capture the audio chunk. 1: As soon as the chunk is loaded, dispatch a callback to the gamethread."),
	ECVF_Default);

static int32 AllowReverbForMultichannelSources = 1;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

	ECVF_Default);

static int32 DispatchToGameThreadOnChunkRequestCVar = 1;
FAutoConsoleVariableRef CVarDispatchToGameThreadOnChunkRequest(
	TEXT("au.streamcache.DispatchToGameThreadOnChunkRequest"),
	DispatchToGameThreadOnChunkRequestCVar,
	TEXT("When set to 1, we will always dispatch a callback to the game thread whenever a USoundWave request has finished. This may cause chunks of audio to be evicted by the time we need them.\n")
	TEXT("0: as soon as the chunk is loaded, capture the audio chunk. 1: As soon as the chunk is loaded, dispatch a callback to the gamethread."),
	ECVF_Default);

static int32 AllowReverbForMultichannelSources = 1;
FAutoConsoleVariableRef CvarAllowReverbForMultichannelSources(

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

Scope (from outer to inner):

file
function     void USoundWave::GetHandleForChunkOfAudio

Source code excerpt:

void USoundWave::GetHandleForChunkOfAudio(TFunction<void(FAudioChunkHandle&&)> OnLoadCompleted, bool bForceSync /*= false*/, int32 ChunkIndex /*= 1*/, ENamedThreads::Type CallbackThread /*= ENamedThreads::GameThread*/)
{
	ENamedThreads::Type ThreadToDispatchCallbackOn = (DispatchToGameThreadOnChunkRequestCVar != 0) ? ENamedThreads::GameThread : ENamedThreads::AnyThread;

	if (!Proxy.IsValid() && FApp::CanEverRenderAudio())
	{
		Proxy = CreateSoundWaveProxy();
	}