Initial 1.0.0-beta release

CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## 1.0.0-beta
+
+### Added
+
+ - Initial support for the `XR_EXT_hand_tracking` extension
+
+### Known Issues
+
+ - This API layer does not currently report the linear or angular velocity of the hands.
+   If requested, the XrHandJointVelocitiesEXT structure will be returned with the validity bits unset.
+   [Issue #1](https://github.com/ultraleap/OpenXRHandTracking/issues/1)
+
+ - The underlying Ultraleap service currently return the same joint radius for all joints.
+   [Issue #2](https://github.com/ultraleap/OpenXRHandTracking/issues/2)
+
+ - `XrSystemHandTrackingPropertiesEXT.supportsHandTracking` will always return `XR_TRUE` when this API layer is enabled,
+   regardless of if a device is connected. `XrHandJointLocationsEXT.isActive` indicates if hand-tracking information is
+   currently available for the requested hand-tracker.
+   [Issue #3](https://github.com/ultraleap/OpenXRHandTracking/issues/3)
+
+ - The user's virtual hands may appear to move relative to the head when the head is moved quickly, even when the user's
+   hands are remaining still. This is due to the temporal warping settings and the fact that the hand position and view
+   position are updated at different rates.
+   [Issue #6](https://github.com/ultraleap/OpenXRHandTracking/issues/6)
+
+ - Unreal Engine 4.25 currently ships with version 1.0.0 of the OpenXR loader which has a
+   [known issue](https://github.com/KhronosGroup/OpenXR-SDK-Source/pull/91) which prevents OpenXR API layers from
+   functioning correctly. This will be resolved when Unreal Engine ships with a newer OpenXR loader, or the existing
+   OpenXR loader DLLs are manually updated.
+   [Issue #4](https://github.com/ultraleap/OpenXRHandTracking/issues/4)
+
+ - There is a known issue with the SteamVR OpenXR runtime 1.13.9
+   [not correctly honouring](https://steamcommunity.com/app/250820/discussions/8/2523653167130760453/)
+   the `XrSystemHandTrackingProperties` as an extension to the `xrGetSystemProperties` call.
+   This API layer includes a work-around that detects and corrects this behaviour.
+   [Issue #5](https://github.com/ultraleap/OpenXRHandTracking/issues/5)

LICENSE.md

@@ -0,0 +1,3 @@
+This Software is subject to the Ultraleap SDK License Agreement and is provided for the purpose of internal evaluation
+and demonstration only. The Ultraleap SDK License Agreement is available at
+https://central.leapmotion.com/agreements/SdkAgreement and are available from Ultraleap on request.

README.md

@@ -0,0 +1,114 @@
+# Ultraleap OpenXR Hand Tracking API Layer
+
+An implementation of the OpenXR `XR_EXT_hand_tracking` extension.
+
+This library is implemented as a OpenXR API layer named `XR_APILAYER_ULTRALEAP_hand_tracking`, which adds
+`XR_EXT_hand_tracking` support to an existing OpenXR runtime which may or may not already support it. If an existing
+runtime already supports `XR_EXT_hand_tracking`, this API layer takes precedence and overrides it.
+
+This API layer supports any Ultraleap or Leap Motion tracking devices supported by the existing
+[Leap Motion v4 Software](https://developer-archive.leapmotion.com/downloads/external/v4-developer-beta/windows), such
+as the [Leap Motion Controller](https://www.ultraleap.com/product/leap-motion-controller/).
+
+## Requirements
+
+### OpenXR Runtime
+
+You will require an OpenXR runtime to be installed to use this API layer. The correct runtime will depend on your
+platform and XR hardware, some of the most common platforms are listed below:
+
+ * [Microsoft Windows Mixed Reality](https://docs.microsoft.com/en-us/windows/mixed-reality/openxr-getting-started)
+ * [Valve SteamVR](https://store.steampowered.com/newshub/app/250820/view/2396425843528787269)
+ * [Oculus OpenXR](https://developer.oculus.com/documentation/native/pc/dg-openxr/)
+
+### Ultraleap Software
+
+You will require the current
+[Leap Motion v4 Software](https://developer-archive.leapmotion.com/downloads/external/v4-developer-beta/windows) to be
+installed to run any applications that use this API layer with OpenXR.
+
+## Downloading
+
+The latest version of this API layer can be installed from the
+[Releases](https://github.com/ultraleap/OpenXRHandTracking/releases) page.
+
+## Installing
+
+Once downloaded follow the following steps to install the API layer.
+
+ - Extract the downloaded `.zip`
+ - Right click the `Install.cmd` script and select "Run as administrator"
+ - Type "Yes" at the prompts accept the license agreement and to start the installation
+ - Wait for the installation to complete.
+
+You can verify that the installation has been successfully completed by installing the
+[Microsoft Mixed Reality OpenXR Developer Tools App](https://www.microsoft.com/store/productId/9n5cvvl23qbt) from the
+Microsoft Store. Once this is opened, navigate to the "System Status" tab, and you should see `XR_EXT_hand_tracking`
+listed in the Extensions section, and `XR_APILAYER_ULTRALEAP_hand_tracking` listed under the API Layers section.
+
+This method of verification has only been confirmed with the Windows Mixed Reality OpenXR runtime, but should work with
+others as well.
+
+## Setup
+
+The API layer will report hand-tracking as supported when this API layer is installed. To be able to actively use the
+hand tracking the following must all be true:
+
+ - Leap Motion v4 Software installed and running
+ - Ultraleap hand-tracking device attached and operating correctly
+ - User's hands visible to the Ultraleap hand-tracking device.
+
+## Configuration
+
+### Mounting, Position & Tilt
+
+The Ultraleap tracking device should be mounted on the front of your HMD in a suitable position, via a secure mounting
+method such as the [Ultraleap VR Developer Mount](https://www.ultraleap.com/product/vr-developer-mount/).
+
+The position of the Ultraleap tracking device, relative to your view position can be configured using the following
+environment variables (position relative to the interpupillary line).
+
+![Leap Mounting Diagram](https://developer.leapmotion.com/documentation/v4/HMD_Mounting.png)
+
+These environment variables must be set prior to the OpenXR application starting, if they are left unset,
+the default values (in brackets) are used:
+
+ - `ULTRALEAP_OPENXR_POS_X` - Position in X in meters (default: 0.0m)
+ - `ULTRALEAP_OPENXR_POS_Y` - Position in Y in meters (default: 0.0m)
+ - `ULTRALEAP_OPENXR_POS_Z` - Position in Z in meters (default: -0.08m/-8cm)
+ - `ULTRALEAP_OPENXR_TILT_ANGLE` - Tilt angle downwards in degrees from the forward facing horizontal (default 0)
+
+### Temporal Warping
+
+The position of the hands in the scene is interpolated to compensate for differences between the captured hand-tracking
+frame and the update time of the user's view. This is controlled by two variables:
+
+ - `ULTRALEAP_OPENXR_TIME_WARP_HAND` - +/- timestamp offset in milliseconds for the hand position (default: +10ms)
+ - `ULTRALEAP_OPENXR_TIME_WARP_VIEW` - +/- timestamp offset in milliseconds for the view position (default: -25ms)
+
+These parameters can be different for each different headset runtime and can be tuned appropriately. These can help
+stabilise the hand-position in space if the view position is moved rapidly.
+
+## Disabling the API layer
+
+If you wish to disable the API layer, this can be achieved by defining the
+`DISABLE_XR_APILAYER_ULTRALEAP_HAND_TRACKING_1` environment variable to any value.
+
+## Uninstalling
+
+You can remove the API layer by right clicking the included `Uninstall.cmd` script and selecting "Run as administrator".
+This will remove the installed files and registry keys.
+
+## Known issues
+
+Known issues in this release, as well as previously fixed issues are tracked in `CHANGELOG.md` included with this
+release.
+
+## Reporting issues
+
+If you encounter an issue with this release, please report it as an issue on our
+[GitHub project](https://github.com/ultraleap/OpenXRHandTracking/issues).
+
+## Licensing
+
+This project is licensed under the terms in `LICENSE.md` included with this release.