SpatializationPlugin

SpatializationPlugin

#Overview

name: SpatializationPlugin

The value of this variable can be defined or overridden in .ini config files. 2 .ini config files referencing this setting variable.

It is referenced in 17 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of SpatializationPlugin is to control the audio spatialization in Unreal Engine 5. It is used to determine which spatialization plugin should be used for audio processing, allowing developers to create more immersive and realistic 3D audio experiences in their games or applications.

This setting variable is primarily used by the audio subsystem of Unreal Engine, specifically within the AudioMixer module. It is also referenced in various platform-specific target settings classes, indicating that it can be configured differently for different platforms.

The value of this variable is typically set in the project settings or platform-specific configuration files. It is represented as an FString, which allows developers to specify the name of the desired spatialization plugin.

SpatializationPlugin interacts with other audio-related variables, such as SourceDataOverridePlugin and ReverbPlugin. Together, these settings control different aspects of the audio processing pipeline.

Developers should be aware that:

  1. The chosen spatialization plugin must be compatible with the target platform.
  2. Changing this setting may require reinitialization of the audio system.
  3. The effectiveness of the spatialization depends on the capabilities of the selected plugin and the overall audio setup in the project.

Best practices when using this variable include:

  1. Selecting a spatialization plugin that best suits the project’s needs and target platforms.
  2. Testing the audio output with different spatialization plugins to find the optimal solution.
  3. Ensuring that the chosen plugin is properly initialized and configured in the project settings.
  4. Considering performance implications, especially on lower-end devices, as some spatialization plugins may be more computationally expensive than others.
  5. Coordinating with the audio team to ensure that the chosen spatialization plugin aligns with the overall audio design goals of the project.

#Setting Variables

#References In INI files

Location: <Workspace>/Projects/Lyra/Config/DefaultEngine.ini:307, section: [/Script/WindowsTargetPlatform.WindowsTargetSettings]

Location: <Workspace>/Projects/Lyra/Config/DefaultEngine.ini:381, section: [/Script/LinuxTargetPlatform.LinuxTargetSettings]

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Developer/Linux/LinuxTargetPlatform/Classes/LinuxTargetSettings.h:25

Scope (from outer to inner):

file
class        class ULinuxTargetSettings : public UObject

Source code excerpt:

	/** Which of the currently enabled spatialization plugins to use. */
	UPROPERTY(config, EditAnywhere, Category = "Audio")
	FString SpatializationPlugin;

	/** Which of the currently enabled source data override plugins to use. */
	UPROPERTY(config, EditAnywhere, Category = "Audio")
	FString SourceDataOverridePlugin;

	/** Which of the currently enabled reverb plugins to use. */

#Loc: <Workspace>/Engine/Source/Developer/Mac/MacTargetPlatform/Classes/MacTargetSettings.h:149

Scope (from outer to inner):

file
class        class UMacTargetSettings : public UObject

Source code excerpt:

	/** Which of the currently enabled spatialization plugins to use. */
	UPROPERTY(config, EditAnywhere, Category = "Audio")
	FString SpatializationPlugin;

	/** Which of the currently enabled source data override plugins to use. */
	UPROPERTY(config, EditAnywhere, Category = "Audio")
	FString SourceDataOverridePlugin;

	/** Which of the currently enabled reverb plugins to use. */

#Loc: <Workspace>/Engine/Source/Developer/Windows/WindowsTargetPlatform/Classes/WindowsTargetSettings.h:86

Scope (from outer to inner):

file
class        class UWindowsTargetSettings : public UObject

Source code excerpt:

	/** Which of the currently enabled spatialization plugins to use. */
	UPROPERTY(config, EditAnywhere, Category = "Audio")
	FString SpatializationPlugin;

	/** Which of the currently enabled source data override plugins to use. */
	UPROPERTY(config, EditAnywhere, Category = "Audio")
	FString SourceDataOverridePlugin;

	/** Which of the currently enabled reverb plugins to use. */

#Loc: <Workspace>/Engine/Source/Runtime/Android/AndroidRuntimeSettings/Classes/AndroidRuntimeSettings.h:584

Scope (from outer to inner):

file
class        class UAndroidRuntimeSettings : public UObject

