// Copyright (c) 2017-2021, The Khronos Group Inc.
//
// SPDX-License-Identifier: CC-BY-4.0

[[runtime-interaction]]
== Runtime Interaction ==

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


[[runtime-discovery]]
=== 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]]
==== 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
https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html[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.

The JSON file is named "active_runtime.json" and 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 might be
at:

```
/etc/xdg/openxr/1/active_runtime.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.
This allows the user's preference to easily override a global default.

===== Windows Active Runtime Location

The Windows OpenXR active runtime information is actually 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 major version.

[NOTE]
.Important
====
If using a 32-bit application on a 64-bit Windows install, "WOW6432Node" is
added before "SOFTWARE", in the above path like so:

```
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]]
===== 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>>.
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 at most one item, the currently active runtime.
  The policy of which runtime is chosen to be active (if more than one is
  installed) is left to the content provider.
  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.
 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.


[NOTE]
.Note
====
Use of a content provider does mean that OpenXR applications on Android will
need the following in their manifest.

[source,xml]
```
<uses-permission android:name="org.khronos.openxr.permission.OPENXR" />
<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" />
</queries>
```

Additionally, applications should **not target API levels higher than 29**
for maximum compatibility, as runtimes may need to query and load classes
from their own packages, which are necessarily not listed in the `<queries>`
tag above.
====

If no runtime is found this way, as a fall-back, a similar process as on
Linux takes place, searching for `active_runtime.json` files in:

* `/odm/etc/openxr/1`
* `/vendor/etc/openxr/1`
* `/system/etc/openxr/1`



