SDK 0.2.3

1 files changed, 619 insertions, 627 deletions

diff --git a/LibOVR/Src/OVR_Device.h b/LibOVR/Src/OVR_Device.h
index 4434916..72a8c5e 100644
--- a/LibOVR/Src/OVR_Device.h
+++ b/LibOVR/Src/OVR_Device.h
@@ -1,627 +1,619 @@
-/************************************************************************************

-

-PublicHeader:   OVR.h

-Filename    :   OVR_Device.h

-Content     :   Definition of HMD-related Device interfaces

-Created     :   September 21, 2012

-Authors     :   Michael Antonov

-

-Copyright   :   Copyright 2012 Oculus VR, Inc. All Rights reserved.

-

-Use of this software is subject to the terms of the Oculus license

-agreement provided at the time of installation or download, or which

-otherwise accompanies this software in either electronic or hard copy form.

-

-*************************************************************************************/

-

-#ifndef OVR_Device_h

-#define OVR_Device_h

-

-#include "OVR_DeviceConstants.h"

-#include "OVR_DeviceHandle.h"

-#include "OVR_DeviceMessages.h"

-#include "OVR_HIDDeviceBase.h"

-

-#include "Kernel/OVR_Atomic.h"

-#include "Kernel/OVR_RefCount.h"

-#include "Kernel/OVR_String.h"

-

