au.FlushAudioRenderCommandsOnSuspend

au.FlushAudioRenderCommandsOnSuspend

#Overview

name: au.FlushAudioRenderCommandsOnSuspend

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.FlushAudioRenderCommandsOnSuspend is to control whether pending commands to the audio thread and audio render thread are processed when the application is suspended. This setting variable is part of the audio system in Unreal Engine 5.

The Unreal Engine subsystem that relies on this setting variable is the Audio System, specifically within the Audio Device Manager module. This can be seen from the file path “Engine/Source/Runtime/Engine/Private/AudioDeviceManager.cpp”.

The value of this variable is set through the Unreal Engine’s console variable system. It is initialized to 0 and can be changed at runtime using console commands or through code.

This variable interacts with the associated variable GCVarFlushAudioRenderCommandsOnSuspend. They share the same value, with au.FlushAudioRenderCommandsOnSuspend being the console-accessible name and GCVarFlushAudioRenderCommandsOnSuspend being the C++ variable used in the code.

Developers must be aware that this variable affects the behavior of the audio system when the application is suspended. When set to 1, it ensures that all pending commands to the audio thread and audio render thread are processed before suspension occurs.

Best practices for using this variable include:

  1. Leave it at the default value (0) unless there’s a specific need to flush audio commands on suspension.
  2. If audio artifacts or issues occur when the application is suspended or resumed, consider enabling this option to see if it resolves the problem.
  3. Be aware of potential performance implications when enabling this option, as it may increase the time it takes for the application to suspend.

Regarding the associated variable GCVarFlushAudioRenderCommandsOnSuspend:

The purpose of GCVarFlushAudioRenderCommandsOnSuspend is to serve as the internal C++ representation of the au.FlushAudioRenderCommandsOnSuspend console variable.

This variable is used directly in the code to check whether audio commands should be flushed when the application is entering the background. It’s referenced in the AppWillEnterBackground function of the FAudioDeviceManager class.

The value of this variable is set through the console variable system, just like au.FlushAudioRenderCommandsOnSuspend.

GCVarFlushAudioRenderCommandsOnSuspend interacts directly with the logic that handles application suspension in the audio system. When it’s set to a non-zero value, it triggers the flushing of audio commands.

Developers should be aware that modifying this variable directly in C++ code is not recommended. Instead, they should use the console variable system to change its value.

Best practices for this variable include:

  1. Treat it as read-only in most cases, using it for conditional checks in the audio system code.
  2. If there’s a need to programmatically change its value, use the console variable system rather than modifying it directly.
  3. Consider the implications on audio performance and suspension behavior when this variable is enabled.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/AudioDeviceManager.cpp:47

Scope: file

Source code excerpt:

static int32 GCVarFlushAudioRenderCommandsOnSuspend = 0;
FAutoConsoleVariableRef CVarFlushAudioRenderCommandsOnSuspend(
	TEXT("au.FlushAudioRenderCommandsOnSuspend"),
	GCVarFlushAudioRenderCommandsOnSuspend,
	TEXT("When set to 1, ensures that we pump through all pending commands to the audio thread and audio render thread on app suspension.\n")
	TEXT("0: Not Disabled, 1: Disabled"),
	ECVF_Default);

static int32 GCVarNeverMuteNonRealtimeAudioDevices = 0;

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/AudioDeviceManager.cpp:45

Scope: file

Source code excerpt:

	ECVF_Default);

static int32 GCVarFlushAudioRenderCommandsOnSuspend = 0;
FAutoConsoleVariableRef CVarFlushAudioRenderCommandsOnSuspend(
	TEXT("au.FlushAudioRenderCommandsOnSuspend"),
	GCVarFlushAudioRenderCommandsOnSuspend,
	TEXT("When set to 1, ensures that we pump through all pending commands to the audio thread and audio render thread on app suspension.\n")
	TEXT("0: Not Disabled, 1: Disabled"),
	ECVF_Default);

static int32 GCVarNeverMuteNonRealtimeAudioDevices = 0;
FAutoConsoleVariableRef CVarNeverMuteNonRealtimeAudioDevices(

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/AudioDeviceManager.cpp:1255

Scope (from outer to inner):

file
function     void FAudioDeviceManager::AppWillEnterBackground

Source code excerpt:


	// Flush all commands to the audio thread and the audio render thread:
	if (GCVarFlushAudioRenderCommandsOnSuspend)
	{
		if (MainAudioDeviceHandle.IsValid())
		{
			FAudioThread::RunCommandOnAudioThread([this]()
			{
				if (MainAudioDeviceHandle.IsValid())