0.4 Win-Beta0.4.0

1 files changed, 480 insertions, 362 deletions

diff --git a/LibOVR/Src/OVR_CAPI.h b/LibOVR/Src/OVR_CAPI.h
index ec4708c..e98cad7 100644
--- a/LibOVR/Src/OVR_CAPI.h
+++ b/LibOVR/Src/OVR_CAPI.h
@@ -1,7 +1,7 @@
 /************************************************************************************
 
 Filename    :   OVR_CAPI.h
-Content     :   C Interface to Oculus sensors and rendering.
+Content     :   C Interface to Oculus tracking and rendering.
 Created     :   November 23, 2013
 Authors     :   Michael Antonov
 
@@ -23,6 +23,15 @@ See the License for the specific language governing permissions and
 limitations under the License.
 
 ************************************************************************************/
+
+/// @file OVR_CAPI.h
+/// Exposes all general Rift functionality.
+/// 
+/// @mainpage Overview
+/// Welcome to the Oculus SDK Reference Manual. All SDK functionality is exposed through a simple and portable C API, found in OVR_CAPI.h.
+///
+/// Please see the Oculus Developer Guide for detailed information about using the SDK in your native applications.
+
 #ifndef OVR_CAPI_h
 #define OVR_CAPI_h
 
@@ -34,59 +43,67 @@ typedef char ovrBool;
 // ***** OVR_EXPORT definition
 
 #if !defined(OVR_EXPORT)
-    #if defined(WIN32)    
+    #ifdef OVR_OS_WIN32
         #define OVR_EXPORT __declspec(dllexport)        
     #else
         #define OVR_EXPORT
     #endif
 #endif
 
+//#define ENABLE_LATENCY_TESTER
+
 //-----------------------------------------------------------------------------------
 // ***** Simple Math Structures
 
-// 2D integer
+/// A 2D vector with integer components.
 typedef struct ovrVector2i_
 {
     int x, y;
 } ovrVector2i;
+/// A 2D size with integer components.
 typedef struct ovrSizei_
 {
     int w, h;
 } ovrSizei;
+/// A 2D rectangle with a position and size.
+/// All components are integers.
 typedef struct ovrRecti_
 {
     ovrVector2i Pos;
     ovrSizei    Size;
 } ovrRecti;
 
-// 3D
+/// A quaternion rotation.
 typedef struct ovrQuatf_
 {
     float x, y, z, w;  
 } ovrQuatf;
+/// A 2D vector with float components.
 typedef struct ovrVector2f_
 {
     float x, y;
 } ovrVector2f;
+/// A 3D vector with float components.
 typedef struct ovrVector3f_
 {
     float x, y, z;
 } ovrVector3f;
+/// A 4x4 matrix with float elements.
 typedef struct ovrMatrix4f_
 {
     float M[4][4];
 } ovrMatrix4f;
-// Position and orientation together.
+/// Position and orientation together.
 typedef struct ovrPosef_
 {
     ovrQuatf     Orientation;
     ovrVector3f  Position;    
 } ovrPosef;
 
-// Full pose (rigid body) configuration with first and second derivatives.
+/// A full pose (rigid body) configuration with first and second derivatives.
 typedef struct ovrPoseStatef_
 {
-    ovrPosef     Pose;
+    ovrPosef     ThePose;
     ovrVector3f  AngularVelocity;
     ovrVector3f  LinearVelocity;
     ovrVector3f  AngularAcceleration;
@@ -94,14 +111,18 @@ typedef struct ovrPoseStatef_
     double       TimeInSeconds;         // Absolute time of this state sample.
 } ovrPoseStatef;
 
-// Field Of View (FOV) in tangent of the angle units.
-// As an example, for a standard 90 degree vertical FOV, we would 
-// have: { UpTan = tan(90 degrees / 2), DownTan = tan(90 degrees / 2) }.
+/// Field Of View (FOV) in tangent of the angle units.
+/// As an example, for a standard 90 degree vertical FOV, we would 
+/// have: { UpTan = tan(90 degrees / 2), DownTan = tan(90 degrees / 2) }.
 typedef struct ovrFovPort_
 {
+    /// The tangent of the angle between the viewing vector and the top edge of the field of view.
     float UpTan;
+    /// The tangent of the angle between the viewing vector and the bottom edge of the field of view.
     float DownTan;
+    /// The tangent of the angle between the viewing vector and the left edge of the field of view.
     float LeftTan;
+    /// The tangent of the angle between the viewing vector and the right edge of the field of view.
     float RightTan;
 } ovrFovPort;
 
@@ -109,71 +130,77 @@ typedef struct ovrFovPort_
 //-----------------------------------------------------------------------------------
 // ***** HMD Types
 
-// Enumerates all HMD types that we support.
+/// Enumerates all HMD types that we support.
 typedef enum
 {
     ovrHmd_None             = 0,    
     ovrHmd_DK1              = 3,
-    ovrHmd_DKHD             = 4,
-    ovrHmd_CrystalCoveProto = 5,
+    ovrHmd_DKHD             = 4,    
     ovrHmd_DK2              = 6,
     ovrHmd_Other             // Some HMD other then the one in the enumeration.
 } ovrHmdType;
 
-// HMD capability bits reported by device.
-// 
+/// HMD capability bits reported by device.
 typedef enum
 {
     // Read-only flags.
-    ovrHmdCap_Present           = 0x0001,   //  This HMD exists (as opposed to being unplugged).
-    ovrHmdCap_Available         = 0x0002,   //  HMD and is sensor is available for use
-                                            //  (if not owned by another app).       
+    ovrHmdCap_Present           = 0x0001,   ///  The HMD is plugged in and detected by the system.
+    ovrHmdCap_Available         = 0x0002,   ///  The HMD and its sensor is available for ownership use.
+											///  i.e. it is not already owned by another application.
+    ovrHmdCap_Captured          = 0x0004,   ///  Set to 'true' if we captured ownership of this HMD.
 
     // These flags are intended for use with the new driver display mode.
-    /*
-    ovrHmdCap_ExtendDesktop     = 0x0004,   // Read only, means display driver is in compatibility mode.
-
-    ovrHmdCap_DisplayOff        = 0x0040,   // Turns off Oculus HMD screen and output.
-    ovrHmdCap_NoMirrorToWindow  = 0x2000,   // Disables mirrowing of HMD output to the window;
-                                            // may improve rendering performance slightly.
-    */
+    ovrHmdCap_ExtendDesktop     = 0x0008,   /// (read only) Means the display driver is in compatibility mode.
 
     // Modifiable flags (through ovrHmd_SetEnabledCaps).
-    ovrHmdCap_LowPersistence    = 0x0080,   //  Supports low persistence mode.
-	ovrHmdCap_LatencyTest       = 0x0100,   //  Supports pixel reading for continuous latency testing.
-    ovrHmdCap_DynamicPrediction = 0x0200,   //  Adjust prediction dynamically based on DK2 Latency.
-    // Support rendering without VSync for debugging
+    ovrHmdCap_NoMirrorToWindow  = 0x2000,   /// Disables mirroring of HMD output to the window. This may improve 
+											/// rendering performance slightly (only if 'ExtendDesktop' is off).
+    ovrHmdCap_DisplayOff        = 0x0040,   /// Turns off HMD screen and output (only if 'ExtendDesktop' is off).
+
+    ovrHmdCap_LowPersistence    = 0x0080,   ///  HMD supports low persistence mode.
+    ovrHmdCap_DynamicPrediction = 0x0200,   ///  Adjust prediction dynamically based on internally measured latency.
+    /// Support rendering without VSync for debugging.
     ovrHmdCap_NoVSync           = 0x1000,
-	ovrHmdCap_NoRestore         = 0x4000,
 
     // These bits can be modified by ovrHmd_SetEnabledCaps.
-    ovrHmdCap_Writable_Mask     = 0x1380
+    ovrHmdCap_Writable_Mask     = 0x33F0,
+    /// These flags are currently passed into the service. May change without notice.
+    ovrHmdCap_Service_Mask      = 0x23F0
 } ovrHmdCaps;
 
 