-namespace OVR {

-

-class SensorDevice;

-class DeviceCommon;

-class DeviceManager;

-

-// MessageHandler is a base class from which users derive to receive messages,

-// its OnMessage handler will be called for messages once it is installed on

-// a device. Same message handler can be installed on multiple devices.

-class MessageHandler

-{

-    friend class MessageHandlerImpl;

-public:

-    MessageHandler();

-    virtual ~MessageHandler();

-

-    // Returns 'true' if handler is currently installed on any devices.

-    bool        IsHandlerInstalled() const;

-

-    // Should be called from derived class destructor to avoid handler

-    // being called after it exits.

-    void        RemoveHandlerFromDevices();

-

-    // Returns a pointer to the internal lock object that is locked by a

-    // background thread while OnMessage() is called.

-    // This lock guaranteed to survive until ~MessageHandler.

-    Lock*       GetHandlerLock() const;

-

-

-    virtual void OnMessage(const Message&) { }

-

-    // Determines if handler supports a specific message type. Can

-    // be used to filter out entire message groups. The result

-    // returned by this function shouldn't change after handler creation.

-    virtual bool SupportsMessageType(MessageType) const { return true; }    

-

-private:    

-    UPInt Internal[4];

-};

-

-

-//-------------------------------------------------------------------------------------

-// ***** DeviceBase

-

-// DeviceBase is the base class for all OVR Devices. It provides the following basic

-// functionality:

-//   - Reports device type, manager, and associated parent (if any).

-//   - Supports installable message handlers, which are notified of device events.

-//   - Device objects are created through DeviceHandle::CreateDevice or more commonly

-//     through DeviceEnumerator<>::CreateDevice.

-//   - Created devices are reference counted, starting with RefCount of 1.

-//   - Device is resources are cleaned up when it is Released, although its handles

-//     may survive longer if referenced.

-

-class DeviceBase : public NewOverrideBase

-{    

-    friend class DeviceHandle;  

-    friend class DeviceManagerImpl;

-public:

-

-    // Enumerating DeviceBase enumerates all devices.

-    enum { EnumDeviceType = Device_All };

-

-    virtual ~DeviceBase() { }

-    virtual void            AddRef();

-    virtual void            Release();

-    

-    virtual DeviceBase*     GetParent() const;

-    virtual DeviceManager*  GetManager() const;  

-

-    virtual void            SetMessageHandler(MessageHandler* handler);

-    virtual MessageHandler* GetMessageHandler() const;

-

-    virtual DeviceType      GetType() const;

-    virtual bool            GetDeviceInfo(DeviceInfo* info) const;

-

-    // returns the MessageHandler's lock

-    Lock*                   GetHandlerLock() const;

-protected:

-    // Internal

-    virtual DeviceCommon*   getDeviceCommon() const = 0;

-};

-

-

-//-------------------------------------------------------------------------------------

-// ***** DeviceInfo

-

-// DeviceInfo describes a device and its capabilities, obtained by calling

-// GetDeviceInfo. This base class only contains device-independent functionality;

-// users will normally use a derived HMDInfo or SensorInfo classes for more

-// extensive device info.

-

-class DeviceInfo

-{

-public:

-    DeviceInfo() : InfoClassType(Device_None), Type(Device_None), Version(0)

-    {  ProductName[0] = Manufacturer[0] = 0; }

-

-    enum { MaxNameLength = 32 };

-    

-    // Type of device for which DeviceInfo is intended.

-    // This will be set to Device_HMD for HMDInfo structure, note that this may be

-    // different form the actual device type since (Device_None) is valid.

-    const DeviceType InfoClassType;

-    // Type of device this describes. This must be the same as InfoClassType when

-    // InfoClassType != Device_None.

-    DeviceType       Type;

-    // Name string describing the product: "Oculus Rift DK1", etc.

-    char             ProductName[MaxNameLength];    

-    char             Manufacturer[MaxNameLength];

-    unsigned         Version;

-    

-protected:

-    DeviceInfo(DeviceType type) : InfoClassType(type), Type(type), Version(0)

-    { ProductName[0] = Manufacturer[0] = 0; }

-    void operator = (const DeviceInfo&) { OVR_ASSERT(0); } // Assignment not allowed.

-};

-

-

-//-------------------------------------------------------------------------------------

-// DeviceEnumerationArgs provides device enumeration argumenrs for DeviceManager::EnumerateDevicesEx.

-class DeviceEnumerationArgs

-{

-public:

-    DeviceEnumerationArgs(DeviceType enumType, bool availableOnly)

-        : EnumType(enumType), AvailableOnly(availableOnly)

-    { }

-

-    // Helper; returns true if args match our enumeration criteria.

-    bool         MatchRule(DeviceType type, bool available) const

-    {

-        return ((EnumType == type) || (EnumType == Device_All)) &&

-                (available || !AvailableOnly);

-    }

-

-protected:    

-    DeviceType   EnumType;

-    bool         AvailableOnly;

-};

-

-

-// DeviceEnumerator<> is used to enumerate and create devices of specified class,

-// it is returned by calling MeviceManager::EnumerateDevices. Initially, the enumerator will

-// refer to the first device of specified type. Additional devices can be accessed by

-// calling Next().

-

-template<class T = DeviceBase>

-class DeviceEnumerator : public DeviceHandle

-{

-    friend class DeviceManager;

-    friend class DeviceManagerImpl;

-public:

-    DeviceEnumerator()

-        : DeviceHandle(), EnumArgs(Device_None, true) { }

-

-    // Next advances enumeration to the next device that first criteria.

-    // Returns false if no more devices exist that match enumeration criteria.

-    bool    Next()          { return enumerateNext(EnumArgs); }

-

-    // Creates an instance of the device referenced by enumerator; returns null

-    // if enumerator does not refer to a valid device or device is unavailable.

-    // If device was already created, the same object with incremented ref-count is returned.

-    T*      CreateDevice()  { return static_cast<T*>(DeviceHandle::CreateDevice()); }

-

-protected:

-    DeviceEnumerator(const DeviceHandle &dev, const DeviceEnumerationArgs& args)

-        : DeviceHandle(dev), EnumArgs(args)

-    { }

-

-    DeviceEnumerationArgs EnumArgs;

-};

-

-//-------------------------------------------------------------------------------------

-// ***** DeviceManager

-

-// DeviceManager maintains and provides access to devices supported by OVR, such as

-// HMDs and sensors. A single instance of DeviceManager is normally created at

-// program startup, allowing devices to be enumerated and created. DeviceManager is

-// reference counted and is AddRefed by its created child devices, causing it to

-// always be the last object that is released.

-//

-// Install MessageHandler on DeviceManager to detect when devices are inserted or removed.

-//

-// The following code will create the manager and its first available HMDDevice,

-// and then release it when not needed:

-//

-//  DeviceManager* manager = DeviceManager::Create();

-//  HMDDevice*     hmd = manager->EnumerateDevices<HMDDevice>().CreateDevice();

-//

-//  if (hmd) hmd->Release();

-//  if (manager) manager->Release();

-

-

-class DeviceManager : public DeviceBase

-{

-public:

-  

-    DeviceManager()

-    { }

-

-    // DeviceBase implementation.

-    virtual DeviceType      GetType() const     { return Device_Manager; }

-    virtual DeviceManager*  GetManager() const  { return const_cast<DeviceManager*>(this); }

-

-

-    // EnumerateDevices enumerates all of the available devices of the specified class,

-    // returning an enumerator that references the first device. An empty enumerator is

-    // returned if no devices are available. The following APIs are exposed through

-    // DeviceEnumerator:

-    //   DeviceEnumerator::GetType()        - Check device type. Returns Device_None 

-    //                                        if no device was found/pointed to.

-    //   DeviceEnumerator::GetDeviceInfo()  - Get more information on device.

-    //   DeviceEnumerator::CreateDevice()   - Create an instance of device.

-    //   DeviceEnumerator::Next()           - Move onto next device.

-    template<class D>

-    DeviceEnumerator<D>     EnumerateDevices(bool availableOnly = true)

-    {

-        // TBD: A cleaner (but less efficient) alternative is though enumeratorFromHandle.

-        DeviceEnumerator<> e = EnumerateDevicesEx(DeviceEnumerationArgs((DeviceType)D::EnumDeviceType, availableOnly));

-        return *reinterpret_cast<DeviceEnumerator<D>*>(&e);

-    }

-  

-    // EnumerateDevicesEx provides internal implementation for device enumeration, enumerating

-    // devices based on dynamically specified DeviceType in DeviceEnumerationArgs.

-    // End users should call DeumerateDevices<>() instead.

-    virtual DeviceEnumerator<> EnumerateDevicesEx(const DeviceEnumerationArgs& args) = 0;

-

-    // Adds a device (DeviceCreateDesc*) into Devices. Returns NULL, 

-    // if unsuccessful or device is already in the list.

-    virtual Ptr<DeviceCreateDesc> AddDevice_NeedsLock(const DeviceCreateDesc& createDesc) = 0;

-

-    // Creates a new DeviceManager. Only one instance of DeviceManager should be created at a time.

-    static   DeviceManager* Create();

-

-    // Static constant for this device type, used in template cast type checks.

-    enum { EnumDeviceType = Device_Manager };

-

-protected:

-    DeviceEnumerator<> enumeratorFromHandle(const DeviceHandle& h, const DeviceEnumerationArgs& args)

-    { return DeviceEnumerator<>(h, args); }

-

-    DeviceManager* getThis() { return this; }

-};

-

-

-

-//-------------------------------------------------------------------------------------

-// ***** HMDInfo 

-

-// This structure describes various aspects of the HMD allowing us to configure rendering.

-//

-//  Currently included data:

-//   - Physical screen dimensions, resolution, and eye distances.

-//     (some of these will be configurable with a tool in the future).

-//     These arguments allow us to properly setup projection across HMDs.

-//   - DisplayDeviceName for identifying HMD screen; system-specific interpretation.

-//

-// TBD:

-//  - Power on/ off?

-//  - Sensor rates and capabilities

-//  - Distortion radius/variables    

-//  - Screen update frequency

-//  - Distortion needed flag

-//  - Update modes:

-//      Set update mode: Stereo (both sides together), mono (same in both eyes),

-//                       Alternating, Alternating scan-lines.

-

-class HMDInfo : public DeviceInfo

-{

-public:

-    // Size of the entire screen, in pixels.

-    unsigned  HResolution, VResolution; 

-    // Physical dimensions of the active screen in meters. Can be used to calculate

-    // projection center while considering IPD.

-    float     HScreenSize, VScreenSize;

-    // Physical offset from the top of the screen to the eye center, in meters.

-    // This will usually, but not necessarily be half of VScreenSize.

-    float     VScreenCenter;

-    // Distance from the eye to screen surface, in meters.

-    // Useful for calculating FOV and projection.

-    float     EyeToScreenDistance;

-    // Distance between physical lens centers useful for calculating distortion center.

-    float     LensSeparationDistance;

-    // Configured distance between the user's eye centers, in meters. Defaults to 0.064.

-    float     InterpupillaryDistance;

-    

-    // Radial distortion correction coefficients.

-    // The distortion assumes that the input texture coordinates will be scaled

-    // by the following equation:    

-    //   uvResult = uvInput * (K0 + K1 * uvLength^2 + K2 * uvLength^4)

-    // Where uvInput is the UV vector from the center of distortion in direction

-    // of the mapped pixel, uvLength is the magnitude of that vector, and uvResult

-    // the corresponding location after distortion.

-    float     DistortionK[4];

-

-    float     ChromaAbCorrection[4];

-

-    // Desktop coordinate position of the screen (can be negative; may not be present on all platforms)

-    int       DesktopX, DesktopY;

-    

-    // Windows:

-    // "\\\\.\\DISPLAY3", etc. Can be used in EnumDisplaySettings/CreateDC.

-    char      DisplayDeviceName[32];

-    

-    // MacOS:

-    long      DisplayId;

-

-

-    HMDInfo()

-        : DeviceInfo(Device_HMD),          

-          HResolution(0), VResolution(0), HScreenSize(0), VScreenSize(0),

-          VScreenCenter(0), EyeToScreenDistance(0),

-          LensSeparationDistance(0), InterpupillaryDistance(0),

-          DesktopX(0), DesktopY(0), DisplayId(0)

-    {

-        DisplayDeviceName[0] = 0;

-        memset(DistortionK, 0, sizeof(DistortionK));

-        DistortionK[0] = 1;

-        ChromaAbCorrection[0] = ChromaAbCorrection[2] = 1;

-        ChromaAbCorrection[1] = ChromaAbCorrection[3] = 0;

-    }

-

-    // Operator = copies local fields only (base class must be correct already)

-    void operator = (const HMDInfo& src)

-    {        

-        HResolution             = src.HResolution;

-        VResolution             = src.VResolution;

-        HScreenSize             = src.HScreenSize;

-        VScreenSize             = src.VScreenSize;

-        VScreenCenter           = src.VScreenCenter;

-        EyeToScreenDistance     = src.EyeToScreenDistance;

-        LensSeparationDistance  = src.LensSeparationDistance;

-        InterpupillaryDistance  = src.InterpupillaryDistance;

-        DistortionK[0]          = src.DistortionK[0];

-        DistortionK[1]          = src.DistortionK[1];

-        DistortionK[2]          = src.DistortionK[2];

-        DistortionK[3]          = src.DistortionK[3];

-        ChromaAbCorrection[0]   = src.ChromaAbCorrection[0];

-        ChromaAbCorrection[1]   = src.ChromaAbCorrection[1];

-        ChromaAbCorrection[2]   = src.ChromaAbCorrection[2];

-        ChromaAbCorrection[3]   = src.ChromaAbCorrection[3];

-        DesktopX                = src.DesktopX;

-        DesktopY                = src.DesktopY;

-        memcpy(DisplayDeviceName, src.DisplayDeviceName, sizeof(DisplayDeviceName));

-        DisplayId               = src.DisplayId;

-    }

-

-    bool IsSameDisplay(const HMDInfo& o) const

-    {

-        return DisplayId == o.DisplayId &&

-               String::CompareNoCase(DisplayDeviceName, 

-                                     o.DisplayDeviceName) == 0;

-    }

-

-};

-

-

-// HMDDevice represents an Oculus HMD device unit. An instance of this class

-// is typically created from the DeviceManager.

-//  After HMD device is created, we its sensor data can be obtained by 

-//  first creating a Sensor object and then.

-

-//  TBD:

-//  - Configure Sensor

-//  - APIs to set On-Screen message, other states?

-

-class HMDDevice : public DeviceBase

-{

-public:

-    HMDDevice()

-    { }

-

-    // Static constant for this device type, used in template cast type checks.

-    enum { EnumDeviceType = Device_HMD };

-

-    virtual DeviceType      GetType() const   { return Device_HMD; }    

-

-    // Creates a sensor associated with this HMD.

-    virtual SensorDevice*   GetSensor() = 0;

-

-    // Disconnects from real HMD device. This HMDDevice remains as 'fake' HMD.

-    // SensorDevice ptr is used to restore the 'fake' HMD (can be NULL).

-    HMDDevice* Disconnect(SensorDevice*);

-    

-    // Returns 'true' if HMD device is a 'fake' HMD (was created this way or 

-    // 'Disconnect' method was called).

-    bool IsDisconnected() const;

-};

-

-

-//-------------------------------------------------------------------------------------

-// ***** SensorRange & SensorInfo

-

-// SensorRange specifies maximum value ranges that SensorDevice hardware is configured

-// to detect. Although this range doesn't affect the scale of MessageBodyFrame values,

-// physical motions whose positive or negative magnitude is outside the specified range

-// may get clamped or misreported. Setting lower values may result in higher precision

-// tracking.

-struct SensorRange

-{

-    SensorRange(float maxAcceleration = 0.0f, float maxRotationRate = 0.0f,

-                float maxMagneticField = 0.0f)

-        : MaxAcceleration(maxAcceleration), MaxRotationRate(maxRotationRate),

-          MaxMagneticField(maxMagneticField)

-    { }

-

-    // Maximum detected acceleration in m/s^2. Up to 8*G equivalent support guaranteed,

-    // where G is ~9.81 m/s^2.

-    // Oculus DK1 HW has thresholds near: 2, 4 (default), 8, 16 G.

-    float   MaxAcceleration;  

-    // Maximum detected angular velocity in rad/s. Up to 8*Pi support guaranteed.

-    // Oculus DK1 HW thresholds near: 1, 2, 4, 8 Pi (default).

-    float   MaxRotationRate;

-    // Maximum detectable Magnetic field strength in Gauss. Up to 2.5 Gauss support guaranteed.

-    // Oculus DK1 HW thresholds near: 0.88, 1.3, 1.9, 2.5 gauss.

-    float   MaxMagneticField;

-};

-

-// SensorInfo describes capabilities of the sensor device.

-class SensorInfo : public DeviceInfo

-{

-public:

-    SensorInfo() : DeviceInfo(Device_Sensor), VendorId(0), ProductId(0)

-    {

-        SerialNumber[0] = 0;

-    }

-

-    // HID Vendor and ProductId of the device.

-    UInt16      VendorId;

-    UInt16      ProductId;

-    // MaxRanges report maximum sensor range values supported by HW.

-    SensorRange MaxRanges;

-    // Sensor (and display) serial number.

-    char        SerialNumber[20];

-

-private:

-    void operator = (const SensorInfo&) { OVR_ASSERT(0); } // Assignment not allowed.

-};

-

-

-//-------------------------------------------------------------------------------------

-// ***** SensorDevice

-

-// SensorDevice is an interface to sensor data.

-// Install a MessageHandler of SensorDevice instance to receive MessageBodyFrame

-// notifications.

-//

-// TBD: Add Polling API? More HID interfaces?

-

-class SensorDevice : public HIDDeviceBase, public DeviceBase

-{

-public:

-    SensorDevice() 

-    { }

-

-    // Static constant for this device type, used in template cast type checks.

-    enum { EnumDeviceType = Device_Sensor };

-

-    virtual DeviceType GetType() const   { return Device_Sensor; }

-

-    

-    // CoordinateFrame defines whether messages come in the coordinate frame

-    // of the sensor device or HMD, which has a different internal sensor.

-    // Sensors obtained form the HMD will automatically use HMD coordinates.

-    enum CoordinateFrame

-    {

-        Coord_Sensor = 0,

-        Coord_HMD    = 1

-    };

-

-    virtual void            SetCoordinateFrame(CoordinateFrame coordframe) = 0;

-    virtual CoordinateFrame GetCoordinateFrame() const = 0;

-

-    // Sets report rate (in Hz) of MessageBodyFrame messages (delivered through MessageHandler::OnMessage call). 

-    // Currently supported maximum rate is 1000Hz. If the rate is set to 500 or 333 Hz then OnMessage will be 

-    // called twice or thrice at the same 'tick'. 

-    // If the rate is  < 333 then the OnMessage / MessageBodyFrame will be called three

-    // times for each 'tick': the first call will contain averaged values, the second

-    // and third calls will provide with most recent two recorded samples.

-    virtual void        SetReportRate(unsigned rateHz) = 0;

-    // Returns currently set report rate, in Hz. If 0 - error occurred.

-    // Note, this value may be different from the one provided for SetReportRate. The return

-    // value will contain the actual rate.

-    virtual unsigned    GetReportRate() const = 0;

-

-    // Sets maximum range settings for the sensor described by SensorRange.    

-    // The function will fail if you try to pass values outside Maximum supported

-    // by the HW, as described by SensorInfo.

-    // Pass waitFlag == true to wait for command completion. For waitFlag == true,

-    // returns true if the range was applied successfully (no HW error).

-    // For waitFlag = false, return 'true' means that command was enqueued successfully.

-    virtual bool       SetRange(const SensorRange& range, bool waitFlag = false) = 0;

-

-    // Return the current sensor range settings for the device. These may not exactly

-    // match the values applied through SetRange.

-    virtual void       GetRange(SensorRange* range) const = 0;

-};

-

-//-------------------------------------------------------------------------------------

-// ***** LatencyTestConfiguration

-// LatencyTestConfiguration specifies configuration information for the Oculus Latency Tester device.

-struct LatencyTestConfiguration

-{

-    LatencyTestConfiguration(const Color& threshold, bool sendSamples = false)

-        : Threshold(threshold), SendSamples(sendSamples) 

-    {

-    }

-

-    // The color threshold for triggering a detected display change.

-    Color    Threshold;

-    // Flag specifying whether we wish to receive a stream of color values from the sensor.

-    bool        SendSamples;

-};

-

-//-------------------------------------------------------------------------------------

-// ***** LatencyTestCalibrate

-// LatencyTestCalibrate specifies colors used for Latency Tester calibration.

-struct LatencyTestCalibrate

-{

-    LatencyTestCalibrate(const Color& value)

-        : Value(value)

-    {

-    }

-

-    // The color being calibrated to.

-    Color   Value;

-};

-

-//-------------------------------------------------------------------------------------

-// ***** LatencyTestStartTest

-// LatencyTestStartTest specifies values used when starting the Latency Tester test.

-struct LatencyTestStartTest

-{

-    LatencyTestStartTest(const Color& targetValue)

-        : TargetValue(targetValue)

-    {

-    }

-

-    // The color value that the display is being set to.

-    Color    TargetValue;

-};

-

-//-------------------------------------------------------------------------------------

-// ***** LatencyTestDisplay

-// LatencyTestDisplay sets the mode and contents of the Latency Tester LED display.

-// See the 'Latency Tester Specification' document for more details.

-struct LatencyTestDisplay

-{

-    LatencyTestDisplay(UByte mode, UInt32 value)

-        : Mode(mode), Value(value)

-    {

-    }

-

-    UByte       Mode;       // The display mode that we wish to select.

-    UInt32      Value;      // The value to display.

-};

-

-//-------------------------------------------------------------------------------------

-// ***** LatencyTestDevice

-

-// LatencyTestDevice provides an interface to the Oculus Latency Tester which is used to test 'motion to photon' latency.

-class LatencyTestDevice : public HIDDeviceBase, public DeviceBase

-{

-public:

-    LatencyTestDevice()

-    { }

-

-    // Static constant for this device type, used in template cast type checks.

-    enum { EnumDeviceType = Device_LatencyTester };

-

-    virtual DeviceType GetType() const { return Device_LatencyTester; }

-

-    // Specifies configuration information including the threshold for triggering a detected color change,

-    // and a flag to enable a stream of sensor values (typically used for debugging).

-    virtual bool SetConfiguration(const LatencyTestConfiguration& configuration, bool waitFlag = false) = 0;

-

-    // Get configuration information from device.

-    virtual bool GetConfiguration(LatencyTestConfiguration* configuration) = 0;

-

-    // Used to calibrate the latency tester at the start of a test. Calibration information is lost

-    // when power is removed from the device.

-    virtual bool SetCalibrate(const LatencyTestCalibrate& calibrate, bool waitFlag = false) = 0;

-

-    // Get calibration information from device.

-    virtual bool GetCalibrate(LatencyTestCalibrate* calibrate) = 0;

-

-    // Triggers the start of a measurement. This starts the millisecond timer on the device and 

-    // causes it to respond with the 'MessageLatencyTestStarted' message.

-    virtual bool SetStartTest(const LatencyTestStartTest& start, bool waitFlag = false) = 0;

-

-    // Used to set the value displayed on the LED display panel.

-    virtual bool SetDisplay(const LatencyTestDisplay& display, bool waitFlag = false) = 0;

-

-    virtual DeviceBase* GetDevice() { return this; }

-};

-

-} // namespace OVR

