The loader was designed with the following goals in mind.

The loader library on Windows and Linux will directly export all core OpenXR commands for the OpenXR version it supports. When an application links directly to the loader library in this way, the OpenXR calls are simple trampoline functions that jump to the appropriate dispatch table entry for the object provided.

The specific list, in alphabetical order, of OpenXR commands directly exported by the loader for API version 1.0 are:

When an OpenXR application chooses to use one of the exports directly exposed from the OpenXR loader, the call chain will look like one of the following (if the user has enabled two API layers):

The "Special Instance" call chain is used in several places where the loader has to perform some work before and after any API layers, but prior to calling the enabled runtime. xrCreateInstance, xrDestroyInstance, and xrGetInstanceProcAddr are three of the main commands that fall into this group. Most commands do not require a terminator and will use the second call chain.

With loader indirect linking an application dynamically generates its own dispatch table of OpenXR commands. This method allows an application to fail gracefully if the loader cannot be found, or supports an older version of the API than the application. To do this, the application uses the appropriate platform specific dynamic symbol lookup (such as dlsym()) on the loader library to discover the address of the xrGetInstanceProcAddr command. Once discovered, this command can be used to query the addresses of all other OpenXR commands (such as xrCreateInstance, xrEnumerateInstanceExtensionProperties and xrEnumerateApiLayerProperties). Then, the application would use its table of function pointers to make the call into the OpenXR API.

One benefit when an application generates its own dispatch table is the removal of the loader trampoline call from most commands in a call chain, which could potentially increase performance. In that case, most commands would use the following call chain:

The OpenXR loader’s dynamic library name is dependent on the user’s underlying operating system. The following table shows the loader library names for common OSs:

<major> and <minor> in the above table refer to the major and minor API versions of OpenXR.

Explicit API layers are API layers which are enabled by an application (e.g. with the xrCreateInstance function) or by setting a loader environment variable.

Implicit API layers are API layers which are enabled simply because they exist. An implicit layer found by the loader will be loaded by default, unless specifically disabled.

Some implicit API layer examples include:

Because implicit API layers are enabled automatically, they have an additional requirement over explicit API layers in that they must specify a "disable environment variable" in the API layer’s JSON manifest file, with key name disable_environment. This environment variable when present will disable the implicit API layer. Implicit API layers are not otherwise visible to or controllable by applications.

Optionally, an implicit API layers may specify an "enable environment variable", in which case the loader will load the implicit API layer only when the enable environment variable is defined in the user’s execution environment. If both enable and disable environment variables are present in the environment, the layer will be disabled.

Both the enable and disable environment variables are specified in the API layer’s JSON manifest file, which is created by the API layer developer.

Discovery of system-installed implicit and explicit API layers is described later in the API Layer Discovery Section. For now, simply know that what distinguishes an API layer as implicit or explicit is dependent on the operating system, as shown in the table below.

Desktop developers may also override the way the loader searches for API layers. If the developer/user would like to find API layers in a non-standard location, they may define the "XR_API_LAYER_PATH" environmental variable. For more information on using "XR_API_LAYER_PATH", see the Overriding the Default API Layer Paths section under "API Layer Interaction".

Desktop developers may want to enable API layers that are not enabled by the given application they are using. On Linux and Windows, the environment variable "XR_ENABLE_API_LAYERS" can be used to enable additional API layers which are not specified (enabled) by the application at xrCreateInstance. "XR_ENABLE_API_LAYERS" is a colon (Linux)/semi-colon (Windows) separated list of API layer names to enable. Order is relevant with the first API layer in the list being the top-most API layer (closest to the application) and the last API layer in the list being the bottom-most API layer (closest to the driver). See the Overall API Layer Ordering section for more information.

Application specified API layers and user specified API layers (via environment variables) are aggregated and duplicates removed by the loader when enabling API layers. API layers specified via environment variable are top-most (closest to the application) while API layers specified by the application are bottom-most. If an API layer name appears multiple times in the list of API layers to enable, all occurrences after the first are ignored.

To use XR_ENABLE_API_LAYERS, simply define the environment variable with a properly delimited list of API layer names. This is not the file name, but the name the API layers use when normally being enabled inside of xrCreateInstance. This usually takes the form of:

This would produce the name of: XR_APILAYER_LUNARG_test

The overall ordering of all API layers by the loader based on the above looks as follows:

As shown in the above image, any implicit API layers will first intercept OpenXR commands, followed by any explicit API layers enabled by environmental variables, finally being intercepted by any explicit API layers directly enabled by the application. Whether or not the API layers continue into a loader terminator call, or directly into a runtime depends on the call chain.

