au.OverrunTimeoutMSec

au.OverrunTimeoutMSec

#Overview

name: au.OverrunTimeoutMSec

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.OverrunTimeoutMSec is to control the amount of time the audio system waits for the render thread to complete before switching to a null device. This setting is crucial for managing audio processing in cases where the render thread becomes unresponsive or takes too long to complete its work.

This setting variable is primarily used in the AudioMixerCore module of Unreal Engine 5, specifically within the audio mixer system. It’s part of the audio rendering and processing subsystem.

The value of this variable is set through a console variable (CVar) system. It’s initialized with a default value of 5000 milliseconds (5 seconds) but can be changed at runtime through console commands or configuration files.

The au.OverrunTimeoutMSec variable interacts directly with the OverrunTimeoutCVar. They share the same value, with OverrunTimeoutCVar being the actual variable used in the C++ code, while au.OverrunTimeoutMSec is the console-accessible name.

Developers should be aware of several important aspects when using this variable:

  1. The value is clamped between 500 and 5000 milliseconds for normal operation.
  2. When a debugger is attached, the timeout is set to the maximum possible value to prevent unnecessary device swaps during debugging sessions.
  3. If the timeout is reached, the system will attempt to switch to a null audio device to prevent further issues.

Best practices for using this variable include:

  1. Avoid setting the value too low, as it might cause unnecessary device swaps in cases of momentary slowdowns.
  2. Consider increasing the value if your game has particularly heavy render thread workloads that might occasionally exceed the default 5-second timeout.
  3. Be cautious when modifying this value, as it can affect the responsiveness and stability of your game’s audio system.

Regarding the associated variable OverrunTimeoutCVar:

The purpose of OverrunTimeoutCVar is to serve as the actual storage for the timeout value used in the C++ code. It’s the backend variable that au.OverrunTimeoutMSec modifies.

This variable is used directly in the AudioMixerCore module, specifically in the IAudioMixerPlatformInterface::RunInternal() function.

The value of OverrunTimeoutCVar is set initially to 5000, but it can be modified through the au.OverrunTimeoutMSec console variable.

OverrunTimeoutCVar interacts with the AudioRenderEvent object, determining how long to wait for this event before timing out.

Developers should be aware that:

  1. This variable is clamped and potentially modified every time it’s used in the RunInternal() function.
  2. Its value is overridden to the maximum possible when a debugger is attached.

Best practices for OverrunTimeoutCVar include:

  1. Avoid modifying it directly in code; instead, use the au.OverrunTimeoutMSec console variable.
  2. Be aware of its usage when profiling or optimizing audio-related code, as it can affect the behavior of the audio system under different load conditions.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/AudioMixerCore/Private/AudioMixer.cpp:106

Scope: file

Source code excerpt:

static int32 OverrunTimeoutCVar = 5000;
FAutoConsoleVariableRef CVarOverrunTimeout(
	TEXT("au.OverrunTimeoutMSec"),
	OverrunTimeoutCVar,
	TEXT("Amount of time to wait for the render thread to time out before swapping to the null device. \n"),
	ECVF_Default);

static int32 UnderrunTimeoutCVar = 5;
FAutoConsoleVariableRef CVarUnderrunTimeout(

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/AudioMixerCore/Private/AudioMixer.cpp:104

Scope: file

Source code excerpt:

	ECVF_Default);

static int32 OverrunTimeoutCVar = 5000;
FAutoConsoleVariableRef CVarOverrunTimeout(
	TEXT("au.OverrunTimeoutMSec"),
	OverrunTimeoutCVar,
	TEXT("Amount of time to wait for the render thread to time out before swapping to the null device. \n"),
	ECVF_Default);

static int32 UnderrunTimeoutCVar = 5;
FAutoConsoleVariableRef CVarUnderrunTimeout(
	TEXT("au.UnderrunTimeoutMSec"),

#Loc: <Workspace>/Engine/Source/Runtime/AudioMixerCore/Private/AudioMixer.cpp:749

Scope (from outer to inner):

file
namespace    Audio
function     uint32 IAudioMixerPlatformInterface::RunInternal

Source code excerpt:


			// Bounds check the timeout for our audio render event.
			OverrunTimeoutCVar = FMath::Clamp(OverrunTimeoutCVar, 500, 5000);

			// If we're debugging, make the timeout the maximum to avoid needless swaps.
			OverrunTimeoutCVar = FPlatformMisc::IsDebuggerPresent() ? TNumericLimits<uint32>::Max() : OverrunTimeoutCVar;

			// Now wait for a buffer to be consumed, which will bump up the read index.
			const double WaitStartTime = FPlatformTime::Seconds();
			if (AudioRenderEvent && !AudioRenderEvent->Wait(static_cast<uint32>(OverrunTimeoutCVar)))
			{
				// if we reached this block, we timed out, and should attempt to
				// bail on our current device.
				RequestDeviceSwap(TEXT(""), /* force */true, TEXT("AudioMixerPlatformInterface. Timeout waiting for h/w."));

				const float TimeWaited = FPlatformTime::Seconds() - WaitStartTime;