Overview

PSVRTracker is a reference library for demonstrating orientation and position tracking of Sony's PSVR Head Mounted Display using Sony's PS4 Stereo Camera. All of the device management and tracking code lives in the PSVRService.dll. The client facing functions and data structures are declared in the C99 style header PSVRClient_CAPI.h.

The HMD and tracker calibration can be managed with with the PSVRConfigTool.exe. The config tool links against the PSVRService.dll and provides color filter calibration, stereo camera setup calibration, and HMD testing tools. You don't technically need to include the config tool in your project, but you will at a minimum need to provide a mechanism for setting the color filtering since the filter settings are unique to the users lighting environment.

The library also supports tracking using "Virtual Stereo Camera" setup using two PS3Eye cameras side by side. Similarly a "Virtual HMD" that allows for tracking of a set of lights without an HMD actually being connected to the PC. These are really only useful if you want to test tracking a homebrew HMD configuration.

PSVRTracker does not integrate with other VR systems itself. It's up to the other developers to create plugins that use the PSVRTracker Client API for other VR systems.

High Level PSVRTracker Organization

The PSVRTracker DLL can be broken down into the following major systems:

ServiceRequestHandler

This class handles incoming requests from the client API. These requests include operations like starting tracking for an HMD or adjusting tracking camera settings. It also keeps track of persistent state for requests (like which HMDs have an active data stream going to the client).

More details can be found in ServiceRequestHandler Programmer Notes

DeviceManager

This container class updates all of the specific device managers for the PSVRTracker DLL. It also is the front end for OS specific device queries.

More details can be found in DeviceManager Programmer Notes

TrackerManager

The TrackerManager class is responsible for managing all connected Sony tracking cameras that PSVRTracker DLL cares about (i.e. the PS4Camera). On a regular interval it polls all connected tracking cameras and extracts any tracking projections it can find. These tracking projections are used to compute an optical tracking pose for each controller.

More details can be found in TrackerManager Programmer Notes

HMDManager

The HMDManager class is responsible for managing all connected Sony Head Mounted displays that PSMoveService cares about (i.e. the PSVR). The HMD manager will add and remove HMD entries as new HMDs are add or removed from the system. Connected HMDs are polled regularly for IMU sensor data. The HMD manager will also compute an HMD pose using sensor fusion of the optical tracking pose with the IMU sensor data.

More details can be found in HMDManager Programmer Notes

USBDeviceManager

The USBDeviceManager acts as both a wrapper around other lower level USB APIs (LibUSB and WinUSB). It supports bulk, interrupt, control USB transfer requests manages by a separate worker thread. It also provides an interface for iterating over currently connected USB devices.

More details can be found in USBDeviceManager Programmer Notes

System Tree

PSVRTracker DLL
|-- ServiceRequestHandler
|   +-- PersistentRequestConnectionState
|       |-- Active Tracker Streams Bitmask
|       |-- Active HMD Stream Bitmask
|       |-- TrackerStreamInfo List
|       +-- HMDStreamInfo List
|-- DeviceManager
|   |-- DeviceManagerConfig
|   |-- IPlatformDeviceAPI
|   |   +-- PlatformDeviceAPIWin32
|   |-- TrackerManager
|   |   |-- TrackerManagerConfig
|   |   +-- ServerTrackerView List
|   |       +-- ITrackerInterface -> PS4CameraTracker
|   |       +-- ITrackerInterface -> VirtualStereoTracker
|   +-- HMDManager
|       |-- HMDManagerConfig
|       +-- ServerHMDView List
|           +-- IHMDInterface -> MorpheusHMD      
|           +-- IHMDInterface -> VirtualHMD      
+-- USBDeviceManager
    |-- USBManagerConfig
    |-- IUSBApi -> LibUSBApi | WinUSBApi | NullUSBApi
    |-- Lock Free Request Queue
    |-- Lock Free Result Queue
    +-- Worker Thread

Code Walkthroughs

PSVRTracker Update Walkthrough