Ordering may also be important internal to the list of explicit API layers. Some API layers may be dependent on other behavior being implemented before or after the loader calls it.

On Desktop systems (such as Windows and Linux) JSON formatted manifest files are used to store OpenXR component information. The OpenXR loader will search specific areas of the computer for the corresponding JSON manifest files that are used to identify the names and attributes of OpenXR API layers. The use of manifest files allows the loader to avoid actively loading the shared library files until the application request causes them to be activated.

The following sections define the standard locations the OpenXR loader searches when looking for JSON manifest files.

Once the loader has obtained a valid address to the API layer’s xrNegotiateLoaderApiLayerInterface function, the loader will create a variable of type XrNegotiateLoaderInfo and initialize it in the following ways:

The loader also creates and initializes a variable of type XrNegotiateApiLayerRequest to allow the API layer to properly respond to the request. The structure will be initialized by the loader in the following way:

The loader will leave the remaining fields uninitialized to allow each API layer to fill in the appropriate information for itself. The loader will then individually call each API layer’s xrNegotiateLoaderApiLayerInterface function and each API layer then must :

The current API layer interface is at version 1. The following sections detail the differences between the various versions.

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).

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:

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.

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:

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.

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

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

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 xrNegotiateLoaderRuntimeInterface function and each runtime then must :

The 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:

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.

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

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.

All OpenXR source utilizes the CMake tool to generate platform-specific build files. Currently, the loader requires CMake version 3.5.1 or newer. CMake may be obtained from either the CMake web-site or often using your computer’s software update mechanism.

The CMake files of interest exist in several locations:

The loader code is formatted using clang-format with the following settings:

Clang-format is required to be executed prior to committing new code whenever possible.

Internally, the loader is implemented using the C++ language, taking advantage of C++11 standard features. Since the OpenXR API is exposed using C, all exported commands must be properly wrapped using extern "C" { and }.

The loader code should use the standard types defined by stdint.h in order to avoid using platform-specific type defines whenever possible. Some commonly used types include:

In some cases, it may not be possible to use these generic type, like when calling a platform-specific function. In those cases, this requirement is waived.

Additionally, STL may be used in any C++ source code areas.

Namespaces outside of the OpenXR loader must not be enabled by default.

Instead, any time you use a function, variable, type or other component coming from a namespace, you must list the full namespace of that item. Some examples are as follows:

The OpenXR loader itself does not internally throw C++ exceptions, for compatibility with environments where exceptions are forbidden. However, since it exposes a C ABI, and the standard library facilities used may throw exceptions, functions exposed to the ABI (those with names matching OpenXR functions) must have XRLOADER_ABI_TRY before the opening { of the function body and XRLOADER_ABI_CATCH_FALLBACK after the closing } of the function body. (This is done automatically for those functions whose trampoline is entirely generated.) In normal cases, these two macros are defined by exception_handling.hpp to expand to try and a full catch clause, respectively. This prevents any exceptions from escaping, in what’s known as a "function-try-block".

In very limited cases, you may choose to disable exception handling through the provided CMake option or by defining XRLOADER_DISABLE_EXCEPTION_HANDLING. The only two reasons you may define this are:

In order to simplify the file management, especially with regards to loading JSON manifest files or finding dynamic library files, the experimental/filesystem is used. This is a set of features which are part of the upcoming C++17 feature set designed to make file management easier.

Since no compiler currently supports C++17, most have enabled a chunk of functionality using the "experimental" namespace. When used, you can find elements of this functionality with the prefix std::experimental::filesystem.

Identifiers in the OpenXR API (e.g. types, parameters, constants, etc.) all follow a set of naming rules, providing a consistent scheme for developers.

The Desktop OpenXR loader uses JSON manifest files for information about available API layers and runtimes. All the functionality for finding, parsing, and processing the various manifest file formats are found in the three manifest file classes: ManifestFile, RuntimeManifestFile, and ApiLayerManifestFile. All three classes are defined in the manifest_file header (.hpp) and source (.cpp) files.

ManifestFile is the base class containing the majority of common code. It only performs a minimal set of validation and provides accessor functions. These functions perform all the work using two primary sources:

RuntimeManifestFile is a derived class (with ManifestFile as the parent) which handles specifically finding and parsing any runtime manifest files. It implements a static function FindManifestFiles which is to be used as a factory method for finding all available runtime manifest files, creating an instance of RuntimeManifestFiles for each, and saving them if they appear to be valid. This is the command that any OpenXR command inside the loader should call if it requires a list of available runtime manifest files.

