AudioThread.EnableAudioCommandLogging

AudioThread.EnableAudioCommandLogging

#Overview

name: AudioThread.EnableAudioCommandLogging

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.EnableAudioCommandLogging is to enable or disable logging of audio commands in the Unreal Engine’s audio system. This setting variable is primarily used for debugging and performance analysis of the audio subsystem.

The Unreal Engine’s audio system, specifically the audio thread module, relies on this setting variable. It is referenced in the Engine/Source/Runtime/Engine/Private/AudioThread.cpp file, which is part of the core engine’s audio processing system.

The value of this variable is set through a console variable (CVar) system. It is initialized to 0 (disabled) by default, but can be changed at runtime using the console command system. The associated C++ variable is GCVarEnableAudioCommandLogging.

This variable interacts with the audio command processing system. When enabled (set to 1), it wraps audio commands with additional logging and profiling code.

Developers must be aware that enabling this variable may have a performance impact, as it adds logging overhead to audio command processing. It should primarily be used for debugging and profiling purposes, not in production builds.

Best practices for using this variable include:

  1. Keep it disabled (0) for normal operation and production builds.
  2. Enable it (1) when debugging audio-related issues or analyzing audio system performance.
  3. Be mindful of the potential performance impact when enabled.
  4. Use in conjunction with other audio debugging tools and console variables for comprehensive audio system analysis.

Regarding the associated variable GCVarEnableAudioCommandLogging:

This is the actual C++ variable that stores the value of the AudioThread.EnableAudioCommandLogging setting. It is defined as a static integer and is directly manipulated by the console variable system.

The purpose of GCVarEnableAudioCommandLogging is to provide a C++ accessible representation of the AudioThread.EnableAudioCommandLogging setting. It allows the audio thread code to quickly check the current state of the logging setting without having to query the console variable system each time.

This variable is used in the GetCommandWrapper function of the FAudioThread class to determine whether to wrap audio commands with additional logging code. When GCVarEnableAudioCommandLogging is set to 1, it triggers the creation of a wrapper function that includes cycle counting and stat ID tracking for each audio command.

Developers should be aware that changes to AudioThread.EnableAudioCommandLogging via the console will be reflected in GCVarEnableAudioCommandLogging, and vice versa. They should not modify GCVarEnableAudioCommandLogging directly, but instead use the console variable system to ensure proper synchronization between the two.

Best practices for GCVarEnableAudioCommandLogging include:

  1. Treat it as a read-only variable in most cases, using the console variable system for modifications.
  2. Use it for quick checks in performance-sensitive code paths where querying the full console variable might be too expensive.
  3. Be aware of its impact on audio command processing when enabled.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:


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

static int32 GCVarEnableBatchProcessing = 1;
FAutoConsoleVariableRef CVarEnableBatchProcessing(
	TEXT("AudioThread.EnableBatchProcessing"),
	GCVarEnableBatchProcessing,
	TEXT("Enables batch processing audio thread commands.\n")

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

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

static int32 GCVarEnableBatchProcessing = 1;
FAutoConsoleVariableRef CVarEnableBatchProcessing(
	TEXT("AudioThread.EnableBatchProcessing"),
	GCVarEnableBatchProcessing,
	TEXT("Enables batch processing audio thread commands.\n")

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

Scope (from outer to inner):

file
function     TUniqueFunction<void

Source code excerpt:

TUniqueFunction<void()> FAudioThread::GetCommandWrapper(TUniqueFunction<void()> InFunction, const TStatId InStatId)
{
	if (GCVarEnableAudioCommandLogging == 1)
	{
		return [Function = MoveTemp(InFunction), InStatId]()
		{
			FScopeCycleCounter ScopeCycleCounter(InStatId);
			FAudioThread::SetCurrentAudioThreadStatId(InStatId);