-

-#endif

+/************************************************************************************
+
+PublicHeader:   OVR.h
+Filename    :   OVR_Device.h
+Content     :   Definition of HMD-related Device interfaces
+Created     :   September 21, 2012
+Authors     :   Michael Antonov
+
+Copyright   :   Copyright 2012 Oculus VR, Inc. All Rights reserved.
+
+Use of this software is subject to the terms of the Oculus license
+agreement provided at the time of installation or download, or which
+otherwise accompanies this software in either electronic or hard copy form.
+
+*************************************************************************************/
+
+#ifndef OVR_Device_h
+#define OVR_Device_h
+
+#include "OVR_DeviceConstants.h"
+#include "OVR_DeviceHandle.h"
+#include "OVR_DeviceMessages.h"
+#include "OVR_HIDDeviceBase.h"
+
+#include "Kernel/OVR_Atomic.h"
+#include "Kernel/OVR_RefCount.h"
+#include "Kernel/OVR_String.h"
+
+namespace OVR {
+
+// Declared externally
+class Profile;
+class ProfileManager; // << Should be renamed for consistency
+
+// Forward declarations
+class SensorDevice;
+class DeviceCommon;
+class DeviceManager;
+
+// MessageHandler is a base class from which users derive to receive messages,
+// its OnMessage handler will be called for messages once it is installed on
+// a device. Same message handler can be installed on multiple devices.
+class MessageHandler
+{
+    friend class MessageHandlerImpl;
+public:
+    MessageHandler();
+    virtual ~MessageHandler();
+
+    // Returns 'true' if handler is currently installed on any devices.
+    bool        IsHandlerInstalled() const;
+
+    // Should be called from derived class destructor to avoid handler
+    // being called after it exits.
+    void        RemoveHandlerFromDevices();
+
+    // Returns a pointer to the internal lock object that is locked by a
+    // background thread while OnMessage() is called.
+    // This lock guaranteed to survive until ~MessageHandler.
+    Lock*       GetHandlerLock() const;
+
+
+    virtual void OnMessage(const Message&) { }
+
+    // Determines if handler supports a specific message type. Can
+    // be used to filter out entire message groups. The result
+    // returned by this function shouldn't change after handler creation.
+    virtual bool SupportsMessageType(MessageType) const { return true; }    
+
+private:    
+    UPInt Internal[4];
+};
+
+
+//-------------------------------------------------------------------------------------
+// ***** DeviceBase
+
+// DeviceBase is the base class for all OVR Devices. It provides the following basic
+// functionality:
+//   - Reports device type, manager, and associated parent (if any).
+//   - Supports installable message handlers, which are notified of device events.
+//   - Device objects are created through DeviceHandle::CreateDevice or more commonly
+//     through DeviceEnumerator<>::CreateDevice.
+//   - Created devices are reference counted, starting with RefCount of 1.
+//   - Device is resources are cleaned up when it is Released, although its handles
+//     may survive longer if referenced.
+
+class DeviceBase : public NewOverrideBase
+{    
+    friend class DeviceHandle;  
+    friend class DeviceManagerImpl;
+public:
+
+    // Enumerating DeviceBase enumerates all devices.
+    enum { EnumDeviceType = Device_All };
+
+    virtual ~DeviceBase() { }
+    virtual void            AddRef();
+    virtual void            Release();
+    
+    virtual DeviceBase*     GetParent() const;
+    virtual DeviceManager*  GetManager() const;  
+
+    virtual void            SetMessageHandler(MessageHandler* handler);
+    virtual MessageHandler* GetMessageHandler() const;
+
+    virtual DeviceType      GetType() const;
+    virtual bool            GetDeviceInfo(DeviceInfo* info) const;
+
+    // returns the MessageHandler's lock
+    Lock*                   GetHandlerLock() const;
+protected:
+    // Internal
+    virtual DeviceCommon*   getDeviceCommon() const = 0;
+};
+
+
+//-------------------------------------------------------------------------------------
+// ***** DeviceInfo
+
+// DeviceInfo describes a device and its capabilities, obtained by calling
+// GetDeviceInfo. This base class only contains device-independent functionality;
+// users will normally use a derived HMDInfo or SensorInfo classes for more
+// extensive device info.
+
+class DeviceInfo
+{
+public:
+    DeviceInfo() : InfoClassType(Device_None), Type(Device_None), Version(0)
+    {  ProductName[0] = Manufacturer[0] = 0; }
+
+    enum { MaxNameLength = 32 };
+    
+    // Type of device for which DeviceInfo is intended.
+    // This will be set to Device_HMD for HMDInfo structure, note that this may be
+    // different form the actual device type since (Device_None) is valid.
+    const DeviceType InfoClassType;
+    // Type of device this describes. This must be the same as InfoClassType when
+    // InfoClassType != Device_None.
+    DeviceType       Type;
+    // Name string describing the product: "Oculus Rift DK1", etc.
+    char             ProductName[MaxNameLength];    
+    char             Manufacturer[MaxNameLength];
+    unsigned         Version;
+    
+protected:
+    DeviceInfo(DeviceType type) : InfoClassType(type), Type(type), Version(0)
+    { ProductName[0] = Manufacturer[0] = 0; }
+    void operator = (const DeviceInfo&) { OVR_ASSERT(0); } // Assignment not allowed.
+};
+
+
+//-------------------------------------------------------------------------------------
+// DeviceEnumerationArgs provides device enumeration argumenrs for DeviceManager::EnumerateDevicesEx.
+class DeviceEnumerationArgs
+{
+public:
+    DeviceEnumerationArgs(DeviceType enumType, bool availableOnly)
+        : EnumType(enumType), AvailableOnly(availableOnly)
+    { }
+
+    // Helper; returns true if args match our enumeration criteria.
+    bool         MatchRule(DeviceType type, bool available) const
+    {
+        return ((EnumType == type) || (EnumType == Device_All)) &&
+                (available || !AvailableOnly);
+    }
+
+protected:    
+    DeviceType   EnumType;
+    bool         AvailableOnly;
+};
+
+
+// DeviceEnumerator<> is used to enumerate and create devices of specified class,
+// it is returned by calling MeviceManager::EnumerateDevices. Initially, the enumerator will
+// refer to the first device of specified type. Additional devices can be accessed by
+// calling Next().
+
+template<class T = DeviceBase>
+class DeviceEnumerator : public DeviceHandle
+{
+    friend class DeviceManager;
+    friend class DeviceManagerImpl;
+public:
+    DeviceEnumerator()
+        : DeviceHandle(), EnumArgs(Device_None, true) { }
+
+    // Next advances enumeration to the next device that first criteria.
+    // Returns false if no more devices exist that match enumeration criteria.
+    bool    Next()          { return enumerateNext(EnumArgs); }
+
+    // Creates an instance of the device referenced by enumerator; returns null
+    // if enumerator does not refer to a valid device or device is unavailable.
+    // If device was already created, the same object with incremented ref-count is returned.
+    T*      CreateDevice()  { return static_cast<T*>(DeviceHandle::CreateDevice()); }
+
+protected:
+    DeviceEnumerator(const DeviceHandle &dev, const DeviceEnumerationArgs& args)
+        : DeviceHandle(dev), EnumArgs(args)
+    { }
+
+    DeviceEnumerationArgs EnumArgs;
+};
+
+//-------------------------------------------------------------------------------------
+// ***** DeviceManager
+
+// DeviceManager maintains and provides access to devices supported by OVR, such as
+// HMDs and sensors. A single instance of DeviceManager is normally created at
+// program startup, allowing devices to be enumerated and created. DeviceManager is
+// reference counted and is AddRefed by its created child devices, causing it to
+// always be the last object that is released.
+//
+// Install MessageHandler on DeviceManager to detect when devices are inserted or removed.
+//
+// The following code will create the manager and its first available HMDDevice,
+// and then release it when not needed:
+//
+//  DeviceManager* manager = DeviceManager::Create();
+//  HMDDevice*     hmd = manager->EnumerateDevices<HMDDevice>().CreateDevice();
+//
+//  if (hmd) hmd->Release();
+//  if (manager) manager->Release();
+
+
+class DeviceManager : public DeviceBase
+{
+public:
+  
+    DeviceManager()
+    { }
+
+    // DeviceBase implementation.
+    virtual DeviceType      GetType() const     { return Device_Manager; }
+    virtual DeviceManager*  GetManager() const  { return const_cast<DeviceManager*>(this); }
+
+    // Every DeviceManager has an associated profile manager, which us used to store
+    // user settings that may affect device behavior. 
+    virtual ProfileManager* GetProfileManager() const = 0;
+
+
+    // EnumerateDevices enumerates all of the available devices of the specified class,
+    // returning an enumerator that references the first device. An empty enumerator is
+    // returned if no devices are available. The following APIs are exposed through
+    // DeviceEnumerator:
+    //   DeviceEnumerator::GetType()        - Check device type. Returns Device_None 
+    //                                        if no device was found/pointed to.
+    //   DeviceEnumerator::GetDeviceInfo()  - Get more information on device.
+    //   DeviceEnumerator::CreateDevice()   - Create an instance of device.
+    //   DeviceEnumerator::Next()           - Move onto next device.
+    template<class D>
+    DeviceEnumerator<D>     EnumerateDevices(bool availableOnly = true)
+    {
+        // TBD: A cleaner (but less efficient) alternative is though enumeratorFromHandle.
+        DeviceEnumerator<> e = EnumerateDevicesEx(DeviceEnumerationArgs((DeviceType)D::EnumDeviceType, availableOnly));
+        return *reinterpret_cast<DeviceEnumerator<D>*>(&e);
+    }
+  
+    // EnumerateDevicesEx provides internal implementation for device enumeration, enumerating
+    // devices based on dynamically specified DeviceType in DeviceEnumerationArgs.
+    // End users should call DeumerateDevices<>() instead.
+    virtual DeviceEnumerator<> EnumerateDevicesEx(const DeviceEnumerationArgs& args) = 0;
+
+    // Creates a new DeviceManager. Only one instance of DeviceManager should be created at a time.
+    static   DeviceManager* Create();
+
+    // Static constant for this device type, used in template cast type checks.
+    enum { EnumDeviceType = Device_Manager };
+
+
+
+    // Adds a device (DeviceCreateDesc*) into Devices. Returns NULL, 
+    // if unsuccessful or device is already in the list.
+    virtual Ptr<DeviceCreateDesc> AddDevice_NeedsLock(const DeviceCreateDesc& createDesc) = 0;
+
+protected:
+    DeviceEnumerator<> enumeratorFromHandle(const DeviceHandle& h, const DeviceEnumerationArgs& args)
+    { return DeviceEnumerator<>(h, args); }
+
+    DeviceManager* getThis() { return this; }
+};
+
+
+
+//-------------------------------------------------------------------------------------
+// ***** HMDInfo 
+
+// This structure describes various aspects of the HMD allowing us to configure rendering.
+//
+//  Currently included data:
+//   - Physical screen dimensions, resolution, and eye distances.
+//     (some of these will be configurable with a tool in the future).
+//     These arguments allow us to properly setup projection across HMDs.
+//   - DisplayDeviceName for identifying HMD screen; system-specific interpretation.
+//
+// TBD:
+//  - Power on/ off?
+//  - Sensor rates and capabilities
+//  - Distortion radius/variables    
+//  - Screen update frequency
+//  - Distortion needed flag
+//  - Update modes:
+//      Set update mode: Stereo (both sides together), mono (same in both eyes),
+//                       Alternating, Alternating scan-lines.
+
+class HMDInfo : public DeviceInfo
+{
+public:
+    // Size of the entire screen, in pixels.
+    unsigned  HResolution, VResolution; 
+    // Physical dimensions of the active screen in meters. Can be used to calculate
+    // projection center while considering IPD.
+    float     HScreenSize, VScreenSize;
+    // Physical offset from the top of the screen to the eye center, in meters.
+    // This will usually, but not necessarily be half of VScreenSize.
+    float     VScreenCenter;
+    // Distance from the eye to screen surface, in meters.
+    // Useful for calculating FOV and projection.
+    float     EyeToScreenDistance;
+    // Distance between physical lens centers useful for calculating distortion center.
+    float     LensSeparationDistance;
+    // Configured distance between the user's eye centers, in meters. Defaults to 0.064.
+    float     InterpupillaryDistance;
+    
+    // Radial distortion correction coefficients.
+    // The distortion assumes that the input texture coordinates will be scaled
+    // by the following equation:    
+    //   uvResult = uvInput * (K0 + K1 * uvLength^2 + K2 * uvLength^4)
+    // Where uvInput is the UV vector from the center of distortion in direction
+    // of the mapped pixel, uvLength is the magnitude of that vector, and uvResult
+    // the corresponding location after distortion.
+    float     DistortionK[4];
+
+    float     ChromaAbCorrection[4];
+
+    // Desktop coordinate position of the screen (can be negative; may not be present on all platforms)
+    int       DesktopX, DesktopY;
+    
+    // Windows:
+    // "\\\\.\\DISPLAY3", etc. Can be used in EnumDisplaySettings/CreateDC.
+    char      DisplayDeviceName[32];
+    
+    // MacOS:
+    long      DisplayId;
+
+
+    HMDInfo()
+        : DeviceInfo(Device_HMD),          
+          HResolution(0), VResolution(0), HScreenSize(0), VScreenSize(0),
+          VScreenCenter(0), EyeToScreenDistance(0),
+          LensSeparationDistance(0), InterpupillaryDistance(0),
+          DesktopX(0), DesktopY(0), DisplayId(0)
+    {
+        DisplayDeviceName[0] = 0;
+        memset(DistortionK, 0, sizeof(DistortionK));
+        DistortionK[0] = 1;
+        ChromaAbCorrection[0] = ChromaAbCorrection[2] = 1;
+        ChromaAbCorrection[1] = ChromaAbCorrection[3] = 0;
+    }
+
+    // Operator = copies local fields only (base class must be correct already)
+    void operator = (const HMDInfo& src)
+    {        
+        HResolution             = src.HResolution;
+        VResolution             = src.VResolution;
+        HScreenSize             = src.HScreenSize;
+        VScreenSize             = src.VScreenSize;
+        VScreenCenter           = src.VScreenCenter;
+        EyeToScreenDistance     = src.EyeToScreenDistance;
+        LensSeparationDistance  = src.LensSeparationDistance;
+        InterpupillaryDistance  = src.InterpupillaryDistance;
+        DistortionK[0]          = src.DistortionK[0];
+        DistortionK[1]          = src.DistortionK[1];
+        DistortionK[2]          = src.DistortionK[2];
+        DistortionK[3]          = src.DistortionK[3];
+        ChromaAbCorrection[0]   = src.ChromaAbCorrection[0];
+        ChromaAbCorrection[1]   = src.ChromaAbCorrection[1];
+        ChromaAbCorrection[2]   = src.ChromaAbCorrection[2];
+        ChromaAbCorrection[3]   = src.ChromaAbCorrection[3];
+        DesktopX                = src.DesktopX;
+        DesktopY                = src.DesktopY;
+        memcpy(DisplayDeviceName, src.DisplayDeviceName, sizeof(DisplayDeviceName));
+        DisplayId               = src.DisplayId;
+    }
+
+    bool IsSameDisplay(const HMDInfo& o) const
+    {
+        return DisplayId == o.DisplayId &&
+               String::CompareNoCase(DisplayDeviceName, 
+                                     o.DisplayDeviceName) == 0;
+    }
+
+};
+
+
+// HMDDevice represents an Oculus HMD device unit. An instance of this class
+// is typically created from the DeviceManager.
+//  After HMD device is created, we its sensor data can be obtained by 
+//  first creating a Sensor object and then.
+
+//  TBD:
+//  - Configure Sensor
+//  - APIs to set On-Screen message, other states?
+
+class HMDDevice : public DeviceBase
+{
+public:
+    HMDDevice()
+    { }
+
+    // Static constant for this device type, used in template cast type checks.
+    enum { EnumDeviceType = Device_HMD };
+
+    virtual DeviceType      GetType() const   { return Device_HMD; }  
+
+    // Creates a sensor associated with this HMD.
+    virtual SensorDevice*   GetSensor() = 0;
+
+
+    // Requests the currently used profile. This profile affects the
+    // settings reported by HMDInfo. 
+    virtual Profile*    GetProfile() const = 0;
+    // Obtains the currently used profile name. This is initialized to the default
+    // profile name, if any; it can then be changed per-device by SetProfileName.    
+    virtual const char* GetProfileName() const = 0;
+    // Sets the profile user name, changing the data returned by GetProfileInfo.
+    virtual bool        SetProfileName(const char* name) = 0;
+
+
+    // Disconnects from real HMD device. This HMDDevice remains as 'fake' HMD.
+    // SensorDevice ptr is used to restore the 'fake' HMD (can be NULL).
+    HMDDevice*  Disconnect(SensorDevice*);
+    
+    // Returns 'true' if HMD device is a 'fake' HMD (was created this way or 
+    // 'Disconnect' method was called).
+    bool        IsDisconnected() const;
+};
+
+
+//-------------------------------------------------------------------------------------
+// ***** SensorRange & SensorInfo
+
+// SensorRange specifies maximum value ranges that SensorDevice hardware is configured
+// to detect. Although this range doesn't affect the scale of MessageBodyFrame values,
+// physical motions whose positive or negative magnitude is outside the specified range
+// may get clamped or misreported. Setting lower values may result in higher precision
+// tracking.
+struct SensorRange
+{
+    SensorRange(float maxAcceleration = 0.0f, float maxRotationRate = 0.0f,
+                float maxMagneticField = 0.0f)
+        : MaxAcceleration(maxAcceleration), MaxRotationRate(maxRotationRate),
+          MaxMagneticField(maxMagneticField)
+    { }
+
+    // Maximum detected acceleration in m/s^2. Up to 8*G equivalent support guaranteed,
+    // where G is ~9.81 m/s^2.
+    // Oculus DK1 HW has thresholds near: 2, 4 (default), 8, 16 G.
+    float   MaxAcceleration;  
+    // Maximum detected angular velocity in rad/s. Up to 8*Pi support guaranteed.
+    // Oculus DK1 HW thresholds near: 1, 2, 4, 8 Pi (default).
+    float   MaxRotationRate;
+    // Maximum detectable Magnetic field strength in Gauss. Up to 2.5 Gauss support guaranteed.
+    // Oculus DK1 HW thresholds near: 0.88, 1.3, 1.9, 2.5 gauss.
+    float   MaxMagneticField;
+};
+
+// SensorInfo describes capabilities of the sensor device.
+class SensorInfo : public DeviceInfo
+{
+public:
+    SensorInfo() : DeviceInfo(Device_Sensor), VendorId(0), ProductId(0)
+    {
+        SerialNumber[0] = 0;
+    }
+
+    // HID Vendor and ProductId of the device.
+    UInt16      VendorId;
+    UInt16      ProductId;
+    // MaxRanges report maximum sensor range values supported by HW.
+    SensorRange MaxRanges;
+    // Sensor (and display) serial number.
+    char        SerialNumber[20];
+
+private:
+    void operator = (const SensorInfo&) { OVR_ASSERT(0); } // Assignment not allowed.
+};
+
+
+//-------------------------------------------------------------------------------------
+// ***** SensorDevice
+
+// SensorDevice is an interface to sensor data.
+// Install a MessageHandler of SensorDevice instance to receive MessageBodyFrame
+// notifications.
+//
+// TBD: Add Polling API? More HID interfaces?
+
+class SensorDevice : public HIDDeviceBase, public DeviceBase
+{
+public:
+    SensorDevice() 
+    { }
+
+    // Static constant for this device type, used in template cast type checks.
+    enum { EnumDeviceType = Device_Sensor };
+
+    virtual DeviceType GetType() const   { return Device_Sensor; }
+
+    
+    // CoordinateFrame defines whether messages come in the coordinate frame
+    // of the sensor device or HMD, which has a different internal sensor.
+    // Sensors obtained form the HMD will automatically use HMD coordinates.
+    enum CoordinateFrame
+    {
+        Coord_Sensor = 0,
+        Coord_HMD    = 1
+    };
+
+    virtual void            SetCoordinateFrame(CoordinateFrame coordframe) = 0;
+    virtual CoordinateFrame GetCoordinateFrame() const = 0;
+
+    // Sets report rate (in Hz) of MessageBodyFrame messages (delivered through MessageHandler::OnMessage call). 
+    // Currently supported maximum rate is 1000Hz. If the rate is set to 500 or 333 Hz then OnMessage will be 
+    // called twice or thrice at the same 'tick'. 
+    // If the rate is  < 333 then the OnMessage / MessageBodyFrame will be called three
+    // times for each 'tick': the first call will contain averaged values, the second
+    // and third calls will provide with most recent two recorded samples.
+    virtual void        SetReportRate(unsigned rateHz) = 0;
+    // Returns currently set report rate, in Hz. If 0 - error occurred.
+    // Note, this value may be different from the one provided for SetReportRate. The return
+    // value will contain the actual rate.
+    virtual unsigned    GetReportRate() const = 0;
+
+    // Sets maximum range settings for the sensor described by SensorRange.    
+    // The function will fail if you try to pass values outside Maximum supported
+    // by the HW, as described by SensorInfo.
+    // Pass waitFlag == true to wait for command completion. For waitFlag == true,
+    // returns true if the range was applied successfully (no HW error).
+    // For waitFlag = false, return 'true' means that command was enqueued successfully.
+    virtual bool       SetRange(const SensorRange& range, bool waitFlag = false) = 0;
+
+    // Return the current sensor range settings for the device. These may not exactly
+    // match the values applied through SetRange.
+    virtual void       GetRange(SensorRange* range) const = 0;
+};
+
+//-------------------------------------------------------------------------------------
+// ***** LatencyTestConfiguration
+// LatencyTestConfiguration specifies configuration information for the Oculus Latency Tester device.
+struct LatencyTestConfiguration
+{
+    LatencyTestConfiguration(const Color& threshold, bool sendSamples = false)
+        : Threshold(threshold), SendSamples(sendSamples) 
+    {
+    }
+
+    // The color threshold for triggering a detected display change.
+    Color    Threshold;
+    // Flag specifying whether we wish to receive a stream of color values from the sensor.
+    bool        SendSamples;
+};
+
+//-------------------------------------------------------------------------------------
+// ***** LatencyTestDisplay
+// LatencyTestDisplay sets the mode and contents of the Latency Tester LED display.
+// See the 'Latency Tester Specification' document for more details.
+struct LatencyTestDisplay
+{
+    LatencyTestDisplay(UByte mode, UInt32 value)
+        : Mode(mode), Value(value)
+    {
+    }
+
+    UByte       Mode;       // The display mode that we wish to select.
+    UInt32      Value;      // The value to display.
+};
+
+//-------------------------------------------------------------------------------------
+// ***** LatencyTestDevice
+
+// LatencyTestDevice provides an interface to the Oculus Latency Tester which is used to test 'motion to photon' latency.
+class LatencyTestDevice : public HIDDeviceBase, public DeviceBase
+{
+public:
+    LatencyTestDevice()
+    { }
+
+    // Static constant for this device type, used in template cast type checks.
+    enum { EnumDeviceType = Device_LatencyTester };
+
+    virtual DeviceType GetType() const { return Device_LatencyTester; }
+
+    // Specifies configuration information including the threshold for triggering a detected color change,
+    // and a flag to enable a stream of sensor values (typically used for debugging).
+    virtual bool SetConfiguration(const LatencyTestConfiguration& configuration, bool waitFlag = false) = 0;
+
+    // Get configuration information from device.
+    virtual bool GetConfiguration(LatencyTestConfiguration* configuration) = 0;
+
+    // Used to calibrate the latency tester at the start of a test. Display the specified color on the screen
+    // beneath the latency tester and then call this method. Calibration information is lost
+    // when power is removed from the device.
+    virtual bool SetCalibrate(const Color& calibrationColor, bool waitFlag = false) = 0;
+
+    // Triggers the start of a measurement. This starts the millisecond timer on the device and 
+    // causes it to respond with the 'MessageLatencyTestStarted' message.
+    virtual bool SetStartTest(const Color& targetColor, bool waitFlag = false) = 0;
+
+    // Used to set the value displayed on the LED display panel.
+    virtual bool SetDisplay(const LatencyTestDisplay& display, bool waitFlag = false) = 0;
+
+    virtual DeviceBase* GetDevice() { return this; }
+};
+
+} // namespace OVR
+
+#endif