The RuntimeManifestFile also provides a utility function for creating an instance of itself if it determines everything is valid inside the JSON file. CreateIfValid not only validates the JSON format, but also verifies that the specific fields required by the RuntimeManifestFile class are available.

Similar to RuntimeManifestFile, ApiLayerManifestFile is a derived class (with ManifestFile as the parent). This class handles specifically finding and parsing any API layer manifest files. It also implements a static function FindManifestFiles which is to be used as a factory method for finding all available API layer manifest files, creating an instance of ApiLayerManifestFiles for each, and saving them if they appear to be valid. This is the command that any OpenXR command inside the loader should call if it requires a list of available API layer manifest files.

The ApiLayerManifestFile also provides a utility function for creating an instance of itself if it determines everything is valid inside the JSON file. CreateIfValid not only validates the JSON format, but also verifies that the specific fields required by the ApiLayerManifestFile class are available.

The OpenXR loader is responsible with interfacing with other libraries to complete its tasks. Typically, there will be some interface negotiation between these other libraries and the loader (see Loader/Layer Interface Negotiation or Loader/Runtime Interface Negotiation for more information). The Interface classes are responsible with using the contents of a ManifestFile to setup the interface. Each Interface class must be used with the appropriate ManifestFile type to properly interface with a specific type of library.

The RuntimeInterface is tasked with working with runtime libraries. Once the runtime manifest file information is found and parsed by the RuntimeManifestFile class, it is passed along to this class which will load the appropriate library and perform the required Loader/Runtime Interface Negotiation.

The RuntimeInterface implements a static function LoadRuntime which is to be used as a factory method for loading the current active runtime, performing the appropriate negotiation, and then creating an instance of RuntimeInterface. This is the command that any OpenXR command inside the loader should call if it requires loading the runtime. The command will only truly load the runtime library if it is not currently loaded, and then keep a reference count of how many requests to load it have been made.

Likewise, the RuntimeInterface implements a static function UnloadRuntime which is to be used to unload the current active runtime. This will reduce the reference count until it is 0 and then unload the active runtime library.

Finally, the RuntimeInterface implements a static function GetRuntime which is used to return the single instance of the RuntimeInterface class.

During XrInstance creation and destruction, the RuntimeInterface needs to work directly with the runtime library. To do this, the RuntimeInterface has two methods that are used by the OpenXR loader:

Once successful completion occurs, the RuntimeInterface will:

To destroy a runtime’s instance as part of the xrDestroyInstance command, the loader calls DestroyInstance;

Similarly, the ApiLayerInterface class is tasked with working with API layer libraries. Once the API layer manifest file information is found and parsed by the ApiLayerManifestFile class, it is passed along to this class which will load the appropriate library and perform the required Loader/Layer Interface Negotiation.

The ApiLayerInterface implements a static function LoadApiLayers which is to be used as a factory method for loading all available API layers, performing the appropriate negotiation, and then creating an instance of ApiLayerInterface for each. This is the command that any OpenXR command inside the loader should call if it requires load one or more API layers:

The primary OpenXR object is the XrInstance, and from that most other data is either queried or created.

A LoaderInstance is created during the OpenXR xrCreateInstance call, and destroyed during the xrDestroyInstance call. During xrCreateInstance the loader code calls LoaderInstance::CreateInstance factory method:

During the CreateInstance call, the loader will perform the following work:

Because the loader knows what runtime need to be called as part of the create sequence, it inserts a terminator during the xrCreateInstance sequence called loaderXrTermCreateInstance after the last API layer in order to create the runtime instance.

The LoaderLogger class was created to provide global logging capability to the OpenXR loader. It was implemented as a Singleton to reduce the overhead of passing pointers/references around to the various loader objects.

To get a reference to the LoaderLogger singleton, use the GetInstance method:

The LoaderLogger works by sending all received messages to various instances of <<loaderlogrecorder, LoaderLogRecorder> objects. To add a LoaderLogRecorder to the LoaderLogger, call AddLogRecorder:

Once added, general log messages will be passed to each of the LoaderLogRecorder stored in an internal vector. Any source inside of the loader may trigger a log message by using the LogMessage command:

Because of the complex nature of that method, and the fact that most log messages can be simplified, the OpenXR loader also supplies the following static methods for logging:

It’s important to note that these static methods also take care of grabbing the LoaderLogger::GetInstance() and making the appropriate call to LoaderLogger::LogMessage().

The LoaderLogRecorder is a base class that defines the basics used for recording a log message somewhere. LoaderLogRecorder provides no protections for multithreading logging. Any required protections should be implemented by the derived class that is multithread sensitive (i.e. if a logger wrote to a file).

