au.SetAudioChannelCount

au.SetAudioChannelCount

#Overview

name: au.SetAudioChannelCount

This variable is created as a Console Variable (cvar).

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of au.SetAudioChannelCount is to change the audio channel count in Unreal Engine 5. This setting variable is part of the audio system and is used to control the number of audio channels available for audio playback.

This setting variable is primarily used by the audio subsystem within Unreal Engine 5, specifically within the FAudioDevice class. It’s referenced in the Engine module, particularly in the AudioDevice.cpp file.

The value of this variable is set through a console variable (CVar) named “au.SetAudioChannelCount”. It’s initialized with a default value of 0 and can be changed at runtime through the console or programmatically.

The au.SetAudioChannelCount variable interacts directly with the AudioChannelCountCVar variable. They share the same value, as AudioChannelCountCVar is the actual storage for the console variable’s value.

Developers must be aware of the following when using this variable:

  1. The maximum value is clamped to the MaxChannelCount that the audio engine was initialized with.
  2. A value of 0 disables the custom channel count, while values greater than 0 enable it.
  3. This setting can affect the performance and quality of audio playback, so it should be used judiciously.

Best practices when using this variable include:

  1. Only modify it when necessary, as changing the audio channel count can have significant impacts on audio performance and quality.
  2. Be mindful of the platform’s capabilities and the game’s requirements when setting this value.
  3. Test thoroughly after changing this value to ensure audio quality and performance are not negatively impacted.

Regarding the associated variable AudioChannelCountCVar:

The purpose of AudioChannelCountCVar is to store the actual value of the audio channel count set by au.SetAudioChannelCount. It serves as the backend storage for the console variable.

This variable is used within the FAudioDevice class to determine the maximum number of audio channels. It’s checked in the Init function to set the initial MaxSources value, and in the GetMaxChannels function to potentially override the current channel count.

The value of AudioChannelCountCVar is set indirectly through the au.SetAudioChannelCount console variable.

AudioChannelCountCVar interacts with MaxSources, MaxChannels, and MaxChannels_GameThread variables within the FAudioDevice class.

Developers should be aware that changes to AudioChannelCountCVar will directly affect the audio system’s behavior, particularly the number of available audio channels.

Best practices for AudioChannelCountCVar include:

  1. Avoid modifying this variable directly; instead, use the au.SetAudioChannelCount console variable to change its value.
  2. Be aware of its impact on the audio system when reading or using its value in custom code.
  3. Consider the performance implications of setting a high channel count, especially on less powerful hardware.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/AudioDevice.cpp:41

Scope: file

Source code excerpt:

static int32 AudioChannelCountCVar = 0;
FAutoConsoleVariableRef CVarSetAudioChannelCount(
	TEXT("au.SetAudioChannelCount"),
	AudioChannelCountCVar,
	TEXT("Changes the audio channel count. Max value is clamped to the MaxChannelCount the audio engine was initialize with.\n")
	TEXT("0: Disable, >0: Enable"),
	ECVF_Default);

static float AudioChannelCountScaleCVar = 1.0f;

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/AudioDevice.cpp:39

Scope: file

Source code excerpt:

#endif // WITH_EDITOR

static int32 AudioChannelCountCVar = 0;
FAutoConsoleVariableRef CVarSetAudioChannelCount(
	TEXT("au.SetAudioChannelCount"),
	AudioChannelCountCVar,
	TEXT("Changes the audio channel count. Max value is clamped to the MaxChannelCount the audio engine was initialize with.\n")
	TEXT("0: Disable, >0: Enable"),
	ECVF_Default);

static float AudioChannelCountScaleCVar = 1.0f;
FAutoConsoleVariableRef CVarSetAudioChannelScaleCount(

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/AudioDevice.cpp:488

Scope (from outer to inner):

file
function     bool FAudioDevice::Init

Source code excerpt:

	// as the Sources array has yet to be initialized. If the cvar is largest, take that value to allow for testing
	const int32 PlatformMaxSources = PlatformSettings.MaxChannels > 0 ? PlatformSettings.MaxChannels : InMaxSources;
	MaxSources = FMath::Max(PlatformMaxSources, AudioChannelCountCVar);
	MaxSources = FMath::Max(MaxSources, 1);
	UE_LOG(LogAudio, Display, TEXT("AudioDevice MaxSources: %d"), MaxSources);

	MaxChannels = MaxSources;
	MaxChannels_GameThread = MaxSources;

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/AudioDevice.cpp:894

Scope (from outer to inner):

file
function     int32 FAudioDevice::GetMaxChannels

Source code excerpt:

	// Get thread-context version of channel max.  Override by cvar if cvar is valid.
	int32 OutMaxChannels = IsInAudioThread() ? MaxChannels : MaxChannels_GameThread;
	if (AudioChannelCountCVar > 0)
	{
		OutMaxChannels = AudioChannelCountCVar;
	}

	// Find product of max channels and final scalar, and clamp between 1 and MaxSources.
	check(MaxSources > 0);
	return FMath::Clamp(static_cast<int32>(OutMaxChannels * MaxChannelScalarToApply), 1, MaxSources);
}