diff options
Diffstat (limited to 'LibOVR/Src/OVR_CAPI.h')
| -rw-r--r-- | LibOVR/Src/OVR_CAPI.h | 790 |
1 files changed, 790 insertions, 0 deletions
diff --git a/LibOVR/Src/OVR_CAPI.h b/LibOVR/Src/OVR_CAPI.h new file mode 100644 index 0000000..ec4708c --- /dev/null +++ b/LibOVR/Src/OVR_CAPI.h @@ -0,0 +1,790 @@ +/************************************************************************************ + +Filename : OVR_CAPI.h +Content : C Interface to Oculus sensors and rendering. +Created : November 23, 2013 +Authors : Michael Antonov + +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_CAPI_h +#define OVR_CAPI_h + +#include <stdint.h> + +typedef char ovrBool; + +//----------------------------------------------------------------------------------- +// ***** OVR_EXPORT definition + +#if !defined(OVR_EXPORT) + #if defined(WIN32) + #define OVR_EXPORT __declspec(dllexport) + #else + #define OVR_EXPORT + #endif +#endif + +//----------------------------------------------------------------------------------- +// ***** Simple Math Structures + +// 2D integer +typedef struct ovrVector2i_ +{ + int x, y; +} ovrVector2i; +typedef struct ovrSizei_ +{ + int w, h; +} ovrSizei; +typedef struct ovrRecti_ +{ + ovrVector2i Pos; + ovrSizei Size; +} ovrRecti; + +// 3D +typedef struct ovrQuatf_ +{ + float x, y, z, w; +} ovrQuatf; +typedef struct ovrVector2f_ +{ + float x, y; +} ovrVector2f; +typedef struct ovrVector3f_ +{ + float x, y, z; +} ovrVector3f; +typedef struct ovrMatrix4f_ +{ + float M[4][4]; +} ovrMatrix4f; +// Position and orientation together. +typedef struct ovrPosef_ +{ + ovrQuatf Orientation; + ovrVector3f Position; +} ovrPosef; + +// Full pose (rigid body) configuration with first and second derivatives. +typedef struct ovrPoseStatef_ +{ + ovrPosef Pose; + ovrVector3f AngularVelocity; + ovrVector3f LinearVelocity; + ovrVector3f AngularAcceleration; + ovrVector3f LinearAcceleration; + 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) }. +typedef struct ovrFovPort_ +{ + float UpTan; + float DownTan; + float LeftTan; + float RightTan; +} ovrFovPort; + + +//----------------------------------------------------------------------------------- +// ***** HMD Types + +// Enumerates all HMD types that we support. +typedef enum +{ + ovrHmd_None = 0, + ovrHmd_DK1 = 3, + ovrHmd_DKHD = 4, + ovrHmd_CrystalCoveProto = 5, + ovrHmd_DK2 = 6, + ovrHmd_Other // Some HMD other then the one in the enumeration. +} ovrHmdType; + +// 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). + + // 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. + */ + + // 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_NoVSync = 0x1000, + ovrHmdCap_NoRestore = 0x4000, + + // These bits can be modified by ovrHmd_SetEnabledCaps. + ovrHmdCap_Writable_Mask = 0x1380 +} ovrHmdCaps; + + +// Sensor capability bits reported by device. +// Used with ovrHmd_StartSensor. +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. +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. +} 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. +typedef enum +{ + ovrEye_Left = 0, + ovrEye_Right = 1, + ovrEye_Count = 2 +} ovrEyeType; + + +// Handle to HMD; returned by ovrHmd_Create. +typedef struct ovrHmdStruct* ovrHmd; + +// This is a complete descriptor of the HMD. +typedef struct ovrHmdDesc_ +{ + ovrHmd Handle; // Handle of this HMD. + ovrHmdType Type; + + // Name string describing the product: "Oculus Rift DK1", etc. + const char* ProductName; + const char* Manufacturer; + + // Capability bits described by ovrHmdCaps. + unsigned int HmdCaps; + // Capability bits described by ovrSensorCaps. + unsigned int SensorCaps; + // 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. + ovrFovPort DefaultEyeFov[ovrEye_Count]; + ovrFovPort MaxEyeFov[ovrEye_Count]; + + // 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. + const char* DisplayDeviceName; + // MacOS + int DisplayId; +} ovrHmdDesc; + +// Describes the type of positional tracking being done. +/* +typedef enum +{ + ovrPose_None, + ovrPose_HeadModel, + ovrPose_Positional +} ovrPoseType; +*/ + + +// 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. +} ovrStatusBits; + + +// State of the sensor at a given absolute time. +typedef struct ovrSensorState_ +{ + // 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; + +// For now. +// TBD: Decide if this becomes a part of HMDDesc +typedef struct ovrSensorDesc_ +{ + // HID Vendor and ProductId of the device. + short VendorId; + short ProductId; + // Sensor (and display) serial number. + char SerialNumber[24]; +} ovrSensorDesc; + + + +// Frame data reported by ovrHmd_BeginFrameTiming(). +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. + float DeltaSeconds; + + // It is generally expected that the following hold: + // 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. + double ThisFrameSeconds; + // 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. + 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. + double ScanoutMidpointSeconds; + // Timing points when each eye will be scanned out to display. Used for 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. +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. +} 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. + +typedef enum +{ + ovrRenderAPI_None, + ovrRenderAPI_OpenGL, + ovrRenderAPI_Android_GLES, // May include extra native window pointers, etc. + ovrRenderAPI_D3D9, + ovrRenderAPI_D3D10, + ovrRenderAPI_D3D11, + ovrRenderAPI_Count +} ovrRenderAPIType; + +// Platform-independent part of rendering API-configuration data. +// It is a part of ovrRenderAPIConfig, passed to ovrHmd_Configure. +typedef struct ovrRenderAPIConfigHeader_ +{ + ovrRenderAPIType API; + ovrSizei RTSize; + int Multisample; +} ovrRenderAPIConfigHeader; + +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. +typedef struct ovrTextureHeader_ +{ + ovrRenderAPIType API; + ovrSizei TextureSize; + ovrRecti RenderViewport; // Pixel viewport in texture that holds eye image. +} ovrTextureHeader; + +typedef struct ovrTexture_ +{ + ovrTextureHeader Header; + uintptr_t PlatformData[8]; +} ovrTexture; + + +// ----------------------------------------------------------------------------------- +// ***** API Interfaces + +// 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. +// 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. +// +// 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. +// +// Shutdown: +// 9. ovrHmd_Destroy(hmd) +// 10. ovr_Shutdown() +// + +#ifdef __cplusplus +extern "C" { +#endif + +// 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. +OVR_EXPORT ovrBool ovr_Initialize(); +OVR_EXPORT void ovr_Shutdown(); + + +// 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. +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. +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). +OVR_EXPORT const char* ovrHmd_GetLastError(ovrHmd hmd); + + +//------------------------------------------------------------------------------------- + +// 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. +OVR_EXPORT unsigned int ovrHmd_GetEnabledCaps(ovrHmd hmd); + +// 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); + + +//------------------------------------------------------------------------------------- +// ***** 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. +OVR_EXPORT ovrSizei ovrHmd_GetFovTextureSize(ovrHmd hmd, ovrEyeType eye, ovrFovPort fov, + float pixelsPerDisplayPixel); + + + +//------------------------------------------------------------------------------------- +// ***** 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 +// frames on another thread, but explicit synchronization must be done since +// functions that depend on configured state are not reentrant. +// +// As an extra requirement, any of the following calls must be done on +// 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 + +// 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. +// +OVR_EXPORT ovrBool ovrHmd_ConfigureRendering( ovrHmd hmd, + 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. +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); + + + +//------------------------------------------------------------------------------------- +// ***** Game-Side 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: +// +// 1. Setup ovrEyeDesc based on 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. +// +// 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. +// + +// 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. +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. +typedef struct ovrDistortionVertex_ +{ + ovrVector2f Pos; + 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; +} 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. +typedef struct ovrDistortionMesh_ +{ + ovrDistortionVertex* pVertexData; + unsigned short* pIndexData; + unsigned int VertexCount; + 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. +OVR_EXPORT ovrBool ovrHmd_CreateDistortionMesh( ovrHmd hmd, + ovrEyeType eyeType, ovrFovPort fov, + unsigned int distortionCaps, + ovrDistortionMesh *meshData ); + +// Frees 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. +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. +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. +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. +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. +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. +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. +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 +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. +OVR_EXPORT double ovr_GetTimeInSeconds(); + +// Waits until the specified absolute time. +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. +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. +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); + + +// ----------------------------------------------------------------------------------- +// ***** Property Access + +// NOTICE: This is experimental part of API that is likely to go away or change. + +// These allow accessing different properties of the HMD and profile. +// Some of the properties may go away with profile/HMD versions, so software should +// use defaults and/or proper fallbacks. +// + +// For now, access profile entries; this will change. +#if !defined(OVR_KEY_USER) + + #define OVR_KEY_USER "User" + #define OVR_KEY_NAME "Name" + #define OVR_KEY_GENDER "Gender" + #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 +#endif + + +// 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 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. +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, + 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); + + +#ifdef __cplusplus +} // extern "C" +#endif + + +#endif // OVR_CAPI_h |