The pure virtual method the base class defines that is used to record log messages is the LogMessage method. Each derived class is responsible for defining exactly how log messages are recorded.

Some utility methods that the LoaderLogRecorder base class supplies allow controls over whether or not log messages are actually recorded. Upon creation, a LoaderLogRecorder is set to actively record all messages that contain the appropriate flags. However, if we want to pause recording to one or more of the LoaderLogRecorders at some point and then resume recording again later, the following utilities can be used:

Currently, there are two private classes derived from LoaderLogRecorder, providing three basic behaviors:

The recorder created by MakeStdErrLoaderLogRecorder() handles recording all error messages that occur in the loader out to std::cerr. This logger is always enabled and is intended to always provide error messages for easier issue diagnosis.

The recorder created by MakeStdOutLoaderLogRecorder() records messages out to std::cout. This logger is enabled when the XR_LOADER_DEBUG environment variable is defined.

The recorder created by MakeDebugUtilsLoaderLogRecorder() triggers an XR_EXT_debug_utils callback every time a log message occurs. Two steps are required before the loader enables this class:

This C-style header contains the definition of the XrGeneratedDispatchTable structure. This structure can be used to store function pointers for any OpenXR commands defined in the xr.xml at the time the loader was built. It includes slots for both core and extension function pointers. Currently, the loader uses this structure as well as the provided API Layers.

A partial listing from the generated table follows:

You’ll notice that the xr prefix was dropped on the name of the elements within the structure to simplify naming as well as avoid any potential compilation conflicts.

The xr_generated_dispatch_table.h header also includes a utility function that can be used to populate a dispatch table once it has been created:

This file is paired with the above xr_generated_dispatch_table.h header and only implements the GeneratedXrPopulateDispatchTable function used to populate the elements of a dispatch table.

xr_loader_generated.hpp contains prototypes for all the manually defined instance command trampoline and terminator functions. This is done so that they can be referenced in the xr_loader_generated.cpp source file which is used for xrGetInstanceProcAddr as well as setting up the loader dispatch table.

The xr_loader_generated.cpp source file contains the implementation of all generated OpenXR trampoline functions.

The loader works with libraries and runtimes which are exposed as either a static or dynamic external library files. Each operating system provides their own utilities for interfacing with these files, which the loader abstracts. Most loader platform code can be found in the following source file:

The OpenXR loader uses a general handle define for all platform library functions. This handle is identified as LoaderPlatformLibraryHandle and is used to interact with all the platform-specific library functions.

To open a platform-specific library file, and therefore retrieve the platform-specific LoaderPlatformLibraryHandle relative to that file, the loader calls the LoaderPlatformLibraryOpen function which has the following prototype:

If the function succeeds, the returned value will be non-NULL. If a failure occurs during this call, the returned value will be NULL. In the case of failure, the loader can call the LoaderPlatformLibraryOpenError function:

The returned C-style character string contains any available platform-specific error code that may have occurred.

When the loader is done using the platform library, it calls LoaderPlatformLibraryClose to release it.

Once a library is opened, the loader will query for the important functions exported by a library using the LoaderPlatformLibraryGetProcAddr function:

If the function succeeds, the returned value will be a valid function pointer address. If the function fails, it will return NULL. A NULL return value could imply that the function simply isn’t exported by the library, or that an error occurred during the platform call. To determine what might have happened, the loader will call the LoaderPlatformLibraryGetProcAddrError function:

The returned C-style character string contains any available platform-specific error code that may have occurred.

Several environment variables are used in the OpenXR loader, especially on the Desktop (Windows/Linux). However, accessing environment variables is different based on each operating system, so we have added global interface functions to use for accessing environment variables. These are defined in src/common/platform_utils.hpp

NOTE: This is outside of the loader source to allow other items in the source folder to use these utilities.

To read an environment variable, the loader calls PlatformUtilsGetEnv:

If the environment variable identified by name exists on the system, the C-style NULL-terminated string will be returned. If the environment variable can not be found, an empty string is returned.

If you want to distinguish between an empty value and a variable not set at all, if the underlying platform distinguishes these cases, use PlatformUtilsGetEnvSet:

It returns true if the environment variable is set.

Access to certain environment variables needs to be done in a way that maintains operational security of the program. To read a secure environment variable, the loader calls PlatformUtilsGetSecureEnv:

If the platform supports secure environment variable reading, the appropriate method will be used. Otherwise, it will fall back to the standard PlatformUtilsGetEnv call.

Since the runtime file name can vary based on the supporting system, the command PlatformGetGlobalRuntimeFileName provides a quick mechanism for querying the name of the file.