mirror of
https://github.com/mii443/rust-openvr.git
synced 2025-08-26 18:19:28 +00:00
460 lines
19 KiB
C++
460 lines
19 KiB
C++
/************************************************************************************
|
|
|
|
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 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
|