DepthBufferPreference

DepthBufferPreference

#Overview

name: DepthBufferPreference

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

#Summary

#Usage in the C++ source code

The purpose of DepthBufferPreference is to specify the preferred depth buffer bitcount for Android devices in Unreal Engine 5. This setting is primarily used for the rendering system, specifically for configuring the depth buffer format on Android platforms.

This setting variable is primarily relied upon by the Android-specific modules of Unreal Engine, particularly the Android Runtime Settings and the OpenGL driver for Android. It’s used in the following subsystems:

  1. Android Runtime Settings (AndroidRuntimeSettings)
  2. Android Window management (ApplicationCore)
  3. Android OpenGL driver (OpenGLDrv)

The value of this variable is set in the Android Runtime Settings, which is likely configurable through the Unreal Engine editor’s project settings. It’s defined as a UPROPERTY with the GlobalConfig flag, indicating that it’s a globally configurable setting.

This variable interacts with other Android-specific settings, such as bValidateTextureFormats and potentially affects how the engine configures the EGL (OpenGL ES) surface for rendering on Android devices.

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

  1. It directly affects the depth buffer format used in Android rendering.
  2. Changes to this setting may impact rendering performance and visual quality on Android devices.
  3. The setting is platform-specific to Android and won’t affect other platforms.

Best practices when using this variable include:

  1. Choose an appropriate depth buffer format that balances visual quality and performance for your target Android devices.
  2. Test thoroughly on a variety of Android devices to ensure compatibility and performance with the chosen depth buffer format.
  3. Consider the requirements of your game or application when setting this value, as some visual effects or rendering techniques may require specific depth buffer formats.
  4. Coordinate this setting with other related Android rendering settings for optimal performance and visual quality.

#Setting Variables

#References In INI files

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

#References in C++ code

#Callsites

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

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

Scope (from outer to inner):

file
class        class UAndroidRuntimeSettings : public UObject

Source code excerpt:

	// The preferred depth buffer bitcount for Android
	UPROPERTY(GlobalConfig, EditAnywhere, Category = "APK Packaging", Meta = (DisplayName = "Preferred Depth Buffer format"))
	TEnumAsByte<EAndroidDepthBufferPreference::Type> DepthBufferPreference;

	// Verifies the device supports at least one of the cooked texture formats at runtime
	UPROPERTY(GlobalConfig, EditAnywhere, Category = "APK Packaging", Meta = (DisplayName = "Validate texture formats"))
	bool bValidateTextureFormats;

	// When building for MinSDKVersion >= 23 gradle will leave native libs uncompressed in the apk. This flag might be helpful for builds that are not intended to be distributed via Google Play

#Loc: <Workspace>/Engine/Source/Runtime/ApplicationCore/Private/Android/AndroidWindow.cpp:148

Scope (from outer to inner):

file
function     JNI_METHOD void Java_com_epicgames_unreal_GameActivity_nativeSetWindowInfo

Source code excerpt:

static FVector4 GAndroidLandscapeSafezone = FVector4(-1.0f, -1.0f, -1.0f, -1.0f);
#if USE_ANDROID_JNI
JNI_METHOD void Java_com_epicgames_unreal_GameActivity_nativeSetWindowInfo(JNIEnv* jenv, jobject thiz, jboolean bIsPortrait, jint DepthBufferPreference, jint PropagateAlpha)
{
	ClearCachedWindowRects();
	GAndroidIsPortrait = bIsPortrait == JNI_TRUE;
	GAndroidDepthBufferPreference = DepthBufferPreference;
	GAndroidPropagateAlpha = PropagateAlpha;
	FPlatformMisc::LowLevelOutputDebugStringf(TEXT("App is running in %s\n"), GAndroidIsPortrait ? TEXT("Portrait") : TEXT("Landscape"));
	FPlatformMisc::LowLevelOutputDebugStringf(TEXT("AndroidPropagateAlpha =  %d\n"), GAndroidPropagateAlpha);
}

JNI_METHOD void Java_com_epicgames_unreal_GameActivity_nativeSetSurfaceViewInfo(JNIEnv* jenv, jobject thiz, jint width, jint height)

#Loc: <Workspace>/Engine/Source/Runtime/OpenGLDrv/Private/Android/AndroidEGL.cpp:148

Scope (from outer to inner):

file
function     EGLConfigParms::EGLConfigParms

Source code excerpt:

{
	// If not default, set the preference
	int DepthBufferPreference = (int)FAndroidWindow::GetDepthBufferPreference();
	if (DepthBufferPreference > 0)
		depthSize = DepthBufferPreference;
	if (FAndroidMisc::GetMobilePropagateAlphaSetting() > 0)
	{
		alphaSize = 8;
	}
}

#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:2613

			string VersionDisplayName = GetVersionDisplayName(bIsEmbedded);
			string DepthBufferPreference;
			Ini.GetString("/Script/AndroidRuntimeSettings.AndroidRuntimeSettings", "DepthBufferPreference", out DepthBufferPreference);
			float MaxAspectRatioValue;
			if (!Ini.TryGetValue("/Script/AndroidRuntimeSettings.AndroidRuntimeSettings", "MaxAspectRatio", out MaxAspectRatioValue))
			{
				MaxAspectRatioValue = 2.1f;
			}
			string Orientation = ConvertOrientationIniValue(GetOrientation(Arch));