AudioThread.SuspendAudioThread

AudioThread.SuspendAudioThread

#Overview

name: AudioThread.SuspendAudioThread

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 AudioThread.SuspendAudioThread is to control the suspension state of the audio thread in Unreal Engine 5. It is used to manage the execution of the audio processing system.

This setting variable is primarily used in the Engine module, specifically within the audio thread management system. It is referenced in the AudioThread.cpp file, which is part of the core audio processing infrastructure.

The value of this variable is set through a console variable (CVar) system. It is initialized with a default value of 0 and can be changed at runtime using console commands or through code.

The AudioThread.SuspendAudioThread variable interacts closely with the GCVarSuspendAudioThread variable. They share the same value, with GCVarSuspendAudioThread being the actual storage for the setting.

Developers must be aware that this variable has a significant impact on audio processing. When set to 1, it suspends the audio thread, which can affect real-time audio performance. It should be used cautiously, primarily for debugging or specific performance optimizations.

Best practices for using this variable include:

  1. Only use it when necessary for debugging or performance analysis.
  2. Always ensure to resume the audio thread (set to 0) after suspending it to avoid long-term audio issues.
  3. Be mindful of the potential impact on audio quality and latency when suspending the audio thread.

Regarding the associated variable GCVarSuspendAudioThread:

The purpose of GCVarSuspendAudioThread is to store the actual value of the AudioThread.SuspendAudioThread setting. It is an integer variable that acts as the backend for the console variable system.

This variable is used within the Engine module, specifically in the audio thread management system. It is checked in the UseAudioThreadCVarSinkFunction to determine whether the audio thread should be suspended or resumed.

The value of GCVarSuspendAudioThread is set through the console variable system and can be modified at runtime.

GCVarSuspendAudioThread interacts directly with the AudioThread.SuspendAudioThread console variable and indirectly with the GIsAudioThreadSuspended atomic boolean variable.

Developers should be aware that changes to GCVarSuspendAudioThread will directly affect the behavior of the audio thread. It’s crucial to handle this variable carefully to avoid unintended audio processing interruptions.

Best practices for using GCVarSuspendAudioThread include:

  1. Avoid direct manipulation of this variable; instead, use the console variable system to modify it.
  2. When checking its value, be aware that it might change asynchronously due to console commands.
  3. Consider the thread safety implications when accessing this variable from different threads.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:


static int32 GCVarSuspendAudioThread = 0;
FAutoConsoleVariableRef CVarSuspendAudioThread(TEXT("AudioThread.SuspendAudioThread"), GCVarSuspendAudioThread, TEXT("0=Resume, 1=Suspend"), ECVF_Cheat);

static int32 GCVarAboveNormalAudioThreadPri = 0;
FAutoConsoleVariableRef CVarAboveNormalAudioThreadPri(TEXT("AudioThread.AboveNormalPriority"), GCVarAboveNormalAudioThreadPri, TEXT("0=Normal, 1=AboveNormal"), ECVF_Default);

static int32 GCVarEnableAudioCommandLogging = 0;
FAutoConsoleVariableRef CVarEnableAudioCommandLogging(TEXT("AudioThread.EnableAudioCommandLogging"), GCVarEnableAudioCommandLogging, TEXT("0=Disbaled, 1=Enabled"), ECVF_Default);

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/AudioThread.cpp:18

Scope: file

Source code excerpt:

extern CORE_API std::atomic<bool> GIsAudioThreadSuspended;

static int32 GCVarSuspendAudioThread = 0;
FAutoConsoleVariableRef CVarSuspendAudioThread(TEXT("AudioThread.SuspendAudioThread"), GCVarSuspendAudioThread, TEXT("0=Resume, 1=Suspend"), ECVF_Cheat);

static int32 GCVarAboveNormalAudioThreadPri = 0;
FAutoConsoleVariableRef CVarAboveNormalAudioThreadPri(TEXT("AudioThread.AboveNormalPriority"), GCVarAboveNormalAudioThreadPri, TEXT("0=Normal, 1=AboveNormal"), ECVF_Default);

static int32 GCVarEnableAudioCommandLogging = 0;
FAutoConsoleVariableRef CVarEnableAudioCommandLogging(TEXT("AudioThread.EnableAudioCommandLogging"), GCVarEnableAudioCommandLogging, TEXT("0=Disbaled, 1=Enabled"), ECVF_Default);

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/AudioThread.cpp:54

Scope (from outer to inner):

file
function     static void UseAudioThreadCVarSinkFunction

Source code excerpt:

	{
		static bool bLastSuspendAudioThread = false;
		const bool bSuspendAudioThread = GCVarSuspendAudioThread != 0;

		if (bLastSuspendAudioThread != bSuspendAudioThread)
		{
			bLastSuspendAudioThread = bSuspendAudioThread;
			if (bSuspendAudioThread && IsAudioThreadRunning())
			{