-// Sensor capability bits reported by device.
-// Used with ovrHmd_StartSensor.
+/// Tracking capability bits reported by the device.
+/// Used with ovrHmd_ConfigureTracking.
 typedef enum
 {
-    ovrSensorCap_Orientation    = 0x0010,   //  Supports orientation tracking (IMU).
-    ovrSensorCap_YawCorrection  = 0x0020,   //  Supports yaw correction through magnetometer or other means.
-    ovrSensorCap_Position       = 0x0040,   //  Supports positional tracking.
-
-} ovrSensorCaps;
-
-// Distortion capability bits reported by device.
-// Used with ovrHmd_ConfigureRendering and ovrHmd_CreateDistortionMesh.
+    ovrTrackingCap_Orientation      = 0x0010,   ///  Supports orientation tracking (IMU).
+    ovrTrackingCap_MagYawCorrection = 0x0020,   ///  Supports yaw drift correction via a magnetometer or other means.
+    ovrTrackingCap_Position         = 0x0040,   ///  Supports positional tracking.
+    ///  Overrides the other flags. Indicates that the application
+    ///  doesn't care about tracking settings. This is the internal
+    ///  default before ovrHmd_ConfigureTracking is called.
+    ovrTrackingCap_Idle             = 0x0100,
+} ovrTrackingCaps;
+
+/// Distortion capability bits reported by device.
+/// Used with ovrHmd_ConfigureRendering and ovrHmd_CreateDistortionMesh.
 typedef enum
 {        
-    ovrDistortionCap_Chromatic	= 0x01,		//	Supports chromatic aberration correction.
-    ovrDistortionCap_TimeWarp	= 0x02,		//	Supports timewarp.
-    ovrDistortionCap_Vignette	= 0x08		//	Supports vignetting around the edges of the view.
+    ovrDistortionCap_Chromatic	= 0x01,		///	Supports chromatic aberration correction.
+    ovrDistortionCap_TimeWarp	= 0x02,		///	Supports timewarp.
+    ovrDistortionCap_Vignette	= 0x08,		///	Supports vignetting around the edges of the view.
+	ovrDistortionCap_NoRestore  = 0x10,		///  Do not save and restore the graphics state when rendering distortion.
+	ovrDistortionCap_FlipInput  = 0x20,		///  Flip the vertical texture coordinate of input images.
+	ovrDistortionCap_SRGB       = 0x40,		///  Assume input images are in sRGB gamma-corrected color space.
+	ovrDistortionCap_Overdrive  = 0x80,		///  Overdrive brightness transitions to reduce artifacts on DK2+ displays
+
+    ovrDistortionCap_ProfileNoTimewarpSpinWaits = 0x10000,  /// Use when profiling with timewarp to remove false positives
 } ovrDistortionCaps;
 
 
-// Specifies which eye is being used for rendering.
-// This type explicitly does not include a third "NoStereo" option, as such is
-// not required for an HMD-centered API.
+/// Specifies which eye is being used for rendering.
+/// This type explicitly does not include a third "NoStereo" option, as such is
+/// not required for an HMD-centered API.
 typedef enum
 {
     ovrEye_Left  = 0,
@@ -182,162 +209,176 @@ typedef enum
 } ovrEyeType;
 
 
-// Handle to HMD; returned by ovrHmd_Create.
-typedef struct ovrHmdStruct* ovrHmd;
 
-// This is a complete descriptor of the HMD.
+/// This is a complete descriptor of the HMD.
 typedef struct ovrHmdDesc_
 {
-    ovrHmd      Handle;  // Handle of this HMD.
+    /// Internal handle of this HMD.
+    struct ovrHmdStruct* Handle;
+
+    /// This HMD's type.
     ovrHmdType  Type;
     
-    // Name string describing the product: "Oculus Rift DK1", etc.
+    /// Name string describing the product: "Oculus Rift DK1", etc.
     const char* ProductName;    
     const char* Manufacturer;
-
-    // Capability bits described by ovrHmdCaps.
+    
+    /// HID Vendor and ProductId of the device.
+    short       VendorId;
+    short       ProductId;
+    /// Sensor (and display) serial number.
+    char        SerialNumber[24];
+    /// Sensor firmware version.
+    short       FirmwareMajor;
+    short       FirmwareMinor;
+    /// External tracking camera frustum dimensions (if present).
+    float       CameraFrustumHFovInRadians;
+    float       CameraFrustumVFovInRadians;
+    float       CameraFrustumNearZInMeters;
+    float       CameraFrustumFarZInMeters;
+
+    /// Capability bits described by ovrHmdCaps.
     unsigned int HmdCaps;
-	// Capability bits described by ovrSensorCaps.
-    unsigned int SensorCaps;
-    // Capability bits described by ovrDistortionCaps.
+	/// Capability bits described by ovrTrackingCaps.
+    unsigned int TrackingCaps;
+    /// Capability bits described by ovrDistortionCaps.
     unsigned int DistortionCaps;
 
-    // Resolution of the entire HMD screen (for both eyes) in pixels.
-    ovrSizei    Resolution;
-    // Where monitor window should be on screen or (0,0).
-    ovrVector2i WindowsPos;     
-
-    // These define the recommended and maximum optical FOVs for the HMD.    
+    /// These define the recommended and maximum optical FOVs for the HMD.    
     ovrFovPort  DefaultEyeFov[ovrEye_Count];
     ovrFovPort  MaxEyeFov[ovrEye_Count];
 
-    // Preferred eye rendering order for best performance.
-    // Can help reduce latency on sideways-scanned screens.
+    /// Preferred eye rendering order for best performance.
+    /// Can help reduce latency on sideways-scanned screens.
     ovrEyeType  EyeRenderOrder[ovrEye_Count];
-    
-    // Display that HMD should present on.
-    // TBD: It may be good to remove this information relying on WidowPos instead.
-    // Ultimately, we may need to come up with a more convenient alternative,
-    // such as a API-specific functions that return adapter, ot something that will
-    // work with our monitor driver.
 
-    // Windows: "\\\\.\\DISPLAY3", etc. Can be used in EnumDisplaySettings/CreateDC.    
+    /// Resolution of the full HMD screen (both eyes) in pixels.
+    ovrSizei    Resolution;
+    /// Location of the application window on the desktop (or 0,0).
+    ovrVector2i WindowsPos;     
+
+    /// Display that the HMD should present on.
+    /// TBD: It may be good to remove this information relying on WindowPos instead.
+    /// Ultimately, we may need to come up with a more convenient alternative,
+    /// such as API-specific functions that return adapter, or something that will
+    /// work with our monitor driver.
+    /// Windows: (e.g. "\\\\.\\DISPLAY3", can be used in EnumDisplaySettings/CreateDC).
     const char* DisplayDeviceName;
-    // MacOS
-    int        DisplayId;
+    /// MacOS:
+    int         DisplayId;
+  
 } ovrHmdDesc;
 
-// Describes the type of positional tracking being done.
-/*
-typedef enum
-{
-    ovrPose_None,
-    ovrPose_HeadModel,
-    ovrPose_Positional
-} ovrPoseType;
-*/
+
+/// Simple type ovrHmd is used in ovrHmd_* calls.
+typedef const ovrHmdDesc * ovrHmd;
 
 
-// Bit flags describing the current status of sensor tracking.
+
+/// Bit flags describing the current status of sensor tracking.
 typedef enum
 {
-    ovrStatus_OrientationTracked    = 0x0001,   // Orientation is currently tracked (connected and in use).
-    ovrStatus_PositionTracked       = 0x0002,   // Position is currently tracked (FALSE if out of range).
-    ovrStatus_PositionConnected     = 0x0020,   // Position tracking HW is connected.
-    ovrStatus_HmdConnected          = 0x0080    // HMD Display is available & connected.
+    ovrStatus_OrientationTracked    = 0x0001,   /// Orientation is currently tracked (connected and in use).
+    ovrStatus_PositionTracked       = 0x0002,   /// Position is currently tracked (false if out of range).
+    ovrStatus_CameraPoseTracked     = 0x0004,   /// Camera pose is currently tracked.
+    ovrStatus_PositionConnected     = 0x0020,   /// Position tracking hardware is connected.
+    ovrStatus_HmdConnected          = 0x0080    /// HMD Display is available and connected.
 } ovrStatusBits;
 
