bBuildForES31

bBuildForES31

#Overview

name: bBuildForES31

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 12 C++ source files. Also referenced in 2 C# build files meaning it may affect the build system logic.

#Summary

#Usage in the C++ source code

The purpose of bBuildForES31 is to control whether the Unreal Engine project should be built to support OpenGL ES 3.1 and above on Android devices. This setting is primarily used for the rendering system, specifically for Android platform development.

The Android subsystem and the OpenGL rendering module rely on this setting variable. It is referenced in various parts of the Android-specific code, including the AndroidRuntimeSettings, AndroidPlatformEditor, and OpenGL driver for Android.

The value of this variable is set in the project’s configuration file, typically in the AndroidRuntimeSettings section of the engine.ini file. It can be modified through the Unreal Engine editor’s project settings or directly in the configuration file.

This variable interacts with other graphics-related settings, particularly bSupportsVulkan. There’s a logic in place to ensure that at least one GPU architecture is supported between OpenGL ES 3.1 and Vulkan.

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

  1. Changing this setting may invalidate shader caches, requiring a rebuild.
  2. It affects the feature level support for Android devices, which can impact performance and compatibility.
  3. When packaging for Meta Quest devices, this setting may be automatically adjusted.

Best practices when using this variable include:

  1. Ensure that the target Android devices support OpenGL ES 3.1 or higher before enabling this setting.
  2. Consider the trade-offs between supporting OpenGL ES 3.1 and Vulkan, as they may impact performance and device compatibility differently.
  3. Test the application thoroughly on various Android devices when changing this setting to ensure compatibility and performance.
  4. Be aware of how this setting interacts with other graphics settings, especially when targeting specific devices like Meta Quest.

#Setting Variables

#References In INI files

Location: <Workspace>/Engine/Config/BaseEngine.ini:3041, section: [/Script/AndroidRuntimeSettings.AndroidRuntimeSettings]

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Developer/Android/AndroidPlatformEditor/Private/AndroidPlatformEditorModule.cpp:116

Scope (from outer to inner):

file
class        class FAndroidPlatformEditorModule : public IModuleInterface
function     virtual void StartupModule
lambda-function

