au.FlushCommandBufferOnTimeout

au.FlushCommandBufferOnTimeout

#Overview

name: au.FlushCommandBufferOnTimeout

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.FlushCommandBufferOnTimeout is to control the behavior of the audio system when a timeout occurs in the audio render thread. This setting variable is part of the audio mixer subsystem in Unreal Engine 5.

The audio mixer module in Unreal Engine relies on this setting variable. Specifically, it’s used in the FMixerSourceManager class, which is responsible for managing audio sources in the mixer.

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

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

Developers must be aware that enabling this variable (setting it to 1) will cause the audio system to flush the audio render thread synchronously when a fence has timed out. This can potentially impact performance, especially if timeouts occur frequently.

Best practices when using this variable include:

  1. Leaving it disabled (0) by default for optimal performance.
  2. Only enabling it (1) when debugging audio-related issues, particularly those related to render thread synchronization.
  3. Monitoring performance impact when enabled, as synchronous flushing can introduce latency.

Regarding the associated variable FlushCommandBufferOnTimeoutCvar:

The purpose of FlushCommandBufferOnTimeoutCvar is to provide a C++ accessible version of the au.FlushCommandBufferOnTimeout setting. It’s used directly in the code to check whether the flush behavior should be executed.

This variable is used in the Audio namespace, specifically within the FMixerSourceManager::Update function. It’s checked when a timeout occurs to determine if the command buffer should be flushed.

The value of this variable is set indirectly through the au.FlushCommandBufferOnTimeout console variable.

Developers should be aware that this variable is used in critical audio processing code and changing its value can affect how the audio system responds to timeouts.

Best practices for this variable include:

  1. Not modifying it directly in code, but rather using the console variable system to change its value.
  2. Being cautious when enabling the flush behavior in production builds, as it can impact audio performance.
  3. Using it in conjunction with logging (as seen in the code) to help diagnose audio render thread issues.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/AudioMixer/Private/AudioMixerSourceManager.cpp:87

Scope: file

Source code excerpt:

static int32 FlushCommandBufferOnTimeoutCvar = 0;
FAutoConsoleVariableRef CVarFlushCommandBufferOnTimeout(
	TEXT("au.FlushCommandBufferOnTimeout"),
	FlushCommandBufferOnTimeoutCvar,
	TEXT("When set to 1, flushes audio render thread synchronously when our fence has timed out.\n")
	TEXT("0: Not Disabled, 1: Disabled"),
	ECVF_Default);

static int32 CommandBufferFlushWaitTimeMsCvar = 1000;

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/AudioMixer/Private/AudioMixerSourceManager.cpp:85

Scope: file

Source code excerpt:

	ECVF_Default);

static int32 FlushCommandBufferOnTimeoutCvar = 0;
FAutoConsoleVariableRef CVarFlushCommandBufferOnTimeout(
	TEXT("au.FlushCommandBufferOnTimeout"),
	FlushCommandBufferOnTimeoutCvar,
	TEXT("When set to 1, flushes audio render thread synchronously when our fence has timed out.\n")
	TEXT("0: Not Disabled, 1: Disabled"),
	ECVF_Default);

static int32 CommandBufferFlushWaitTimeMsCvar = 1000;
FAutoConsoleVariableRef CVarCommandBufferFlushWaitTimeMs(

#Loc: <Workspace>/Engine/Source/Runtime/AudioMixer/Private/AudioMixerSourceManager.cpp:520

Scope (from outer to inner):

file
namespace    Audio
function     void FMixerSourceManager::Update

Source code excerpt:


				// Make sure we've actually emptied the command queue from the render thread before writing to it
				if (FlushCommandBufferOnTimeoutCvar && NextCommandBuffer.SourceCommandQueue.Num() != 0)
				{
					UE_LOG(LogAudioMixer, Warning, TEXT("Audio render callback stopped. Flushing %d commands."), NextCommandBuffer.SourceCommandQueue.Num());

					// Pop and execute all the commands that came since last update tick
					for (int32 Id = 0; Id < NextCommandBuffer.SourceCommandQueue.Num(); ++Id)
					{