OpenXR API Layer template

This repository contains the source project for a basic OpenXR API layer template that can be customized easily.

More about OpenXR and the OpenXR Loader.

Prerequisites:

• Visual Studio 2019 or above;
• NuGet package manager (installed via Visual Studio Installer);
• Python 3 interpreter (installed via Visual Studio Installer or externally available in your PATH).

Customization:

• Find documentation and tutorials on the wiki;
• Find the sample code from the tutorials in the example branches.

DISCLAIMER: This software is distributed as-is, without any warranties or conditions of any kind. Use at your own risks.

---

OpenXR Recenter Override

DISCLAIMER: This software is distributed as-is, without any warranties or conditions of any kind. Use at your own risks!

Version: 0.1.0

This document contains instructions on how to use OpenXR recenter override API layer.

Purpose of OpenXR recenter override

The position inside your cockpit you're in when running a sim in virtual reality is a crucial part in player immersion. Most VR-enabled games offer the possibility to recenter the in-game view on pressing a button, some even allow shifting the position afterwards. But both these possibilities are usually lacking the required precision to reproducibly line up a physical sim rig exactly with the virtual cockpit. OpenXR recenter override (OXRRO) project offers the means to adjust the neutral position on mm scale for translation and to a tenth of a degree on the yaw axis. You can also save your current neutral position in order to load and reuse it in upcoming sessions.

Limitations:

• The recenter override API Layer is made for Windows 64-bit only.
• The software (obviously) only works with VR/AR applications using an OpenXR runtime implementation.

Contact

On explicit user request you can also sponsor the project via GitHub Sponsors

Installation

Run installer executable

Just double click the installation executable called Install_OpenXR-RecenterOverride_<current_version>.exe and follow the instructions. A few hints regarding the installation process:

• Using a sub directory of program files as installation target is recommended, especially for compatibility with WMR based headsets.
• Although the installation needs administrative privileges make sure to run the installation executable using the windows account you're using to launch your games/Open XR applications. This enables the installer to put the configuration file(s) into the correct appdata directory.
• If something goes wrong on installation and you don't know what or why, you can check the log file Setup Log <yyyy-mm-dd xxx>.txt that is created in the %TEMP% folder.

Optional: Confirm correct installation

You can use the application OpenXR Explorer to verify the correct installation:

• Install OpenXR Explorer
• Connect your headset
• Start your corresponding VR runtime application (e.g. SteamVR, Oculus App, Mixed Reality Portal, Varjo Base, PiTool, etc.)
• Start OpenXR explorer
• Search for the section xrEnumerateApiLayerProperties (should be in the middle column at the bottom by default)
• Check if the entry XR_APILAYER_NOVENDOR_recenter_override with version v1 exists

Update

To get OXRRO updated, download and run the latest installation executable from Github. If you want to change the installation directory you have to uninstall the previous version first.

Uninstall

To remove the OpenXR-RecenterOverride layer just use windows settings/control panel as you would do with any other application. During de-installation you can choose to delete your configuration and log files in the appdata directory or to keep them for later use.

• If something goes wrong on de-installation and you don't know what or why, you can check the log file Uninstall Log <yyyy-mm-dd xxx>.txt that is created in the %TEMP% folder.

How to use

For initial setup, you need to do 4 things to be able to use OXRRO:

1. adapt configuration to your liking:
   The software needs to be able to execute a recenter view action, so you have to setup the keyboard shortcut according to the key (combination) you've set in the game. You can also modify the keyboard shortcuts used to interact with OXRRO, enable/disable audio feedback, or enable/disable automatic triggering of recenter action after modifying target position. For more details on the config file and how to use it have a look at the configuration section
2. setup target position: Note that for the default keyboard shortcuts to work num lock needs to be active on the keyboard.
   The target position is automatically loaded on game/VR startup. You can override the target position with your current hmd position by activating the capture shortcut. You can also move the target position in all 6 directions or rotate it around the yaw axis.
3. trigger centering of view using the oxrro shortcut:
   You can apply the target position using the apply shortcut (5 on the numblock by default). By default recentering is automatically triggered after moving, rotating, or "hmd-capturing" the target position.
   For technical reasons, the recenter action is triggered only after you released all keys of the corresponding shortcut.