Source code excerpt:

	/** Which of the currently enabled spatialization plugins to use. */
	UPROPERTY(config, EditAnywhere, Category = "Audio")
	FString SpatializationPlugin;

	/** Which of the currently enabled source data override plugins to use. */
	UPROPERTY(config, EditAnywhere, Category = "Audio")
	FString SourceDataOverridePlugin;

	/** Which of the currently enabled reverb plugins to use. */

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

Scope (from outer to inner):

file
namespace    Audio
function     void FMixerSourceManager::Init

Source code excerpt:

		bUsingSpatializationPlugin = false;
		SpatialInterfaceInfo = MixerDevice->GetCurrentSpatializationPluginInterfaceInfo();
		const auto& SpatializationPlugin = SpatialInterfaceInfo.SpatializationPlugin;
		if (SpatialInterfaceInfo.SpatializationPlugin.IsValid())
		{
			bUsingSpatializationPlugin = true;
		}
		// Cache the source data override plugin
		SourceDataOverridePlugin = MixerDevice->SourceDataOverridePluginInterface;
		if (SourceDataOverridePlugin.IsValid())

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

Scope (from outer to inner):

file
namespace    Audio
function     void FMixerSourceManager::ReleaseSource

Source code excerpt:

			AUDIO_MIXER_CHECK(bUsingSpatializationPlugin);
			LLM_SCOPE(ELLMTag::AudioMixerPlugins);
			SpatialInterfaceInfo.SpatializationPlugin->OnReleaseSource(SourceId);
		}

		if (SourceInfo.bUseOcclusionPlugin)
		{
			MixerDevice->OcclusionInterface->OnReleaseSource(SourceId);
		}

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

Scope (from outer to inner):

file
namespace    Audio
function     void FMixerSourceManager::InitSource
lambda-function

Source code excerpt:

				bUsingSpatializationPlugin = false;
				SpatialInterfaceInfo = MixerDevice->GetCurrentSpatializationPluginInterfaceInfo();
				const auto& SpatializationPlugin = SpatialInterfaceInfo.SpatializationPlugin;
				if (SpatialInterfaceInfo.SpatializationPlugin.IsValid())
				{
					bUsingSpatializationPlugin = true;
				}

				SpatialInterfaceInfo.SpatializationPlugin->OnInitSource(SourceId, InitParams.AudioComponentUserID, InitParams.SpatializationPluginSettings);
			}

			// Create the occlusion plugin source effect
			if (InitParams.OcclusionPluginSettings != nullptr)
			{
				MixerDevice->OcclusionInterface->OnInitSource(SourceId, InitParams.AudioComponentUserID, InitParams.NumInputChannels, InitParams.OcclusionPluginSettings);

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

Scope (from outer to inner):

file
namespace    Audio
function     void FMixerSourceManager::ComputePluginAudio

Source code excerpt:

			SCOPE_CYCLE_COUNTER(STAT_AudioMixerHRTF);

			AUDIO_MIXER_CHECK(SpatialInterfaceInfo.SpatializationPlugin.IsValid());
			AUDIO_MIXER_CHECK(SourceInfo.NumInputChannels <= SpatialInterfaceInfo.MaxChannelsSupportedBySpatializationPlugin);

			FAudioPluginSourceInputData AudioPluginInputData;
			AudioPluginInputData.AudioBuffer = &SourceInfo.SourceBuffer;
			AudioPluginInputData.NumChannels = SourceInfo.NumInputChannels;
			AudioPluginInputData.SourceId = SourceId;

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

Scope (from outer to inner):

file
namespace    Audio
function     void FMixerSourceManager::ComputePluginAudio

Source code excerpt:

			{
				LLM_SCOPE(ELLMTag::AudioMixerPlugins);
				SpatialInterfaceInfo.SpatializationPlugin->ProcessAudio(AudioPluginInputData, SourceInfo.AudioPluginOutputData);
			}

			// If this is an external send, we treat this source audio as if it was still a mono source
			// This will allow it to traditionally pan in the ComputeOutputBuffers function and be
			// sent to submixes (e.g. reverb) panned and mixed down. Certain submixes will want this spatial 
			// information in addition to the external send. We've already bypassed adding this source

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

Scope (from outer to inner):

file
namespace    Audio
function     void FMixerSourceManager::ComputeNextBlockOfSamples

Source code excerpt:

		{
			RenderThreadPhase = ESourceManagerRenderThreadPhase::SpatialInterface_OnAllSourcesProcessed;
			AUDIO_MIXER_CHECK(SpatialInterfaceInfo.SpatializationPlugin.IsValid());
			LLM_SCOPE(ELLMTag::AudioMixerPlugins);
			SpatialInterfaceInfo.SpatializationPlugin->OnAllSourcesProcessed();
		}

		// Let the plugin know we finished processing all sources
		if (bUsingSourceDataOverridePlugin)
		{
			RenderThreadPhase = ESourceManagerRenderThreadPhase::SourceDataOverride_OnAllSourcesProcessed;

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

Scope (from outer to inner):

file
function     bool FAudioDevice::SetCurrentSpatializationPlugin

Source code excerpt:

			CurrentSpatializationInterfaceInfoPtr = &Plugin;

			if(!Plugin.bIsInitialized && Plugin.SpatializationPlugin)
			{
				Plugin.SpatializationPlugin->Initialize(PluginInitializationParams);
				Plugin.bIsInitialized = true;
			}

			return true;
		}
	}

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

