diff options
Diffstat (limited to 'LibOVR/Src/OVR_Stereo.h')
| -rw-r--r-- | LibOVR/Src/OVR_Stereo.h | 460 |
1 files changed, 460 insertions, 0 deletions
diff --git a/LibOVR/Src/OVR_Stereo.h b/LibOVR/Src/OVR_Stereo.h new file mode 100644 index 0000000..bd5438d --- /dev/null +++ b/LibOVR/Src/OVR_Stereo.h @@ -0,0 +1,460 @@ +/************************************************************************************ + +PublicHeader: OVR.h +Filename : OVR_Stereo.h +Content : Stereo rendering functions +Created : November 30, 2013 +Authors : Tom Fosyth + +Copyright : Copyright 2014 Oculus VR, Inc. All Rights reserved. + +Licensed under the Oculus VR Rift SDK License Version 3.1 (the "License"); +you may not use the Oculus VR Rift SDK except in compliance with the License, +which is provided at the time of installation or download, or which +otherwise accompanies this software in either electronic or hard copy form. + +You may obtain a copy of the License at + +http://www.oculusvr.com/licenses/LICENSE-3.1 + +Unless required by applicable law or agreed to in writing, the Oculus VR SDK +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. + +*************************************************************************************/ + +#ifndef OVR_Stereo_h +#define OVR_Stereo_h + +#include "OVR_Device.h" + +// CAPI Forward declaration. +typedef struct ovrFovPort_ ovrFovPort; +typedef struct ovrRecti_ ovrRecti; + +namespace OVR { + +//----------------------------------------------------------------------------------- +// ***** Stereo Enumerations + +// StereoEye specifies which eye we are rendering for; it is used to +// retrieve StereoEyeParams. +enum StereoEye +{ + StereoEye_Center, + StereoEye_Left, + StereoEye_Right +}; + + +//----------------------------------------------------------------------------------- +// ***** FovPort + +// FovPort describes Field Of View (FOV) of a viewport. +// This class has values for up, down, left and right, stored in +// tangent of the angle units to simplify calculations. +// +// As an example, for a standard 90 degree vertical FOV, we would +// have: { UpTan = tan(90 degrees / 2), DownTan = tan(90 degrees / 2) }. +// +// CreateFromRadians/Degrees helper functions can be used to +// access FOV in different units. + +struct FovPort +{ + float UpTan; + float DownTan; + float LeftTan; + float RightTan; + + FovPort ( float sideTan = 0.0f ) : + UpTan(sideTan), DownTan(sideTan), LeftTan(sideTan), RightTan(sideTan) { } + FovPort ( float u, float d, float l, float r ) : + UpTan(u), DownTan(d), LeftTan(l), RightTan(r) { } + + // C-interop support: FovPort <-> ovrFovPort (implementation in OVR_CAPI.cpp). + FovPort (const ovrFovPort &src); + operator const ovrFovPort () const; + + + static FovPort CreateFromRadians(float horizontalFov, float verticalFov) + { + FovPort result; + result.UpTan = tanf ( verticalFov * 0.5f ); + result.DownTan = tanf ( verticalFov * 0.5f ); + result.LeftTan = tanf ( horizontalFov * 0.5f ); + result.RightTan = tanf ( horizontalFov * 0.5f ); + return result; + } + + static FovPort CreateFromDegrees(float horizontalFovDegrees, + float verticalFovDegrees) + { + return CreateFromRadians(DegreeToRad(horizontalFovDegrees), + DegreeToRad(verticalFovDegrees)); + } + + // Get Horizontal/Vertical components of Fov in radians. + float GetVerticalFovRadians() const { return atanf(UpTan) + atanf(DownTan); } + float GetHorizontalFovRadians() const { return atanf(LeftTan) + atanf(RightTan); } + // Get Horizontal/Vertical components of Fov in degrees. + float GetVerticalFovDegrees() const { return RadToDegree(GetVerticalFovRadians()); } + float GetHorizontalFovDegrees() const { return RadToDegree(GetHorizontalFovRadians()); } + + // Compute maximum tangent value among all four sides. + float GetMaxSideTan() const + { + return Alg::Max(Alg::Max(UpTan, DownTan), Alg::Max(LeftTan, RightTan)); + } + + // Converts Fov Tan angle units to [-1,1] render target NDC space + Vector2f TanAngleToRendertargetNDC(Vector2f const &tanEyeAngle); + + + // Compute per-channel minimum and maximum of Fov. + static FovPort Min(const FovPort& a, const FovPort& b) + { + FovPort fov( Alg::Min( a.UpTan , b.UpTan ), + Alg::Min( a.DownTan , b.DownTan ), + Alg::Min( a.LeftTan , b.LeftTan ), + Alg::Min( a.RightTan, b.RightTan ) ); + return fov; + } + + static FovPort Max(const FovPort& a, const FovPort& b) + { + FovPort fov( Alg::Max( a.UpTan , b.UpTan ), + Alg::Max( a.DownTan , b.DownTan ), + Alg::Max( a.LeftTan , b.LeftTan ), + Alg::Max( a.RightTan, b.RightTan ) ); + return fov; + } +}; + + + +//----------------------------------------------------------------------------------- +// ***** ScaleAndOffset + +struct ScaleAndOffset2D +{ + Vector2f Scale; + Vector2f Offset; + + ScaleAndOffset2D(float sx = 0.0f, float sy = 0.0f, float ox = 0.0f, float oy = 0.0f) + : Scale(sx, sy), Offset(ox, oy) + { } +}; + + +//----------------------------------------------------------------------------------- +// ***** Misc. utility functions. + +// Inputs are 4 points (pFitX[0],pFitY[0]) through (pFitX[3],pFitY[3]) +// Result is four coefficients in pResults[0] through pResults[3] such that +// y = pResult[0] + x * ( pResult[1] + x * ( pResult[2] + x * ( pResult[3] ) ) ); +// passes through all four input points. +// Return is true if it succeeded, false if it failed (because two control points +// have the same pFitX value). +bool FitCubicPolynomial ( float *pResult, const float *pFitX, const float *pFitY ); + +//----------------------------------------------------------------------------------- +// ***** LensConfig + +// LensConfig describes the configuration of a single lens in an HMD. +// - Eqn and K[] describe a distortion function. +// - MetersPerTanAngleAtCenter is the relationship between distance on a +// screen (at the center of the lens), and the angle variance of the light after it +// has passed through the lens. +// - ChromaticAberration is an array of parameters for controlling +// additional Red and Blue scaling in order to reduce chromatic aberration +// caused by the Rift lenses. +struct LensConfig +{ + // The result is a scaling applied to the distance from the center of the lens. + float DistortionFnScaleRadiusSquared (float rsq) const; + // x,y,z components map to r,g,b scales. + Vector3f DistortionFnScaleRadiusSquaredChroma (float rsq) const; + + // DistortionFn applies distortion to the argument. + // Input: the distance in TanAngle/NIC space from the optical center to the input pixel. + // Output: the resulting distance after distortion. + float DistortionFn(float r) const + { + return r * DistortionFnScaleRadiusSquared ( r * r ); + } + + // DistortionFnInverse computes the inverse of the distortion function on an argument. + float DistortionFnInverse(float r) const; + + // Also computes the inverse, but using a polynomial approximation. Warning - it's just an approximation! + float DistortionFnInverseApprox(float r) const; + // Sets up InvK[]. + void SetUpInverseApprox(); + + // Sets a bunch of sensible defaults. + void SetToIdentity(); + + + + enum { NumCoefficients = 11 }; + + DistortionEqnType Eqn; + float K[NumCoefficients]; + float MaxR; // The highest R you're going to query for - the curve is unpredictable beyond it. + + float MetersPerTanAngleAtCenter; + + // Additional per-channel scaling is applied after distortion: + // Index [0] - Red channel constant coefficient. + // Index [1] - Red channel r^2 coefficient. + // Index [2] - Blue channel constant coefficient. + // Index [3] - Blue channel r^2 coefficient. + float ChromaticAberration[4]; + + float InvK[NumCoefficients]; + float MaxInvR; +}; + + +// For internal use - storing and loading lens config data + +// Returns true on success. +bool LoadLensConfig ( LensConfig *presult, UByte const *pbuffer, int bufferSizeInBytes ); + +// Returns number of bytes needed. +int SaveLensConfigSizeInBytes ( LensConfig const &config ); +// Returns true on success. +bool SaveLensConfig ( UByte *pbuffer, int bufferSizeInBytes, LensConfig const &config ); + + +//----------------------------------------------------------------------------------- +// ***** DistortionRenderDesc + +// This describes distortion for a single eye in an HMD with a display, not just the lens by itself. +struct DistortionRenderDesc +{ + // The raw lens values. + LensConfig Lens; + + // These map from [-1,1] across the eye being rendered into TanEyeAngle space (but still distorted) + Vector2f LensCenter; + Vector2f TanEyeAngleScale; + // Computed from device characteristics, IPD and eye-relief. + // (not directly used for rendering, but very useful) + Vector2f PixelsPerTanAngleAtCenter; +}; + + + +//----------------------------------------------------------------------------------- +// ***** HmdRenderInfo + +// All the parts of the HMD info that are needed to set up the rendering system. + +struct HmdRenderInfo +{ + // The start of this sturucture is intentionally very similar to HMDInfo in OVER_Device.h + // However to reduce interdependencies, one does not simply #include the other. + + HmdTypeEnum HmdType; + + // Size of the entire screen + Size<int> ResolutionInPixels; + Size<float> ScreenSizeInMeters; + float ScreenGapSizeInMeters; + + // Characteristics of the lenses. + float CenterFromTopInMeters; + float LensSeparationInMeters; + float LensDiameterInMeters; + float LensSurfaceToMidplateInMeters; + EyeCupType EyeCups; + + // Timing & shutter data. All values in seconds. + struct ShutterInfo + { + HmdShutterTypeEnum Type; + float VsyncToNextVsync; // 1/framerate + float VsyncToFirstScanline; // for global shutter, vsync->shutter open. + float FirstScanlineToLastScanline; // for global shutter, will be zero. + float PixelSettleTime; // estimated. + float PixelPersistence; // Full persistence = 1/framerate. + } Shutter; + + + // These are all set from the user's profile. + struct EyeConfig + { + // Distance from center of eyeball to front plane of lens. + float ReliefInMeters; + // Distance from nose (technically, center of Rift) to the middle of the eye. + float NoseToPupilInMeters; + + LensConfig Distortion; + } EyeLeft, EyeRight; + + + HmdRenderInfo() + { + HmdType = HmdType_None; + ResolutionInPixels.w = 0; + ResolutionInPixels.h = 0; + ScreenSizeInMeters.w = 0.0f; + ScreenSizeInMeters.h = 0.0f; + ScreenGapSizeInMeters = 0.0f; + CenterFromTopInMeters = 0.0f; + LensSeparationInMeters = 0.0f; + LensDiameterInMeters = 0.0f; + LensSurfaceToMidplateInMeters = 0.0f; + Shutter.Type = HmdShutter_LAST; + Shutter.VsyncToNextVsync = 0.0f; + Shutter.VsyncToFirstScanline = 0.0f; + Shutter.FirstScanlineToLastScanline = 0.0f; + Shutter.PixelSettleTime = 0.0f; + Shutter.PixelPersistence = 0.0f; + EyeCups = EyeCup_DK1A; + EyeLeft.ReliefInMeters = 0.0f; + EyeLeft.NoseToPupilInMeters = 0.0f; + EyeLeft.Distortion.SetToIdentity(); + EyeRight = EyeLeft; + } + + // The "center eye" is the position the HMD tracking returns, + // and games will also usually use it for audio, aiming reticles, some line-of-sight tests, etc. + EyeConfig GetEyeCenter() const + { + EyeConfig result; + result.ReliefInMeters = 0.5f * ( EyeLeft.ReliefInMeters + EyeRight.ReliefInMeters ); + result.NoseToPupilInMeters = 0.0f; + result.Distortion.SetToIdentity(); + return result; + } + +}; + + + + +//----------------------------------------------------------------------------------- + +// Stateless computation functions, in somewhat recommended execution order. +// For examples on how to use many of them, see the StereoConfig::UpdateComputedState function. + +const float OVR_DEFAULT_EXTRA_EYE_ROTATION = 30.0f * Math<float>::DegreeToRadFactor; + +// Creates a dummy debug HMDInfo matching a particular HMD model. +// Useful for development without an actual HMD attached. +HMDInfo CreateDebugHMDInfo(HmdTypeEnum hmdType); + + +// profile may be NULL, in which case it uses the hard-coded defaults. +// distortionType should be left at the default unless you require something specific for your distortion shaders. +// eyeCupOverride can be EyeCup_LAST, in which case it uses the one in the profile. +HmdRenderInfo GenerateHmdRenderInfoFromHmdInfo ( HMDInfo const &hmdInfo, + Profile const *profile = NULL, + DistortionEqnType distortionType = Distortion_CatmullRom10, + EyeCupType eyeCupOverride = EyeCup_LAST ); + +LensConfig GenerateLensConfigFromEyeRelief ( float eyeReliefInMeters, HmdRenderInfo const &hmd, + DistortionEqnType distortionType = Distortion_CatmullRom10 ); + +DistortionRenderDesc CalculateDistortionRenderDesc ( StereoEye eyeType, HmdRenderInfo const &hmd, + LensConfig const *pLensOverride = NULL ); + +FovPort CalculateFovFromEyePosition ( float eyeReliefInMeters, + float offsetToRightInMeters, + float offsetDownwardsInMeters, + float lensDiameterInMeters, + float extraEyeRotationInRadians = OVR_DEFAULT_EXTRA_EYE_ROTATION); + +FovPort CalculateFovFromHmdInfo ( StereoEye eyeType, + DistortionRenderDesc const &distortion, + HmdRenderInfo const &hmd, + float extraEyeRotationInRadians = OVR_DEFAULT_EXTRA_EYE_ROTATION ); + +FovPort GetPhysicalScreenFov ( StereoEye eyeType, DistortionRenderDesc const &distortion ); + +FovPort ClampToPhysicalScreenFov ( StereoEye eyeType, DistortionRenderDesc const &distortion, + FovPort inputFovPort ); + +Sizei CalculateIdealPixelSize ( StereoEye eyeType, DistortionRenderDesc const &distortion, + FovPort fov, float pixelsPerDisplayPixel ); + +Recti GetFramebufferViewport ( StereoEye eyeType, HmdRenderInfo const &hmd ); + +Matrix4f CreateProjection ( bool rightHanded, FovPort fov, + float zNear = 0.01f, float zFar = 10000.0f ); + +Matrix4f CreateOrthoSubProjection ( bool rightHanded, StereoEye eyeType, + float tanHalfFovX, float tanHalfFovY, + float unitsX, float unitsY, float distanceFromCamera, + float interpupillaryDistance, Matrix4f const &projection, + float zNear = 0.0f, float zFar = 0.0f ); + +ScaleAndOffset2D CreateNDCScaleAndOffsetFromFov ( FovPort fov ); + +ScaleAndOffset2D CreateUVScaleAndOffsetfromNDCScaleandOffset ( ScaleAndOffset2D scaleAndOffsetNDC, + Recti renderedViewport, + Sizei renderTargetSize ); + + +//----------------------------------------------------------------------------------- +// ***** StereoEyeParams + +// StereoEyeParams describes RenderDevice configuration needed to render +// the scene for one eye. +struct StereoEyeParams +{ + StereoEye Eye; + Matrix4f ViewAdjust; // Translation to be applied to view matrix. + + // Distortion and the VP on the physical display - the thing to run the distortion shader on. + DistortionRenderDesc Distortion; + Recti DistortionViewport; + + // Projection and VP of a particular view (you could have multiple of these). + Recti RenderedViewport; // Viewport that we render the standard scene to. + FovPort Fov; // The FOVs of this scene. + Matrix4f RenderedProjection; // Projection matrix used with this eye. + ScaleAndOffset2D EyeToSourceNDC; // Mapping from TanEyeAngle space to [-1,+1] on the rendered image. + ScaleAndOffset2D EyeToSourceUV; // Mapping from TanEyeAngle space to actual texture UV coords. +}; + + +//----------------------------------------------------------------------------------- +// A set of "forward-mapping" functions, mapping from framebuffer space to real-world and/or texture space. +Vector2f TransformScreenNDCToTanFovSpace ( DistortionRenderDesc const &distortion, + const Vector2f &framebufferNDC ); +void TransformScreenNDCToTanFovSpaceChroma ( Vector2f *resultR, Vector2f *resultG, Vector2f *resultB, + DistortionRenderDesc const &distortion, + const Vector2f &framebufferNDC ); +Vector2f TransformTanFovSpaceToRendertargetTexUV ( StereoEyeParams const &eyeParams, + Vector2f const &tanEyeAngle ); +Vector2f TransformTanFovSpaceToRendertargetNDC ( StereoEyeParams const &eyeParams, + Vector2f const &tanEyeAngle ); +Vector2f TransformScreenPixelToScreenNDC( Recti const &distortionViewport, + Vector2f const &pixel ); +Vector2f TransformScreenPixelToTanFovSpace ( Recti const &distortionViewport, + DistortionRenderDesc const &distortion, + Vector2f const &pixel ); +Vector2f TransformScreenNDCToRendertargetTexUV( DistortionRenderDesc const &distortion, + StereoEyeParams const &eyeParams, + Vector2f const &pixel ); +Vector2f TransformScreenPixelToRendertargetTexUV( Recti const &distortionViewport, + DistortionRenderDesc const &distortion, + StereoEyeParams const &eyeParams, + Vector2f const &pixel ); + +// A set of "reverse-mapping" functions, mapping from real-world and/or texture space back to the framebuffer. +// Be aware that many of these are significantly slower than their forward-mapping counterparts. +Vector2f TransformTanFovSpaceToScreenNDC( DistortionRenderDesc const &distortion, + const Vector2f &tanEyeAngle, bool usePolyApprox = false ); +Vector2f TransformRendertargetNDCToTanFovSpace( const ScaleAndOffset2D &eyeToSourceNDC, + const Vector2f &textureNDC ); + +} //namespace OVR + +#endif // OVR_Stereo_h
\ No newline at end of file |