runtime.adoc

Runtime Interaction

This section discusses the various requirements for the loader and an OpenXR runtime to properly interact.

Runtime Discovery

OpenXR may have a choice of multiple runtimes on a user’s system. The selection of the active runtime is handled external to the loader. The loader is responsible for discovering only the active OpenXR runtime on the system, and loading it properly. The standard process in which the loader discovers the active runtime on a system is platform dependent.

Active Runtime Information

The means of identifying the active runtime used by an OpenXR application vary based on the underlying operating system and is detailed in the sub-sections below. This information is also important if the active runtime needs to be changed by an external entity (on those platforms that support updating).

Linux Active Runtime Location

On Linux, the active runtime information is contained inside a JSON-formatted file located in a standard XDG configuration directory or the system’s standard global configuration directory (typically /etc), under the relative path:

openxr/<major_api_version>

<major_api_version> should be replaced with the integer value for the corresponding OpenXR API version.

Two JSON file names are checked in each directory. First, the loader looks for active_runtime.<arch>.json, where <arch> is an architecture and ABI specifier from the Architecture/ABI Identifiers table. If no such file is found, active_runtime.json is then checked. The JSON file contains the necessary information on how OpenXR components can load the appropriate runtime library.

For example, a globally-configured OpenXR 1.x active runtime file on an x86_64 PC might be at:

/etc/xdg/openxr/1/active_runtime.x86_64.json

When multiple such files exist, XDG_CONFIG_HOME is preferred, followed by the elements of XDG_CONFIG_DIRS in order, followed by the system’s global configuration directory. Both filenames are tested in a given directory before moving on. This allows the user’s preference to easily override a global default.

Note	NOTE active_runtime filenames may be a symbolic link to a file with a runtime-specific name, for ease of runtime switching and enumeration by the user or system tools. See Linux Installed Runtimes Enumeration for more information.

Windows Active Runtime Location

The Windows OpenXR active runtime information is located in the Windows Registry (not to be confused with the OpenXR registry) under the key:

HKEY_LOCAL_MACHINE\SOFTWARE\Khronos\OpenXR\<major_api_version>

Where <major_api_version> should be replaced with the integer value for the corresponding OpenXR API version.

Note	Important If using a 32-bit application on a 64-bit Windows install, "WOW6432Node" is added before "SOFTWARE" in the preceding path as follows: HKEY_LOCAL_MACHINE\WOW6432Node\SOFTWARE\Khronos\OpenXR\<major_api_version>

This means that the complete registry path to the OpenXR 1.x active runtime registry value is:

HKEY_LOCAL_MACHINE\SOFTWARE\Khronos\OpenXR\1

Under that registry key, the value "ActiveRuntime" is defined as a string value and should be defined to full directory path of the runtime’s JSON file.

An example "ActiveRuntime" value might look something like the following:

C:\windows\system32\my_system_runtime.json

Android Active Runtime Location

The Android OpenXR active runtime data, equivalent to the contents of a runtime manifest JSON file, is determined by a ContentProvider. Vendors producing Android-based devices where only a single runtime would make sense may consider implementing the "System" content provider directly. Others can use a working-group-provided installable "RuntimeBroker" implementation of the content provider and associated preference UI, and will only need to add metadata to their manifest file as described in Android Runtime Metadata for Installable Broker. The RuntimeBroker package’s responsibility is to externalize runtime finding logic and the runtime state user preferences.

An OpenXR runtime selection ContentProvider responds to one of two authorities:

• org.khronos.openxr.runtime_broker - For use only by the working-group-provided package with the user preferences activity. This should not be installed or modified by vendors: it will be distributed through typical end-user channels for application packages and is intended for user-controlled installable (e.g. plug-in) devices. Read access is guarded by a permission of "normal" protection level named org.khronos.openxr.permission.OPENXR.

• org.khronos.openxr.system_runtime_broker - This may be provided by vendors in system-installed packages. Read access is guarded by a permission of "normal" protection level named org.khronos.openxr.permission.OPENXR_SYSTEM.

The installable RuntimeBroker content provider defines the permission group org.khronos.openxr.permission-group.OPENXR, containing the above two permissions. The runtime brokers may use their respective permissions to guard read access to the ContentProvider. Write permission should not be allowed, or should be limited to explicit choices by the device user. The defined URIs for the ContentProvider authorities are as follows:

• /openxr/major_ver/abi/abi/runtimes/active - This URI represents a table containing zero, one, or more items, corresponding to the single currently active runtime. The loader should attempt to use dlopen on the returned items sequentially and use the first item for which dlopen succeeds. This is to allow backwards compatibility with obsolete loader revisions. No sort order is required to be honored by the content provider. Available columns include:

  • package_name - Name of the package providing the runtime

  • native_lib_dir - ABI-specific directory containing the runtime’s shared library

  • so_filename - The filename to load as the runtime: Combines with native_lib_dir to provide the absolute path of the shared object.

  • has_functions - Boolean, if true, it indicates the loader should query the functions/ URI to identify the names of entry points it should query.

• /openxr/major_ver/abi/abi/runtimes/package/functions - This URI is for package-specific function name remapping. Since this is an optional field in the corresponding JSON manifests for OpenXR, it is optional here as well. If the active runtime contains "true" in its "has_functions" column, then this table must exist and be queryable. No sort order is required to be honored by the content provider. package is the package name containing the active runtime. Available columns include:

  • function_name - Corresponds to the "key" in the JSON manifest field.

  • symbol_name - Corresponds to the "value" in the JSON manifest field.

Within the loader, the results from either content provider are used to construct an object corresponding to an equivalent JSON runtime manifest file as used on other platforms.

If no runtime is found this way, as a fall-back, a similar process as on Linux takes place, searching for active_runtime.<arch>.json and active_runtime.json files in the following locations in priority order:

1. /product/etc/openxr/major_ver

2. /odm/etc/openxr/major_ver

3. /oem/etc/openxr/major_ver

4. /vendor/etc/openxr/major_ver

5. /system/etc/openxr/major_ver

<major_api_version> should be replaced with the integer value for the corresponding OpenXR API version, and <arch> is an architecture and ABI specifier from the Architecture/ABI Identifiers table. Both filenames are checked in each directory before moving on to the next.

Android IPC and Runtime Access

As Android is a permission-limited environment, additional constraints are placed on runtimes and applications. In modern versions of Android, applications cannot query arbitrary packages for arbitrary services that are not pre-declared in the manifest. To avoid needing to update application manifests for each OpenXR runtime’s requirements, the intent service name org.khronos.openxr.OpenXRRuntimeService (same as used by installable runtime discovery) is reserved for use by OpenXR runtimes and their components. Similarly, the intent service name org.khronos.openxr.OpenXRApiLayerService is reserved for use by OpenXR API layers and their components. To target an API level higher than 29, applications must: include provisions in their manifest to allow them to query for services with these intent names. In turn, runtimes and their components that need to locate their originating package should: query first for packages providing a service for the relevant intent, then traverse the list of resolutions to find their own package. There is no set API provided by an intent service of this name: it exists solely as a marker of an OpenXR runtime and as a key for retrieving OpenXR runtime component packages without needing to perform arbitrary package queries. This does pose the risk that an application can view all OpenXR runtimes installed, rather than only the active one. However, the number of runtimes per device is likely to be very small, and this opens the smallest weakness possible to achieve the required functionality.

Note

Note Applications will require the following <queries> statements in their manifest for the loader to locate and load the runtime correctly. (If building an application using the loader AAR provided by the working group, beginning with version 1.0.28, these items are included in the AAR manifest and will be merged into your application manifest automatically.) <uses-permission android:name="org.khronos.openxr.permission.OPENXR_SYSTEM" /> <queries> <provider android:authorities="org.khronos.openxr.runtime_broker;org.khronos.openxr.system_runtime_broker" /> <intent> <action android:name="org.khronos.openxr.OpenXRRuntimeService" /> </intent> <intent> <action android:name="org.khronos.openxr.OpenXRApiLayerService" /> </intent> </queries> The permission is needed to contact a system broker. The provider query is to be able to contact system and installable brokers. The intent query is for runtimes to look up their own package, which is required when targeting API levels higher than 29. It is also recommended to include the following, which could be needed for haptic feedback: <uses-permission android:name="android.permission.VIBRATE" /> Earlier versions of the installable broker also wanted the following permission, but this is no longer required. It is harmless to leave it in place, but the broker no longer requires it. <uses-permission android:name="org.khronos.openxr.permission.OPENXR" />

Architecture/ABI Identifiers

