Configuration

Our OpenXR layer comes with a number of configurable options and feature flags to allow more fine control over the layer itself. This can leveraged in two ways, either through using a configuration file (recommended) or through the use of environment variables.

Use the buttons below to be taken to the desired section:

The OpenXR Logo

Once you've set up your preferred method of configuration the table below shows all the layer's configurable options. These same methods are also used to set any feature flags you may want to use.

Configuration File

All of the layer’s configurable options (including feature flags) can be set using key value pairs in JSON.

Note

This is the recommended way of setting any configurations, as this file is parsed every time an application using our layer is started. This differs to environment variables as these are only updated when you close and reopen your OpenXR program.

For example, if developing in Unity and using environment variables, you would be required to close and reopen Unity every time you made a configuration change. Where as with the configuration file this isn’t necessary.

Firstly, navigate to the appropriate path for your operating system below:

  • Windows:

    • %PROGRAMDATA%\Ultraleap\OpenXR

  • Linux:

    • System-wide: /etc/ultraleap

    • Per-user: ~/.config/ultraleap (Overrides System-wide configuration if present)

Then create a new file in that directory called api_layer_config.json and open it up.

Additions to the file should be done in a key-value pair format where the key is the configurable variable and the value is the desired setting:

{
  "CONFIG_KEY1_STRING": "HelloWorld",
  "CONFIG_KEY2_BOOL": false,
  "CONFIG_KEY3_VECTOR": [1,2,3]
}

Below is a simple example of the configuration file to get you started. It sets logging level to warn, and the tracker offset to 8cm forward from the midpoint of your interpupillary distance with no tilt:

{
  "log_level": "warn",
  "pos": [0, 0, -0.08],
  "tilt_angle": 0
}

Note

If you’re making use of both the configuration file and environment variables then environment variables override their configuration file counterpart.

If you run into a scenario where the configuration file isn’t working, double check your environment variables!

Note

JSON can be picky with its syntax and prone to mistakes, it’s always good practice to run your file through a JSON validator <https://jsonlint.com/> to ensure it is error-free.

More information regarding both of these configuration options, and all other possible additions to the configuration file can be found under the configuration and features sections.

Back to top

Environment Variables

Any of the configuration options can also be set using environment variables. If set, these override the values from the configuration file.

Note

These environment variables must be set prior to the OpenXR application starting, and if left unset first fall back to the configuration file settings and then default values failing that.

Environment variable keys for our layer are fully upper-case and prefixed with ULTRALEAP_OPENXR_.

For example, the key tilt_angle from tracker mounting’s equivalent environment variable is ULTRALEAP_OPENXR_TILT_ANGLE.

Note

The environment variable key-value pairs are the same on all platforms.

To see what options you can configure with environment variables check out the table above for configuration options or head over to the features page.

Back to top