au.MetaSound.OperatorPoolSyncGraphRetrieval

au.MetaSound.OperatorPoolSyncGraphRetrieval

#Overview

name: au.MetaSound.OperatorPoolSyncGraphRetrieval

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.MetaSound.OperatorPoolSyncGraphRetrieval is to control the behavior of graph retrieval in the Metasound system, specifically for the operator pool functionality. It determines whether the graph should be retrieved synchronously on the requesting thread before an asynchronous task to create an instance.

This setting variable is primarily used in the Metasound plugin, which is part of Unreal Engine’s audio system. Based on the callsites, it’s specifically utilized in the MetasoundGenerator module.

The value of this variable is set through a console variable (cvar) system. It’s initialized to true by default but can be changed at runtime through the console or configuration files.

The associated variable bMetasoundPoolSyncGraphRetrieval directly interacts with au.MetaSound.OperatorPoolSyncGraphRetrieval. They share the same value, with bMetasoundPoolSyncGraphRetrieval being the actual boolean flag used in the code logic.

Developers must be aware that enabling this variable (which is the default behavior) will cause graph retrieval to occur synchronously on the requesting thread. This can potentially impact performance, especially if graph retrieval is a time-consuming operation.

Best practices when using this variable include:

  1. Consider the performance implications of synchronous graph retrieval in your specific use case.
  2. Monitor and profile the performance impact, especially in scenarios with many Metasound operators.
  3. If asynchronous behavior is preferred and doesn’t cause issues in your game, consider disabling this setting.

Regarding the associated variable bMetasoundPoolSyncGraphRetrieval:

The purpose of bMetasoundPoolSyncGraphRetrieval is to serve as the actual boolean flag used in the code to control the synchronous graph retrieval behavior.

It’s used within the Metasound::OperatorPoolPrivate namespace, specifically in the FOperatorPool::BuildAndAddOperator function. This suggests it’s closely tied to the operator pool management in the Metasound system.

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

This variable directly controls the flow of the BuildAndAddOperator function. When true, it causes the function to retrieve the Metasound graph synchronously before proceeding with the operator building process.

Developers should be aware that this variable directly impacts the behavior of the operator pool. Changing its value will affect how graphs are retrieved and potentially the timing of operator creation.

Best practices for using this variable include:

  1. Understand the implications of synchronous vs asynchronous graph retrieval in your specific use case.
  2. Consider the potential impact on frame rate or audio processing if graph retrieval is a heavy operation.
  3. If modifying this variable, ensure comprehensive testing to verify that the changed behavior doesn’t introduce issues in your game’s audio system.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Plugins/Runtime/Metasound/Source/MetasoundGenerator/Private/MetasoundOperatorCache.cpp:29

Scope (from outer to inner):

file
namespace    Metasound
namespace    OperatorPoolPrivate

Source code excerpt:

		static bool bMetasoundPoolSyncGraphRetrieval = true;
		FAutoConsoleVariableRef CVarMetasoundPoolSyncGraphRetrieval(
			TEXT("au.MetaSound.OperatorPoolSyncGraphRetrieval"),
			bMetasoundPoolSyncGraphRetrieval,
			TEXT("Retrieves graph on the requesting thread prior to asynchronous task to create instance.\n"),
			ECVF_Default);

#if METASOUND_OPERATORCACHEPROFILER_ENABLED
		static std::atomic<uint32> CacheHitCount = 0;

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Plugins/Runtime/Metasound/Source/MetasoundGenerator/Private/MetasoundOperatorCache.cpp:27

Scope (from outer to inner):

file
namespace    Metasound
namespace    OperatorPoolPrivate

Source code excerpt:

	namespace OperatorPoolPrivate
	{
		static bool bMetasoundPoolSyncGraphRetrieval = true;
		FAutoConsoleVariableRef CVarMetasoundPoolSyncGraphRetrieval(
			TEXT("au.MetaSound.OperatorPoolSyncGraphRetrieval"),
			bMetasoundPoolSyncGraphRetrieval,
			TEXT("Retrieves graph on the requesting thread prior to asynchronous task to create instance.\n"),
			ECVF_Default);

#if METASOUND_OPERATORCACHEPROFILER_ENABLED
		static std::atomic<uint32> CacheHitCount = 0;
		static std::atomic<uint32> CacheAttemptCount = 0;

#Loc: <Workspace>/Engine/Plugins/Runtime/Metasound/Source/MetasoundGenerator/Private/MetasoundOperatorCache.cpp:330

Scope (from outer to inner):

file
namespace    Metasound
function     void FOperatorPool::BuildAndAddOperator

Source code excerpt:


		TSharedPtr<const Metasound::FGraph> Graph;
		if (bMetasoundPoolSyncGraphRetrieval)
		{
			// get the metasound graph and add to init params (might wait for async registration to complete)
			Graph = FMetasoundFrontendRegistryContainer::Get()->GetGraph(InBuildData->RegistryKey);
			if (!Graph.IsValid())
			{
				UE_LOG(LogMetasoundGenerator, Error, TEXT("Failed to retrieve graph '%s' synchronously when attempting to BuildAndAddOperator to pool"), *InBuildData->RegistryKey.ToString());

#Loc: <Workspace>/Engine/Plugins/Runtime/Metasound/Source/MetasoundGenerator/Private/MetasoundOperatorCache.cpp:361

Scope (from outer to inner):

file
namespace    Metasound
function     void FOperatorPool::BuildAndAddOperator
lambda-function

Source code excerpt:

			else
			{
				if (bMetasoundPoolSyncGraphRetrieval)
				{
					return;
				}
				else
				{
					// get the metasound graph and add to init params (might wait for async registration to complete)