On platforms such as Linux and Android where the active runtime manifest may be found by filename, the following table of known architectures and ABIs is used.

Architecture/ABI Identifier	Android NDK ABI Name	Debian Port Name	Description
x32		x32	64-bit x86 instructions, using an ILP32 model (32-bit pointers)
x86_64	x86_64	x86_64	64-bit x86
i686	x86	i386	32-bit x86
aarch64	arm64-v8a	aarch64	64-bit ARM architecture, little endian
armv7a-vfp	armeabi-v7a (See note.)	armhf	32-bit ARMv7-A architecture, little endian, with hardware floating point and VFP PCS ABI
armv5te		armel (See note.)	32-bit ARMv5TE architecture or compatible, little endian
mips64		mips64el	64-bit MIPS architecture, little endian
mips		mipsel	32-bit MIPS architecture, little endian
ppc64		ppc64	64-bit PowerPC architecture, big endian
ppc64el		ppc64el	64-bit POWER8/POWER9 architecture, little endian (OpenPOWER ELF ABI v2)
s390x		s390x	64-bit S390/z-Series architecture, big endian
hppa		hppa	32-bit HP PA-RISC architecture, big endian
alpha		alpha	64-bit Alpha architecture
ia64		ia64	64-bit IA-64 architecture
m68k		m68k	32-bit Motorola 68000-based architecture, big endian
riscv64		riscv64	64-bit RISC-V architecture, little endian
sparc64		sparc64	64-bit SPARC architecture
loong64		loong64	64-bit LoongArch architecture, little endian (LP64D ABI)

Note: The preceding table defines armv7a-vfp as the architecture/ABI identifier for 32-bit ARM in Android. While the Android ABI called armeabi-v7a does not use VFP PCS as the system ABI, a definition in openxr_platform_defines.h enables the VFP PCS calling convention for all OpenXR API calls and function pointers.

Note: Raspberry Pi OS differs in its architecture definitions from upstream Debian by redefining armhf as ARMv6, rather than ARMv7. Therefore, on that operating system, armhf maps to ID armv5te.

Runtime Enumeration

When multiple runtimes are installed on a system, the OpenXR loader will find the currently active runtime using the mechanism described before.

At that point, the loader will act as if this runtime is currently the only installed one.

To be able to allow additional tooling to discover other runtimes that are installed, but currently are not the active runtime on the system, each runtime should register the path to their manifest in a platform-dependant way in a list of "available runtimes".

Runtime manifest files may optionally contain a "name" field. Tools that allow users to configure what runtime is currently active should display this user-friendly name if present when referring to the runtime in question.

Windows Installed Runtimes Enumeration

On Windows, the available runtimes' information is located in the Windows Registry.

It can be found under the key:

HKEY_LOCAL_MACHINE\SOFTWARE\Khronos\OpenXR\<major_api_version>\AvailableRuntimes