-
-// State of the sensor at a given absolute time.
-typedef struct ovrSensorState_
+/// Specifies a reading we can query from the sensor.
+typedef struct ovrSensorData_
 {
-    // Predicted pose configuration at requested absolute time.
-    // One can determine the time difference between predicted and actual
-    // readings by comparing ovrPoseState.TimeInSeconds.
-    ovrPoseStatef  Predicted;
-    // Actual recorded pose configuration based on the sensor sample at a 
-    // moment closest to the requested time.
-    ovrPoseStatef  Recorded;
-
-    // Sensor temperature reading, in degrees Celsius, as sample time.
-    float          Temperature;    
-    // Sensor status described by ovrStatusBits.
-    unsigned int   StatusFlags;
-} ovrSensorState;
+    ovrVector3f    Accelerometer;    /// Acceleration reading in m/s^2.
+    ovrVector3f    Gyro;             /// Rotation rate in rad/s.
+    ovrVector3f    Magnetometer;     /// Magnetic field in Gauss.
+    float          Temperature;      /// Temperature of the sensor in degrees Celsius.
+    float          TimeInSeconds;    /// Time when the reported IMU reading took place, in seconds.
+} ovrSensorData;
+
 
-// For now.
-// TBD: Decide if this becomes a part of HMDDesc
-typedef struct ovrSensorDesc_
+/// Tracking state at a given absolute time (describes predicted HMD pose etc).
+/// Returned by ovrHmd_GetTrackingState.
+typedef struct ovrTrackingState_
 {
-    // HID Vendor and ProductId of the device.
-    short   VendorId;
-    short   ProductId;
-    // Sensor (and display) serial number.
-    char    SerialNumber[24];
-} ovrSensorDesc;
+    /// Predicted head pose (and derivatives) at the requested absolute time.
+    /// The look-ahead interval is equal to (HeadPose.TimeInSeconds - RawSensorData.TimeInSeconds).
+    ovrPoseStatef  HeadPose;
 
+    /// Current pose of the external camera (if present).
+    /// This pose includes camera tilt (roll and pitch). For a leveled coordinate
+    /// system use LeveledCameraPose.
+    ovrPosef       CameraPose;
 
+    /// Camera frame aligned with gravity.
+    /// This value includes position and yaw of the camera, but not roll and pitch.
+    /// It can be used as a reference point to render real-world objects in the correct location.
+    ovrPosef       LeveledCameraPose;
 
-// Frame data reported by ovrHmd_BeginFrameTiming().
+    /// The most recent sensor data received from the HMD.
+    ovrSensorData  RawSensorData;
+
+    /// Tracking status described by ovrStatusBits.
+    unsigned int   StatusFlags;
+} ovrTrackingState;
+
+
+/// Frame timing data reported by ovrHmd_BeginFrameTiming() or ovrHmd_BeginFrame().
 typedef struct ovrFrameTiming_
 {
-    // The amount of time that has passed since the previous frame returned
-    // BeginFrameSeconds value, usable for movement scaling.
-    // This will be clamped to no more than 0.1 seconds to prevent
-    // excessive movement after pauses for loading or initialization.
+    /// The amount of time that has passed since the previous frame's
+	/// ThisFrameSeconds value (usable for movement scaling).
+    /// This will be clamped to no more than 0.1 seconds to prevent
+    /// excessive movement after pauses due to loading or initialization.
     float			DeltaSeconds;
 
-    // It is generally expected that the following hold:
-    // ThisFrameSeconds < TimewarpPointSeconds < NextFrameSeconds < 
-    // EyeScanoutSeconds[EyeOrder[0]] <= ScanoutMidpointSeconds <= EyeScanoutSeconds[EyeOrder[1]]
+    /// It is generally expected that the following holds:
+    /// ThisFrameSeconds < TimewarpPointSeconds < NextFrameSeconds < 
+    /// EyeScanoutSeconds[EyeOrder[0]] <= ScanoutMidpointSeconds <= EyeScanoutSeconds[EyeOrder[1]].
 
-    // Absolute time value of when rendering of this frame began or is expected to
-    // begin; generally equal to NextFrameSeconds of the previous frame. Can be used
-    // for animation timing.
+    /// Absolute time value when rendering of this frame began or is expected to
+    /// begin. Generally equal to NextFrameSeconds of the previous frame. Can be used
+    /// for animation timing.
     double			ThisFrameSeconds;
-    // Absolute point when IMU expects to be sampled for this frame.
+    /// Absolute point when IMU expects to be sampled for this frame.
     double			TimewarpPointSeconds;
-    // Absolute time when frame Present + GPU Flush will finish, and the next frame starts.
+    /// Absolute time when frame Present followed by GPU Flush will finish and the next frame begins.
     double			NextFrameSeconds;
 
-    // Time when when half of the screen will be scanned out. Can be passes as a prediction
-    // value to ovrHmd_GetSensorState() go get general orientation.
+    /// Time when when half of the screen will be scanned out. Can be passed as an absolute time
+	/// to ovrHmd_GetTrackingState() to get the predicted general orientation.
     double		    ScanoutMidpointSeconds;
-    // Timing points when each eye will be scanned out to display. Used for rendering each eye. 
+    /// Timing points when each eye will be scanned out to display. Used when rendering each eye.
     double			EyeScanoutSeconds[2];    
-
 } ovrFrameTiming;
 
 
 
-// Rendering information for each eye, computed by either ovrHmd_ConfigureRendering().
-// or ovrHmd_GetRenderDesc() based on the specified Fov.
-// Note that the rendering viewport is not included here as it can be 
-// specified separately and modified per frame though:
-//    (a) calling ovrHmd_GetRenderScaleAndOffset with game-rendered api,
-// or (b) passing different values in ovrTexture in case of SDK-rendered distortion.
+/// Rendering information for each eye. Computed by either ovrHmd_ConfigureRendering()
+/// or ovrHmd_GetRenderDesc() based on the specified FOV. Note that the rendering viewport 
+/// is not included here as it can be specified separately and modified per frame through:
+///    (a) ovrHmd_GetRenderScaleAndOffset in the case of client rendered distortion,
+/// or (b) passing different values via ovrTexture in the case of SDK rendered distortion.
 typedef struct ovrEyeRenderDesc_
 {    
     ovrEyeType  Eye;
     ovrFovPort  Fov;
-	ovrRecti	DistortedViewport; 	        // Distortion viewport 
-    ovrVector2f PixelsPerTanAngleAtCenter;  // How many display pixels will fit in tan(angle) = 1.
-    ovrVector3f ViewAdjust;  		        // Translation to be applied to view matrix.
+	ovrRecti	DistortedViewport; 	        /// Distortion viewport.
+    ovrVector2f PixelsPerTanAngleAtCenter;  /// How many display pixels will fit in tan(angle) = 1.
+    ovrVector3f ViewAdjust;  		        /// Translation to be applied to view matrix.
 } ovrEyeRenderDesc;
 
 
 //-----------------------------------------------------------------------------------
 // ***** Platform-independent Rendering Configuration
 
-// These types are used to hide platform-specific details when passing
-// render device, OS and texture data to the APIs.
-//
-// The benefit of having these wrappers vs. platform-specific API functions is
-// that they allow game glue code to be portable. A typical example is an
-// engine that has multiple back ends, say GL and D3D. Portable code that calls
-// these back ends may also use LibOVR. To do this, back ends can be modified
-// to return portable types such as ovrTexture and ovrRenderAPIConfig.
-
+/// These types are used to hide platform-specific details when passing
+/// render device, OS, and texture data to the API.
+///
+/// The benefit of having these wrappers versus platform-specific API functions is
+/// that they allow game glue code to be portable. A typical example is an
+/// engine that has multiple back ends, say GL and D3D. Portable code that calls
+/// these back ends may also use LibOVR. To do this, back ends can be modified
+/// to return portable types such as ovrTexture and ovrRenderAPIConfig.
 typedef enum
 {
     ovrRenderAPI_None,
@@ -349,8 +390,8 @@ typedef enum
     ovrRenderAPI_Count
 } ovrRenderAPIType;
 