Scope (from outer to inner):

file
function     void FAudioDevice::Teardown

Source code excerpt:

	for(const auto& Plugin : SpatializationInterfaces)
	{
		if(TAudioSpatializationPtr SpatialPluginPtr = Plugin.SpatializationPlugin)
		{
			SpatialPluginPtr->Shutdown();
		}
	}

	SpatializationInterfaces.Empty();

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

Scope (from outer to inner):

file
function     FAudioDevice::FAudioSpatializationInterfaceInfo::FAudioSpatializationInterfaceInfo

Source code excerpt:


	// use the factory to create a PluginInterface
	SpatializationPlugin = InAudioSpatializationFactoryPtr->CreateNewSpatializationPlugin(InAudioDevice);

	// cache metadata from the incoming plugin interface 
	bSpatializationIsExternalSend = InAudioSpatializationFactoryPtr->IsExternalSend();
	MaxChannelsSupportedBySpatializationPlugin = InAudioSpatializationFactoryPtr->GetMaxSupportedChannels();
	bReturnsToSubmixGraph = InAudioSpatializationFactoryPtr->ReturnsToSubmixGraph();
}

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

Scope (from outer to inner):

file
function     bool FAudioDevice::FAudioSpatializationInterfaceInfo::IsValid

Source code excerpt:

bool FAudioDevice::FAudioSpatializationInterfaceInfo::IsValid() const
{
	return SpatializationPlugin.IsValid() || !PluginName.IsNone();
}


bool FAudioDevice::ShouldUseAttenuation(const UWorld* World) const
{
	// We use attenuation settings:

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Public/AudioDevice.h:1309

Scope (from outer to inner):

file
class        class FAudioDevice : public FExec
function     TAudioSpatializationPtr GetSpatializationPluginInterface

Source code excerpt:

	TAudioSpatializationPtr GetSpatializationPluginInterface()
	{
		return GetCurrentSpatializationPluginInterfaceInfo().SpatializationPlugin;
	}

	/** Return the spatialization plugin interface info (requested by name). */
	struct FAudioSpatializationInterfaceInfo;
	ENGINE_API FAudioSpatializationInterfaceInfo GetCurrentSpatializationPluginInterfaceInfo();

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Public/AudioDevice.h:1981

Scope (from outer to inner):

file
class        class FAudioDevice : public FExec

Source code excerpt:


		FName PluginName;
		TAudioSpatializationPtr SpatializationPlugin = nullptr;
		int32 MaxChannelsSupportedBySpatializationPlugin = 1;
		uint8 bSpatializationIsExternalSend:1;
		uint8 bIsInitialized:1;
		uint8 bReturnsToSubmixGraph:1;
	};

#Loc: <Workspace>/Engine/Source/Runtime/IOS/IOSRuntimeSettings/Classes/IOSRuntimeSettings.h:527

Scope (from outer to inner):

file
class        class UIOSRuntimeSettings : public UObject

Source code excerpt:

	/** Which of the currently enabled spatialization plugins to use. */
	UPROPERTY(config, EditAnywhere, Category = "Audio")
	FString SpatializationPlugin;

	/** Which of the currently enabled source data override plugins to use. */
	UPROPERTY(config, EditAnywhere, Category = "Audio")
	FString SourceDataOverridePlugin;

	/** Which of the currently enabled reverb plugins to use. */