Each installed runtime should add a DWORD value under that key. The `DWORD’s name is the full path to the runtime’s manifest

Similarly to how Implicit API layers can control their activation state in the registry, as described in [windows-manifest-registry-usage]:

• A value of 0 indicates that the runtime can be discovered by tools that want to enumerate all installed runtimes.

• A non-zero value may be used if the runtime wants to disable itself from enumeration (for example, if hardware configuration, or first time setup hasn’t been run by the user yet).

For instance, the OpenXR 1.x runtime used as an example in section Windows Active Runtime Location would add a DWORD value in:

HKEY_LOCAL_MACHINE\SOFTWARE\Khronos\OpenXR\1\AvailableRuntimes

With the name:

C:\Windows\system32\my_system_runtime.json

And set it to 0.

All considerations for 32 bit platforms mentioned in section Windows Active Runtime Location still apply.

Tools that want to change the currently ActiveRuntime should not modify the list of AvailableRuntimes, but rather copy the path to the correct location.

Linux Installed Runtimes Enumeration

As previously defined, the OpenXR configuration on Linux is either stored in a standard XDG configuration directory, or the system-wide configuration directory.

Aside from the currently active runtime, installed runtimes that make themselves available for enumeration should install their runtime manifest into one of these directories, using any name suitable.

Rules about precedence in different directories for runtime enumeration follow the same rules as in section Linux Active Runtime Location for selecting the folder containing the active runtime manifest.

Tools that want to change the current active runtime should only update the active_runtime.<arch>.json and/or active_runtime.json symlink to the active runtime, and not move, copy, or delete any other files.

Runtime Manifest File Format

As mentioned before, the OpenXR loader on Windows and Linux uses manifest files to discover the active runtime. The loader only loads the actual runtime library when necessary. Because of this, the manifest files contain important information about the runtime. The JSON file itself does not have any requirements for naming, beyond the requirement of using the ".json" extension.

Here is an example runtime JSON manifest file:

Example 1. Runtime Manifest

{
   "file_format_version": "1.0.0",
   "runtime": {
      "name": "openxr_sample_runtime",
      "library_path": "./dbuild/src/impl/libopenxr_sample_impl.so"
   }
}

Table 1. Runtime Manifest File Fields

Field Name	Required	Field Value
"file_format_version"	Yes	The JSON format major.minor.patch version number of this file. Currently supported version is 1.0.0.
"runtime"	Yes	The identifier used to group all runtime information together.
"library_path"	Yes	The "library_path" specifies either a filename, a relative pathname, or a full pathname to the runtime’s shared library file. If "library_path" specifies a relative pathname, it is relative to the path of the JSON manifest file (e.g. for cases when an application provides a runtime that is in the same folder hierarchy as the rest of the application files). If "library_path" specifies a filename, the library must live in the system’s shared object search path. There are no rules about the name of the runtime shared library files other than it should end with the appropriate suffix (".DLL" on Windows, and ".so" on Linux).
"functions"	No	This section can be used to identify a different function name for the loader to use in place of standard runtime interface functions. The "functions" node is required if the runtime is using an alternative name for xrNegotiateLoaderRuntimeInterface.
"name"	No	An optional user-facing name that can be used by tooling to refer to this specific runtime.

Vendors may add non-standard fields to their runtime manifest files. These vendor specific fields must be prefixed with their vendor id (e.g: VENDOR_name_of_field).

Note	Note If the same runtime shared library supports multiple, incompatible versions of OpenXR API, it must have separate JSON files for each API major version (all of which may point to the same shared library).

Runtime Manifest File Version History

The current highest supported runtime manifest file format supported is 1.0.0. Information about each version is detailed in the following sub-sections:

Runtime Manifest File Version 1.0.0

The initial version of the runtime manifest file specified the basic format and fields of a runtime JSON file. The fields of the 1.0.0 file format include:

• "file_format_version"

• "runtime"

• "library_path"

• "name"

  • This is an optional field, added before the OpenXR 1.0.18 release. As it is not used by the loader nor does it introduce incompatibility, it was added to the format described here without incrementing the manifest file format version number.

Android Runtime Metadata for Installable Broker

The working-group-provided installable RuntimeBroker provides a ContentProvider matching the specification of Android Active Runtime Location. The returned data is determined by a combination of user settings and package metadata, rather than a JSON manifest file. To be identified by the RuntimeBroker as an OpenXR runtime, a package must:

• Specify the <application> attribute android:extractNativeLibs="true", to allow the runtime .so to be loaded dynamically from another package.

• Provide an exported Service (no specific methods are required)

  • With an intent-filter for the action name org.khronos.openxr.OpenXRRuntimeService

  • Exposing a meta-data value named org.khronos.openxr.OpenXRRuntime.SoFilename with the filename of the runtime .so file

  • Exposing a meta-data value named org.khronos.openxr.OpenXRRuntime.MajorVersion with the major version number of the OpenXR runtime standard supported.

  • Optionally exposing meta-data values named org.khronos.openxr.OpenXRRuntime.Functions.function_name with value of the symbol name, if any functions to be loaded do not have symbol names matching the specification’s function name.

For example, the following markup could be added within the <application> tag to expose a runtime with no function name remapping:

<service
    android:name=".MyOpenXRService"
    android:label="@string/service_name"
    android:exported="true">
    <meta-data
        android:name="org.khronos.openxr.OpenXRRuntime.SoFilename"
        android:value="libopenxr_sample.so" />
    <meta-data
        android:name="org.khronos.openxr.OpenXRRuntime.MajorVersion"
        android:value="1" />

    <intent-filter>
        <action android:name="org.khronos.openxr.OpenXRRuntimeService" />
    </intent-filter>
</service>

To find a runtime, the RuntimeBroker first retrieves all services that advertise the org.khronos.openxr.OpenXRRuntimeService intent with the correct org.khronos.openxr.OpenXRRuntime.MajorVersion value. If exactly one runtime is found (and it is not disabled by user preference in the broker), it is considered the active OpenXR runtime. If more than one is found, user preferences are used to identify the "active" runtime.

The path containing the dynamic library is computed from ApplicationInfo.nativeLibraryDir and the specified ABI, and the filename is returned using the filename found in the OpenXR metadata value. The "hasFunctions" column is dynamically generated based on the presence of any function metadata entries.

Note that system-provided runtimes exposed using the "System" content provider do not need to expose this same metadata, as the implementation of the system content provider can be used to store and report this information.

Loader Distribution

Any application using the OpenXR API is responsible with making sure it can properly execute on a user’s system. Some OpenXR environments may not use an OpenXR loader but instead provide libraries which directly link with their runtime. Other runtime or platform vendors may choose to provide a separate OpenXR loader for debug or developmental reasons. Whatever the scenario, if an application uses an OpenXR loader, then that application is responsible for packaging the OpenXR loader in a location that will not interfere with other applications. If an engine or platform provides an OpenXR loader for applications, it must: provide documentation on how to properly package the necessary files.

Overriding the Default Runtime Usage

There may be times that a developer wishes to ignore the standard runtime discovery process and force the loader to use a specific runtime. This could be for many reasons including:

• Forcing on a Beta runtime

• Replacing a problematic runtime in favor of another

In order to support this, the loader can be forced to look at specific runtime with the XR_RUNTIME_JSON environment variable. In order to use the setting, simply set it to the full global path location of the desired runtime manifest file.

Note	Important If the "XR_RUNTIME_JSON" variable is defined, then the loader will not look in the standard location for the active runtime. Instead, the loader will only utilize the filename defined in the environment variable.

Example 2. Setting XR_RUNTIME_JSON Override

Windows

set XR_RUNTIME_JSON=\windows\system32\steam_runtime.json

Linux

export XR_RUNTIME_JSON=/home/user/.config/openxr/1/steamxr.json

Loader/Runtime Interface Negotiation

The OpenXR symbols exported by a runtime must not clash with the loader’s exported OpenXR symbols. Because of this, all runtimes must export only the following command with beginning with the xr prefix. This command is not a part of the OpenXR API itself, only a private interface between the loader and runtimes for version 1 and higher interfaces. In order to negotiate the loader/runtime interface version, the runtime must implement the fname:xrNegotiateLoaderRuntimeInterface` function (or a renamed version of this function identified in the manifest file). fname:xrNegotiateLoaderRuntimeInterface` is defined in openxr.h.

fname:xrNegotiateLoaderRuntimeInterface` function should be directly exported by a runtime so that using "GetProcAddress" on Windows or "dlsym" on Linux, should return a valid function pointer to it (see Runtime Exporting of Commands for more information).