4. save the target position:
   When you're satisfied with the target position, save it into the config file, so it can be loaded in upcoming sessions

Once the target position is set up, you just have to press the apply shortcut to apply the target position after loading into VR.

Configuration

Configuration files can be found at ...\Users\*<Your_Username>*\AppData\Local\OpenXR-RecenterOverride\. After initial installation this directory contains the default configuration file OpenXR-RecenterOverride.ini. You can make changes to that file to configure options you want to be the same for all OpenXR applications. Changes to the config file(s) are not reflected live in the software and require a manual reload (or even a restart of the application for some settings) Upon starting an OpenXR application with the API layer active for the first time, a configuration file named after the application is created in the same directory. You can use it to copy (partial) sections from the default configuration file whenever you want to make changes only for that application specifically.

Use of the Configuration file

What you can modify in a configuration file:

• general behavior of the software, e.g. using voice prompts, recentering after target manipulation
• keyboard output to trigger in-game view centering
• keyboard inputs (e.g. to apply target pose)
  Note that all keys and values in the configuration file(s) are case sensitive. That means all keyboard shortcuts must only contain capital letters, numbers and/or underscores

Sections in configuration file

• [startup]: modify OXRRO's behavior on application start, e.g. disable a specific feature by setting the corresponding key to 0.
  • enabled: you can disable all functionality globally or for a single application. Note that you cannot enable a single application if the software is disabled globally in the default config file. Modifying this setting requires an application restart.
  • audio_enabled: you can disable the voice prompts confirming activating a keyboard shortcut or signaling an error. Changing this value only requires a reload of configuration.
  • apply_on_manipulation: controls whether or not the new target position is directly applied after manipulating it (moving, rotating or capturing hmd position).
  • upside_down: turn in-game coordinate system upside down by rotating it 180 degrees around the 'forward' axis. Necessary for correct orientation of target position and manipulation in some games (automatically set for iRacing). Changing this value requires the VR session to be restarted.
• [output]: configure the shortcut used to interact with the game. Separate multiple keys by using + without any whitespaces in between
  • recenter: key combination used to trigger in-game view recenter, needs to match the game configuration
• [input]: change the key combinations used to interact with oxrro. Separate multiple keys by using + without any whitespaces in between
  • capture: set the target position to reflect the current hmd pose. Note that any rotation of the hmd on pitch or roll is ignored.
  • apply: apply the current target position
  • forward,back,up,down,right,left: move the target position in the according direction by 1mm
  • rotate_right,rotate_left: rotate the forward vector of the target position by 1/10th of a degree
  • fast_modifier: press/hold this key in addition to one of the 6 manipulation keys above to move/rotate 10mm or 1 degree respectively
  • toggle_overlay: not yet implemented
  • save_config: save target position into global config file
  • save_config_app: save target position into application specific config file
  • reload_config:
• [target]: holds the target position loaded at startup or configuration reload. Note that manual manipulation is not recommended!
  • x,y,z: hold the position within vr playspace
  • a,b,c,d: hold the values of the quaternion representing the forward vector orientation

Logging

The recenter override layers logs rudimentary information and errors in a text file located at ...\Users<Your_Username>\AppData\Local\OpenXR-RecenterOverride\OpenXR-RecenterOverride.log. After unexpected behavior or a crash you can check that file for abnormalities or error reports.

If you encounter repeatable bugs or crashes you can use the Windows Performance Recorder Profile (WPRP) trace-logging in combination with the configuration contained within scripts\Trace_OpenXR-RecenterOverride.wprp to create a more detailed protocol.

Trace-logging can become very useful to investigate user issues.

To capture a trace for the API layer:

• start the OpenXR application
• Open a command line prompt or powershell in administrator mode and in a folder where you have write permissions
• Begin recording a trace with the command: wpr -start "C:\Program Files\OpenXR-RecenterOverride\Trace_OpenXR-RecenterOverride.wprp" -filemode
• Leave that command prompt open
• Reproduce the crash/issue
• Back to the command prompt, finish the recording with: wpr -stop arbitrary_name_of_file.etl
• These files are highly compressible!

You can send the trace file to the developer or use an application such as Tabnalysis to inspect the content yourself.

