au.Ambisonics.VirtualIntermediateChannels

au.Ambisonics.VirtualIntermediateChannels

#Overview

name: au.Ambisonics.VirtualIntermediateChannels

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

• type: Var
• help: Enables decoding to a virtual 7.1 speaker config before mixdown.\n0: Decode directly to output device configuration, 1: Enabled

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of au.Ambisonics.VirtualIntermediateChannels is to control the decoding process of Ambisonic audio in Unreal Engine’s sound system. Specifically, it determines whether to use an intermediate 7.1 speaker configuration before final mixdown or to decode directly to the output device configuration.

This setting variable is primarily used in the SoundFields plugin, which is part of Unreal Engine’s audio system. The plugin is responsible for handling Ambisonic audio, a full-sphere surround sound technique.

The value of this variable is set through the Unreal Engine console variable system. It’s initialized with a default value of 1 (enabled) and can be changed at runtime.

The associated variable VirtualIntermediateChannelsCvar directly interacts with au.Ambisonics.VirtualIntermediateChannels. They share the same value, with VirtualIntermediateChannelsCvar being the actual integer variable used in the code logic.

Developers should be aware that this variable significantly affects the audio decoding process. When enabled (set to 1), it introduces an additional step in the decoding pipeline, potentially affecting performance and audio quality.

Best practices when using this variable include:

1. Consider the target platforms and their typical audio setups.
2. Test thoroughly with both settings (0 and 1) to determine which provides better audio quality for your specific use case.
3. Be mindful of potential performance impacts, especially on less powerful devices.

Regarding the associated variable VirtualIntermediateChannelsCvar:

The purpose of VirtualIntermediateChannelsCvar is to provide a convenient way to access the value of au.Ambisonics.VirtualIntermediateChannels within the C++ code.

It’s used directly in the FAmbisonicsSoundfieldDecoder class to determine the decoding method. When VirtualIntermediateChannelsCvar is true, the decoder uses the DecodeAudioToSevenOneAndDownmixToDevice method. Otherwise, it uses DecodeAudioDirectlyToDeviceOutputPositions.

The value of VirtualIntermediateChannelsCvar is set by the console variable system when au.Ambisonics.VirtualIntermediateChannels is modified.

No other variables directly interact with VirtualIntermediateChannelsCvar, but it’s crucial for the control flow in the Ambisonic decoding process.

Developers should be aware that changes to au.Ambisonics.VirtualIntermediateChannels will be reflected in VirtualIntermediateChannelsCvar, and vice versa.

Best practices include using VirtualIntermediateChannelsCvar for runtime checks in the decoding logic, while using au.Ambisonics.VirtualIntermediateChannels for external configuration and debugging purposes.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Plugins/Runtime/SoundFields/Source/SoundFields/Private/SoundFields.cpp:10

Scope: file

Source code excerpt:

static int32 VirtualIntermediateChannelsCvar = 1;
FAutoConsoleVariableRef CVarVirtualIntermediateChannels(
	TEXT("au.Ambisonics.VirtualIntermediateChannels"),
	VirtualIntermediateChannelsCvar,
	TEXT("Enables decoding to a virtual 7.1 speaker config before mixdown.\n")
	TEXT("0: Decode directly to output device configuration, 1: Enabled"),
	ECVF_Default);

class FAmbisonicsSoundfieldEncoder : public ISoundfieldEncoderStream

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Plugins/Runtime/SoundFields/Source/SoundFields/Private/SoundFields.cpp:8

Scope: file

Source code excerpt:

#include UE_INLINE_GENERATED_CPP_BY_NAME(SoundFields)

static int32 VirtualIntermediateChannelsCvar = 1;
FAutoConsoleVariableRef CVarVirtualIntermediateChannels(
	TEXT("au.Ambisonics.VirtualIntermediateChannels"),
	VirtualIntermediateChannelsCvar,
	TEXT("Enables decoding to a virtual 7.1 speaker config before mixdown.\n")
	TEXT("0: Decode directly to output device configuration, 1: Enabled"),
	ECVF_Default);

class FAmbisonicsSoundfieldEncoder : public ISoundfieldEncoderStream
{

#Loc: <Workspace>/Engine/Plugins/Runtime/SoundFields/Source/SoundFields/Private/SoundFields.cpp:63

Scope (from outer to inner):

file
class        class FAmbisonicsSoundfieldDecoder : public ISoundfieldDecoderStream
function     virtual void Decode

Source code excerpt:

		const FAmbisonicsSoundfieldBuffer* AudioToDecode = &InputAudio;

		if (VirtualIntermediateChannelsCvar)
		{
			Decoder.DecodeAudioToSevenOneAndDownmixToDevice(*AudioToDecode, OutputPositions, OutputAudio);
		}
		else
		{
			Decoder.DecodeAudioDirectlyToDeviceOutputPositions(*AudioToDecode, OutputPositions, OutputAudio);

#Loc: <Workspace>/Engine/Plugins/Runtime/SoundFields/Source/SoundFields/Private/SoundFields.cpp:85

Scope (from outer to inner):

file
class        class FAmbisonicsSoundfieldDecoder : public ISoundfieldDecoderStream
function     virtual void DecodeAndMixIn

Source code excerpt:

		DecoderOutputBuffer.AddUninitialized(OutputData.AudioBuffer.Num());

		if (VirtualIntermediateChannelsCvar)
		{
			Decoder.DecodeAudioToSevenOneAndDownmixToDevice(*AudioToDecode, OutputPositions, DecoderOutputBuffer);
		}
		else
		{
			Decoder.DecodeAudioDirectlyToDeviceOutputPositions(*AudioToDecode, OutputPositions, DecoderOutputBuffer);