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