-// Platform-independent part of rendering API-configuration data.
-// It is a part of ovrRenderAPIConfig, passed to ovrHmd_Configure.
+/// Platform-independent part of rendering API-configuration data.
+/// It is a part of ovrRenderAPIConfig, passed to ovrHmd_Configure.
 typedef struct ovrRenderAPIConfigHeader_
 {
     ovrRenderAPIType API;
@@ -358,22 +399,24 @@ typedef struct ovrRenderAPIConfigHeader_
     int              Multisample;
 } ovrRenderAPIConfigHeader;
 
+/// Contains platform-specific information for rendering.
 typedef struct ovrRenderAPIConfig_
 {
     ovrRenderAPIConfigHeader Header;
     uintptr_t                PlatformData[8];
 } ovrRenderAPIConfig;
 
-// Platform-independent part of eye texture descriptor.
-// It is a part of ovrTexture, passed to ovrHmd_EndFrame.
-//  - If RenderViewport is all zeros, will be used.
+/// Platform-independent part of the eye texture descriptor.
+/// It is a part of ovrTexture, passed to ovrHmd_EndFrame.
+/// If RenderViewport is all zeros then the full texture will be used.
 typedef struct ovrTextureHeader_
 {
-    ovrRenderAPIType API;    
+    ovrRenderAPIType API;
     ovrSizei         TextureSize;
     ovrRecti         RenderViewport;  // Pixel viewport in texture that holds eye image.
 } ovrTextureHeader;
 