Note

Important Remember, during the call to fname:xrNegotiateLoaderRuntimeInterface, the runtime must: grab control of the active runtime manifest file. Functions that should be used to grab control of the manifest file are defined in the common code as described in the Active Runtime File Management section of this document. The runtime must: also determine when to release control of this file. This may be due to the last instance an application created is destroyed, the application is exiting, or some period of inactivity occurs.

Runtime Exporting of Commands

The fname:xrNegotiateLoaderRuntimeInterface should be directly exported by a runtime so that using "GetProcAddress" on Windows or "dlsym" on Linux, should return a valid function pointer to it. However, all other OpenXR entry points must: either:

• NOT be exported directly from the runtime library

• or NOT use the official OpenXR command names if they are exported

This requirement is especially for runtime libraries that include other functionality (such as OpenGL) and thus could be loaded by the application prior to when the OpenXR loader library is loaded by the application.

Beware of interposing by dynamic OS library loaders if the official OpenXR names are used. On Linux, if official names are used, the runtime library must be linked with -Bsymbolic.

Runtime Interface Versions

The current Runtime Interface is at version 1. The following sections detail the differences between the various versions.

Runtime Interface Version 1

• Defined manifest file version 1.0.0.

• Introduced the concept of negotiation.

  • Requires runtimes to export xrNegotiateLoaderRuntimeInterface function.

Additional Loader Requirements

• The loader must: not call the runtime for xrEnumerateApiLayerProperties

• The loader must: not call the runtime for xrEnumerateInstanceExtensionProperties, if "layerName" is not equal to NULL.