xr.DisableOpenXROnAndroidWithoutOculus

xr.DisableOpenXROnAndroidWithoutOculus

#Overview

name: xr.DisableOpenXROnAndroidWithoutOculus

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.

#Summary

#Usage in the C++ source code

The purpose of xr.DisableOpenXROnAndroidWithoutOculus is to control the initialization of OpenXR on Android devices when the project is not packaged for Oculus mobile devices. This setting variable is primarily used in the OpenXR plugin for Unreal Engine 5, specifically in the OpenXRHMD module.

The OpenXRHMD module relies on this setting variable to determine whether to initialize OpenXR on Android devices. It is part of the Unreal Engine’s XR (Extended Reality) subsystem.

The value of this variable is set as a console variable (CVar) with a default value of true. It can be modified at runtime through the console or configuration files.

This variable interacts with the associated variable CVarDisableOpenXROnAndroidWithoutOculus, which is a TAutoConsoleVariable that shares the same value and purpose.

Developers must be aware that when this variable is set to true (default), OpenXR will not initialize on Android unless the project is specifically packaged for Oculus mobile devices. This behavior is implemented due to issues with the OpenXR loader hanging during initialization on some devices instead of failing gracefully.

Best practices when using this variable include:

  1. Ensure that projects intended for Oculus mobile devices are properly packaged (ProjectSetting->Platforms->Android->Advanced APK Packaging->PackageForOculusMobileDevices list should not be empty).
  2. For non-Oculus Android XR projects, consider setting this variable to false if you want to use OpenXR, but be aware of potential initialization issues on some devices.
  3. Monitor and test the behavior on various Android devices when modifying this setting.

Regarding the associated variable CVarDisableOpenXROnAndroidWithoutOculus:

This is the actual console variable implementation of xr.DisableOpenXROnAndroidWithoutOculus. It is used in the same way and for the same purpose as described above. The variable is defined as a static TAutoConsoleVariable in the OpenXRHMDModule.cpp file.

The value of CVarDisableOpenXROnAndroidWithoutOculus is checked in the FOpenXRHMDModule::InitInstance() function to determine whether to proceed with OpenXR initialization on Android devices. If the variable is true and the project is not packaged for Oculus mobile devices, the initialization will be aborted.

When working with this variable, developers should:

  1. Use CVarDisableOpenXROnAndroidWithoutOculus.GetValueOnAnyThread() to retrieve its current value in C++ code.
  2. Be aware that changes to this variable at runtime will affect the behavior of OpenXR initialization on subsequent attempts.
  3. Consider the implications of modifying this variable on the overall XR experience and compatibility across different Android devices.

#Setting Variables

#References In INI files

Location: <Workspace>/Engine/Config/BaseDeviceProfiles.ini:1229, section: [MagicLeap_Vulkan DeviceProfile]

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Plugins/Runtime/OpenXR/Source/OpenXRHMD/Private/OpenXRHMDModule.cpp:27

Scope: file

Source code excerpt:


static TAutoConsoleVariable<bool> CVarDisableOpenXROnAndroidWithoutOculus(
	TEXT("xr.DisableOpenXROnAndroidWithoutOculus"),
	true,
	TEXT("If true OpenXR will not initialize on Android unless the project is packaged for Oculus (ProjectSetting->Platforms->Android->Advanced APK Packaging->PackageForOculusMobileDevices list not empty).  Currently defaulted to true because the OpenXR loader we are using hangs during intialization on some devices instead of failing, as it should."),
	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<bool> CVarCheckOpenXRInstanceConformance(
	TEXT("xr.CheckOpenXRInstanceConformance"),

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Plugins/Runtime/OpenXR/Source/OpenXRHMD/Private/OpenXRHMDModule.cpp:26

Scope: file

Source code excerpt:

	ECVF_Default);		// @todo: Should we specify ECVF_Cheat here so this doesn't show up in release builds?

static TAutoConsoleVariable<bool> CVarDisableOpenXROnAndroidWithoutOculus(
	TEXT("xr.DisableOpenXROnAndroidWithoutOculus"),
	true,
	TEXT("If true OpenXR will not initialize on Android unless the project is packaged for Oculus (ProjectSetting->Platforms->Android->Advanced APK Packaging->PackageForOculusMobileDevices list not empty).  Currently defaulted to true because the OpenXR loader we are using hangs during intialization on some devices instead of failing, as it should."),
	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<bool> CVarCheckOpenXRInstanceConformance(

#Loc: <Workspace>/Engine/Plugins/Runtime/OpenXR/Source/OpenXRHMD/Private/OpenXRHMDModule.cpp:595

Scope (from outer to inner):

file
function     bool FOpenXRHMDModule::InitInstance

Source code excerpt:

	else
	{
		if (CVarDisableOpenXROnAndroidWithoutOculus.GetValueOnAnyThread())
		{
			UE_LOG(LogHMD, Log, TEXT("OpenXRHMDModule: vr.DisableOpenXROnAndroidWithoutOculus is true and this project is not packaged for Oculus Mobile Devices.  Disabling OpenXR."));
			return false;
		}
		else
		{