1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/LibOVR/Src/OVR_Stereo.h	Wed Jan 14 06:51:16 2015 +0200
     1.3 @@ -0,0 +1,681 @@
     1.4 +/************************************************************************************
     1.5 +
     1.6 +Filename    :   OVR_Stereo.h
     1.7 +Content     :   Stereo rendering functions
     1.8 +Created     :   November 30, 2013
     1.9 +Authors     :   Tom Fosyth
    1.10 +
    1.11 +Copyright   :   Copyright 2014 Oculus VR, LLC All Rights reserved.
    1.12 +
    1.13 +Licensed under the Oculus VR Rift SDK License Version 3.2 (the "License"); 
    1.14 +you may not use the Oculus VR Rift SDK except in compliance with the License, 
    1.15 +which is provided at the time of installation or download, or which 
    1.16 +otherwise accompanies this software in either electronic or hard copy form.
    1.17 +
    1.18 +You may obtain a copy of the License at
    1.19 +
    1.20 +http://www.oculusvr.com/licenses/LICENSE-3.2 
    1.21 +
    1.22 +Unless required by applicable law or agreed to in writing, the Oculus VR SDK 
    1.23 +distributed under the License is distributed on an "AS IS" BASIS,
    1.24 +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    1.25 +See the License for the specific language governing permissions and
    1.26 +limitations under the License.
    1.27 +
    1.28 +*************************************************************************************/
    1.29 +
    1.30 +#ifndef OVR_Stereo_h
    1.31 +#define OVR_Stereo_h
    1.32 +
    1.33 +#include "Sensors/OVR_DeviceConstants.h"
    1.34 +#include "Displays/OVR_Display.h"
    1.35 +#include "OVR_Profile.h"
    1.36 +
    1.37 +// CAPI Forward declaration.
    1.38 +typedef struct ovrFovPort_ ovrFovPort;
    1.39 +typedef struct ovrRecti_ ovrRecti;
    1.40 +
    1.41 +namespace OVR {
    1.42 +
    1.43 +class SensorDevice; // Opaque forward declaration
    1.44 +
    1.45 +
    1.46 +//-----------------------------------------------------------------------------------
    1.47 +// ***** Stereo Enumerations
    1.48 +
    1.49 +// StereoEye specifies which eye we are rendering for; it is used to
    1.50 +// retrieve StereoEyeParams.
    1.51 +enum StereoEye
    1.52 +{
    1.53 +    StereoEye_Center,
    1.54 +    StereoEye_Left,
    1.55 +    StereoEye_Right    
    1.56 +};
    1.57 +
    1.58 +
    1.59 +//-----------------------------------------------------------------------------------
    1.60 +// ***** FovPort
    1.61 +
    1.62 +// FovPort describes Field Of View (FOV) of a viewport.
    1.63 +// This class has values for up, down, left and right, stored in 
    1.64 +// tangent of the angle units to simplify calculations.
    1.65 +//
    1.66 +// As an example, for a standard 90 degree vertical FOV, we would 
    1.67 +// have: { UpTan = tan(90 degrees / 2), DownTan = tan(90 degrees / 2) }.
    1.68 +//
    1.69 +// CreateFromRadians/Degrees helper functions can be used to
    1.70 +// access FOV in different units.
    1.71 +
    1.72 +struct FovPort
    1.73 +{
    1.74 +    float UpTan;
    1.75 +    float DownTan;
    1.76 +    float LeftTan;
    1.77 +    float RightTan;
    1.78 +
    1.79 +    FovPort ( float sideTan = 0.0f ) :
    1.80 +        UpTan(sideTan), DownTan(sideTan), LeftTan(sideTan), RightTan(sideTan) { }
    1.81 +    FovPort ( float u, float d, float l, float r ) :
    1.82 +        UpTan(u), DownTan(d), LeftTan(l), RightTan(r) { }
    1.83 +
    1.84 +    // C-interop support: FovPort <-> ovrFovPort (implementation in OVR_CAPI.cpp).
    1.85 +    FovPort(const ovrFovPort& src);
    1.86 +    operator ovrFovPort () const;
    1.87 +
    1.88 +    static FovPort CreateFromRadians(float horizontalFov, float verticalFov)
    1.89 +    {
    1.90 +        FovPort result;
    1.91 +        result.UpTan    = tanf (   verticalFov * 0.5f );
    1.92 +        result.DownTan  = tanf (   verticalFov * 0.5f );
    1.93 +        result.LeftTan  = tanf ( horizontalFov * 0.5f );
    1.94 +        result.RightTan = tanf ( horizontalFov * 0.5f );
    1.95 +        return result;
    1.96 +    }
    1.97 +
    1.98 +    static FovPort CreateFromDegrees(float horizontalFovDegrees,
    1.99 +                                     float verticalFovDegrees)
   1.100 +    {
   1.101 +        return CreateFromRadians(DegreeToRad(horizontalFovDegrees),
   1.102 +                                 DegreeToRad(verticalFovDegrees));
   1.103 +    }
   1.104 +
   1.105 +    //  Get Horizontal/Vertical components of Fov in radians.
   1.106 +    float GetVerticalFovRadians() const     { return atanf(UpTan)    + atanf(DownTan); }
   1.107 +    float GetHorizontalFovRadians() const   { return atanf(LeftTan)  + atanf(RightTan); }
   1.108 +    //  Get Horizontal/Vertical components of Fov in degrees.
   1.109 +    float GetVerticalFovDegrees() const     { return RadToDegree(GetVerticalFovRadians()); }
   1.110 +    float GetHorizontalFovDegrees() const   { return RadToDegree(GetHorizontalFovRadians()); }
   1.111 +
   1.112 +    // Compute maximum tangent value among all four sides.
   1.113 +    float GetMaxSideTan() const
   1.114 +    {
   1.115 +        return Alg::Max(Alg::Max(UpTan, DownTan), Alg::Max(LeftTan, RightTan));
   1.116 +    }
   1.117 +
   1.118 +    // Converts Fov Tan angle units to [-1,1] render target NDC space
   1.119 +    Vector2f TanAngleToRendertargetNDC(Vector2f const &tanEyeAngle);
   1.120 +
   1.121 +
   1.122 +    // Compute per-channel minimum and maximum of Fov.
   1.123 +    static FovPort Min(const FovPort& a, const FovPort& b)
   1.124 +    {   
   1.125 +        FovPort fov( Alg::Min( a.UpTan   , b.UpTan    ),   
   1.126 +                     Alg::Min( a.DownTan , b.DownTan  ),
   1.127 +                     Alg::Min( a.LeftTan , b.LeftTan  ),
   1.128 +                     Alg::Min( a.RightTan, b.RightTan ) );
   1.129 +        return fov;
   1.130 +    }
   1.131 +
   1.132 +    static FovPort Max(const FovPort& a, const FovPort& b)
   1.133 +    {   
   1.134 +        FovPort fov( Alg::Max( a.UpTan   , b.UpTan    ),   
   1.135 +                     Alg::Max( a.DownTan , b.DownTan  ),
   1.136 +                     Alg::Max( a.LeftTan , b.LeftTan  ),
   1.137 +                     Alg::Max( a.RightTan, b.RightTan ) );
   1.138 +        return fov;
   1.139 +    }
   1.140 +};
   1.141 +
   1.142 +
   1.143 +//-----------------------------------------------------------------------------------
   1.144 +// ***** ScaleAndOffset
   1.145 +
   1.146 +struct ScaleAndOffset2D
   1.147 +{
   1.148 +    Vector2f Scale;
   1.149 +    Vector2f Offset;
   1.150 +
   1.151 +    ScaleAndOffset2D(float sx = 0.0f, float sy = 0.0f, float ox = 0.0f, float oy = 0.0f)
   1.152 +      : Scale(sx, sy), Offset(ox, oy)        
   1.153 +    { }
   1.154 +};
   1.155 +
   1.156 +
   1.157 +//-----------------------------------------------------------------------------------
   1.158 +// ***** Misc. utility functions.
   1.159 +
   1.160 +// Inputs are 4 points (pFitX[0],pFitY[0]) through (pFitX[3],pFitY[3])
   1.161 +// Result is four coefficients in pResults[0] through pResults[3] such that
   1.162 +//      y = pResult[0] + x * ( pResult[1] + x * ( pResult[2] + x * ( pResult[3] ) ) );
   1.163 +// passes through all four input points.
   1.164 +// Return is true if it succeeded, false if it failed (because two control points
   1.165 +// have the same pFitX value).
   1.166 +bool FitCubicPolynomial ( float *pResult, const float *pFitX, const float *pFitY );
   1.167 +
   1.168 +//-----------------------------------------------------------------------------------
   1.169 +// ***** LensConfig
   1.170 +
   1.171 +// LensConfig describes the configuration of a single lens in an HMD.
   1.172 +// - Eqn and K[] describe a distortion function.
   1.173 +// - MetersPerTanAngleAtCenter is the relationship between distance on a
   1.174 +//   screen (at the center of the lens), and the angle variance of the light after it
   1.175 +//   has passed through the lens.
   1.176 +// - ChromaticAberration is an array of parameters for controlling
   1.177 +//   additional Red and Blue scaling in order to reduce chromatic aberration
   1.178 +//   caused by the Rift lenses.
   1.179 +struct LensConfig
   1.180 +{
   1.181 +    LensConfig()
   1.182 +      : Eqn(Distortion_CatmullRom10)
   1.183 +      //K()
   1.184 +      , MaxR(0.0f)
   1.185 +      , MetersPerTanAngleAtCenter(0.0f)
   1.186 +      //ChromaticAberration()
   1.187 +      //InvK()
   1.188 +      , MaxInvR(0.0f)
   1.189 +    {
   1.190 +        memset(&K, 0, sizeof(K));
   1.191 +        memset(&ChromaticAberration, 0, sizeof(ChromaticAberration));
   1.192 +        memset(&InvK, 0, sizeof(InvK));
   1.193 +    }
   1.194 +    
   1.195 +    // The result is a scaling applied to the distance from the center of the lens.
   1.196 +    float    DistortionFnScaleRadiusSquared (float rsq) const;
   1.197 +    // x,y,z components map to r,g,b scales.
   1.198 +    Vector3f DistortionFnScaleRadiusSquaredChroma (float rsq) const;
   1.199 +
   1.200 +    // DistortionFn applies distortion to the argument.
   1.201 +    // Input: the distance in TanAngle/NIC space from the optical center to the input pixel.
   1.202 +    // Output: the resulting distance after distortion.
   1.203 +    float DistortionFn(float r) const
   1.204 +    {
   1.205 +        return r * DistortionFnScaleRadiusSquared ( r * r );
   1.206 +    }
   1.207 +
   1.208 +    // DistortionFnInverse computes the inverse of the distortion function on an argument.
   1.209 +    float DistortionFnInverse(float r) const;
   1.210 +
   1.211 +    // Also computes the inverse, but using a polynomial approximation. Warning - it's just an approximation!
   1.212 +    float DistortionFnInverseApprox(float r) const;
   1.213 +    // Sets up InvK[].
   1.214 +    void SetUpInverseApprox();
   1.215 +
   1.216 +    // Sets a bunch of sensible defaults.
   1.217 +    void SetToIdentity();
   1.218 +
   1.219 +
   1.220 +
   1.221 +    enum { NumCoefficients = 11 };
   1.222 +
   1.223 +    DistortionEqnType   Eqn;
   1.224 +    float               K[NumCoefficients];
   1.225 +    float               MaxR;       // The highest R you're going to query for - the curve is unpredictable beyond it.
   1.226 +
   1.227 +    float               MetersPerTanAngleAtCenter;
   1.228 +
   1.229 +    // Additional per-channel scaling is applied after distortion:
   1.230 +    //  Index [0] - Red channel constant coefficient.
   1.231 +    //  Index [1] - Red channel r^2 coefficient.
   1.232 +    //  Index [2] - Blue channel constant coefficient.
   1.233 +    //  Index [3] - Blue channel r^2 coefficient.
   1.234 +    float               ChromaticAberration[4];
   1.235 +
   1.236 +    float               InvK[NumCoefficients];
   1.237 +    float               MaxInvR;
   1.238 +};
   1.239 +
   1.240 +
   1.241 +// For internal use - storing and loading lens config data
   1.242 +
   1.243 +// Returns true on success.
   1.244 +bool LoadLensConfig ( LensConfig *presult, uint8_t const *pbuffer, int bufferSizeInBytes );
   1.245 +
   1.246 +// Returns number of bytes needed.
   1.247 +int SaveLensConfigSizeInBytes ( LensConfig const &config );
   1.248 +// Returns true on success.
   1.249 +bool SaveLensConfig ( uint8_t *pbuffer, int bufferSizeInBytes, LensConfig const &config );
   1.250 +
   1.251 +
   1.252 +//-----------------------------------------------------------------------------------
   1.253 +// ***** DistortionRenderDesc
   1.254 +
   1.255 +// This describes distortion for a single eye in an HMD with a display, not just the lens by itself.
   1.256 +struct DistortionRenderDesc
   1.257 +{
   1.258 +    // The raw lens values.
   1.259 +    LensConfig          Lens;
   1.260 +
   1.261 +    // These map from [-1,1] across the eye being rendered into TanEyeAngle space (but still distorted)
   1.262 +    Vector2f            LensCenter;
   1.263 +    Vector2f            TanEyeAngleScale;
   1.264 +    // Computed from device characteristics, IPD and eye-relief.
   1.265 +    // (not directly used for rendering, but very useful)
   1.266 +    Vector2f            PixelsPerTanAngleAtCenter;
   1.267 +};
   1.268 +
   1.269 +
   1.270 +//-------------------------------------------------------------------------------------
   1.271 +// ***** HMDInfo 
   1.272 +
   1.273 +// This structure describes various aspects of the HMD allowing us to configure rendering.
   1.274 +//
   1.275 +//  Currently included data:
   1.276 +//   - Physical screen dimensions, resolution, and eye distances.
   1.277 +//     (some of these will be configurable with a tool in the future).
   1.278 +//     These arguments allow us to properly setup projection across HMDs.
   1.279 +//   - DisplayDeviceName for identifying HMD screen; system-specific interpretation.
   1.280 +//
   1.281 +// TBD:
   1.282 +//  - Power on/ off?
   1.283 +//  - Sensor rates and capabilities
   1.284 +//  - Distortion radius/variables    
   1.285 +//  - Screen update frequency
   1.286 +//  - Distortion needed flag
   1.287 +//  - Update modes:
   1.288 +//      Set update mode: Stereo (both sides together), mono (same in both eyes),
   1.289 +//                       Alternating, Alternating scan-lines.
   1.290 +
   1.291 +// Win32 Oculus VR Display Driver Shim Information
   1.292 +struct Win32ShimInfo
   1.293 +{
   1.294 +	int DeviceNumber;
   1.295 +	int NativeWidth;
   1.296 +	int NativeHeight;
   1.297 +	int Rotation;
   1.298 +	int UseMirroring;
   1.299 +
   1.300 +	Win32ShimInfo() :
   1.301 +		DeviceNumber(-1),
   1.302 +		NativeWidth(-1),
   1.303 +		NativeHeight(-1),
   1.304 +		Rotation(-1),
   1.305 +		UseMirroring(1)
   1.306 +	{
   1.307 +	}
   1.308 +};
   1.309 +
   1.310 +class HMDInfo
   1.311 +{
   1.312 +public:
   1.313 +	// Name string describing the product: "Oculus Rift DK1", etc.
   1.314 +	String      ProductName;
   1.315 +	String      Manufacturer;
   1.316 +
   1.317 +	unsigned    Version;
   1.318 +
   1.319 +	// Characteristics of the HMD screen and enclosure
   1.320 +	HmdTypeEnum HmdType;
   1.321 +	Size<int>   ResolutionInPixels;
   1.322 +	Size<float> ScreenSizeInMeters;
   1.323 +	float       ScreenGapSizeInMeters;
   1.324 +	float       CenterFromTopInMeters;
   1.325 +	float       LensSeparationInMeters;
   1.326 +    Vector2f    PelOffsetR;                     // Offsets from the green pel in pixels (i.e. usual values are 0.5 or 0.333)
   1.327 +    Vector2f    PelOffsetB;
   1.328 +
   1.329 +
   1.330 +	// Timing & shutter data. All values in seconds.
   1.331 +	struct ShutterInfo
   1.332 +	{
   1.333 +		HmdShutterTypeEnum  Type;
   1.334 +		float   VsyncToNextVsync;                // 1/framerate
   1.335 +		float   VsyncToFirstScanline;            // for global shutter, vsync->shutter open.
   1.336 +		float   FirstScanlineToLastScanline;     // for global shutter, will be zero.
   1.337 +		float   PixelSettleTime;                 // estimated.
   1.338 +		float   PixelPersistence;                // Full persistence = 1/framerate.
   1.339 +	}           Shutter;
   1.340 +
   1.341 +	// Desktop coordinate position of the screen (can be negative; may not be present on all platforms)
   1.342 +	int         DesktopX;
   1.343 +	int         DesktopY;
   1.344 +
   1.345 +	// Windows:
   1.346 +	// "\\\\.\\DISPLAY3", etc. Can be used in EnumDisplaySettings/CreateDC.
   1.347 +	String      DisplayDeviceName;
   1.348 +	Win32ShimInfo ShimInfo;
   1.349 +
   1.350 +	// MacOS:
   1.351 +	int         DisplayId;
   1.352 +
   1.353 +	bool	    InCompatibilityMode;
   1.354 +
   1.355 +	// Printed serial number for the HMD; should match external sticker
   1.356 +    String      PrintedSerial;
   1.357 +
   1.358 +    // Tracker descriptor information:
   1.359 +    int         VendorId;
   1.360 +    int         ProductId;
   1.361 +    int         FirmwareMajor;
   1.362 +    int         FirmwareMinor;
   1.363 +
   1.364 +    float   CameraFrustumHFovInRadians;
   1.365 +    float   CameraFrustumVFovInRadians;
   1.366 +    float   CameraFrustumNearZInMeters;
   1.367 +    float   CameraFrustumFarZInMeters;
   1.368 +
   1.369 +	// Constructor initializes all values to 0s.
   1.370 +	// To create a "virtualized" HMDInfo, use CreateDebugHMDInfo instead.
   1.371 +	HMDInfo() :
   1.372 +		ProductName(),
   1.373 +        Manufacturer(),
   1.374 +        Version(0),
   1.375 +		HmdType(HmdType_None),
   1.376 +		ResolutionInPixels(0),
   1.377 +		ScreenSizeInMeters(0.0f),
   1.378 +		ScreenGapSizeInMeters(0.0f),
   1.379 +		CenterFromTopInMeters(0),
   1.380 +		LensSeparationInMeters(0),
   1.381 +        PelOffsetR(0.0f,0.0f),
   1.382 +        PelOffsetB(0.0f,0.0f),
   1.383 +      //Shutter (initialized below)
   1.384 +		DesktopX(0),
   1.385 +		DesktopY(0),
   1.386 +        DisplayDeviceName(),
   1.387 +        ShimInfo(),
   1.388 +		DisplayId(-1),
   1.389 +		InCompatibilityMode(false),
   1.390 +        PrintedSerial(),
   1.391 +        VendorId(-1),
   1.392 +        ProductId(-1),
   1.393 +        FirmwareMajor(-1),
   1.394 +        FirmwareMinor(-1),
   1.395 +        CameraFrustumHFovInRadians(0.0f),
   1.396 +        CameraFrustumVFovInRadians(0.0f),
   1.397 +        CameraFrustumNearZInMeters(0.0f),
   1.398 +        CameraFrustumFarZInMeters(0.0f)
   1.399 +	{
   1.400 +		Shutter.Type = HmdShutter_LAST;
   1.401 +		Shutter.VsyncToNextVsync = 0.0f;
   1.402 +		Shutter.VsyncToFirstScanline = 0.0f;
   1.403 +		Shutter.FirstScanlineToLastScanline = 0.0f;
   1.404 +		Shutter.PixelSettleTime = 0.0f;
   1.405 +		Shutter.PixelPersistence = 0.0f;
   1.406 +    }
   1.407 +
   1.408 +	// Operator = copies local fields only (base class must be correct already)
   1.409 +	void operator=(const HMDInfo& src)
   1.410 +	{
   1.411 +		ProductName = src.ProductName;
   1.412 +		Manufacturer = src.Manufacturer;
   1.413 +		Version = src.Version;
   1.414 +		HmdType = src.HmdType;
   1.415 +		ResolutionInPixels = src.ResolutionInPixels;
   1.416 +		ScreenSizeInMeters = src.ScreenSizeInMeters;
   1.417 +		ScreenGapSizeInMeters = src.ScreenGapSizeInMeters;
   1.418 +		CenterFromTopInMeters = src.CenterFromTopInMeters;
   1.419 +		LensSeparationInMeters = src.LensSeparationInMeters;
   1.420 +        PelOffsetR = src.PelOffsetR;
   1.421 +        PelOffsetB = src.PelOffsetB;
   1.422 +		DesktopX = src.DesktopX;
   1.423 +		DesktopY = src.DesktopY;
   1.424 +		Shutter = src.Shutter;
   1.425 +		DisplayDeviceName = src.DisplayDeviceName;
   1.426 +		ShimInfo = src.ShimInfo;
   1.427 +		DisplayId = src.DisplayId;
   1.428 +		InCompatibilityMode = src.InCompatibilityMode;
   1.429 +        VendorId = src.VendorId;
   1.430 +        ProductId = src.ProductId;
   1.431 +        FirmwareMajor = src.FirmwareMajor;
   1.432 +        FirmwareMinor = src.FirmwareMinor;
   1.433 +        PrintedSerial = src.PrintedSerial;
   1.434 +        CameraFrustumHFovInRadians = src.CameraFrustumHFovInRadians;
   1.435 +        CameraFrustumVFovInRadians = src.CameraFrustumVFovInRadians;
   1.436 +        CameraFrustumNearZInMeters = src.CameraFrustumNearZInMeters;
   1.437 +        CameraFrustumFarZInMeters = src.CameraFrustumFarZInMeters;
   1.438 +    }
   1.439 +
   1.440 +	void SetScreenParameters(int hres, int vres,
   1.441 +							 float hsize, float vsize,
   1.442 +							 float vCenterFromTopInMeters, float lensSeparationInMeters,
   1.443 +							 bool compatibilityMode)
   1.444 +	{
   1.445 +		ResolutionInPixels = Sizei(hres, vres);
   1.446 +		ScreenSizeInMeters = Sizef(hsize, vsize);
   1.447 +		CenterFromTopInMeters = vCenterFromTopInMeters;
   1.448 +		LensSeparationInMeters = lensSeparationInMeters;
   1.449 +		InCompatibilityMode = compatibilityMode;
   1.450 +	}
   1.451 +
   1.452 +	bool IsSameDisplay(const HMDInfo& o) const
   1.453 +	{
   1.454 +		return DisplayId == o.DisplayId &&
   1.455 +			DisplayDeviceName.CompareNoCase(o.DisplayDeviceName) == 0;
   1.456 +	}
   1.457 +
   1.458 +	static bool CreateFromSensorAndDisplay(SensorDevice* sensor, Display* display, HMDInfo* hmdi);
   1.459 +};
   1.460 +
   1.461 +
   1.462 +//-----------------------------------------------------------------------------------
   1.463 +// ***** HmdRenderInfo
   1.464 +
   1.465 +// All the parts of the HMD info that are needed to set up the rendering system.
   1.466 +
   1.467 +struct HmdRenderInfo
   1.468 +{
   1.469 +    // The start of this structure is intentionally very similar to HMDInfo in OVER_Device.h
   1.470 +    // However to reduce interdependencies, one does not simply #include the other.
   1.471 +
   1.472 +    HmdTypeEnum HmdType;
   1.473 +
   1.474 +    // Size of the entire screen
   1.475 +    Size<int>   ResolutionInPixels;
   1.476 +    Size<float> ScreenSizeInMeters;
   1.477 +    float       ScreenGapSizeInMeters;
   1.478 +    Vector2f    PelOffsetR;                     // Offsets from the green pel in pixels (i.e. usual values are 0.5 or 0.333)
   1.479 +    Vector2f    PelOffsetB;
   1.480 +
   1.481 +    // Characteristics of the lenses.
   1.482 +    float       CenterFromTopInMeters;
   1.483 +    float       LensSeparationInMeters;
   1.484 +    float       LensDiameterInMeters;
   1.485 +    float       LensSurfaceToMidplateInMeters;
   1.486 +    EyeCupType  EyeCups;
   1.487 +
   1.488 +    // Timing & shutter data. All values in seconds.
   1.489 +    struct ShutterInfo
   1.490 +    {
   1.491 +        HmdShutterTypeEnum  Type;
   1.492 +        float               VsyncToNextVsync;                // 1/framerate
   1.493 +        float               VsyncToFirstScanline;            // for global shutter, vsync->shutter open.
   1.494 +        float               FirstScanlineToLastScanline;     // for global shutter, will be zero.
   1.495 +        float               PixelSettleTime;                 // estimated.
   1.496 +        float               PixelPersistence;                // Full persistence = 1/framerate.
   1.497 +    }           Shutter;
   1.498 +
   1.499 +
   1.500 +    // These are all set from the user's profile.
   1.501 +    struct EyeConfig
   1.502 +    {
   1.503 +        // Distance from center of eyeball to front plane of lens.
   1.504 +        float               ReliefInMeters;
   1.505 +        // Distance from nose (technically, center of Rift) to the middle of the eye.
   1.506 +        float               NoseToPupilInMeters;
   1.507 +
   1.508 +        LensConfig          Distortion;
   1.509 +    } EyeLeft, EyeRight;
   1.510 +
   1.511 +
   1.512 +    HmdRenderInfo()
   1.513 +    {
   1.514 +        HmdType = HmdType_None;
   1.515 +        ResolutionInPixels.w = 0;
   1.516 +        ResolutionInPixels.h = 0;
   1.517 +        ScreenSizeInMeters.w = 0.0f;
   1.518 +        ScreenSizeInMeters.h = 0.0f;
   1.519 +        ScreenGapSizeInMeters = 0.0f;
   1.520 +        CenterFromTopInMeters = 0.0f;
   1.521 +        LensSeparationInMeters = 0.0f;
   1.522 +        LensDiameterInMeters = 0.0f;
   1.523 +        LensSurfaceToMidplateInMeters = 0.0f;
   1.524 +        PelOffsetR = Vector2f ( 0.0f, 0.0f );
   1.525 +        PelOffsetB = Vector2f ( 0.0f, 0.0f );
   1.526 +        Shutter.Type = HmdShutter_LAST;
   1.527 +        Shutter.VsyncToNextVsync = 0.0f;
   1.528 +        Shutter.VsyncToFirstScanline = 0.0f;
   1.529 +        Shutter.FirstScanlineToLastScanline = 0.0f;
   1.530 +        Shutter.PixelSettleTime = 0.0f;
   1.531 +        Shutter.PixelPersistence = 0.0f;
   1.532 +        EyeCups = EyeCup_DK1A;
   1.533 +        EyeLeft.ReliefInMeters = 0.0f;
   1.534 +        EyeLeft.NoseToPupilInMeters = 0.0f;
   1.535 +        EyeLeft.Distortion.SetToIdentity();
   1.536 +        EyeRight = EyeLeft;
   1.537 +    }
   1.538 +
   1.539 +    // The "center eye" is the position the HMD tracking returns,
   1.540 +    // and games will also usually use it for audio, aiming reticles, some line-of-sight tests, etc.
   1.541 +    EyeConfig GetEyeCenter() const
   1.542 +    {
   1.543 +        EyeConfig result;
   1.544 +        result.ReliefInMeters = 0.5f * ( EyeLeft.ReliefInMeters + EyeRight.ReliefInMeters );
   1.545 +        result.NoseToPupilInMeters = 0.0f;
   1.546 +        result.Distortion.SetToIdentity();
   1.547 +        return result;
   1.548 +    }
   1.549 +
   1.550 +};
   1.551 +
   1.552 +
   1.553 +//-----------------------------------------------------------------------------------
   1.554 +
   1.555 +// Stateless computation functions, in somewhat recommended execution order.
   1.556 +// For examples on how to use many of them, see the StereoConfig::UpdateComputedState function.
   1.557 +
   1.558 +const float OVR_DEFAULT_EXTRA_EYE_ROTATION = 30.0f * MATH_FLOAT_DEGREETORADFACTOR;
   1.559 +
   1.560 +// Creates a dummy debug HMDInfo matching a particular HMD model.
   1.561 +// Useful for development without an actual HMD attached.
   1.562 +HMDInfo             CreateDebugHMDInfo(HmdTypeEnum hmdType);
   1.563 +
   1.564 +
   1.565 +// profile may be NULL, in which case it uses the hard-coded defaults.
   1.566 +// distortionType should be left at the default unless you require something specific for your distortion shaders.
   1.567 +// eyeCupOverride can be EyeCup_LAST, in which case it uses the one in the profile.
   1.568 +HmdRenderInfo       GenerateHmdRenderInfoFromHmdInfo ( HMDInfo const &hmdInfo,
   1.569 +                                                       Profile const *profile = NULL,
   1.570 +                                                       DistortionEqnType distortionType = Distortion_CatmullRom10,
   1.571 +                                                       EyeCupType eyeCupOverride = EyeCup_LAST );
   1.572 +
   1.573 +LensConfig          GenerateLensConfigFromEyeRelief ( float eyeReliefInMeters, HmdRenderInfo const &hmd,
   1.574 +                                                      DistortionEqnType distortionType = Distortion_CatmullRom10 );
   1.575 +
   1.576 +DistortionRenderDesc CalculateDistortionRenderDesc ( StereoEye eyeType, HmdRenderInfo const &hmd,
   1.577 +                                                     LensConfig const *pLensOverride = NULL );
   1.578 +
   1.579 +FovPort             CalculateFovFromEyePosition ( float eyeReliefInMeters,
   1.580 +                                                  float offsetToRightInMeters,
   1.581 +                                                  float offsetDownwardsInMeters,
   1.582 +                                                  float lensDiameterInMeters,
   1.583 +                                                  float extraEyeRotationInRadians = OVR_DEFAULT_EXTRA_EYE_ROTATION);
   1.584 +
   1.585 +FovPort             CalculateFovFromHmdInfo ( StereoEye eyeType,
   1.586 +                                              DistortionRenderDesc const &distortion,
   1.587 +                                              HmdRenderInfo const &hmd,
   1.588 +                                              float extraEyeRotationInRadians = OVR_DEFAULT_EXTRA_EYE_ROTATION );
   1.589 +
   1.590 +FovPort             GetPhysicalScreenFov ( StereoEye eyeType, DistortionRenderDesc const &distortion );
   1.591 +
   1.592 +FovPort             ClampToPhysicalScreenFov ( StereoEye eyeType, DistortionRenderDesc const &distortion,
   1.593 +                                               FovPort inputFovPort );
   1.594 +
   1.595 +Sizei               CalculateIdealPixelSize ( StereoEye eyeType, DistortionRenderDesc const &distortion,
   1.596 +                                              FovPort fov, float pixelsPerDisplayPixel );
   1.597 +
   1.598 +Recti               GetFramebufferViewport ( StereoEye eyeType, HmdRenderInfo const &hmd );
   1.599 +
   1.600 +Matrix4f            CreateProjection ( bool rightHanded, FovPort fov,
   1.601 +                                       float zNear = 0.01f, float zFar = 10000.0f );
   1.602 +
   1.603 +Matrix4f            CreateOrthoSubProjection ( bool rightHanded, StereoEye eyeType,
   1.604 +                                               float tanHalfFovX, float tanHalfFovY,
   1.605 +                                               float unitsX, float unitsY, float distanceFromCamera,
   1.606 +                                               float interpupillaryDistance, Matrix4f const &projection,
   1.607 +                                               float zNear = 0.0f, float zFar = 0.0f );
   1.608 +
   1.609 +ScaleAndOffset2D    CreateNDCScaleAndOffsetFromFov ( FovPort fov );
   1.610 +
   1.611 +ScaleAndOffset2D    CreateUVScaleAndOffsetfromNDCScaleandOffset ( ScaleAndOffset2D scaleAndOffsetNDC,
   1.612 +                                                                  Recti renderedViewport,
   1.613 +                                                                  Sizei renderTargetSize );
   1.614 +
   1.615 +
   1.616 +//-----------------------------------------------------------------------------------
   1.617 +// ***** StereoEyeParams
   1.618 +
   1.619 +// StereoEyeParams describes RenderDevice configuration needed to render
   1.620 +// the scene for one eye. 
   1.621 +struct StereoEyeParams
   1.622 +{
   1.623 +    StereoEye               Eye;
   1.624 +    Matrix4f                HmdToEyeViewOffset;         // Translation to be applied to view matrix.
   1.625 +
   1.626 +    // Distortion and the VP on the physical display - the thing to run the distortion shader on.
   1.627 +    DistortionRenderDesc    Distortion;
   1.628 +    Recti                   DistortionViewport;
   1.629 +
   1.630 +    // Projection and VP of a particular view (you could have multiple of these).
   1.631 +    Recti                   RenderedViewport;       // Viewport that we render the standard scene to.
   1.632 +    FovPort                 Fov;                    // The FOVs of this scene.
   1.633 +    Matrix4f                RenderedProjection;     // Projection matrix used with this eye.
   1.634 +    ScaleAndOffset2D        EyeToSourceNDC;         // Mapping from TanEyeAngle space to [-1,+1] on the rendered image.
   1.635 +    ScaleAndOffset2D        EyeToSourceUV;          // Mapping from TanEyeAngle space to actual texture UV coords.
   1.636 +};
   1.637 +
   1.638 +
   1.639 +//-----------------------------------------------------------------------------------
   1.640 +// A set of "forward-mapping" functions, mapping from framebuffer space to real-world and/or texture space.
   1.641 +Vector2f TransformScreenNDCToTanFovSpace ( DistortionRenderDesc const &distortion,
   1.642 +                                           const Vector2f &framebufferNDC );
   1.643 +void TransformScreenNDCToTanFovSpaceChroma ( Vector2f *resultR, Vector2f *resultG, Vector2f *resultB, 
   1.644 +                                             DistortionRenderDesc const &distortion,
   1.645 +                                             const Vector2f &framebufferNDC );
   1.646 +Vector2f TransformTanFovSpaceToRendertargetTexUV ( ScaleAndOffset2D const &eyeToSourceUV,
   1.647 +                                                   Vector2f const &tanEyeAngle );
   1.648 +Vector2f TransformTanFovSpaceToRendertargetNDC ( ScaleAndOffset2D const &eyeToSourceNDC,
   1.649 +                                                 Vector2f const &tanEyeAngle );
   1.650 +Vector2f TransformScreenPixelToScreenNDC( Recti const &distortionViewport,
   1.651 +                                          Vector2f const &pixel );
   1.652 +Vector2f TransformScreenPixelToTanFovSpace ( Recti const &distortionViewport,
   1.653 +                                             DistortionRenderDesc const &distortion,
   1.654 +                                             Vector2f const &pixel );
   1.655 +Vector2f TransformScreenNDCToRendertargetTexUV( DistortionRenderDesc const &distortion,
   1.656 +                                                StereoEyeParams const &eyeParams,
   1.657 +                                                Vector2f const &pixel );
   1.658 +Vector2f TransformScreenPixelToRendertargetTexUV( Recti const &distortionViewport,
   1.659 +                                                  DistortionRenderDesc const &distortion,
   1.660 +                                                  StereoEyeParams const &eyeParams,
   1.661 +                                                  Vector2f const &pixel );
   1.662 +
   1.663 +// A set of "reverse-mapping" functions, mapping from real-world and/or texture space back to the framebuffer.
   1.664 +// Be aware that many of these are significantly slower than their forward-mapping counterparts.
   1.665 +Vector2f TransformTanFovSpaceToScreenNDC( DistortionRenderDesc const &distortion,
   1.666 +                                          const Vector2f &tanEyeAngle, bool usePolyApprox = false );
   1.667 +Vector2f TransformRendertargetNDCToTanFovSpace( const ScaleAndOffset2D &eyeToSourceNDC,
   1.668 +                                                const Vector2f &textureNDC );
   1.669 +
   1.670 +// Handy wrappers.
   1.671 +inline Vector2f TransformTanFovSpaceToRendertargetTexUV ( StereoEyeParams const &eyeParams,
   1.672 +                                                          Vector2f const &tanEyeAngle )
   1.673 +{
   1.674 +    return TransformTanFovSpaceToRendertargetTexUV ( eyeParams.EyeToSourceUV, tanEyeAngle );
   1.675 +}
   1.676 +inline Vector2f TransformTanFovSpaceToRendertargetNDC ( StereoEyeParams const &eyeParams,
   1.677 +                                                        Vector2f const &tanEyeAngle )
   1.678 +{
   1.679 +    return TransformTanFovSpaceToRendertargetNDC ( eyeParams.EyeToSourceNDC, tanEyeAngle );
   1.680 +}
   1.681 +
   1.682 +} //namespace OVR
   1.683 +
   1.684 +#endif // OVR_Stereo_h