UnfocusedVolumeMultiplier

UnfocusedVolumeMultiplier

#Overview

name: UnfocusedVolumeMultiplier

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

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of UnfocusedVolumeMultiplier is to control the volume of audio when the application loses focus. This setting variable is part of the audio system in Unreal Engine 5.

Based on the Callsites section, the UnfocusedVolumeMultiplier is primarily used in the Core module of Unreal Engine, specifically within the FApp class. This class is responsible for managing application-wide settings and behaviors.

The value of this variable is set in multiple ways:

1. It is initialized with a default value of 0.0f in the FApp class declaration.
2. It can be loaded from the config file (GEngineIni) using the GetUnfocusedVolumeMultiplier() function.
3. It can be manually set using the SetUnfocusedVolumeMultiplier() function.

The UnfocusedVolumeMultiplier interacts with other variables and systems:

1. It is related to the VolumeMultiplier variable, which likely controls the overall volume.
2. It works in conjunction with the bUseVRFocus and bHasVRFocus flags, which are used for VR-specific focus handling.

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

1. The value is stored in the config file, so changes made programmatically will persist between sessions.
2. The default value is 0.0f, which means the audio will be muted when the application loses focus.
3. The value is retrieved lazily (only when needed) to optimize performance.

Best practices for using this variable include:

1. Use the provided getter (GetUnfocusedVolumeMultiplier()) and setter (SetUnfocusedVolumeMultiplier()) functions instead of accessing the variable directly.
2. Consider the impact on user experience when setting this value. A value of 0.0f might be too jarring for some applications, while a value close to 1.0f might not provide enough audio feedback that the app has lost focus.
3. If developing a VR application, ensure proper coordination with the VR focus flags (bUseVRFocus and bHasVRFocus) to handle focus correctly in VR environments.
4. Be mindful of platform-specific behaviors regarding application focus and adjust the use of this variable accordingly.

#Setting Variables

#References In INI files

Location: <Workspace>/Engine/Config/BaseEngine.ini:1546, section: [Audio]

• INI Section: Audio
• Raw value: 0.0
• Is Array: False

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Core/Private/Misc/App.cpp:41

Scope: file

Source code excerpt:

TOptional<FQualifiedFrameTime> FApp::CurrentFrameTime;
float FApp::VolumeMultiplier = 1.0f;
float FApp::UnfocusedVolumeMultiplier = 0.0f;
bool FApp::bUseVRFocus = false;
bool FApp::bHasVRFocus = false;
bool (*FApp::HasFocusFunction)() = nullptr;


/* FApp static interface

#Loc: <Workspace>/Engine/Source/Runtime/Core/Private/Misc/App.cpp:318

Scope (from outer to inner):

file
function     float FApp::GetUnfocusedVolumeMultiplier

Source code excerpt:

	{
		GUnfocusedVolumeMultiplierInitialised = true;
		GConfig->GetFloat(TEXT("Audio"), TEXT("UnfocusedVolumeMultiplier"), UnfocusedVolumeMultiplier, GEngineIni);
	}
	return UnfocusedVolumeMultiplier;
}

void FApp::SetUnfocusedVolumeMultiplier(float InVolumeMultiplier)
{
	UnfocusedVolumeMultiplier = InVolumeMultiplier;
	GConfig->SetFloat(TEXT("Audio"), TEXT("UnfocusedVolumeMultiplier"), UnfocusedVolumeMultiplier, GEngineIni);
	GUnfocusedVolumeMultiplierInitialised = true;
}

void FApp::SetUseVRFocus(bool bInUseVRFocus)
{
	UE_CLOG(bUseVRFocus != bInUseVRFocus, LogApp, Verbose, TEXT("UseVRFocus has changed to %d"), int(bInUseVRFocus));

#Loc: <Workspace>/Engine/Source/Runtime/Core/Public/Misc/App.h:741

Scope (from outer to inner):

file
class        class FApp

Source code excerpt:

	/**
	 * Helper function to get UnfocusedVolumeMultiplier from config and store so it's not retrieved every frame
	 * 
	 * @return Volume multiplier to use when app loses focus
	 */
	static CORE_API float GetUnfocusedVolumeMultiplier();

	/**
	* Sets the Unfocused Volume Multiplier
	*/
	static CORE_API void SetUnfocusedVolumeMultiplier(float InVolumeMultiplier);

#Loc: <Workspace>/Engine/Source/Runtime/Core/Public/Misc/App.h:864

Scope (from outer to inner):

file
class        class FApp

Source code excerpt:

	/** Read from config to define the volume when app loses focus */
	static CORE_API float UnfocusedVolumeMultiplier;

	/** Holds a flag indicating if VRFocus should be used */
	static CORE_API bool bUseVRFocus;

	/** Holds a flag indicating if app has focus in side the VR headset */
	static CORE_API bool bHasVRFocus;