Third-party tracking

Developing tracking plugin for Varjo 

In order to use third-party tracking system you need to use Varjo Tracking Plugin SDK available on the Downloads page.

Tracking Plugin API 

Before starting to implement tracking plugin support, please read through this page describing all the processes and functions that you access through the Varjo API.  

Following structure describes tracked device pose: 

typedef struct varjo_DevicePose { 
   varjo_Nanoseconds timeStamp;     //!< Pose timestamp (ns) 
   int64_t frameNo;                 //!< Frame number, increases monotonically. 
   varjo_Vector3D position;         //!< Device position (m) 
   varjo_Quaternion rotation;       //!< Device rotation 
   varjo_Vector3D velocity;         //!< Device linear velocity (m/s) 
   varjo_Vector3D angularVelocity;  //!< Device angular velocity (radians/s) 
   varjo_Vector3D acceleration;     //!< Device acceleration (m/s^2) 
   varjo_PoseFlags poseFlags;       //!< Bit field value describing pose 
   double confidence;               //!< Tracker confidence 
} varjo_DevicePose; 

 

The following definitions explain the types of data stored in the pose: 

struct varjo_Vector3D { 
    double x;  //!< X coordinate. 
    double y; //!< Y coordinate. 
    double z;  //!< Z coordinate. 
}; 

 

Tracker coordinates:

 struct varjo_Quaternion { 
    double w; 
    double x; 
    double y; 
    double z; 
}; 

 

Double precision quaternion for tracker rotation. 

 typedef int32_t varjo_Bool; 
 typedef int64_t varjo_Nanoseconds; 

 Time is in nanoseconds. Absolute times are relative to an epoch which is constant during execution of the program. 

 

Varjo Plugin API

Thfollowing scheme describes the flow of the Varjo Plugin API (the Plugin API is located below Varjo SW).

 

Tracking point location

Tracking point of the HMD is located between lenses, as shown in the diagrams below.

Coordinate system for HMD is right-handed, positive X goes right, positive Y goes up and negative Z goes forward from HMD user’s perspective.

In VR-1, XR-1 and VR-2 series HMDs the IMU is located (from HMD user’s perspective):

  • 0.5mm to the right, 13.4mm down and 57.2mm forward from the HMD tracking point;
  • IMU is oriented such that its positive X points right, positive Y points down and positive Z points forward.

 

Your tracking plugin can be initialized using varjo_PluginInit.

Use varjo_TrackerStart to begin tracker processing, and varjo_TrackerStop to end tracker processing.

In order to get the current tracker pose for HMD use varjo_GetHMDPose.

End the session with deinitialization of your tracking plugin using varjo_PluginShutdown.

 

Using tracking plugin

Tracking plugin installation

The plugin supplied by the tracking system vendor should be installed in the location specified by the vendor.

Tracking plugin registration and selection

You must create a file with a .manifest extension to register the plugin in Varjo software stack. It should be placed in <%ProgramData%\Varjo\VarjoTracking\Plugins\<vendor_name>\plugin.manifest>. The manifest file must contain following fields:

{
    "manifestFileVersion": "0.1.0.0",
    "ID": "{12345678-XXXX-YYYY-ZZZZ-123456789XYZ}",
    "vendorName": "vendorName",
    "productName": "productName",
    "path": "C:\\Program Files\\Folder\\plugin.dll"
}

The VarjoTracking process on start-up will enumerate all manifest files in the subdirectories of the %ProgramData%\Varjo\VarjoTracking\Plugins folder. All the manifests will be validated, and plugins that pass validation will communicate to Varjo software. VarjoBase will show all of the available tracking systems in the UI, and the user will be able to select the tracking system of their choice.

You can find functions that are affecting your tracking plugin behavior with Varjo API in varjo_PluginUtilityAPI.