[[runtime-enumeration]]
==== 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`, and just 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 this directory, 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 an `active_runtime.json`.

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

[[runtime-manifest-file-format]]
==== 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]
.Runtime Manifest
====
[source,json]
----
{
   "file_format_version": "1.0.0",
   "runtime": {
      "name": "openxr_sample_runtime",
      "library_path": "./dbuild/src/impl/libopenxr_sample_impl.so"
   }
}
----
====

.Runtime Manifest File Fields

[options="header",cols="20%,10%,70%"]
|====
| 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]]
===== 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]]
===== 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:

[source,xml]
```
<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.getNativeLibraryDir()` 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]]
==== 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]]
==== 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]
.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]]
=== 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).

[[xrNegotiateLoaderRuntimeInterface,xrNegotiateLoaderRuntimeInterface]]
[source,c++]
----
XrResult xrNegotiateLoaderRuntimeInterface(
            const XrNegotiateLoaderInfo *loaderInfo,
            XrNegotiateRuntimeRequest *runtimeRequest);
----
  * pname:loaderInfo must: be a valid pointer to a constant
    slink:XrNegotiateLoaderInfo structure.
  * pname:runtimeRequest must be a valid pointer to a
    slink:XrNegotiateRuntimeRequest structure.

This 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, Runtime
Exporting of Commands>> for more information).

If the function succeeds, the runtime should return `XR_SUCCESS`.
If the function fails, the runtime should return
`XR_ERROR_INITIALIZATION_FAILED`.
The entire <<loader-runtime-negotiation-process, negotiation process>> is
defined in more detail below.

The sname:XrNegotiateLoaderInfo struct is defined in the
`src/common/loader_interfaces.h` header.
It is used to pass information about the loader to a runtime during the
negotiation process.
See the definition of slink:XrNegotiateLoaderInfo under the
<<loader-api-layer-interface-negotiation,layer negotiation>> section for
more information.

The sname:XrNegotiateRuntimeRequest can also be found in the
`src/common/loader_interfaces.h` header.
It is used to pass information about the runtime back to the loader during
the negotiation process.

[[XrNegotiateRuntimeRequest,XrNegotiateRuntimeRequest]]
[source,c++]
----
struct XrNegotiateRuntimeRequest {
    XrLoaderInterfaceStructs structType;
    uint32_t structVersion;
    size_t structSize;
    uint32_t runtimeInterfaceVersion;
    uint32_t runtimeApiVersion;
    PFN_xrGetInstanceProcAddr getInstanceProcAddr;
};
----
  * pname:structType must: be a valid value of
    elink:XrLoaderInterfaceStructs.
    In this case, it must specifically be
    `XR_LOADER_INTERFACE_STRUCT_RUNTIME_REQUEST`.
  * pname:structVersion must: be a valid version of the structure.
    The `loader_interfaces.h` header uses the value
    `XR_RUNTIME_INFO_STRUCT_VERSION` to describe the current latest version
    of this structure.
  * pname:structSize must: be the size in bytes of the current version of
    the structure (i.e. sizeof(XrNegotiateRuntimeRequest))
  * pname:runtimeInterfaceVersion is the version of the
    <<runtime-interface-versions,loader/runtime interface version>> being
    requested by the runtime.
    Should not be outside of the bounds of the
    slink:XrNegotiateLoaderInfo::`minInterfaceVersion` and
    sname:XrNegotiateLoaderInfo::`maxInterfaceVersion` values (inclusive).
  * pname:runtimeApiVersion is the version of the OpenXR API supported by
    this runtime as formatted by `XR_MAKE_VERSION` defined in `openxr.h`.
    Patch is ignored.
  * pname:getInstanceProcAddr is a pointer to the runtime's
    `xrGetInstanceProcAddr` call that will be used by the loader to complete
    a dispatch table to all valid OpenXR commands supported by the runtime.

[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, 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.
====


[[loader-runtime-negotiation-process]]
==== Loader/Runtime Negotiation Process ====

Once the loader has obtained a valid address to the runtime's
flink:xrNegotiateLoaderRuntimeInterface function, the loader will create a
variable of type slink:XrNegotiateLoaderInfo and initialize it in the
following ways:

1. Set the structure "structType" to
   `XR_LOADER_INTERFACE_STRUCT_LOADER_INFO`
2. Set the structure "structVersion" to the current version,
   `XR_LOADER_INFO_STRUCT_VERSION`
3. Set the structure "structSize" to the current size of the
   `XrNegotiateLoaderInfo` structure
4. Set "minInterfaceVersion" to the minimum
   <<runtime-interface-versions,loader/runtime interface version>> that the
   loader supports
5. Set "maxInterfaceVersion" to the current version of the
   <<runtime-interface-versions,loader/runtime interface>> at the time of
   loader compilation
6. Set "minApiVersion" to the minimum version of OpenXR supported by the
   loader
7. Set "maxApiVersion" to the maximum version of OpenXR supported by the
   loader (the current version at the time of loader compilation).

The loader will also create an initialize a variable of type
slink:XrNegotiateRuntimeRequest to allow the runtime to properly respond to
the request.
The structure will be initialized by the loader in the following way:

1. Set the structure "structType" to
   `XR_LOADER_INTERFACE_STRUCT_RUNTIME_REQUEST`
2. Set the structure "structVersion" to the current version,
   `XR_RUNTIME_INFO_STRUCT_VERSION`
3. Set the structure "structSize" to the current size of the
   `XrNegotiateRuntimeRequest` structure

The loader will leave the remaining fields uninitialized to allow each
runtime to fill in the appropriate information for itself.
The loader will then individually call each runtime's
flink:xrNegotiateLoaderRuntimeInterface function and each runtime then must:

* Determine if it can support the loader's request:
** Does the runtime support any <<runtime-interface-versions, loader/runtime
   interface version>> between pname:loaderInfo->pname:minInterfaceVersion
   and pname:loaderInfo->pname:maxInterfaceVersion:
** *AND* does the runtime support any OpenXR API version between
   pname:loaderInfo->pname:minApiVersion and
   pname:loaderInfo->pname:maxApiVersion:
* If it is able to support the request, it must: return `XR_SUCCESS` and:
** Fill in pname:runtimeRequest->pname:runtimeInterfaceVersion with the
   runtime interface version it desires to support
** Fill in pname:runtimeRequest->pname:runtimeApiVersion with the API
   version of OpenXR it will execute under.
** Fill in pname:runtimeRequest->pname:getInstanceProcAddr with a valid
   function pointer so that the loader can query function pointers to the
   remaining OpenXR commands supported by the runtime.
* Otherwise, it must: return `XR_ERROR_INITIALIZATION_FAILED`


[[runtime-exporting-of-commands]]
==== Runtime Exporting of Commands ====

The flink: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]]
==== 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]]
===== Runtime Interface Version 1 =====

* Defined manifest file version 1.0.0.
* Introduced the concept of negotiation.
** Requires runtimes to export `xrNegotiateLoaderRuntimeInterface` function.


[[android-runtime-negotiation]]
==== Android Runtime Negotiation ====

The Android loader uses the same protocol for initializing the dispatch
table as described above.
The only difference is that the Android loader queries API layer and
extension information directly from the respective libraries and does not
use the json manifest files used by the Windows and Linux loaders.

[[additional-loader-requirements]]
=== 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`.