+/// Contains platform-specific information about a texture.
 typedef struct ovrTexture_
 {
     ovrTextureHeader Header;
@@ -387,21 +430,22 @@ typedef struct ovrTexture_
 // Basic steps to use the API:
 //
 // Setup:
-//  1. ovrInitialize();
-//  2. ovrHMD hmd = ovrHmd_Create(0);  ovrHmd_GetDesc(hmd, &hmdDesc);
-//  3. Use hmdDesc and ovrHmd_GetFovTextureSize() to determine graphics configuration.
-//  4. Call ovrHmd_StartSensor() to configure and initialize tracking.
+//  1. ovrInitialize()
+//  2. ovrHMD hmd = ovrHmd_Create(0)
+//  3. Use hmd members and ovrHmd_GetFovTextureSize() to determine graphics configuration.
+//  4. Call ovrHmd_ConfigureTracking() to configure and initialize tracking.
 //  5. Call ovrHmd_ConfigureRendering() to setup graphics for SDK rendering,
 //     which is the preferred approach.
-//     Please refer to "Game-Side Rendering" below if you prefer to do that instead.
-//  5. Allocate textures as needed.
+//     Please refer to "Client Distorton Rendering" below if you prefer to do that instead.
+//  6. If the ovrHmdCap_ExtendDesktop flag is not set, then use ovrHmd_AttachToWindow to 
+//     associate the relevant application window with the hmd.
+//  5. Allocate render target textures as needed.
 //
 // Game Loop:
-//  6. Call ovrHmd_BeginFrame() to get frame timing and orientation information.
-//  7. Render each eye in between ovrHmd_BeginEyeRender and ovrHmd_EndEyeRender calls,
-//     providing the result texture to the API.
-//  8. Call ovrHmd_EndFrame() to render distorted textures to the back buffer
-//     and present them on the Hmd.
+//  6. Call ovrHmd_BeginFrame() to get the current frame timing information.
+//  7. Render each eye using ovrHmd_GetEyePose to get the predicted head pose.
+//  8. Call ovrHmd_EndFrame() to render the distorted textures to the back buffer
+//     and present them on the hmd.
 //
 // Shutdown:
 //  9. ovrHmd_Destroy(hmd)
@@ -414,87 +458,102 @@ extern "C" {
 
 // Library init/shutdown, must be called around all other OVR code.
 // No other functions calls are allowed before ovr_Initialize succeeds or after ovr_Shutdown.
+/// Initializes all Oculus functionality.
 OVR_EXPORT ovrBool  ovr_Initialize();
+/// Shuts down all Oculus functionality.
 OVR_EXPORT void     ovr_Shutdown();
 
+/// Returns version string representing libOVR version. Static, so
+/// string remains valid for app lifespan
+OVR_EXPORT const char* ovr_GetVersionString();
+
 
-// Detects or re-detects HMDs and reports the total number detected.
-// Users can get information about each HMD by calling ovrHmd_Create with an index.
+
+/// Detects or re-detects HMDs and reports the total number detected.
+/// Users can get information about each HMD by calling ovrHmd_Create with an index.
 OVR_EXPORT int      ovrHmd_Detect();
 
 
-// Creates a handle to an HMD and optionally fills in data about it.
-// Index can [0 .. ovrHmd_Detect()-1]; index mappings can cange after each ovrHmd_Detect call.
-// If not null, returned handle must be freed with ovrHmd_Destroy.
+/// Creates a handle to an HMD which doubles as a description structure.
+/// Index can [0 .. ovrHmd_Detect()-1]. Index mappings can cange after each ovrHmd_Detect call.
+/// If not null, then the returned handle must be freed with ovrHmd_Destroy.
 OVR_EXPORT ovrHmd   ovrHmd_Create(int index);
 OVR_EXPORT void     ovrHmd_Destroy(ovrHmd hmd);
 
-// Creates a "fake" HMD used for debugging only. This is not tied to specific hardware,
-// but may be used to debug some of the related rendering.
+/// Creates a 'fake' HMD used for debugging only. This is not tied to specific hardware,
+/// but may be used to debug some of the related rendering.
 OVR_EXPORT ovrHmd   ovrHmd_CreateDebug(ovrHmdType type);
 
 
-// Returns last error for HMD state. Returns null for no error.
-// String is valid until next call or GetLastError or HMD is destroyed.
-// Pass null hmd to get global error (for create, etc).
+/// Returns last error for HMD state. Returns null for no error.
+/// String is valid until next call or GetLastError or HMD is destroyed.
+/// Pass null hmd to get global errors (during create etc).
 OVR_EXPORT const char* ovrHmd_GetLastError(ovrHmd hmd);
 
+/// Platform specific function to specify the application window whose output will be 
+/// displayed on the HMD. Only used if the ovrHmdCap_ExtendDesktop flag is false.
+///   Windows: SwapChain associated with this window will be displayed on the HMD.
+///            Specify 'destMirrorRect' in window coordinates to indicate an area
+///            of the render target output that will be mirrored from 'sourceRenderTargetRect'.
+///            Null pointers mean "full size".
+/// @note Source and dest mirror rects are not yet implemented.
+OVR_EXPORT ovrBool ovrHmd_AttachToWindow(ovrHmd hmd, void* window,
+										 const ovrRecti* destMirrorRect,
+										 const ovrRecti* sourceRenderTargetRect);
 
 //-------------------------------------------------------------------------------------
 
-// Returns capability bits that are enabled at this time; described by ovrHmdCaps.
-// Note that this value is different font ovrHmdDesc::HmdCaps, which describes what
-// capabilities are available.
+/// Returns capability bits that are enabled at this time as described by ovrHmdCaps.
+/// Note that this value is different font ovrHmdDesc::HmdCaps, which describes what
+/// capabilities are available for that HMD.
 OVR_EXPORT unsigned int ovrHmd_GetEnabledCaps(ovrHmd hmd);
 
-// Modifies capability bits described by ovrHmdCaps that can be modified,
-// such as ovrHmd_LowPersistance.
+/// Modifies capability bits described by ovrHmdCaps that can be modified,
+/// such as ovrHmd_LowPersistance.
 OVR_EXPORT void         ovrHmd_SetEnabledCaps(ovrHmd hmd, unsigned int hmdCaps);
 
 
 //-------------------------------------------------------------------------------------
-// ***** Sensor Interface
-
-// All sensor interface functions are thread-safe, allowing sensor state to be sampled
-// from different threads.
-// Starts sensor sampling, enabling specified capabilities, described by ovrSensorCaps.
-//  - supportedSensorCaps specifies support that is requested. The function will succeed 
-//	  even if these caps are not available (i.e. sensor or camera is unplugged). Support
-//    will automatically be enabled if such device is plugged in later. Software should
-//    check ovrSensorState.StatusFlags for real-time status.
-//  - requiredSensorCaps specify sensor capabilities required at the time of the call.
-//    If they are not available, the function will fail. Pass 0 if only specifying
-//    supportedSensorCaps.
-OVR_EXPORT ovrBool  ovrHmd_StartSensor(ovrHmd hmd,	unsigned int supportedSensorCaps,
-													unsigned int requiredSensorCaps);
-// Stops sensor sampling, shutting down internal resources.
-OVR_EXPORT void     ovrHmd_StopSensor(ovrHmd hmd);
-// Resets sensor orientation.
-OVR_EXPORT void     ovrHmd_ResetSensor(ovrHmd hmd);
-
-// Returns sensor state reading based on the specified absolute system time.
-// Pass absTime value of 0.0 to request the most recent sensor reading; in this case
-// both PredictedPose and SamplePose will have the same value.
-// ovrHmd_GetEyePredictedSensorState relies on this internally.
-// This may also be used for more refined timing of FrontBuffer rendering logic, etc.
-OVR_EXPORT ovrSensorState ovrHmd_GetSensorState(ovrHmd hmd, double absTime);
-
-// Returns information about a sensor.
-// Only valid after StartSensor.
-OVR_EXPORT ovrBool     ovrHmd_GetSensorDesc(ovrHmd hmd, ovrSensorDesc* descOut);
+// ***** Tracking Interface
+
+/// All tracking interface functions are thread-safe, allowing tracking state to be sampled
+/// from different threads.
+/// ConfigureTracking starts sensor sampling, enabling specified capabilities,
+///    described by ovrTrackingCaps.
+///  - supportedTrackingCaps specifies support that is requested. The function will succeed 
+///	  even if these caps are not available (i.e. sensor or camera is unplugged). Support
+///    will automatically be enabled if such device is plugged in later. Software should
+///    check ovrTrackingState.StatusFlags for real-time status.
+///  - requiredTrackingCaps specify sensor capabilities required at the time of the call.
+///    If they are not available, the function will fail. Pass 0 if only specifying
+///    supportedTrackingCaps.
+///  - Pass 0 for both supportedTrackingCaps and requiredTrackingCaps to disable tracking.
+OVR_EXPORT ovrBool  ovrHmd_ConfigureTracking(ovrHmd hmd, unsigned int supportedTrackingCaps,
+													     unsigned int requiredTrackingCaps);
+
+/// Re-centers the sensor orientation.
+/// Normally this will recenter the (x,y,z) translational components and the yaw 
+/// component of orientation.
+OVR_EXPORT void     ovrHmd_RecenterPose(ovrHmd hmd);
+
+/// Returns tracking state reading based on the specified absolute system time.
+/// Pass an absTime value of 0.0 to request the most recent sensor reading. In this case
+/// both PredictedPose and SamplePose will have the same value.
+/// ovrHmd_GetEyePose relies on this internally.
+/// This may also be used for more refined timing of FrontBuffer rendering logic, etc.
+OVR_EXPORT ovrTrackingState ovrHmd_GetTrackingState(ovrHmd hmd, double absTime);
 
 
 //-------------------------------------------------------------------------------------
 // ***** Graphics Setup
 
-// Fills in description about HMD; this is the same as filled in by ovrHmd_Create.
-OVR_EXPORT void     ovrHmd_GetDesc(ovrHmd hmd, ovrHmdDesc* desc);
 
-// Calculates texture size recommended for rendering one eye within HMD, given FOV cone.
-// Higher FOV will generally require larger textures to maintain quality.
-//  - pixelsPerDisplayPixel specifies that number of render target pixels per display
-//    pixel at center of distortion; 1.0 is the default value. Lower values
-//    can improve performance.
+/// Calculates the recommended texture size for rendering a given eye within the HMD
+/// with a given FOV cone. Higher FOV will generally require larger textures to 
+/// maintain quality.
+///  - pixelsPerDisplayPixel specifies the ratio of the number of render target pixels 
+///    to display pixels at the center of distortion. 1.0 is the default value. Lower
+///    values can improve performance.
 OVR_EXPORT ovrSizei ovrHmd_GetFovTextureSize(ovrHmd hmd, ovrEyeType eye, ovrFovPort fov,
                                              float pixelsPerDisplayPixel);
 
@@ -503,8 +562,8 @@ OVR_EXPORT ovrSizei ovrHmd_GetFovTextureSize(ovrHmd hmd, ovrEyeType eye, ovrFovP
 //-------------------------------------------------------------------------------------
 // *****  Rendering API Thread Safety
 
-//  All of rendering APIs, inclusing Configure and frame functions are *NOT
-//  Thread Safe*.  It is ok to use ConfigureRendering on one thread and handle
+//  All of rendering functions including the configure and frame functions
+// are *NOT thread safe*. It is ok to use ConfigureRendering on one thread and handle
 //  frames on another thread, but explicit synchronization must be done since
 //  functions that depend on configured state are not reentrant.
 //
@@ -512,113 +571,102 @@ OVR_EXPORT ovrSizei ovrHmd_GetFovTextureSize(ovrHmd hmd, ovrEyeType eye, ovrFovP
 //  the render thread, which is the same thread that calls ovrHmd_BeginFrame
 //  or ovrHmd_BeginFrameTiming.
 //    - ovrHmd_EndFrame
-//    - ovrHmd_BeginEyeRender
-//    - ovrHmd_EndEyeRender
-//    - ovrHmd_GetFramePointTime
 //    - ovrHmd_GetEyePose
 //    - ovrHmd_GetEyeTimewarpMatrices
 
 
 //-------------------------------------------------------------------------------------
-// *****  SDK-Rendering Functions
+// *****  SDK Distortion Rendering Functions
 
 // These functions support rendering of distortion by the SDK through direct
-// access to the underlying rendering HW, such as D3D or GL.
-// This is the recommended approach, as it allows for better support or future
-// Oculus hardware and a range of low-level optimizations.
-
-
-// Configures rendering; fills in computed render parameters.
-// This function can be called multiple times to change rendering settings.
-// The users pass in two eye view descriptors that are used to
-// generate complete rendering information for each eye in eyeRenderDescOut[2].
-//
-//  - apiConfig provides D3D/OpenGL specific parameters. Pass null
-//    to shutdown rendering and release all resources.
-//  - distortionCaps describe distortion settings that will be applied.
-//
+// access to the underlying rendering API, such as D3D or GL.
+// This is the recommended approach since it allows better support for future
+// Oculus hardware, and enables a range of low-level optimizations.
+
+
+/// Configures rendering and fills in computed render parameters.
+/// This function can be called multiple times to change rendering settings.
+/// eyeRenderDescOut is a pointer to an array of two ovrEyeRenderDesc structs
+/// that are used to return complete rendering information for each eye.
+///
+///  - apiConfig provides D3D/OpenGL specific parameters. Pass null
+///    to shutdown rendering and release all resources.
+///  - distortionCaps describe desired distortion settings.
+///
 OVR_EXPORT ovrBool ovrHmd_ConfigureRendering( ovrHmd hmd,
-                                              const ovrRenderAPIConfig* apiConfig,                                              
+                                              const ovrRenderAPIConfig* apiConfig,
                                               unsigned int distortionCaps,
                                               const ovrFovPort eyeFovIn[2],
                                               ovrEyeRenderDesc eyeRenderDescOut[2] );
 
 
-// Begins a frame, returning timing and orientation information useful for simulation.
-// This should be called in the beginning of game rendering loop (on render thread).
-// This function relies on ovrHmd_BeginFrameTiming for some of its functionality.
-// Pass 0 for frame index if not using GetFrameTiming.
+/// Begins a frame, returning timing information.
+/// This should be called at the beginning of the game rendering loop (on the render thread).
+/// Pass 0 for the frame index if not using ovrHmd_GetFrameTiming.
 OVR_EXPORT ovrFrameTiming ovrHmd_BeginFrame(ovrHmd hmd, unsigned int frameIndex);
 
-// Ends frame, rendering textures to frame buffer. This may perform distortion and scaling
-// internally, assuming is it not delegated to another thread. 
-// Must be called on the same thread as BeginFrame. Calls ovrHmd_BeginEndTiming internally.
-// *** This Function will to Present/SwapBuffers and potentially wait for GPU Sync ***.
-OVR_EXPORT void     ovrHmd_EndFrame(ovrHmd hmd);
-
-
-// Marks beginning of eye rendering. Must be called on the same thread as BeginFrame.
-// This function uses ovrHmd_GetEyePose to predict sensor state that should be
-// used rendering the specified eye.
-// This combines current absolute time with prediction that is appropriate for this HMD.
-// It is ok to call ovrHmd_BeginEyeRender() on both eyes before calling ovrHmd_EndEyeRender.
-// If rendering one eye at a time, it is best to render eye specified by
-// HmdDesc.EyeRenderOrder[0] first.
-OVR_EXPORT ovrPosef ovrHmd_BeginEyeRender(ovrHmd hmd, ovrEyeType eye);
-
-// Marks the end of eye rendering and submits the eye texture for display after it is ready.
-// Rendering viewport within the texture can change per frame if necessary.
-// Specified texture may be presented immediately or wait until ovrHmd_EndFrame based
-// on the implementation. The API performs distortion and scaling internally.
-// 'renderPose' will typically be the value returned from ovrHmd_BeginEyeRender, but can
-// be different if a different pose was used for rendering.
-OVR_EXPORT void     ovrHmd_EndEyeRender(ovrHmd hmd, ovrEyeType eye,
-                                        ovrPosef renderPose, ovrTexture* eyeTexture);
+/// Ends a frame, submitting the rendered textures to the frame buffer.
+/// - RenderViewport within each eyeTexture can change per frame if necessary.
+/// - 'renderPose' will typically be the value returned from ovrHmd_GetEyePose, 
+///   but can be different if a different head pose was used for rendering.
+/// - This may perform distortion and scaling internally, assuming is it not 
+///   delegated to another thread. 
+/// - Must be called on the same thread as BeginFrame.
+/// - *** This Function will call Present/SwapBuffers and potentially wait for GPU Sync ***.
+OVR_EXPORT void     ovrHmd_EndFrame(ovrHmd hmd,
+                                    const ovrPosef renderPose[2],
+                                    const ovrTexture eyeTexture[2]);
+
+
+/// Returns the predicted head pose to use when rendering the specified eye.
+/// - Must be called between ovrHmd_BeginFrameTiming and ovrHmd_EndFrameTiming.
+/// - If the pose is used for rendering the eye, it should be passed to ovrHmd_EndFrame.
+OVR_EXPORT ovrPosef ovrHmd_GetEyePose(ovrHmd hmd, ovrEyeType eye);
 
 
 
 //-------------------------------------------------------------------------------------
-// *****  Game-Side Rendering Functions
+// *****  Client Distortion Rendering Functions
 
-// These functions provide distortion data and render timing support necessary to allow
-// game rendering of distortion. Game-side rendering involves the following steps:
+// These functions provide the distortion data and render timing support necessary to allow
+// client rendering of distortion. Client-side rendering involves the following steps:
 //
-//  1. Setup ovrEyeDesc based on desired texture size and Fov.
+//  1. Setup ovrEyeDesc based on the desired texture size and FOV.
 //     Call ovrHmd_GetRenderDesc to get the necessary rendering parameters for each eye.
 // 
-//  2. Use ovrHmd_CreateDistortionMesh to generate distortion mesh.
+//  2. Use ovrHmd_CreateDistortionMesh to generate the distortion mesh.
 //
-//  3. Use ovrHmd_BeginFrameTiming, ovrHmd_GetEyePose and ovrHmd_BeginFrameTiming
-//     in the rendering loop to obtain timing and predicted view orientation for
-//     each eye.
-//      - If relying on timewarp, use ovr_WaitTillTime after rendering+flush, followed
-//        by ovrHmd_GetEyeTimewarpMatrices to obtain timewarp matrices used 
-//        in distortion pixel shader to reduce latency.
+//  3. Use ovrHmd_BeginFrameTiming, ovrHmd_GetEyePose, and ovrHmd_BeginFrameTiming
+//     in the rendering loop to obtain timing and predicted head orientation when
+//     rendering each eye.
+//      - When using timewarp, use ovr_WaitTillTime after the rendering and gpu flush, followed
+//        by ovrHmd_GetEyeTimewarpMatrices to obtain the timewarp matrices used 
+//        by the distortion pixel shader. This will minimize latency.
 //
 
-// Computes distortion viewport, view adjust and other rendering for the specified
-// eye. This can be used instead of ovrHmd_ConfigureRendering to help setup rendering on
-// the game side.
+/// Computes the distortion viewport, view adjust, and other rendering parameters for 
+/// the specified eye. This can be used instead of ovrHmd_ConfigureRendering to do 
+/// setup for client rendered distortion.
 OVR_EXPORT ovrEyeRenderDesc ovrHmd_GetRenderDesc(ovrHmd hmd,
                                                  ovrEyeType eyeType, ovrFovPort fov);
 
 
-// Describes a vertex used for distortion; this is intended to be converted into
-// the engine-specific format.
-// Some fields may be unused based on ovrDistortionCaps selected. TexG and TexB, for example,
-// are not used if chromatic correction is not requested.
+/// Describes a vertex used by the distortion mesh. This is intended to be converted into
+/// the engine-specific format. Some fields may be unused based on the ovrDistortionCaps 
+/// flags selected. TexG and TexB, for example, are not used if chromatic correction is 
+/// not requested.
 typedef struct ovrDistortionVertex_
 {
-    ovrVector2f Pos;
+    ovrVector2f ScreenPosNDC;    // [-1,+1],[-1,+1] over the entire framebuffer.
     float       TimeWarpFactor;  // Lerp factor between time-warp matrices. Can be encoded in Pos.z.
     float       VignetteFactor;  // Vignette fade factor. Can be encoded in Pos.w.
-    ovrVector2f TexR;
-    ovrVector2f TexG;
-    ovrVector2f TexB;    
+    ovrVector2f TanEyeAnglesR;
+    ovrVector2f TanEyeAnglesG;
+    ovrVector2f TanEyeAnglesB;    
 } ovrDistortionVertex;
 
-// Describes a full set of distortion mesh data, filled in by ovrHmd_CreateDistortionMesh.
-// Contents of this data structure, if not null, should be freed by ovrHmd_DestroyDistortionMesh.
+/// Describes a full set of distortion mesh data, filled in by ovrHmd_CreateDistortionMesh.
+/// Contents of this data structure, if not null, should be freed by ovrHmd_DestroyDistortionMesh.
 typedef struct ovrDistortionMesh_
 {
     ovrDistortionVertex* pVertexData;
@@ -627,82 +675,80 @@ typedef struct ovrDistortionMesh_
     unsigned int         IndexCount;
 } ovrDistortionMesh;
 
-// Generate distortion mesh per eye.
-// Distortion capabilities will depend on 'distortionCaps' flags; user should rely on
-// appropriate shaders based on their settings.
-// Distortion mesh data will be allocated and stored into the ovrDistortionMesh data structure,
-// which should be explicitly freed with ovrHmd_DestroyDistortionMesh.
-// Users should call ovrHmd_GetRenderScaleAndOffset to get uvScale and Offset values for rendering.
-// The function shouldn't fail unless theres is a configuration or memory error, in which case
-// ovrDistortionMesh values will be set to null.
+/// Generate distortion mesh per eye.
+/// Distortion capabilities will depend on 'distortionCaps' flags. Users should 
+/// render using the appropriate shaders based on their settings.
+/// Distortion mesh data will be allocated and written into the ovrDistortionMesh data structure,
+/// which should be explicitly freed with ovrHmd_DestroyDistortionMesh.
+/// Users should call ovrHmd_GetRenderScaleAndOffset to get uvScale and Offset values for rendering.
+/// The function shouldn't fail unless theres is a configuration or memory error, in which case
+/// ovrDistortionMesh values will be set to null.
+/// This is the only function in the SDK reliant on eye relief, currently imported from profiles, 
+/// or overriden here.
 OVR_EXPORT ovrBool  ovrHmd_CreateDistortionMesh( ovrHmd hmd,
                                                  ovrEyeType eyeType, ovrFovPort fov,
                                                  unsigned int distortionCaps,
-                                                 ovrDistortionMesh *meshData );
+                                                 ovrDistortionMesh *meshData);
 
-// Frees distortion mesh allocated by ovrHmd_GenerateDistortionMesh. meshData elements
-// are set to null and zeroes after the call.
+/// Used to free the distortion mesh allocated by ovrHmd_GenerateDistortionMesh. meshData elements
+/// are set to null and zeroes after the call.
 OVR_EXPORT void     ovrHmd_DestroyDistortionMesh( ovrDistortionMesh* meshData );
 
-// Computes updated 'uvScaleOffsetOut' to be used with a distortion if render target size or
-// viewport changes after the fact. This can be used to adjust render size every frame, if desired.
+/// Computes updated 'uvScaleOffsetOut' to be used with a distortion if render target size or
+/// viewport changes after the fact. This can be used to adjust render size every frame if desired.
 OVR_EXPORT void     ovrHmd_GetRenderScaleAndOffset( ovrFovPort fov,
                                                     ovrSizei textureSize, ovrRecti renderViewport,
                                                     ovrVector2f uvScaleOffsetOut[2] );
 
 
-// Thread-safe timing function for the main thread. Caller should increment frameIndex
-// with every frame and pass the index to RenderThread for processing.
+/// Thread-safe timing function for the main thread. Caller should increment frameIndex
+/// with every frame and pass the index where applicable to functions called on the 
+/// rendering thread.
 OVR_EXPORT ovrFrameTiming ovrHmd_GetFrameTiming(ovrHmd hmd, unsigned int frameIndex);
 
-// Called at the beginning of the frame on the Render Thread.
-// Pass frameIndex == 0 if ovrHmd_GetFrameTiming isn't being used. Otherwise,
-// pass the same frame index as was used for GetFrameTiming on the main thread.
+/// Called at the beginning of the frame on the rendering thread.
+/// Pass frameIndex == 0 if ovrHmd_GetFrameTiming isn't being used. Otherwise,
+/// pass the same frame index as was used for GetFrameTiming on the main thread.
 OVR_EXPORT ovrFrameTiming ovrHmd_BeginFrameTiming(ovrHmd hmd, unsigned int frameIndex);
 
-// Marks the end of game-rendered frame, tracking the necessary timing information. This
-// function must be called immediately after Present/SwapBuffers + GPU sync. GPU sync is important
-// before this call to reduce latency and ensure proper timing.
+/// Marks the end of client distortion rendered frame, tracking the necessary timing information.
+/// This function must be called immediately after Present/SwapBuffers + GPU sync. GPU sync is
+/// important before this call to reduce latency and ensure proper timing.
 OVR_EXPORT void     ovrHmd_EndFrameTiming(ovrHmd hmd);
 
-// Initializes and resets frame time tracking. This is typically not necessary, but
-// is helpful if game changes vsync state or video mode. vsync is assumed to be on if this
-// isn't called. Resets internal frame index to the specified number.
+/// Initializes and resets frame time tracking. This is typically not necessary, but
+/// is helpful if game changes vsync state or video mode. vsync is assumed to be on if this
+/// isn't called. Resets internal frame index to the specified number.
 OVR_EXPORT void     ovrHmd_ResetFrameTiming(ovrHmd hmd, unsigned int frameIndex);
 
 
-// Predicts and returns Pose that should be used rendering the specified eye.
-// Must be called between ovrHmd_BeginFrameTiming & ovrHmd_EndFrameTiming.
-OVR_EXPORT ovrPosef ovrHmd_GetEyePose(ovrHmd hmd, ovrEyeType eye);
-
-// Computes timewarp matrices used by distortion mesh shader, these are used to adjust
-// for orientation change since the last call to ovrHmd_GetEyePose for this eye.
-// The ovrDistortionVertex::TimeWarpFactor is used to blend between the matrices,
-// usually representing two different sides of the screen.
-// Must be called on the same thread as ovrHmd_BeginFrameTiming.
+/// Computes timewarp matrices used by distortion mesh shader, these are used to adjust
+/// for head orientation change since the last call to ovrHmd_GetEyePose when rendering
+/// this eye. The ovrDistortionVertex::TimeWarpFactor is used to blend between the
+/// matrices, usually representing two different sides of the screen.
+/// Must be called on the same thread as ovrHmd_BeginFrameTiming.
 OVR_EXPORT void     ovrHmd_GetEyeTimewarpMatrices(ovrHmd hmd, ovrEyeType eye,
                                                   ovrPosef renderPose, ovrMatrix4f twmOut[2]);
 
 
-
 //-------------------------------------------------------------------------------------
 // ***** Stateless math setup functions
 
-// Used to generate projection from ovrEyeDesc::Fov.
+/// Used to generate projection from ovrEyeDesc::Fov.
 OVR_EXPORT ovrMatrix4f ovrMatrix4f_Projection( ovrFovPort fov,
                                                float znear, float zfar, ovrBool rightHanded );
 
-// Used for 2D rendering, Y is down
-// orthoScale = 1.0f / pixelsPerTanAngleAtCenter
-// orthoDistance = distance from camera, such as 0.8m
+/// Used for 2D rendering, Y is down
+/// orthoScale = 1.0f / pixelsPerTanAngleAtCenter
+/// orthoDistance = distance from camera, such as 0.8m
 OVR_EXPORT ovrMatrix4f ovrMatrix4f_OrthoSubProjection(ovrMatrix4f projection, ovrVector2f orthoScale,
                                                       float orthoDistance, float eyeViewAdjustX);
 
-// Returns global, absolute high-resolution time in seconds. This is the same
-// value as used in sensor messages.
+/// Returns global, absolute high-resolution time in seconds. This is the same
+/// value as used in sensor messages.
 OVR_EXPORT double   ovr_GetTimeInSeconds();
 
-// Waits until the specified absolute time.
+/// Waits until the specified absolute time.
 OVR_EXPORT double   ovr_WaitTillTime(double absTime);
 
 
@@ -710,17 +756,72 @@ OVR_EXPORT double   ovr_WaitTillTime(double absTime);
 // -----------------------------------------------------------------------------------
 // ***** Latency Test interface
 
-// Does latency test processing and returns 'TRUE' if specified rgb color should
-// be used to clear the screen.
+/// Does latency test processing and returns 'TRUE' if specified rgb color should
+/// be used to clear the screen.
 OVR_EXPORT ovrBool      ovrHmd_ProcessLatencyTest(ovrHmd hmd, unsigned char rgbColorOut[3]);
 
-// Returns non-null string once with latency test result, when it is available.
-// Buffer is valid until next call.
+/// Returns non-null string once with latency test result, when it is available.
+/// Buffer is valid until next call.
 OVR_EXPORT const char*  ovrHmd_GetLatencyTestResult(ovrHmd hmd);
 
-// Returns latency for HMDs that support internal latency testing via the
-// pixel-read back method (-1 for invalid or N/A)
-OVR_EXPORT double       ovrHmd_GetMeasuredLatencyTest2(ovrHmd hmd);
+
+
+//-------------------------------------------------------------------------------------
+// ***** Health and Safety Warning Display interface
+//
+
+/// Used by ovrhmd_GetHSWDisplayState to report the current display state.
+typedef struct ovrHSWDisplayState_
+{
+    /// If true then the warning should be currently visible
+    /// and the following variables have meaning. Else there is no
+    /// warning being displayed for this application on the given HMD.
+    ovrBool Displayed;
+    double  StartTime;       /// Absolute time when the warning was first displayed. See ovr_GetTimeInSeconds().
+    double  DismissibleTime; /// Earliest absolute time when the warning can be dismissed. May be a time in the past.
+} ovrHSWDisplayState;
+
+/// Returns the current state of the HSW display. If the application is doing the rendering of
+/// the HSW display then this function serves to indicate that the the warning should be 
+/// currently displayed. If the application is using SDK-based eye rendering then the SDK by 
+/// default automatically handles the drawing of the HSW display. An application that uses 
+/// application-based eye rendering should use this function to know when to start drawing the
+/// HSW display itself and can optionally use it in conjunction with ovrhmd_DismissHSWDisplay
+/// as described below.
+///
+/// Example usage for application-based rendering:
+///    bool HSWDisplayCurrentlyDisplayed = false; // global or class member variable
+///    ovrHSWDisplayState hswDisplayState;
+///    ovrhmd_GetHSWDisplayState(Hmd, &hswDisplayState);
+///
+///    if (hswDisplayState.Displayed && !HSWDisplayCurrentlyDisplayed) {
+///        <insert model into the scene that stays in front of the user>
+///        HSWDisplayCurrentlyDisplayed = true;
+///    }
+OVR_EXPORT void ovrHmd_GetHSWDisplayState(ovrHmd hmd, ovrHSWDisplayState *hasWarningState);
+
+/// Dismisses the HSW display if the warning is dismissible and the earliest dismissal time 
+/// has occurred. Returns true if the display is valid and could be dismissed. The application 
+/// should recognize that the HSW display is being displayed (via ovrhmd_GetHSWDisplayState)
+/// and if so then call this function when the appropriate user input to dismiss the warning
+/// occurs.
+///
+/// Example usage :
+///    void ProcessEvent(int key) {
+///        if(key == escape) {
+///            ovrHSWDisplayState hswDisplayState;
+///            ovrhmd_GetHSWDisplayState(hmd, &hswDisplayState);
+///
+///            if(hswDisplayState.Displayed && ovrhmd_DismissHSWDisplay(hmd)) {
+///                <remove model from the scene>
+///                HSWDisplayCurrentlyDisplayed = false;
+///            }
+///        }
+///    }
+OVR_EXPORT ovrBool ovrHmd_DismissHSWDisplay(ovrHmd hmd);
+
+
+
 
 
 // -----------------------------------------------------------------------------------
@@ -742,45 +843,62 @@ OVR_EXPORT double       ovrHmd_GetMeasuredLatencyTest2(ovrHmd hmd);
     #define OVR_KEY_PLAYER_HEIGHT               "PlayerHeight"
     #define OVR_KEY_EYE_HEIGHT                  "EyeHeight"
     #define OVR_KEY_IPD                         "IPD"
-    #define OVR_KEY_NECK_TO_EYE_HORIZONTAL      "NeckEyeHori"
-    #define OVR_KEY_NECK_TO_EYE_VERTICAL        "NeckEyeVert"
-
-    #define OVR_DEFAULT_GENDER                  "Male"
-    #define OVR_DEFAULT_PLAYER_HEIGHT           1.778f
-    #define OVR_DEFAULT_EYE_HEIGHT              1.675f
-    #define OVR_DEFAULT_IPD                     0.064f
-    #define OVR_DEFAULT_NECK_TO_EYE_HORIZONTAL  0.12f
-    #define OVR_DEFAULT_NECK_TO_EYE_VERTICAL    0.12f
+    #define OVR_KEY_NECK_TO_EYE_DISTANCE        "NeckEyeDistance"
+
+	// TODO: remove this duplication with OVR_Profile.h
+	// Default measurements empirically determined at Oculus to make us happy
+	// The neck model numbers were derived as an average of the male and female averages from ANSUR-88
+	// NECK_TO_EYE_HORIZONTAL = H22 - H43 = INFRAORBITALE_BACK_OF_HEAD - TRAGION_BACK_OF_HEAD
+	// NECK_TO_EYE_VERTICAL = H21 - H15 = GONION_TOP_OF_HEAD - ECTOORBITALE_TOP_OF_HEAD
+	// These were determined to be the best in a small user study, clearly beating out the previous default values
+	#define OVR_DEFAULT_GENDER                  "Unknown"
+	#define OVR_DEFAULT_PLAYER_HEIGHT           1.778f
+	#define OVR_DEFAULT_EYE_HEIGHT              1.675f
+	#define OVR_DEFAULT_IPD                     0.064f
+	#define OVR_DEFAULT_NECK_TO_EYE_HORIZONTAL  0.0805f
+	#define OVR_DEFAULT_NECK_TO_EYE_VERTICAL    0.075f
+	#define OVR_DEFAULT_EYE_RELIEF_DIAL         3
 #endif
 
+/// Get boolean property. Returns first element if property is a boolean array.
+/// Returns defaultValue if property doesn't exist.
+OVR_EXPORT ovrBool      ovrHmd_GetBool(ovrHmd hmd, const char* propertyName, ovrBool defaultVal);
 
-// Get float property. Returns first element if property is a float array.
-// Returns defaultValue if property doesn't exist.
-OVR_EXPORT float       ovrHmd_GetFloat(ovrHmd hmd, const char* propertyName, float defaultVal);
+/// Modify bool property; false if property doesn't exist or is readonly.
+OVR_EXPORT ovrBool      ovrHmd_SetBool(ovrHmd hmd, const char* propertyName, ovrBool value);
 
-// Modify float property; false if property doesn't exist or is readonly.
-OVR_EXPORT ovrBool      ovrHmd_SetFloat(ovrHmd hmd, const char* propertyName, float value);
+/// Get integer property. Returns first element if property is an integer array.
+/// Returns defaultValue if property doesn't exist.
+OVR_EXPORT int          ovrHmd_GetInt(ovrHmd hmd, const char* propertyName, int defaultVal);
+
+/// Modify integer property; false if property doesn't exist or is readonly.
+OVR_EXPORT ovrBool      ovrHmd_SetInt(ovrHmd hmd, const char* propertyName, int value);
 
+/// Get float property. Returns first element if property is a float array.
+/// Returns defaultValue if property doesn't exist.
+OVR_EXPORT float        ovrHmd_GetFloat(ovrHmd hmd, const char* propertyName, float defaultVal);
 
-// Get float[] property. Returns the number of elements filled in, 0 if property doesn't exist.
-// Maximum of arraySize elements will be written.
+/// Modify float property; false if property doesn't exist or is readonly.
+OVR_EXPORT ovrBool      ovrHmd_SetFloat(ovrHmd hmd, const char* propertyName, float value);
+
+/// Get float[] property. Returns the number of elements filled in, 0 if property doesn't exist.
+/// Maximum of arraySize elements will be written.
 OVR_EXPORT unsigned int ovrHmd_GetFloatArray(ovrHmd hmd, const char* propertyName,
                                             float values[], unsigned int arraySize);
 
-// Modify float[] property; false if property doesn't exist or is readonly.
+/// Modify float[] property; false if property doesn't exist or is readonly.
 OVR_EXPORT ovrBool      ovrHmd_SetFloatArray(ovrHmd hmd, const char* propertyName,
                                              float values[], unsigned int arraySize);
 
-// Get string property. Returns first element if property is a string array.
-// Returns defaultValue if property doesn't exist.
-// String memory is guaranteed to exist until next call to GetString or GetStringArray, or HMD is destroyed.
-OVR_EXPORT const char* ovrHmd_GetString(ovrHmd hmd, const char* propertyName,
+/// Get string property. Returns first element if property is a string array.
+/// Returns defaultValue if property doesn't exist.
+/// String memory is guaranteed to exist until next call to GetString or GetStringArray, or HMD is destroyed.
+OVR_EXPORT const char*  ovrHmd_GetString(ovrHmd hmd, const char* propertyName,
                                         const char* defaultVal);
 
-// Returns array size of a property, 0 if property doesn't exist.
-// Can be used to check existence of a property.
-OVR_EXPORT unsigned int ovrHmd_GetArraySize(ovrHmd hmd, const char* propertyName);
-
+/// Set string property
+OVR_EXPORT ovrBool ovrHmd_SetString(ovrHmd hmddesc, const char* propertyName,
+                                    const char* value);
 
 #ifdef __cplusplus 
 } // extern "C"