diff options
Diffstat (limited to 'LibOVR/Src/OVR_CAPI.h')
| -rw-r--r-- | LibOVR/Src/OVR_CAPI.h | 963 |
1 files changed, 0 insertions, 963 deletions
diff --git a/LibOVR/Src/OVR_CAPI.h b/LibOVR/Src/OVR_CAPI.h deleted file mode 100644 index a2b5e79..0000000 --- a/LibOVR/Src/OVR_CAPI.h +++ /dev/null @@ -1,963 +0,0 @@ -/************************************************************************************ - -Filename : OVR_CAPI.h -Content : C Interface to Oculus tracking and rendering. -Created : November 23, 2013 -Authors : Michael Antonov - -Copyright : Copyright 2014 Oculus VR, LLC All Rights reserved. - -Licensed under the Oculus VR Rift SDK License Version 3.2 (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.2 - -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. - -************************************************************************************/ - -/// @file OVR_CAPI.h -/// Exposes all general Rift functionality. - -#ifndef OVR_CAPI_h -#define OVR_CAPI_h - -#include <stdint.h> - -#include "OVR_CAPI_Keys.h" - -typedef char ovrBool; - -//----------------------------------------------------------------------------------- -// ***** OVR_EXPORT definition - -#if !defined(OVR_EXPORT) - #ifdef OVR_OS_WIN32 - #define OVR_EXPORT __declspec(dllexport) - #else - #define OVR_EXPORT - #endif -#endif - - - -//----------------------------------------------------------------------------------- -// ***** OVR_ALIGNAS definition -// -#if !defined(OVR_ALIGNAS) - // C++11 alignas - #if defined(__GNUC__) && (((__GNUC__ * 100) + __GNUC_MINOR__) >= 408) && (defined(__GXX_EXPERIMENTAL_CXX0X__) || (__cplusplus >= 201103L)) - #define OVR_ALIGNAS(n) alignas(n) - #elif defined(__clang__) && !defined(__APPLE__) && (((__clang_major__ * 100) + __clang_minor__) >= 300) && (__cplusplus >= 201103L) - #define OVR_ALIGNAS(n) alignas(n) - #elif defined(__clang__) && defined(__APPLE__) && (((__clang_major__ * 100) + __clang_minor__) >= 401) && (__cplusplus >= 201103L) - #define OVR_ALIGNAS(n) alignas(n) - #elif defined(_MSC_VER) && (_MSC_VER >= 1900) - #define OVR_ALIGNAS(n) alignas(n) - #elif defined(__EDG_VERSION__) && (__EDG_VERSION__ >= 408) - #define OVR_ALIGNAS(n) alignas(n) - - // Pre-C++11 alignas fallbacks - #elif defined(__GNUC__) || defined(__clang__) - #define OVR_ALIGNAS(n) __attribute__((aligned(n))) - #elif defined(_MSC_VER) || defined(__INTEL_COMPILER) - #define OVR_ALIGNAS(n) __declspec(align(n)) // For Microsoft the alignment must be a literal integer. - #elif defined(__CC_ARM) - #define OVR_ALIGNAS(n) __align(n) - #else - #error Need to define OVR_ALIGNAS - #endif -#endif - -#if defined(_MSC_VER) - #pragma warning(push) - #pragma warning(disable: 4324) // structure was padded due to __declspec(align()) -#endif - - -//#define ENABLE_LATENCY_TESTER - -//----------------------------------------------------------------------------------- -// ***** Simple Math Structures - -/// A 2D vector with integer components. -typedef struct ovrVector2i_ -{ - int x, y; -} ovrVector2i; - -/// A 2D size with integer components. -typedef struct ovrSizei_ -{ - int w, h; -} ovrSizei; -/// A 2D rectangle with a position and size. -/// All components are integers. -typedef struct ovrRecti_ -{ - ovrVector2i Pos; - ovrSizei Size; -} ovrRecti; - -/// A quaternion rotation. -typedef struct ovrQuatf_ -{ - float x, y, z, w; -} ovrQuatf; - -/// A 2D vector with float components. -typedef struct ovrVector2f_ -{ - float x, y; -} ovrVector2f; - -/// A 3D vector with float components. -typedef struct ovrVector3f_ -{ - float x, y, z; -} ovrVector3f; - -/// A 4x4 matrix with float elements. -typedef struct ovrMatrix4f_ -{ - float M[4][4]; -} ovrMatrix4f; - -/// Position and orientation together. -typedef struct ovrPosef_ -{ - ovrQuatf Orientation; - ovrVector3f Position; -} ovrPosef; - -/// A full pose (rigid body) configuration with first and second derivatives. -typedef struct ovrPoseStatef_ -{ - ovrPosef ThePose; ///< The body's position and orientation. - ovrVector3f AngularVelocity; ///< The body's angular velocity in radians per second. - ovrVector3f LinearVelocity; ///< The body's velocity in meters per second. - ovrVector3f AngularAcceleration; ///< The body's angular acceleration in radians per second per second. - ovrVector3f LinearAcceleration; ///< The body's acceleration in meters per second per second. - 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_ -{ - /// The tangent of the angle between the viewing vector and the top edge of the field of view. - float UpTan; - /// The tangent of the angle between the viewing vector and the bottom edge of the field of view. - float DownTan; - /// The tangent of the angle between the viewing vector and the left edge of the field of view. - float LeftTan; - /// The tangent of the angle between the viewing vector and the right edge of the field of view. - float RightTan; -} ovrFovPort; - -//----------------------------------------------------------------------------------- -// ***** HMD Types - -/// Enumerates all HMD types that we support. -typedef enum -{ - ovrHmd_None = 0, - ovrHmd_DK1 = 3, - ovrHmd_DKHD = 4, - 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, /// The HMD is plugged in and detected by the system. - ovrHmdCap_Available = 0x0002, /// The HMD and its sensor are available for ownership use. - /// i.e. it is not already owned by another application. - ovrHmdCap_Captured = 0x0004, /// Set to 'true' if we captured ownership of this HMD. - - // These flags are intended for use with the new driver display mode. - ovrHmdCap_ExtendDesktop = 0x0008, /// (read only) Means the display driver is in compatibility mode. - - // Modifiable flags (through ovrHmd_SetEnabledCaps). - ovrHmdCap_NoMirrorToWindow = 0x2000, /// Disables mirroring of HMD output to the window. This may improve - /// rendering performance slightly (only if 'ExtendDesktop' is off). - ovrHmdCap_DisplayOff = 0x0040, /// Turns off HMD screen and output (only if 'ExtendDesktop' is off). - - ovrHmdCap_LowPersistence = 0x0080, /// HMD supports low persistence mode. - ovrHmdCap_DynamicPrediction = 0x0200, /// Adjust prediction dynamically based on internally measured latency. - ovrHmdCap_DirectPentile = 0x0400, /// Write directly in pentile color mapping format - ovrHmdCap_NoVSync = 0x1000, /// Support rendering without VSync for debugging. - - // These bits can be modified by ovrHmd_SetEnabledCaps. - ovrHmdCap_Writable_Mask = 0x32F0, - - /// These flags are currently passed into the service. May change without notice. - ovrHmdCap_Service_Mask = 0x22F0 -} ovrHmdCaps; - - -/// Tracking capability bits reported by the device. -/// Used with ovrHmd_ConfigureTracking. -typedef enum -{ - ovrTrackingCap_Orientation = 0x0010, /// Supports orientation tracking (IMU). - ovrTrackingCap_MagYawCorrection = 0x0020, /// Supports yaw drift correction via a magnetometer or other means. - ovrTrackingCap_Position = 0x0040, /// Supports positional tracking. - /// Overrides the other flags. Indicates that the application - /// doesn't care about tracking settings. This is the internal - /// default before ovrHmd_ConfigureTracking is called. - ovrTrackingCap_Idle = 0x0100, -} ovrTrackingCaps; - -/// Distortion capability bits reported by device. -/// Used with ovrHmd_ConfigureRendering and ovrHmd_CreateDistortionMesh. -typedef enum -{ - ovrDistortionCap_Chromatic = 0x01, /// Supports chromatic aberration correction. - ovrDistortionCap_TimeWarp = 0x02, /// Supports timewarp. - // 0x04 unused - ovrDistortionCap_Vignette = 0x08, /// Supports vignetting around the edges of the view. - ovrDistortionCap_NoRestore = 0x10, /// Do not save and restore the graphics and compute state when rendering distortion. - ovrDistortionCap_FlipInput = 0x20, /// Flip the vertical texture coordinate of input images. - ovrDistortionCap_SRGB = 0x40, /// Assume input images are in sRGB gamma-corrected color space. - ovrDistortionCap_Overdrive = 0x80, /// Overdrive brightness transitions to reduce artifacts on DK2+ displays - ovrDistortionCap_HqDistortion = 0x100, /// High-quality sampling of distortion buffer for anti-aliasing - ovrDistortionCap_LinuxDevFullscreen = 0x200, /// Indicates window is fullscreen on a device when set. The SDK will automatically apply distortion mesh rotation if needed. - ovrDistortionCap_ComputeShader = 0x400, /// Using compute shader (DX11+ only) - - ovrDistortionCap_ProfileNoTimewarpSpinWaits = 0x10000, /// Use when profiling with timewarp to remove false positives -} ovrDistortionCaps; - -/// Specifies which eye is being used for rendering. -/// This type explicitly does not include a third "NoStereo" option, as such is -/// not required for an HMD-centered API. -typedef enum -{ - ovrEye_Left = 0, - ovrEye_Right = 1, - ovrEye_Count = 2 -} ovrEyeType; - -/// This is a complete descriptor of the HMD. -typedef struct ovrHmdDesc_ -{ - /// Internal handle of this HMD. - struct ovrHmdStruct* Handle; - - /// This HMD's type. - ovrHmdType Type; - - /// Name string describing the product: "Oculus Rift DK1", etc. - const char* ProductName; - const char* Manufacturer; - - /// HID Vendor and ProductId of the device. - short VendorId; - short ProductId; - /// Sensor (and display) serial number. - char SerialNumber[24]; - /// Sensor firmware version. - short FirmwareMajor; - short FirmwareMinor; - /// External tracking camera frustum dimensions (if present). - float CameraFrustumHFovInRadians; - float CameraFrustumVFovInRadians; - float CameraFrustumNearZInMeters; - float CameraFrustumFarZInMeters; - - /// Capability bits described by ovrHmdCaps. - unsigned int HmdCaps; - /// Capability bits described by ovrTrackingCaps. - unsigned int TrackingCaps; - /// Capability bits described by ovrDistortionCaps. - unsigned int DistortionCaps; - - /// 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]; - - /// Resolution of the full HMD screen (both eyes) in pixels. - ovrSizei Resolution; - /// Location of the application window on the desktop (or 0,0). - ovrVector2i WindowsPos; - - /// Display that the HMD should present on. - /// TBD: It may be good to remove this information relying on WindowPos instead. - /// Ultimately, we may need to come up with a more convenient alternative, - /// such as API-specific functions that return adapter, or something that will - /// work with our monitor driver. - /// Windows: (e.g. "\\\\.\\DISPLAY3", can be used in EnumDisplaySettings/CreateDC). - const char* DisplayDeviceName; - /// MacOS: - int DisplayId; - -} ovrHmdDesc; - -/// Simple type ovrHmd is used in ovrHmd_* calls. -typedef const ovrHmdDesc * ovrHmd; - -/// 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_CameraPoseTracked = 0x0004, /// Camera pose is currently tracked. - ovrStatus_PositionConnected = 0x0020, /// Position tracking hardware is connected. - ovrStatus_HmdConnected = 0x0080 /// HMD Display is available and connected. -} ovrStatusBits; - -/// Specifies a reading we can query from the sensor. -typedef struct ovrSensorData_ -{ - ovrVector3f Accelerometer; /// Acceleration reading in m/s^2. - ovrVector3f Gyro; /// Rotation rate in rad/s. - ovrVector3f Magnetometer; /// Magnetic field in Gauss. - float Temperature; /// Temperature of the sensor in degrees Celsius. - float TimeInSeconds; /// Time when the reported IMU reading took place, in seconds. -} ovrSensorData; - -/// Tracking state at a given absolute time (describes predicted HMD pose etc). -/// Returned by ovrHmd_GetTrackingState. -typedef struct ovrTrackingState_ -{ - /// Predicted head pose (and derivatives) at the requested absolute time. - /// The look-ahead interval is equal to (HeadPose.TimeInSeconds - RawSensorData.TimeInSeconds). - ovrPoseStatef HeadPose; - - /// Current pose of the external camera (if present). - /// This pose includes camera tilt (roll and pitch). For a leveled coordinate - /// system use LeveledCameraPose. - ovrPosef CameraPose; - - /// Camera frame aligned with gravity. - /// This value includes position and yaw of the camera, but not roll and pitch. - /// It can be used as a reference point to render real-world objects in the correct location. - ovrPosef LeveledCameraPose; - - /// The most recent sensor data received from the HMD. - ovrSensorData RawSensorData; - - /// Tracking status described by ovrStatusBits. - unsigned int StatusFlags; - - //// 0.4.1 - - // Measures the time from receiving the camera frame until vision CPU processing completes. - double LastVisionProcessingTime; - - //// 0.4.3 - - // Measures the time from exposure until the pose is available for the frame, including processing time. - double LastVisionFrameLatency; - - /// Tag the vision processing results to a certain frame counter number. - uint32_t LastCameraFrameCounter; -} ovrTrackingState; - -/// Frame timing data reported by ovrHmd_BeginFrameTiming() or ovrHmd_BeginFrame(). -typedef struct ovrFrameTiming_ -{ - /// The amount of time that has passed since the previous frame's - /// ThisFrameSeconds value (usable for movement scaling). - /// This will be clamped to no more than 0.1 seconds to prevent - /// excessive movement after pauses due to loading or initialization. - float DeltaSeconds; - - /// It is generally expected that the following holds: - /// ThisFrameSeconds < TimewarpPointSeconds < NextFrameSeconds < - /// EyeScanoutSeconds[EyeOrder[0]] <= ScanoutMidpointSeconds <= EyeScanoutSeconds[EyeOrder[1]]. - - /// Absolute time value when rendering of this frame began or is expected to - /// begin. Generally equal to NextFrameSeconds of the previous frame. Can be used - /// for animation timing. - double ThisFrameSeconds; - /// Absolute point when IMU expects to be sampled for this frame. - double TimewarpPointSeconds; - /// Absolute time when frame Present followed by GPU Flush will finish and the next frame begins. - double NextFrameSeconds; - - /// Time when half of the screen will be scanned out. Can be passed as an absolute time - /// to ovrHmd_GetTrackingState() to get the predicted general orientation. - double ScanoutMidpointSeconds; - /// Timing points when each eye will be scanned out to display. Used when rendering each eye. - double EyeScanoutSeconds[2]; -} ovrFrameTiming; - -/// Rendering information for each eye. Computed by either ovrHmd_ConfigureRendering() -/// or ovrHmd_GetRenderDesc() based on the specified FOV. Note that the rendering viewport -/// is not included here as it can be specified separately and modified per frame through: -/// (a) ovrHmd_GetRenderScaleAndOffset in the case of client rendered distortion, -/// or (b) passing different values via ovrTexture in the case of SDK rendered distortion. -typedef struct ovrEyeRenderDesc_ -{ - ovrEyeType Eye; ///< The eye index this instance corresponds to. - ovrFovPort Fov; ///< The field of view. - ovrRecti DistortedViewport; ///< Distortion viewport. - ovrVector2f PixelsPerTanAngleAtCenter; ///< How many display pixels will fit in tan(angle) = 1. - ovrVector3f HmdToEyeViewOffset; ///< Translation to be applied to view matrix for each eye offset. -} ovrEyeRenderDesc; - -//----------------------------------------------------------------------------------- -// ***** Platform-independent Rendering Configuration - -/// These types are used to hide platform-specific details when passing -/// render device, OS, and texture data to the API. -/// -/// The benefit of having these wrappers versus platform-specific API functions is -/// that they allow game glue code to be portable. A typical example is an -/// engine that has multiple back ends, say GL and D3D. Portable code that calls -/// these back ends may also use LibOVR. To do this, back ends can be modified -/// to return portable types such as ovrTexture and ovrRenderAPIConfig. -typedef enum -{ -#if !defined(HEADLESS_APP) - ovrRenderAPI_None, - ovrRenderAPI_OpenGL, - ovrRenderAPI_Android_GLES, // May include extra native window pointers, etc. - ovrRenderAPI_D3D9, - ovrRenderAPI_D3D10, - ovrRenderAPI_D3D11, - ovrRenderAPI_Count -#else /* !defined(HEADLESS_APP) */ - ovrRenderAPI_None, - ovrRenderAPI_Count -#endif /* !defined(HEADLESS_APP) */ -} ovrRenderAPIType; - -/// Platform-independent part of rendering API-configuration data. -/// It is a part of ovrRenderAPIConfig, passed to ovrHmd_Configure. -typedef struct OVR_ALIGNAS(8) ovrRenderAPIConfigHeader_ -{ - ovrRenderAPIType API; - ovrSizei BackBufferSize; // Previously named RTSize. - int Multisample; -} ovrRenderAPIConfigHeader; - -/// Contains platform-specific information for rendering. -typedef struct OVR_ALIGNAS(8) ovrRenderAPIConfig_ -{ - ovrRenderAPIConfigHeader Header; - uintptr_t PlatformData[8]; -} ovrRenderAPIConfig; - -/// Platform-independent part of the eye texture descriptor. -/// It is a part of ovrTexture, passed to ovrHmd_EndFrame. -/// If RenderViewport is all zeros then the full texture will be used. -typedef struct OVR_ALIGNAS(8) ovrTextureHeader_ -{ - ovrRenderAPIType API; - ovrSizei TextureSize; - ovrRecti RenderViewport; // Pixel viewport in texture that holds eye image. - uint32_t _PAD0_; -} ovrTextureHeader; - -/// Contains platform-specific information about a texture. -typedef struct OVR_ALIGNAS(8) ovrTexture_ -{ - ovrTextureHeader Header; - uintptr_t PlatformData[8]; -} ovrTexture; - - -// ----------------------------------------------------------------------------------- -// ***** API Interfaces - -// Basic steps to use the API: -// -// Setup: -// * ovrInitialize() -// * ovrHMD hmd = ovrHmd_Create(0) -// * Use hmd members and ovrHmd_GetFovTextureSize() to determine graphics configuration. -// * Call ovrHmd_ConfigureTracking() to configure and initialize tracking. -// * Call ovrHmd_ConfigureRendering() to setup graphics for SDK rendering, -// which is the preferred approach. -// Please refer to "Client Distorton Rendering" below if you prefer to do that instead. -// * If the ovrHmdCap_ExtendDesktop flag is not set, then use ovrHmd_AttachToWindow to -// associate the relevant application window with the hmd. -// * Allocate render target textures as needed. -// -// Game Loop: -// * Call ovrHmd_BeginFrame() to get the current frame timing information. -// * Render each eye using ovrHmd_GetEyePoses or ovrHmd_GetHmdPosePerEye to get -// the predicted hmd pose and each eye pose. -// * Call ovrHmd_EndFrame() to render the distorted textures to the back buffer -// and present them on the hmd. -// -// Shutdown: -// * ovrHmd_Destroy(hmd) -// * ovr_Shutdown() -// - -#ifdef __cplusplus -extern "C" { -#endif - -#if !defined(HEADLESS_APP) -// ovr_InitializeRenderingShim initializes the rendering shim appart from everything -// else in LibOVR. This may be helpful if the application prefers to avoid -// creating any OVR resources (allocations, service connections, etc) at this point. -// ovr_InitializeRenderingShim does not bring up anything within LibOVR except the -// necessary hooks to enable the Direct-to-Rift functionality. -// -// Either ovr_InitializeRenderingShim() or ovr_Initialize() must be called before any -// Direct3D or OpenGL initilization is done by applictaion (creation of devices, etc). -// ovr_Initialize() must still be called after to use the rest of LibOVR APIs. -OVR_EXPORT ovrBool ovr_InitializeRenderingShim(); -#endif /* !defined(HEADLESS_APP) */ - -// Library init/shutdown, must be called around all other OVR code. -// No other functions calls besides ovr_InitializeRenderingShim are allowed -// before ovr_Initialize succeeds or after ovr_Shutdown. -/// Initializes all Oculus functionality. -OVR_EXPORT ovrBool ovr_Initialize(); -/// Shuts down all Oculus functionality. -OVR_EXPORT void ovr_Shutdown(); - -/// Returns version string representing libOVR version. Static, so -/// string remains valid for app lifespan -OVR_EXPORT const char* ovr_GetVersionString(); - -/// Detects or re-detects HMDs and reports the total number detected. -/// Users can get information about each HMD by calling ovrHmd_Create with an index. -OVR_EXPORT int ovrHmd_Detect(); - -/// Creates a handle to an HMD which doubles as a description structure. -/// Index can [0 .. ovrHmd_Detect()-1]. Index mappings can cange after each ovrHmd_Detect call. -/// If not null, then the returned handle must be freed with ovrHmd_Destroy. -OVR_EXPORT ovrHmd ovrHmd_Create(int index); -OVR_EXPORT void ovrHmd_Destroy(ovrHmd hmd); - -/// Creates a 'fake' HMD used for debugging only. This is not tied to specific hardware, -/// but may be used to debug some of the related rendering. -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 errors (during create etc). -OVR_EXPORT const char* ovrHmd_GetLastError(ovrHmd hmd); - -#if !defined(HEADLESS_APP) -/// Platform specific function to specify the application window whose output will be -/// displayed on the HMD. Only used if the ovrHmdCap_ExtendDesktop flag is false. -/// Windows: SwapChain associated with this window will be displayed on the HMD. -/// Specify 'destMirrorRect' in window coordinates to indicate an area -/// of the render target output that will be mirrored from 'sourceRenderTargetRect'. -/// Null pointers mean "full size". -/// @note Source and dest mirror rects are not yet implemented. -OVR_EXPORT ovrBool ovrHmd_AttachToWindow(ovrHmd hmd, void* window, - const ovrRecti* destMirrorRect, - const ovrRecti* sourceRenderTargetRect); -#endif /* !defined(HEADLESS_APP) */ - -/// Returns capability bits that are enabled at this time as described by ovrHmdCaps. -/// Note that this value is different font ovrHmdDesc::HmdCaps, which describes what -/// capabilities are available for that HMD. -OVR_EXPORT unsigned int ovrHmd_GetEnabledCaps(ovrHmd hmd); - -/// Modifies capability bits described by ovrHmdCaps that can be modified, -/// such as ovrHmdCap_LowPersistance. -OVR_EXPORT void ovrHmd_SetEnabledCaps(ovrHmd hmd, unsigned int hmdCaps); - -//------------------------------------------------------------------------------------- -// ***** Tracking Interface - -/// All tracking interface functions are thread-safe, allowing tracking state to be sampled -/// from different threads. -/// ConfigureTracking starts sensor sampling, enabling specified capabilities, -/// described by ovrTrackingCaps. -/// - supportedTrackingCaps specifies support that is requested. The function will succeed -/// even if these caps are not available (i.e. sensor or camera is unplugged). Support -/// will automatically be enabled if such device is plugged in later. Software should -/// check ovrTrackingState.StatusFlags for real-time status. -/// - requiredTrackingCaps specify sensor capabilities required at the time of the call. -/// If they are not available, the function will fail. Pass 0 if only specifying -/// supportedTrackingCaps. -/// - Pass 0 for both supportedTrackingCaps and requiredTrackingCaps to disable tracking. -OVR_EXPORT ovrBool ovrHmd_ConfigureTracking(ovrHmd hmd, unsigned int supportedTrackingCaps, - unsigned int requiredTrackingCaps); - -/// Re-centers the sensor orientation. -/// Normally this will recenter the (x,y,z) translational components and the yaw -/// component of orientation. -OVR_EXPORT void ovrHmd_RecenterPose(ovrHmd hmd); - -/// Returns tracking state reading based on the specified absolute system time. -/// Pass an absTime value of 0.0 to request the most recent sensor reading. In this case -/// both PredictedPose and SamplePose will have the same value. -/// ovrHmd_GetEyePoses relies on this function internally. -/// This may also be used for more refined timing of FrontBuffer rendering logic, etc. -OVR_EXPORT ovrTrackingState ovrHmd_GetTrackingState(ovrHmd hmd, double absTime); - -//------------------------------------------------------------------------------------- -// ***** Graphics Setup - -/// Calculates the recommended texture size for rendering a given eye within the HMD -/// with a given FOV cone. Higher FOV will generally require larger textures to -/// maintain quality. -/// - pixelsPerDisplayPixel specifies the ratio of the number of render target pixels -/// to display pixels at the center of distortion. 1.0 is the default value. Lower -/// values can improve performance. -OVR_EXPORT ovrSizei ovrHmd_GetFovTextureSize(ovrHmd hmd, ovrEyeType eye, ovrFovPort fov, - float pixelsPerDisplayPixel); - -//------------------------------------------------------------------------------------- -// ***** Rendering API Thread Safety - -// All of rendering functions including the configure and frame functions -// are *NOT thread safe*. It is ok to use ConfigureRendering on one thread and handle -// frames on another thread, but explicit synchronization must be done since -// functions that depend on configured state are not reentrant. -// -// 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_GetEyeTimewarpMatrices - -//------------------------------------------------------------------------------------- -// ***** SDK Distortion Rendering Functions - -// These functions support rendering of distortion by the SDK through direct -// access to the underlying rendering API, such as D3D or GL. -// This is the recommended approach since it allows better support for future -// Oculus hardware, and enables a range of low-level optimizations. - -/// Configures rendering and fills in computed render parameters. -/// This function can be called multiple times to change rendering settings. -/// eyeRenderDescOut is a pointer to an array of two ovrEyeRenderDesc structs -/// that are used to return complete rendering information for each eye. -/// - apiConfig provides D3D/OpenGL specific parameters. Pass null -/// to shutdown rendering and release all resources. -/// - distortionCaps describe desired distortion settings. -OVR_EXPORT ovrBool ovrHmd_ConfigureRendering( ovrHmd hmd, - const ovrRenderAPIConfig* apiConfig, - unsigned int distortionCaps, - const ovrFovPort eyeFovIn[2], - ovrEyeRenderDesc eyeRenderDescOut[2] ); - - -/// Begins a frame, returning timing information. -/// This should be called at the beginning of the game rendering loop (on the render thread). -/// Pass 0 for the frame index if not using ovrHmd_GetFrameTiming. -OVR_EXPORT ovrFrameTiming ovrHmd_BeginFrame(ovrHmd hmd, unsigned int frameIndex); - -/// Ends a frame, submitting the rendered textures to the frame buffer. -/// - RenderViewport within each eyeTexture can change per frame if necessary. -/// - 'renderPose' will typically be the value returned from ovrHmd_GetEyePoses, -/// ovrHmd_GetHmdPosePerEye but can be different if a different head pose was -/// used for rendering. -/// - This may perform distortion and scaling internally, assuming is it not -/// delegated to another thread. -/// - Must be called on the same thread as BeginFrame. -/// - *** This Function will call Present/SwapBuffers and potentially wait for GPU Sync ***. -OVR_EXPORT void ovrHmd_EndFrame(ovrHmd hmd, - const ovrPosef renderPose[2], - const ovrTexture eyeTexture[2]); - -/// Returns predicted head pose in outHmdTrackingState and offset eye poses in outEyePoses -/// as an atomic operation. Caller need not worry about applying HmdToEyeViewOffset to the -/// returned outEyePoses variables. -/// - Thread-safe function where caller should increment frameIndex with every frame -/// and pass the index where applicable to functions called on the rendering thread. -/// - hmdToEyeViewOffset[2] can be ovrEyeRenderDesc.HmdToEyeViewOffset returned from -/// ovrHmd_ConfigureRendering or ovrHmd_GetRenderDesc. For monoscopic rendering, -/// use a vector that is the average of the two vectors for both eyes. -/// - If frameIndex is not being used, pass in 0. -/// - Assuming outEyePoses are used for rendering, it should be passed into ovrHmd_EndFrame. -/// - If called doesn't need outHmdTrackingState, it can be NULL -OVR_EXPORT void ovrHmd_GetEyePoses(ovrHmd hmd, unsigned int frameIndex, ovrVector3f hmdToEyeViewOffset[2], - ovrPosef outEyePoses[2], ovrTrackingState* outHmdTrackingState); - -/// Function was previously called ovrHmd_GetEyePose -/// Returns the predicted head pose to use when rendering the specified eye. -/// - Important: Caller must apply HmdToEyeViewOffset before using ovrPosef for rendering -/// - Must be called between ovrHmd_BeginFrameTiming and ovrHmd_EndFrameTiming. -/// - If the pose is used for rendering the eye, it should be passed to ovrHmd_EndFrame. -/// - Parameter 'eye' is used for prediction timing only -OVR_EXPORT ovrPosef ovrHmd_GetHmdPosePerEye(ovrHmd hmd, ovrEyeType eye); - - -//------------------------------------------------------------------------------------- -// ***** Client Distortion Rendering Functions - -// These functions provide the distortion data and render timing support necessary to allow -// client rendering of distortion. Client-side rendering involves the following steps: -// -// 1. Setup ovrEyeDesc based on the desired texture size and FOV. -// Call ovrHmd_GetRenderDesc to get the necessary rendering parameters for each eye. -// -// 2. Use ovrHmd_CreateDistortionMesh to generate the distortion mesh. -// -// 3. Use ovrHmd_BeginFrameTiming, ovrHmd_GetEyePoses, and ovrHmd_BeginFrameTiming in -// the rendering loop to obtain timing and predicted head orientation when rendering each eye. -// - When using timewarp, use ovr_WaitTillTime after the rendering and gpu flush, followed -// by ovrHmd_GetEyeTimewarpMatrices to obtain the timewarp matrices used -// by the distortion pixel shader. This will minimize latency. -// - -/// Computes the distortion viewport, view adjust, and other rendering parameters for -/// the specified eye. This can be used instead of ovrHmd_ConfigureRendering to do -/// setup for client rendered distortion. -OVR_EXPORT ovrEyeRenderDesc ovrHmd_GetRenderDesc(ovrHmd hmd, - ovrEyeType eyeType, ovrFovPort fov); - - -/// Describes a vertex used by the distortion mesh. This is intended to be converted into -/// the engine-specific format. Some fields may be unused based on the ovrDistortionCaps -/// flags selected. TexG and TexB, for example, are not used if chromatic correction is -/// not requested. -typedef struct ovrDistortionVertex_ -{ - ovrVector2f ScreenPosNDC; ///< [-1,+1],[-1,+1] over the entire framebuffer. - float TimeWarpFactor; ///< Lerp factor between time-warp matrices. Can be encoded in Pos.z. - float VignetteFactor; ///< Vignette fade factor. Can be encoded in Pos.w. - ovrVector2f TanEyeAnglesR; ///< The tangents of the horizontal and vertical eye angles for the red channel. - ovrVector2f TanEyeAnglesG; ///< The tangents of the horizontal and vertical eye angles for the green channel. - ovrVector2f TanEyeAnglesB; ///< The tangents of the horizontal and vertical eye angles for the blue channel. -} 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; ///< The distortion vertices representing each point in the mesh. - unsigned short* pIndexData; ///< Indices for connecting the mesh vertices into polygons. - unsigned int VertexCount; ///< The number of vertices in the mesh. - unsigned int IndexCount; ///< The number of indices in the mesh. -} ovrDistortionMesh; - -/// Generate distortion mesh per eye. -/// Distortion capabilities will depend on 'distortionCaps' flags. Users should -/// render using the appropriate shaders based on their settings. -/// Distortion mesh data will be allocated and written into the ovrDistortionMesh data structure, -/// which should be explicitly freed with ovrHmd_DestroyDistortionMesh. -/// Users should call ovrHmd_GetRenderScaleAndOffset to get uvScale and Offset values for rendering. -/// The function shouldn't fail unless theres is a configuration or memory error, in which case -/// ovrDistortionMesh values will be set to null. -/// This is the only function in the SDK reliant on eye relief, currently imported from profiles, -/// or overridden here. -OVR_EXPORT ovrBool ovrHmd_CreateDistortionMesh( ovrHmd hmd, - ovrEyeType eyeType, ovrFovPort fov, - unsigned int distortionCaps, - ovrDistortionMesh *meshData); -OVR_EXPORT ovrBool ovrHmd_CreateDistortionMeshDebug( ovrHmd hmddesc, - ovrEyeType eyeType, ovrFovPort fov, - unsigned int distortionCaps, - ovrDistortionMesh *meshData, - float debugEyeReliefOverrideInMetres); - - -/// Used to free the distortion mesh allocated by ovrHmd_GenerateDistortionMesh. meshData elements -/// are set to null and zeroes after the call. -OVR_EXPORT void ovrHmd_DestroyDistortionMesh( ovrDistortionMesh* meshData ); - -/// Computes updated 'uvScaleOffsetOut' to be used with a distortion if render target size or -/// viewport changes after the fact. This can be used to adjust render size every frame if desired. -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 where applicable to functions called on the -/// rendering thread. -OVR_EXPORT ovrFrameTiming ovrHmd_GetFrameTiming(ovrHmd hmd, unsigned int frameIndex); - -/// Called at the beginning of the frame on the rendering thread. -/// Pass frameIndex == 0 if ovrHmd_GetFrameTiming isn't being used. Otherwise, -/// pass the same frame index as was used for GetFrameTiming on the main thread. -OVR_EXPORT ovrFrameTiming ovrHmd_BeginFrameTiming(ovrHmd hmd, unsigned int frameIndex); - -/// Marks the end of client distortion rendered frame, tracking the necessary timing information. -/// This function must be called immediately after Present/SwapBuffers + GPU sync. GPU sync is -/// important before this call to reduce latency and ensure proper timing. -OVR_EXPORT void ovrHmd_EndFrameTiming(ovrHmd hmd); - -/// Initializes and resets frame time tracking. This is typically not necessary, but -/// is helpful if game changes vsync state or video mode. vsync is assumed to be on if this -/// isn't called. Resets internal frame index to the specified number. -OVR_EXPORT void ovrHmd_ResetFrameTiming(ovrHmd hmd, unsigned int frameIndex); - -/// Computes timewarp matrices used by distortion mesh shader, these are used to adjust -/// for head orientation change since the last call to ovrHmd_GetEyePoses -/// when rendering this eye. The ovrDistortionVertex::TimeWarpFactor is used to blend between the -/// matrices, usually representing two different sides of the screen. -/// Must be called on the same thread as ovrHmd_BeginFrameTiming. -OVR_EXPORT void ovrHmd_GetEyeTimewarpMatrices (ovrHmd hmd, ovrEyeType eye, - ovrPosef renderPose, ovrMatrix4f twmOut[2]); -OVR_EXPORT void ovrHmd_GetEyeTimewarpMatricesDebug(ovrHmd hmd, ovrEyeType eye, - ovrPosef renderPose, ovrMatrix4f twmOut[2], - double debugTimingOffsetInSeconds); - - - - -//------------------------------------------------------------------------------------- -// ***** 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 hmdToEyeViewOffsetX); - -/// 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 the latency testing color in rgbColorOut to render when using a DK2 -/// Returns false if this feature is disabled or not-applicable (e.g. using a DK1) -OVR_EXPORT ovrBool ovrHmd_GetLatencyTest2DrawColor(ovrHmd hmddesc, unsigned char rgbColorOut[3]); - -//------------------------------------------------------------------------------------- -// ***** Health and Safety Warning Display interface -// - -#if !defined(HEADLESS_APP) - -/// Used by ovrhmd_GetHSWDisplayState to report the current display state. -typedef struct ovrHSWDisplayState_ -{ - /// If true then the warning should be currently visible - /// and the following variables have meaning. Else there is no - /// warning being displayed for this application on the given HMD. - ovrBool Displayed; ///< True if the Health&Safety Warning is currently displayed. - double StartTime; ///< Absolute time when the warning was first displayed. See ovr_GetTimeInSeconds(). - double DismissibleTime; ///< Earliest absolute time when the warning can be dismissed. May be a time in the past. -} ovrHSWDisplayState; - -/// Returns the current state of the HSW display. If the application is doing the rendering of -/// the HSW display then this function serves to indicate that the warning should be -/// currently displayed. If the application is using SDK-based eye rendering then the SDK by -/// default automatically handles the drawing of the HSW display. An application that uses -/// application-based eye rendering should use this function to know when to start drawing the -/// HSW display itself and can optionally use it in conjunction with ovrhmd_DismissHSWDisplay -/// as described below. -/// -/// Example usage for application-based rendering: -/// bool HSWDisplayCurrentlyDisplayed = false; // global or class member variable -/// ovrHSWDisplayState hswDisplayState; -/// ovrhmd_GetHSWDisplayState(Hmd, &hswDisplayState); -/// -/// if (hswDisplayState.Displayed && !HSWDisplayCurrentlyDisplayed) { -/// <insert model into the scene that stays in front of the user> -/// HSWDisplayCurrentlyDisplayed = true; -/// } -OVR_EXPORT void ovrHmd_GetHSWDisplayState(ovrHmd hmd, ovrHSWDisplayState *hasWarningState); - -/// Dismisses the HSW display if the warning is dismissible and the earliest dismissal time -/// has occurred. Returns true if the display is valid and could be dismissed. The application -/// should recognize that the HSW display is being displayed (via ovrhmd_GetHSWDisplayState) -/// and if so then call this function when the appropriate user input to dismiss the warning -/// occurs. -/// -/// Example usage : -/// void ProcessEvent(int key) { -/// if (key == escape) { -/// ovrHSWDisplayState hswDisplayState; -/// ovrhmd_GetHSWDisplayState(hmd, &hswDisplayState); -/// -/// if (hswDisplayState.Displayed && ovrhmd_DismissHSWDisplay(hmd)) { -/// <remove model from the scene> -/// HSWDisplayCurrentlyDisplayed = false; -/// } -/// } -/// } -OVR_EXPORT ovrBool ovrHmd_DismissHSWDisplay(ovrHmd hmd); - -#endif /* !defined(HEADLESS_APP) */ - -/// Get boolean property. Returns first element if property is a boolean array. -/// Returns defaultValue if property doesn't exist. -OVR_EXPORT ovrBool ovrHmd_GetBool(ovrHmd hmd, const char* propertyName, ovrBool defaultVal); - -/// Modify bool property; false if property doesn't exist or is readonly. -OVR_EXPORT ovrBool ovrHmd_SetBool(ovrHmd hmd, const char* propertyName, ovrBool value); - -/// Get integer property. Returns first element if property is an integer array. -/// Returns defaultValue if property doesn't exist. -OVR_EXPORT int ovrHmd_GetInt(ovrHmd hmd, const char* propertyName, int defaultVal); - -/// Modify integer property; false if property doesn't exist or is readonly. -OVR_EXPORT ovrBool ovrHmd_SetInt(ovrHmd hmd, const char* propertyName, int value); - -/// Get float property. Returns first element if property is a float array. -/// Returns defaultValue if property doesn't exist. -OVR_EXPORT float ovrHmd_GetFloat(ovrHmd hmd, const char* propertyName, float defaultVal); - -/// 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); - -/// Set string property -OVR_EXPORT ovrBool ovrHmd_SetString(ovrHmd hmddesc, const char* propertyName, - const char* value); - -// ----------------------------------------------------------------------------------- -// ***** Logging - -/// Start performance logging. guid is optional and if included is written with each file entry. -/// If called while logging is already active with the same filename, only the guid will be updated -/// If called while logging is already active with a different filename, ovrHmd_StopPerfLog() will be called, followed by ovrHmd_StartPerfLog() -OVR_EXPORT ovrBool ovrHmd_StartPerfLog(ovrHmd hmd, const char* fileName, const char* userData1); -/// Stop performance logging. -OVR_EXPORT ovrBool ovrHmd_StopPerfLog(ovrHmd hmd); - - -#ifdef __cplusplus -} // extern "C" -#endif - - -#if defined(_MSC_VER) - #pragma warning(pop) -#endif - - -#endif // OVR_CAPI_h |