List of keyboard bindings

To combine multiple keys for a single shortcut they need to be separated by '+' with no spaces in between the key descriptors.

List of supported shortcut key names:

Name	Key
SHIFT	shift key
CTRL	control key
ALT	alt key
LSHIFT	left shift key
RSHIFT	right shift key
LCTRL	left control key
RCTRL	right control key
LALT	left alt key
RALT	right alt key
0- 9	numerical key
A- Z	alphabetical key
BACKQUOTE	`~ key (US)
TAB	tabulator key
CAPS	caps lock key
PLUS	+ key (any country)
MINUS	- key (any country)
OPENBRACKET	[{ key (US)
CLOSEBRACKET	]} key (US)
SEMICOLON	;: key (US)
QUOTE	'" key (US)
BACKSLASH	\| key (US)
COMMA	, key (any country)
PERIOD	. key (any country)
SLASH	/? key (US)
BACK	backspace key
CLR	clear key
RETURN	return key
ESC	escape key
SPACE	space key
LEFT	cursor left key
UP	cursor up key
RIGHT	cursor right key
DOWN	cursor down key
INS	insert key
DEL	delete key
HOME	home key
END	end key
PGUP	page up key
PGDN	page down key
NUM0	0 key on NUM
NUM1	1 key on NUM
NUM2	2 key on NUM
NUM3	3 key on NUM
NUM4	4 key on NUM
NUM5	5 key on NUM
NUM6	6 key on NUM
NUM7	7 key on NUM
NUM8	8 key on NUM
NUM9	9 key on NUM
NUMLOCK	numlock key
NUMDIVIDE	/ key on NUM
NUMMULTIPLY	* key on NUM
NUMSUBTRACT	- key on NUM
NUMADD	+ key on NUM
NUMDECIMAL	. key on NUM
NUMSEPARATOR	separator key on NUM
F1	F1 key
F2	F2 key
F3	F3 key
F4	F4 key
F5	F5 key
F6	F6 key
F7	F7 key
F8	F8 key
F9	F9 key
F10	F10 key
F11	F11 key
F12	F12 key
PRTSC	print screen key
SCROLL	scroll lock key
PAUSE	pause key
SELECT	select key
PRINT	print key
HELP	help key
EXEC	execute key
GAMEPAD_A	A button on gamepad
GAMEPAD_B	B button on gamepad
GAMEPAD_X	X button on gamepad
GAMEPAD_Y	Y button on gamepad
GAMEPAD_RIGHT_SHOULDER	right shoulder button on gamepad
GAMEPAD_LEFT_SHOULDER	left shoulder button on gamepad
GAMEPAD_LEFT_TRIGGER	left trigger button on gamepad
GAMEPAD_RIGHT_TRIGGER	right trigger button on gamepad
GAMEPAD_DPAD_UP	digital pad up on gamepad
GAMEPAD_DPAD_DOWN	digital pad down on gamepad
GAMEPAD_DPAD_LEFT	digital pad left on gamepad
GAMEPAD_DPAD_RIGHT	digital pad right on gamepad
GAMEPAD_START	start button on gamepad
GAMEPAD_VIEW	view button on gamepad
GAMEPAD_LEFT_THUMBSTICK_BUTTON	left thumbstick pressed on gamepad
GAMEPAD_RIGHT_THUMBSTICK_BUTTON	right thumbstick pressed on gamepad
GAMEPAD_LEFT_THUMBSTICK_UP	left thumbstick up on gamepad
GAMEPAD_LEFT_THUMBSTICK_DOWN	left thumbstick down on gamepad
GAMEPAD_LEFT_THUMBSTICK_RIGHT	left thumbstick left on gamepad
GAMEPAD_LEFT_THUMBSTICK_LEFT	left thumbstick right on gamepad
GAMEPAD_RIGHT_THUMBSTICK_UP	right thumbstick up on gamepad
GAMEPAD_RIGHT_THUMBSTICK_DOWN	right thumbstick down on gamepad
GAMEPAD_RIGHT_THUMBSTICK_RIGHT	right thumbstick left on gamepad
GAMEPAD_RIGHT_THUMBSTICK_LEFT	right thumbstick right on gamepad