Source code excerpt:

					if (PropertyChangedEvent.Property != nullptr)
					{
						if (PropertyChangedEvent.Property->GetFName() == GET_MEMBER_NAME_CHECKED(UAndroidRuntimeSettings, bBuildForES31) &&
							AndroidRuntimeSettings->bBuildForES31 == false)
						{
							FCoreDelegates::OnFeatureLevelDisabled.Broadcast(ERHIFeatureLevel::ES3_1, FName());
							return;
						}

						if (PropertyChangedEvent.Property->GetFName() == GET_MEMBER_NAME_CHECKED(UAndroidRuntimeSettings, bSupportsVulkan) &&

#Loc: <Workspace>/Engine/Source/Developer/Android/AndroidTargetPlatformControls/Private/AndroidTargetPlatformControls.h:113

Scope (from outer to inner):

file
class        class FAndroidTargetPlatformControls : public TNonDesktopTargetPlatformControlsBase<FAndroidPlatformProperties>
function     virtual void GetBuildProjectSettingKeys

Source code excerpt:

		OutSection = TEXT("/Script/AndroidRuntimeSettings.AndroidRuntimeSettings");
		InBoolKeys.Add(TEXT("bBuildForArm64"));	InBoolKeys.Add(TEXT("bBuildForX8664"));
		InBoolKeys.Add(TEXT("bBuildForES31")); InBoolKeys.Add(TEXT("bBuildWithHiddenSymbolVisibility"));
		InBoolKeys.Add(TEXT("bSaveSymbols")); InStringKeys.Add(TEXT("NDKAPILevel"));
	}

	virtual bool ShouldExpandTo32Bit(const uint16* Indices, const int32 NumIndices) const override;
	//~ End ITargetPlatform Interface

#Loc: <Workspace>/Engine/Source/Developer/Android/AndroidTargetPlatformSettings/Private/AndroidTargetPlatformSettings.cpp:27

Scope (from outer to inner):

file
function     bool FAndroidTargetPlatformSettings::SupportsES31

Source code excerpt:

{
	// default no support for ES31
	bool bBuildForES31 = false;
#if WITH_ENGINE
	GConfig->GetBool(TEXT("/Script/AndroidRuntimeSettings.AndroidRuntimeSettings"), TEXT("bBuildForES31"), bBuildForES31, GEngineIni);
#endif
	return bBuildForES31;
}

bool FAndroidTargetPlatformSettings::SupportsVulkan() const
{
	// default to not supporting Vulkan
	bool bSupportsVulkan = false;

#Loc: <Workspace>/Engine/Source/Editor/PIEPreviewDeviceProfileSelector/Private/PIEPreviewDevice.cpp:240

Scope (from outer to inner):

file
function     ERHIFeatureLevel::Type FPIEPreviewDevice::GetPreviewDeviceFeatureLevel

Source code excerpt:

			// check the project's gles support:
			bool bProjectBuiltForES31 = false;
			GConfig->GetBool(TEXT("/Script/AndroidRuntimeSettings.AndroidRuntimeSettings"), TEXT("bBuildForES31"), bProjectBuiltForES31, GEngineIni);

			// Android Preview Device is currently expected to work on gles.
			check(bDeviceSupportsES31 && bProjectBuiltForES31);

			return ERHIFeatureLevel::ES3_1;
		}

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

Scope (from outer to inner):

file
class        class UAndroidRuntimeSettings : public UObject

Source code excerpt:

	// Include shaders for devices supporting OpenGL ES 3.2 and above (default)
	UPROPERTY(GlobalConfig, EditAnywhere, Category = Build, meta = (DisplayName = "Support OpenGL ES3.2", EditCondition = "!bPackageForMetaQuest"))
	bool bBuildForES31;

	// Support the Vulkan RHI and include Vulkan shaders
	UPROPERTY(GlobalConfig, EditAnywhere, Category = Build, meta = (DisplayName = "Support Vulkan"))
	bool bSupportsVulkan;

	// Enable Vulkan SM5 rendering support

#Loc: <Workspace>/Engine/Source/Runtime/Android/AndroidRuntimeSettings/Private/AndroidRuntimeSettings.cpp:47

Scope (from outer to inner):

file
function     UAndroidRuntimeSettings::UAndroidRuntimeSettings

Source code excerpt:

	, bStreamLandscapeMeshLODs(false)
{
	bBuildForES31 = bBuildForES31 || !bSupportsVulkan;
}

void UAndroidRuntimeSettings::PostReloadConfig(FProperty* PropertyThatWasLoaded)
{
	Super::PostReloadConfig(PropertyThatWasLoaded);

#Loc: <Workspace>/Engine/Source/Runtime/Android/AndroidRuntimeSettings/Private/AndroidRuntimeSettings.cpp:121

Scope (from outer to inner):

file
function     void UAndroidRuntimeSettings::HandleMetaQuestSupport

Source code excerpt:

			EnsureValidGPUArch();
		}
		if (bBuildForES31)
		{
			bBuildForES31 = false;
			UpdateSinglePropertyInConfigFile(GetClass()->FindPropertyByName(GET_MEMBER_NAME_CHECKED(UAndroidRuntimeSettings, bBuildForES31)), GetDefaultConfigFilename());
			UE_LOG(LogAndroidRuntimeSettings, Warning, TEXT("Support OpenGL ES3.2 has been changed to false.\n"));
			EnsureValidGPUArch();
		}

		UE_LOG(LogAndroidRuntimeSettings, Display, TEXT("Enabled Package for Meta Quest devices.\nThe following settings have been applied:\n"));
		UE_LOG(LogAndroidRuntimeSettings, Display, TEXT("Support arm64: %d.\n"), bBuildForArm64);

#Loc: <Workspace>/Engine/Source/Runtime/Android/AndroidRuntimeSettings/Private/AndroidRuntimeSettings.cpp:134

Scope (from outer to inner):

file
function     void UAndroidRuntimeSettings::HandleMetaQuestSupport

Source code excerpt:

		UE_LOG(LogAndroidRuntimeSettings, Display, TEXT("Support x86_64: %d.\n"), bBuildForX8664);
		UE_LOG(LogAndroidRuntimeSettings, Display, TEXT("Support Vulkan Desktop: %d.\n"), bSupportsVulkanSM5);
		UE_LOG(LogAndroidRuntimeSettings, Display, TEXT("Support OpenGL ES3.2: %d."), bBuildForES31);

		int32 SupportedDevicesTagIndex = ExtraApplicationSettings.Find("com.oculus.supportedDevices");
		FString SupportedDevicesValue("quest|quest2|questpro|quest3");
		int32 SupportedDevicesIndex = ExtraApplicationSettings.Find(SupportedDevicesValue);
		// The supported devices tag is present but not up to date and does not contain all the currently supported devices.
		bool bNeedtoUpdateDevices = (SupportedDevicesTagIndex != INDEX_NONE) && (SupportedDevicesIndex == INDEX_NONE);

#Loc: <Workspace>/Engine/Source/Runtime/Android/AndroidRuntimeSettings/Private/AndroidRuntimeSettings.cpp:196

Scope (from outer to inner):

file
function     void UAndroidRuntimeSettings::PostEditChangeProperty

Source code excerpt:

	{
		if (PropertyChangedEvent.Property->GetFName() == GET_MEMBER_NAME_CHECKED(UAndroidRuntimeSettings, bSupportsVulkan) ||
			PropertyChangedEvent.Property->GetFName() == GET_MEMBER_NAME_CHECKED(UAndroidRuntimeSettings, bBuildForES31))
		{
			// Supported shader formats changed so invalidate cache
			InvalidateAllAndroidPlatforms();

			OnPropertyChanged.Broadcast(PropertyChangedEvent);
		}

#Loc: <Workspace>/Engine/Source/Runtime/Android/AndroidRuntimeSettings/Private/AndroidRuntimeSettings.cpp:266

Scope (from outer to inner):

file
function     void UAndroidRuntimeSettings::EnsureValidGPUArch

Source code excerpt:

{
	// Ensure that at least one GPU architecture is supported
	if (!bSupportsVulkan && !bBuildForES31 && !bSupportsVulkanSM5)
	{
		UE_LOG(LogAndroidRuntimeSettings, Warning, TEXT("No GPU architecture is selected.\n"));
		// Default to Vulkan for Meta Quest devices
		if (bPackageForMetaQuest)
		{
			bSupportsVulkan = true;

#Loc: <Workspace>/Engine/Source/Runtime/Android/AndroidRuntimeSettings/Private/AndroidRuntimeSettings.cpp:278

Scope (from outer to inner):

file
function     void UAndroidRuntimeSettings::EnsureValidGPUArch

Source code excerpt:

		else
		{
			bBuildForES31 = true;
			UpdateSinglePropertyInConfigFile(GetClass()->FindPropertyByName(GET_MEMBER_NAME_CHECKED(UAndroidRuntimeSettings, bBuildForES31)), GetDefaultConfigFilename());
			UE_LOG(LogAndroidRuntimeSettings, Warning, TEXT("Support OpenGL ES3.2 has been changed to true.\n"));
		}

		// Supported shader formats changed so invalidate cache
		InvalidateAllAndroidPlatforms();
	}

#Loc: <Workspace>/Engine/Source/Runtime/OpenGLDrv/Private/Android/AndroidOpenGL.cpp:336

Scope (from outer to inner):

file
function     bool PlatformInitOpenGL

Source code excerpt:

		static const auto CVarDisableES31 = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.Android.DisableOpenGLES31Support"));

		bool bBuildForES31 = false;
		GConfig->GetBool(TEXT("/Script/AndroidRuntimeSettings.AndroidRuntimeSettings"), TEXT("bBuildForES31"), bBuildForES31, GEngineIni);

		const bool bSupportsFloatingPointRTs = FAndroidMisc::SupportsFloatingPointRenderTargets();

		if (bBuildForES31 && bES32Supported)
		{
			FOpenGLES::CurrentFeatureLevelSupport = FAndroidOpenGL::GLMinorVersion >= 2 ? FOpenGLES::EFeatureLevelSupport::ES32 : FOpenGLES::EFeatureLevelSupport::ES31;
			UE_LOG(LogRHI, Log, TEXT("App is packaged for OpenGL ES 3.1 and an ES %d.%d-capable device was detected."), FAndroidOpenGL::GLMajorVerion, FAndroidOpenGL::GLMinorVersion);
		}
		else
		{

#References in C# build files

This variable is referenced in the following C# build files:

Location: <Workspace>/Engine/Source/Programs/UnrealBuildTool/Platform/Android/UEDeployAndroid.cs:2655


			bool bBuildForES31 = false;
			Ini.GetBool("/Script/AndroidRuntimeSettings.AndroidRuntimeSettings", "bBuildForES31", out bBuildForES31);
			bool bSupportsVulkan = false;
			Ini.GetBool("/Script/AndroidRuntimeSettings.AndroidRuntimeSettings", "bSupportsVulkan", out bSupportsVulkan);

			int PropagateAlpha = 0;
			Ini.GetInt32("/Script/Engine.RendererSettings", "r.Mobile.PropagateAlpha", out PropagateAlpha);

Location: <Workspace>/Engine/Source/Programs/UnrealBuildTool/Platform/Android/UEDeployAndroid.cs:1430

			ConfigHierarchy Ini = GetConfigCacheIni(ConfigHierarchyType.Engine);
			bool bBuildForES31 = false;
			Ini.GetBool("/Script/AndroidRuntimeSettings.AndroidRuntimeSettings", "bBuildForES31", out bBuildForES31);
			bool bSupportsVulkan = false;
			Ini.GetBool("/Script/AndroidRuntimeSettings.AndroidRuntimeSettings", "bSupportsVulkan", out bSupportsVulkan);

			Logger.LogInformation("bBuildForES31: {bBuildForES31}", (bBuildForES31 ? "true" : "false"));
			Logger.LogInformation("bSupportsVulkan: {bSupportsVulkan}", (bSupportsVulkan ? "true" : "false"));
		}