ovr_sdk
diff LibOVR/Src/OVR_CAPI.h @ 0:1b39a1b46319
initial 0.4.4
| author | John Tsiombikas <nuclear@member.fsf.org> |
|---|---|
| date | Wed, 14 Jan 2015 06:51:16 +0200 |
| parents | |
| children |
line diff
1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 1.2 +++ b/LibOVR/Src/OVR_CAPI.h Wed Jan 14 06:51:16 2015 +0200 1.3 @@ -0,0 +1,950 @@ 1.4 +/************************************************************************************ 1.5 + 1.6 +Filename : OVR_CAPI.h 1.7 +Content : C Interface to Oculus tracking and rendering. 1.8 +Created : November 23, 2013 1.9 +Authors : Michael Antonov 1.10 + 1.11 +Copyright : Copyright 2014 Oculus VR, LLC All Rights reserved. 1.12 + 1.13 +Licensed under the Oculus VR Rift SDK License Version 3.2 (the "License"); 1.14 +you may not use the Oculus VR Rift SDK except in compliance with the License, 1.15 +which is provided at the time of installation or download, or which 1.16 +otherwise accompanies this software in either electronic or hard copy form. 1.17 + 1.18 +You may obtain a copy of the License at 1.19 + 1.20 +http://www.oculusvr.com/licenses/LICENSE-3.2 1.21 + 1.22 +Unless required by applicable law or agreed to in writing, the Oculus VR SDK 1.23 +distributed under the License is distributed on an "AS IS" BASIS, 1.24 +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 1.25 +See the License for the specific language governing permissions and 1.26 +limitations under the License. 1.27 + 1.28 +************************************************************************************/ 1.29 + 1.30 +/// @file OVR_CAPI.h 1.31 +/// Exposes all general Rift functionality. 1.32 + 1.33 +#ifndef OVR_CAPI_h 1.34 +#define OVR_CAPI_h 1.35 + 1.36 +#include <stdint.h> 1.37 + 1.38 +#include "OVR_CAPI_Keys.h" 1.39 + 1.40 +typedef char ovrBool; 1.41 + 1.42 +//----------------------------------------------------------------------------------- 1.43 +// ***** OVR_EXPORT definition 1.44 + 1.45 +#if !defined(OVR_EXPORT) 1.46 + #ifdef OVR_OS_WIN32 1.47 + #define OVR_EXPORT __declspec(dllexport) 1.48 + #else 1.49 + #define OVR_EXPORT 1.50 + #endif 1.51 +#endif 1.52 + 1.53 + 1.54 + 1.55 +//----------------------------------------------------------------------------------- 1.56 +// ***** OVR_ALIGNAS definition 1.57 +// 1.58 +#if !defined(OVR_ALIGNAS) 1.59 + // C++11 alignas 1.60 + #if defined(__GNUC__) && (((__GNUC__ * 100) + __GNUC_MINOR__) >= 408) && (defined(__GXX_EXPERIMENTAL_CXX0X__) || (__cplusplus >= 201103L)) 1.61 + #define OVR_ALIGNAS(n) alignas(n) 1.62 + #elif defined(__clang__) && !defined(__APPLE__) && (((__clang_major__ * 100) + __clang_minor__) >= 300) && (__cplusplus >= 201103L) 1.63 + #define OVR_ALIGNAS(n) alignas(n) 1.64 + #elif defined(__clang__) && defined(__APPLE__) && (((__clang_major__ * 100) + __clang_minor__) >= 401) && (__cplusplus >= 201103L) 1.65 + #define OVR_ALIGNAS(n) alignas(n) 1.66 + #elif defined(_MSC_VER) && (_MSC_VER >= 1900) 1.67 + #define OVR_ALIGNAS(n) alignas(n) 1.68 + #elif defined(__EDG_VERSION__) && (__EDG_VERSION__ >= 408) 1.69 + #define OVR_ALIGNAS(n) alignas(n) 1.70 + 1.71 + // Pre-C++11 alignas fallbacks 1.72 + #elif defined(__GNUC__) || defined(__clang__) 1.73 + #define OVR_ALIGNAS(n) __attribute__((aligned(n))) 1.74 + #elif defined(_MSC_VER) || defined(__INTEL_COMPILER) 1.75 + #define OVR_ALIGNAS(n) __declspec(align(n)) // For Microsoft the alignment must be a literal integer. 1.76 + #elif defined(__CC_ARM) 1.77 + #define OVR_ALIGNAS(n) __align(n) 1.78 + #else 1.79 + #error Need to define OVR_ALIGNAS 1.80 + #endif 1.81 +#endif 1.82 + 1.83 +#if defined(_MSC_VER) 1.84 + #pragma warning(push) 1.85 + #pragma warning(disable: 4324) // structure was padded due to __declspec(align()) 1.86 +#endif 1.87 + 1.88 + 1.89 +//#define ENABLE_LATENCY_TESTER 1.90 + 1.91 +//----------------------------------------------------------------------------------- 1.92 +// ***** Simple Math Structures 1.93 + 1.94 +/// A 2D vector with integer components. 1.95 +typedef struct ovrVector2i_ 1.96 +{ 1.97 + int x, y; 1.98 +} ovrVector2i; 1.99 + 1.100 +/// A 2D size with integer components. 1.101 +typedef struct ovrSizei_ 1.102 +{ 1.103 + int w, h; 1.104 +} ovrSizei; 1.105 +/// A 2D rectangle with a position and size. 1.106 +/// All components are integers. 1.107 +typedef struct ovrRecti_ 1.108 +{ 1.109 + ovrVector2i Pos; 1.110 + ovrSizei Size; 1.111 +} ovrRecti; 1.112 + 1.113 +/// A quaternion rotation. 1.114 +typedef struct ovrQuatf_ 1.115 +{ 1.116 + float x, y, z, w; 1.117 +} ovrQuatf; 1.118 + 1.119 +/// A 2D vector with float components. 1.120 +typedef struct ovrVector2f_ 1.121 +{ 1.122 + float x, y; 1.123 +} ovrVector2f; 1.124 + 1.125 +/// A 3D vector with float components. 1.126 +typedef struct ovrVector3f_ 1.127 +{ 1.128 + float x, y, z; 1.129 +} ovrVector3f; 1.130 + 1.131 +/// A 4x4 matrix with float elements. 1.132 +typedef struct ovrMatrix4f_ 1.133 +{ 1.134 + float M[4][4]; 1.135 +} ovrMatrix4f; 1.136 + 1.137 +/// Position and orientation together. 1.138 +typedef struct ovrPosef_ 1.139 +{ 1.140 + ovrQuatf Orientation; 1.141 + ovrVector3f Position; 1.142 +} ovrPosef; 1.143 + 1.144 +/// A full pose (rigid body) configuration with first and second derivatives. 1.145 +typedef struct ovrPoseStatef_ 1.146 +{ 1.147 + ovrPosef ThePose; ///< The body's position and orientation. 1.148 + ovrVector3f AngularVelocity; ///< The body's angular velocity in radians per second. 1.149 + ovrVector3f LinearVelocity; ///< The body's velocity in meters per second. 1.150 + ovrVector3f AngularAcceleration; ///< The body's angular acceleration in radians per second per second. 1.151 + ovrVector3f LinearAcceleration; ///< The body's acceleration in meters per second per second. 1.152 + double TimeInSeconds; ///< Absolute time of this state sample. 1.153 +} ovrPoseStatef; 1.154 + 1.155 +/// Field Of View (FOV) in tangent of the angle units. 1.156 +/// As an example, for a standard 90 degree vertical FOV, we would 1.157 +/// have: { UpTan = tan(90 degrees / 2), DownTan = tan(90 degrees / 2) }. 1.158 +typedef struct ovrFovPort_ 1.159 +{ 1.160 + /// The tangent of the angle between the viewing vector and the top edge of the field of view. 1.161 + float UpTan; 1.162 + /// The tangent of the angle between the viewing vector and the bottom edge of the field of view. 1.163 + float DownTan; 1.164 + /// The tangent of the angle between the viewing vector and the left edge of the field of view. 1.165 + float LeftTan; 1.166 + /// The tangent of the angle between the viewing vector and the right edge of the field of view. 1.167 + float RightTan; 1.168 +} ovrFovPort; 1.169 + 1.170 +//----------------------------------------------------------------------------------- 1.171 +// ***** HMD Types 1.172 + 1.173 +/// Enumerates all HMD types that we support. 1.174 +typedef enum 1.175 +{ 1.176 + ovrHmd_None = 0, 1.177 + ovrHmd_DK1 = 3, 1.178 + ovrHmd_DKHD = 4, 1.179 + ovrHmd_DK2 = 6, 1.180 + ovrHmd_Other // Some HMD other then the one in the enumeration. 1.181 +} ovrHmdType; 1.182 + 1.183 +/// HMD capability bits reported by device. 1.184 +typedef enum 1.185 +{ 1.186 + // Read-only flags. 1.187 + ovrHmdCap_Present = 0x0001, /// The HMD is plugged in and detected by the system. 1.188 + ovrHmdCap_Available = 0x0002, /// The HMD and its sensor are available for ownership use. 1.189 + /// i.e. it is not already owned by another application. 1.190 + ovrHmdCap_Captured = 0x0004, /// Set to 'true' if we captured ownership of this HMD. 1.191 + 1.192 + // These flags are intended for use with the new driver display mode. 1.193 + ovrHmdCap_ExtendDesktop = 0x0008, /// (read only) Means the display driver is in compatibility mode. 1.194 + 1.195 + // Modifiable flags (through ovrHmd_SetEnabledCaps). 1.196 + ovrHmdCap_NoMirrorToWindow = 0x2000, /// Disables mirroring of HMD output to the window. This may improve 1.197 + /// rendering performance slightly (only if 'ExtendDesktop' is off). 1.198 + ovrHmdCap_DisplayOff = 0x0040, /// Turns off HMD screen and output (only if 'ExtendDesktop' is off). 1.199 + 1.200 + ovrHmdCap_LowPersistence = 0x0080, /// HMD supports low persistence mode. 1.201 + ovrHmdCap_DynamicPrediction = 0x0200, /// Adjust prediction dynamically based on internally measured latency. 1.202 + ovrHmdCap_DirectPentile = 0x0400, /// Write directly in pentile color mapping format 1.203 + ovrHmdCap_NoVSync = 0x1000, /// Support rendering without VSync for debugging. 1.204 + 1.205 + // These bits can be modified by ovrHmd_SetEnabledCaps. 1.206 + ovrHmdCap_Writable_Mask = 0x32F0, 1.207 + 1.208 + /// These flags are currently passed into the service. May change without notice. 1.209 + ovrHmdCap_Service_Mask = 0x22F0 1.210 +} ovrHmdCaps; 1.211 + 1.212 + 1.213 +/// Tracking capability bits reported by the device. 1.214 +/// Used with ovrHmd_ConfigureTracking. 1.215 +typedef enum 1.216 +{ 1.217 + ovrTrackingCap_Orientation = 0x0010, /// Supports orientation tracking (IMU). 1.218 + ovrTrackingCap_MagYawCorrection = 0x0020, /// Supports yaw drift correction via a magnetometer or other means. 1.219 + ovrTrackingCap_Position = 0x0040, /// Supports positional tracking. 1.220 + /// Overrides the other flags. Indicates that the application 1.221 + /// doesn't care about tracking settings. This is the internal 1.222 + /// default before ovrHmd_ConfigureTracking is called. 1.223 + ovrTrackingCap_Idle = 0x0100, 1.224 +} ovrTrackingCaps; 1.225 + 1.226 +/// Distortion capability bits reported by device. 1.227 +/// Used with ovrHmd_ConfigureRendering and ovrHmd_CreateDistortionMesh. 1.228 +typedef enum 1.229 +{ 1.230 + ovrDistortionCap_Chromatic = 0x01, /// Supports chromatic aberration correction. 1.231 + ovrDistortionCap_TimeWarp = 0x02, /// Supports timewarp. 1.232 + // 0x04 unused 1.233 + ovrDistortionCap_Vignette = 0x08, /// Supports vignetting around the edges of the view. 1.234 + ovrDistortionCap_NoRestore = 0x10, /// Do not save and restore the graphics and compute state when rendering distortion. 1.235 + ovrDistortionCap_FlipInput = 0x20, /// Flip the vertical texture coordinate of input images. 1.236 + ovrDistortionCap_SRGB = 0x40, /// Assume input images are in sRGB gamma-corrected color space. 1.237 + ovrDistortionCap_Overdrive = 0x80, /// Overdrive brightness transitions to reduce artifacts on DK2+ displays 1.238 + ovrDistortionCap_HqDistortion = 0x100, /// High-quality sampling of distortion buffer for anti-aliasing 1.239 + ovrDistortionCap_LinuxDevFullscreen = 0x200, /// Indicates window is fullscreen on a device when set. The SDK will automatically apply distortion mesh rotation if needed. 1.240 + ovrDistortionCap_ComputeShader = 0x400, /// Using compute shader (DX11+ only) 1.241 + 1.242 + ovrDistortionCap_ProfileNoTimewarpSpinWaits = 0x10000, /// Use when profiling with timewarp to remove false positives 1.243 +} ovrDistortionCaps; 1.244 + 1.245 +/// Specifies which eye is being used for rendering. 1.246 +/// This type explicitly does not include a third "NoStereo" option, as such is 1.247 +/// not required for an HMD-centered API. 1.248 +typedef enum 1.249 +{ 1.250 + ovrEye_Left = 0, 1.251 + ovrEye_Right = 1, 1.252 + ovrEye_Count = 2 1.253 +} ovrEyeType; 1.254 + 1.255 +/// This is a complete descriptor of the HMD. 1.256 +typedef struct ovrHmdDesc_ 1.257 +{ 1.258 + /// Internal handle of this HMD. 1.259 + struct ovrHmdStruct* Handle; 1.260 + 1.261 + /// This HMD's type. 1.262 + ovrHmdType Type; 1.263 + 1.264 + /// Name string describing the product: "Oculus Rift DK1", etc. 1.265 + const char* ProductName; 1.266 + const char* Manufacturer; 1.267 + 1.268 + /// HID Vendor and ProductId of the device. 1.269 + short VendorId; 1.270 + short ProductId; 1.271 + /// Sensor (and display) serial number. 1.272 + char SerialNumber[24]; 1.273 + /// Sensor firmware version. 1.274 + short FirmwareMajor; 1.275 + short FirmwareMinor; 1.276 + /// External tracking camera frustum dimensions (if present). 1.277 + float CameraFrustumHFovInRadians; 1.278 + float CameraFrustumVFovInRadians; 1.279 + float CameraFrustumNearZInMeters; 1.280 + float CameraFrustumFarZInMeters; 1.281 + 1.282 + /// Capability bits described by ovrHmdCaps. 1.283 + unsigned int HmdCaps; 1.284 + /// Capability bits described by ovrTrackingCaps. 1.285 + unsigned int TrackingCaps; 1.286 + /// Capability bits described by ovrDistortionCaps. 1.287 + unsigned int DistortionCaps; 1.288 + 1.289 + /// These define the recommended and maximum optical FOVs for the HMD. 1.290 + ovrFovPort DefaultEyeFov[ovrEye_Count]; 1.291 + ovrFovPort MaxEyeFov[ovrEye_Count]; 1.292 + 1.293 + /// Preferred eye rendering order for best performance. 1.294 + /// Can help reduce latency on sideways-scanned screens. 1.295 + ovrEyeType EyeRenderOrder[ovrEye_Count]; 1.296 + 1.297 + /// Resolution of the full HMD screen (both eyes) in pixels. 1.298 + ovrSizei Resolution; 1.299 + /// Location of the application window on the desktop (or 0,0). 1.300 + ovrVector2i WindowsPos; 1.301 + 1.302 + /// Display that the HMD should present on. 1.303 + /// TBD: It may be good to remove this information relying on WindowPos instead. 1.304 + /// Ultimately, we may need to come up with a more convenient alternative, 1.305 + /// such as API-specific functions that return adapter, or something that will 1.306 + /// work with our monitor driver. 1.307 + /// Windows: (e.g. "\\\\.\\DISPLAY3", can be used in EnumDisplaySettings/CreateDC). 1.308 + const char* DisplayDeviceName; 1.309 + /// MacOS: 1.310 + int DisplayId; 1.311 + 1.312 +} ovrHmdDesc; 1.313 + 1.314 +/// Simple type ovrHmd is used in ovrHmd_* calls. 1.315 +typedef const ovrHmdDesc * ovrHmd; 1.316 + 1.317 +/// Bit flags describing the current status of sensor tracking. 1.318 +typedef enum 1.319 +{ 1.320 + ovrStatus_OrientationTracked = 0x0001, /// Orientation is currently tracked (connected and in use). 1.321 + ovrStatus_PositionTracked = 0x0002, /// Position is currently tracked (false if out of range). 1.322 + ovrStatus_CameraPoseTracked = 0x0004, /// Camera pose is currently tracked. 1.323 + ovrStatus_PositionConnected = 0x0020, /// Position tracking hardware is connected. 1.324 + ovrStatus_HmdConnected = 0x0080 /// HMD Display is available and connected. 1.325 +} ovrStatusBits; 1.326 + 1.327 +/// Specifies a reading we can query from the sensor. 1.328 +typedef struct ovrSensorData_ 1.329 +{ 1.330 + ovrVector3f Accelerometer; /// Acceleration reading in m/s^2. 1.331 + ovrVector3f Gyro; /// Rotation rate in rad/s. 1.332 + ovrVector3f Magnetometer; /// Magnetic field in Gauss. 1.333 + float Temperature; /// Temperature of the sensor in degrees Celsius. 1.334 + float TimeInSeconds; /// Time when the reported IMU reading took place, in seconds. 1.335 +} ovrSensorData; 1.336 + 1.337 +/// Tracking state at a given absolute time (describes predicted HMD pose etc). 1.338 +/// Returned by ovrHmd_GetTrackingState. 1.339 +typedef struct ovrTrackingState_ 1.340 +{ 1.341 + /// Predicted head pose (and derivatives) at the requested absolute time. 1.342 + /// The look-ahead interval is equal to (HeadPose.TimeInSeconds - RawSensorData.TimeInSeconds). 1.343 + ovrPoseStatef HeadPose; 1.344 + 1.345 + /// Current pose of the external camera (if present). 1.346 + /// This pose includes camera tilt (roll and pitch). For a leveled coordinate 1.347 + /// system use LeveledCameraPose. 1.348 + ovrPosef CameraPose; 1.349 + 1.350 + /// Camera frame aligned with gravity. 1.351 + /// This value includes position and yaw of the camera, but not roll and pitch. 1.352 + /// It can be used as a reference point to render real-world objects in the correct location. 1.353 + ovrPosef LeveledCameraPose; 1.354 + 1.355 + /// The most recent sensor data received from the HMD. 1.356 + ovrSensorData RawSensorData; 1.357 + 1.358 + /// Tracking status described by ovrStatusBits. 1.359 + unsigned int StatusFlags; 1.360 + 1.361 + //// 0.4.1 1.362 + 1.363 + // Measures the time from receiving the camera frame until vision CPU processing completes. 1.364 + double LastVisionProcessingTime; 1.365 + 1.366 + //// 0.4.3 1.367 + 1.368 + // Measures the time from exposure until the pose is available for the frame, including processing time. 1.369 + double LastVisionFrameLatency; 1.370 + 1.371 + /// Tag the vision processing results to a certain frame counter number. 1.372 + uint32_t LastCameraFrameCounter; 1.373 +} ovrTrackingState; 1.374 + 1.375 +/// Frame timing data reported by ovrHmd_BeginFrameTiming() or ovrHmd_BeginFrame(). 1.376 +typedef struct ovrFrameTiming_ 1.377 +{ 1.378 + /// The amount of time that has passed since the previous frame's 1.379 + /// ThisFrameSeconds value (usable for movement scaling). 1.380 + /// This will be clamped to no more than 0.1 seconds to prevent 1.381 + /// excessive movement after pauses due to loading or initialization. 1.382 + float DeltaSeconds; 1.383 + 1.384 + /// It is generally expected that the following holds: 1.385 + /// ThisFrameSeconds < TimewarpPointSeconds < NextFrameSeconds < 1.386 + /// EyeScanoutSeconds[EyeOrder[0]] <= ScanoutMidpointSeconds <= EyeScanoutSeconds[EyeOrder[1]]. 1.387 + 1.388 + /// Absolute time value when rendering of this frame began or is expected to 1.389 + /// begin. Generally equal to NextFrameSeconds of the previous frame. Can be used 1.390 + /// for animation timing. 1.391 + double ThisFrameSeconds; 1.392 + /// Absolute point when IMU expects to be sampled for this frame. 1.393 + double TimewarpPointSeconds; 1.394 + /// Absolute time when frame Present followed by GPU Flush will finish and the next frame begins. 1.395 + double NextFrameSeconds; 1.396 + 1.397 + /// Time when half of the screen will be scanned out. Can be passed as an absolute time 1.398 + /// to ovrHmd_GetTrackingState() to get the predicted general orientation. 1.399 + double ScanoutMidpointSeconds; 1.400 + /// Timing points when each eye will be scanned out to display. Used when rendering each eye. 1.401 + double EyeScanoutSeconds[2]; 1.402 +} ovrFrameTiming; 1.403 + 1.404 +/// Rendering information for each eye. Computed by either ovrHmd_ConfigureRendering() 1.405 +/// or ovrHmd_GetRenderDesc() based on the specified FOV. Note that the rendering viewport 1.406 +/// is not included here as it can be specified separately and modified per frame through: 1.407 +/// (a) ovrHmd_GetRenderScaleAndOffset in the case of client rendered distortion, 1.408 +/// or (b) passing different values via ovrTexture in the case of SDK rendered distortion. 1.409 +typedef struct ovrEyeRenderDesc_ 1.410 +{ 1.411 + ovrEyeType Eye; ///< The eye index this instance corresponds to. 1.412 + ovrFovPort Fov; ///< The field of view. 1.413 + ovrRecti DistortedViewport; ///< Distortion viewport. 1.414 + ovrVector2f PixelsPerTanAngleAtCenter; ///< How many display pixels will fit in tan(angle) = 1. 1.415 + ovrVector3f HmdToEyeViewOffset; ///< Translation to be applied to view matrix for each eye offset. 1.416 +} ovrEyeRenderDesc; 1.417 + 1.418 +//----------------------------------------------------------------------------------- 1.419 +// ***** Platform-independent Rendering Configuration 1.420 + 1.421 +/// These types are used to hide platform-specific details when passing 1.422 +/// render device, OS, and texture data to the API. 1.423 +/// 1.424 +/// The benefit of having these wrappers versus platform-specific API functions is 1.425 +/// that they allow game glue code to be portable. A typical example is an 1.426 +/// engine that has multiple back ends, say GL and D3D. Portable code that calls 1.427 +/// these back ends may also use LibOVR. To do this, back ends can be modified 1.428 +/// to return portable types such as ovrTexture and ovrRenderAPIConfig. 1.429 +typedef enum 1.430 +{ 1.431 + ovrRenderAPI_None, 1.432 + ovrRenderAPI_OpenGL, 1.433 + ovrRenderAPI_Android_GLES, // May include extra native window pointers, etc. 1.434 + ovrRenderAPI_D3D9, 1.435 + ovrRenderAPI_D3D10, 1.436 + ovrRenderAPI_D3D11, 1.437 + ovrRenderAPI_Count 1.438 +} ovrRenderAPIType; 1.439 + 1.440 +/// Platform-independent part of rendering API-configuration data. 1.441 +/// It is a part of ovrRenderAPIConfig, passed to ovrHmd_Configure. 1.442 +typedef struct OVR_ALIGNAS(8) ovrRenderAPIConfigHeader_ 1.443 +{ 1.444 + ovrRenderAPIType API; 1.445 + ovrSizei BackBufferSize; // Previously named RTSize. 1.446 + int Multisample; 1.447 +} ovrRenderAPIConfigHeader; 1.448 + 1.449 +/// Contains platform-specific information for rendering. 1.450 +typedef struct OVR_ALIGNAS(8) ovrRenderAPIConfig_ 1.451 +{ 1.452 + ovrRenderAPIConfigHeader Header; 1.453 + uintptr_t PlatformData[8]; 1.454 +} ovrRenderAPIConfig; 1.455 + 1.456 +/// Platform-independent part of the eye texture descriptor. 1.457 +/// It is a part of ovrTexture, passed to ovrHmd_EndFrame. 1.458 +/// If RenderViewport is all zeros then the full texture will be used. 1.459 +typedef struct OVR_ALIGNAS(8) ovrTextureHeader_ 1.460 +{ 1.461 + ovrRenderAPIType API; 1.462 + ovrSizei TextureSize; 1.463 + ovrRecti RenderViewport; // Pixel viewport in texture that holds eye image. 1.464 + uint32_t _PAD0_; 1.465 +} ovrTextureHeader; 1.466 + 1.467 +/// Contains platform-specific information about a texture. 1.468 +typedef struct OVR_ALIGNAS(8) ovrTexture_ 1.469 +{ 1.470 + ovrTextureHeader Header; 1.471 + uintptr_t PlatformData[8]; 1.472 +} ovrTexture; 1.473 + 1.474 + 1.475 +// ----------------------------------------------------------------------------------- 1.476 +// ***** API Interfaces 1.477 + 1.478 +// Basic steps to use the API: 1.479 +// 1.480 +// Setup: 1.481 +// * ovrInitialize() 1.482 +// * ovrHMD hmd = ovrHmd_Create(0) 1.483 +// * Use hmd members and ovrHmd_GetFovTextureSize() to determine graphics configuration. 1.484 +// * Call ovrHmd_ConfigureTracking() to configure and initialize tracking. 1.485 +// * Call ovrHmd_ConfigureRendering() to setup graphics for SDK rendering, 1.486 +// which is the preferred approach. 1.487 +// Please refer to "Client Distorton Rendering" below if you prefer to do that instead. 1.488 +// * If the ovrHmdCap_ExtendDesktop flag is not set, then use ovrHmd_AttachToWindow to 1.489 +// associate the relevant application window with the hmd. 1.490 +// * Allocate render target textures as needed. 1.491 +// 1.492 +// Game Loop: 1.493 +// * Call ovrHmd_BeginFrame() to get the current frame timing information. 1.494 +// * Render each eye using ovrHmd_GetEyePoses or ovrHmd_GetHmdPosePerEye to get 1.495 +// the predicted hmd pose and each eye pose. 1.496 +// * Call ovrHmd_EndFrame() to render the distorted textures to the back buffer 1.497 +// and present them on the hmd. 1.498 +// 1.499 +// Shutdown: 1.500 +// * ovrHmd_Destroy(hmd) 1.501 +// * ovr_Shutdown() 1.502 +// 1.503 + 1.504 +#ifdef __cplusplus 1.505 +extern "C" { 1.506 +#endif 1.507 + 1.508 +// ovr_InitializeRenderingShim initializes the rendering shim appart from everything 1.509 +// else in LibOVR. This may be helpful if the application prefers to avoid 1.510 +// creating any OVR resources (allocations, service connections, etc) at this point. 1.511 +// ovr_InitializeRenderingShim does not bring up anything within LibOVR except the 1.512 +// necessary hooks to enable the Direct-to-Rift functionality. 1.513 +// 1.514 +// Either ovr_InitializeRenderingShim() or ovr_Initialize() must be called before any 1.515 +// Direct3D or OpenGL initilization is done by applictaion (creation of devices, etc). 1.516 +// ovr_Initialize() must still be called after to use the rest of LibOVR APIs. 1.517 +OVR_EXPORT ovrBool ovr_InitializeRenderingShim(); 1.518 + 1.519 +// Library init/shutdown, must be called around all other OVR code. 1.520 +// No other functions calls besides ovr_InitializeRenderingShim are allowed 1.521 +// before ovr_Initialize succeeds or after ovr_Shutdown. 1.522 +/// Initializes all Oculus functionality. 1.523 +OVR_EXPORT ovrBool ovr_Initialize(); 1.524 +/// Shuts down all Oculus functionality. 1.525 +OVR_EXPORT void ovr_Shutdown(); 1.526 + 1.527 +/// Returns version string representing libOVR version. Static, so 1.528 +/// string remains valid for app lifespan 1.529 +OVR_EXPORT const char* ovr_GetVersionString(); 1.530 + 1.531 +/// Detects or re-detects HMDs and reports the total number detected. 1.532 +/// Users can get information about each HMD by calling ovrHmd_Create with an index. 1.533 +OVR_EXPORT int ovrHmd_Detect(); 1.534 + 1.535 +/// Creates a handle to an HMD which doubles as a description structure. 1.536 +/// Index can [0 .. ovrHmd_Detect()-1]. Index mappings can cange after each ovrHmd_Detect call. 1.537 +/// If not null, then the returned handle must be freed with ovrHmd_Destroy. 1.538 +OVR_EXPORT ovrHmd ovrHmd_Create(int index); 1.539 +OVR_EXPORT void ovrHmd_Destroy(ovrHmd hmd); 1.540 + 1.541 +/// Creates a 'fake' HMD used for debugging only. This is not tied to specific hardware, 1.542 +/// but may be used to debug some of the related rendering. 1.543 +OVR_EXPORT ovrHmd ovrHmd_CreateDebug(ovrHmdType type); 1.544 + 1.545 +/// Returns last error for HMD state. Returns null for no error. 1.546 +/// String is valid until next call or GetLastError or HMD is destroyed. 1.547 +/// Pass null hmd to get global errors (during create etc). 1.548 +OVR_EXPORT const char* ovrHmd_GetLastError(ovrHmd hmd); 1.549 + 1.550 +/// Platform specific function to specify the application window whose output will be 1.551 +/// displayed on the HMD. Only used if the ovrHmdCap_ExtendDesktop flag is false. 1.552 +/// Windows: SwapChain associated with this window will be displayed on the HMD. 1.553 +/// Specify 'destMirrorRect' in window coordinates to indicate an area 1.554 +/// of the render target output that will be mirrored from 'sourceRenderTargetRect'. 1.555 +/// Null pointers mean "full size". 1.556 +/// @note Source and dest mirror rects are not yet implemented. 1.557 +OVR_EXPORT ovrBool ovrHmd_AttachToWindow(ovrHmd hmd, void* window, 1.558 + const ovrRecti* destMirrorRect, 1.559 + const ovrRecti* sourceRenderTargetRect); 1.560 + 1.561 +/// Returns capability bits that are enabled at this time as described by ovrHmdCaps. 1.562 +/// Note that this value is different font ovrHmdDesc::HmdCaps, which describes what 1.563 +/// capabilities are available for that HMD. 1.564 +OVR_EXPORT unsigned int ovrHmd_GetEnabledCaps(ovrHmd hmd); 1.565 + 1.566 +/// Modifies capability bits described by ovrHmdCaps that can be modified, 1.567 +/// such as ovrHmdCap_LowPersistance. 1.568 +OVR_EXPORT void ovrHmd_SetEnabledCaps(ovrHmd hmd, unsigned int hmdCaps); 1.569 + 1.570 +//------------------------------------------------------------------------------------- 1.571 +// ***** Tracking Interface 1.572 + 1.573 +/// All tracking interface functions are thread-safe, allowing tracking state to be sampled 1.574 +/// from different threads. 1.575 +/// ConfigureTracking starts sensor sampling, enabling specified capabilities, 1.576 +/// described by ovrTrackingCaps. 1.577 +/// - supportedTrackingCaps specifies support that is requested. The function will succeed 1.578 +/// even if these caps are not available (i.e. sensor or camera is unplugged). Support 1.579 +/// will automatically be enabled if such device is plugged in later. Software should 1.580 +/// check ovrTrackingState.StatusFlags for real-time status. 1.581 +/// - requiredTrackingCaps specify sensor capabilities required at the time of the call. 1.582 +/// If they are not available, the function will fail. Pass 0 if only specifying 1.583 +/// supportedTrackingCaps. 1.584 +/// - Pass 0 for both supportedTrackingCaps and requiredTrackingCaps to disable tracking. 1.585 +OVR_EXPORT ovrBool ovrHmd_ConfigureTracking(ovrHmd hmd, unsigned int supportedTrackingCaps, 1.586 + unsigned int requiredTrackingCaps); 1.587 + 1.588 +/// Re-centers the sensor orientation. 1.589 +/// Normally this will recenter the (x,y,z) translational components and the yaw 1.590 +/// component of orientation. 1.591 +OVR_EXPORT void ovrHmd_RecenterPose(ovrHmd hmd); 1.592 + 1.593 +/// Returns tracking state reading based on the specified absolute system time. 1.594 +/// Pass an absTime value of 0.0 to request the most recent sensor reading. In this case 1.595 +/// both PredictedPose and SamplePose will have the same value. 1.596 +/// ovrHmd_GetEyePoses relies on this function internally. 1.597 +/// This may also be used for more refined timing of FrontBuffer rendering logic, etc. 1.598 +OVR_EXPORT ovrTrackingState ovrHmd_GetTrackingState(ovrHmd hmd, double absTime); 1.599 + 1.600 +//------------------------------------------------------------------------------------- 1.601 +// ***** Graphics Setup 1.602 + 1.603 +/// Calculates the recommended texture size for rendering a given eye within the HMD 1.604 +/// with a given FOV cone. Higher FOV will generally require larger textures to 1.605 +/// maintain quality. 1.606 +/// - pixelsPerDisplayPixel specifies the ratio of the number of render target pixels 1.607 +/// to display pixels at the center of distortion. 1.0 is the default value. Lower 1.608 +/// values can improve performance. 1.609 +OVR_EXPORT ovrSizei ovrHmd_GetFovTextureSize(ovrHmd hmd, ovrEyeType eye, ovrFovPort fov, 1.610 + float pixelsPerDisplayPixel); 1.611 + 1.612 +//------------------------------------------------------------------------------------- 1.613 +// ***** Rendering API Thread Safety 1.614 + 1.615 +// All of rendering functions including the configure and frame functions 1.616 +// are *NOT thread safe*. It is ok to use ConfigureRendering on one thread and handle 1.617 +// frames on another thread, but explicit synchronization must be done since 1.618 +// functions that depend on configured state are not reentrant. 1.619 +// 1.620 +// As an extra requirement, any of the following calls must be done on 1.621 +// the render thread, which is the same thread that calls ovrHmd_BeginFrame 1.622 +// or ovrHmd_BeginFrameTiming. 1.623 +// - ovrHmd_EndFrame 1.624 +// - ovrHmd_GetEyeTimewarpMatrices 1.625 + 1.626 +//------------------------------------------------------------------------------------- 1.627 +// ***** SDK Distortion Rendering Functions 1.628 + 1.629 +// These functions support rendering of distortion by the SDK through direct 1.630 +// access to the underlying rendering API, such as D3D or GL. 1.631 +// This is the recommended approach since it allows better support for future 1.632 +// Oculus hardware, and enables a range of low-level optimizations. 1.633 + 1.634 +/// Configures rendering and fills in computed render parameters. 1.635 +/// This function can be called multiple times to change rendering settings. 1.636 +/// eyeRenderDescOut is a pointer to an array of two ovrEyeRenderDesc structs 1.637 +/// that are used to return complete rendering information for each eye. 1.638 +/// - apiConfig provides D3D/OpenGL specific parameters. Pass null 1.639 +/// to shutdown rendering and release all resources. 1.640 +/// - distortionCaps describe desired distortion settings. 1.641 +OVR_EXPORT ovrBool ovrHmd_ConfigureRendering( ovrHmd hmd, 1.642 + const ovrRenderAPIConfig* apiConfig, 1.643 + unsigned int distortionCaps, 1.644 + const ovrFovPort eyeFovIn[2], 1.645 + ovrEyeRenderDesc eyeRenderDescOut[2] ); 1.646 + 1.647 + 1.648 +/// Begins a frame, returning timing information. 1.649 +/// This should be called at the beginning of the game rendering loop (on the render thread). 1.650 +/// Pass 0 for the frame index if not using ovrHmd_GetFrameTiming. 1.651 +OVR_EXPORT ovrFrameTiming ovrHmd_BeginFrame(ovrHmd hmd, unsigned int frameIndex); 1.652 + 1.653 +/// Ends a frame, submitting the rendered textures to the frame buffer. 1.654 +/// - RenderViewport within each eyeTexture can change per frame if necessary. 1.655 +/// - 'renderPose' will typically be the value returned from ovrHmd_GetEyePoses, 1.656 +/// ovrHmd_GetHmdPosePerEye but can be different if a different head pose was 1.657 +/// used for rendering. 1.658 +/// - This may perform distortion and scaling internally, assuming is it not 1.659 +/// delegated to another thread. 1.660 +/// - Must be called on the same thread as BeginFrame. 1.661 +/// - *** This Function will call Present/SwapBuffers and potentially wait for GPU Sync ***. 1.662 +OVR_EXPORT void ovrHmd_EndFrame(ovrHmd hmd, 1.663 + const ovrPosef renderPose[2], 1.664 + const ovrTexture eyeTexture[2]); 1.665 + 1.666 +/// Returns predicted head pose in outHmdTrackingState and offset eye poses in outEyePoses 1.667 +/// as an atomic operation. Caller need not worry about applying HmdToEyeViewOffset to the 1.668 +/// returned outEyePoses variables. 1.669 +/// - Thread-safe function where caller should increment frameIndex with every frame 1.670 +/// and pass the index where applicable to functions called on the rendering thread. 1.671 +/// - hmdToEyeViewOffset[2] can be ovrEyeRenderDesc.HmdToEyeViewOffset returned from 1.672 +/// ovrHmd_ConfigureRendering or ovrHmd_GetRenderDesc. For monoscopic rendering, 1.673 +/// use a vector that is the average of the two vectors for both eyes. 1.674 +/// - If frameIndex is not being used, pass in 0. 1.675 +/// - Assuming outEyePoses are used for rendering, it should be passed into ovrHmd_EndFrame. 1.676 +/// - If called doesn't need outHmdTrackingState, it can be NULL 1.677 +OVR_EXPORT void ovrHmd_GetEyePoses(ovrHmd hmd, unsigned int frameIndex, ovrVector3f hmdToEyeViewOffset[2], 1.678 + ovrPosef outEyePoses[2], ovrTrackingState* outHmdTrackingState); 1.679 + 1.680 +/// Function was previously called ovrHmd_GetEyePose 1.681 +/// Returns the predicted head pose to use when rendering the specified eye. 1.682 +/// - Important: Caller must apply HmdToEyeViewOffset before using ovrPosef for rendering 1.683 +/// - Must be called between ovrHmd_BeginFrameTiming and ovrHmd_EndFrameTiming. 1.684 +/// - If the pose is used for rendering the eye, it should be passed to ovrHmd_EndFrame. 1.685 +/// - Parameter 'eye' is used for prediction timing only 1.686 +OVR_EXPORT ovrPosef ovrHmd_GetHmdPosePerEye(ovrHmd hmd, ovrEyeType eye); 1.687 + 1.688 + 1.689 +//------------------------------------------------------------------------------------- 1.690 +// ***** Client Distortion Rendering Functions 1.691 + 1.692 +// These functions provide the distortion data and render timing support necessary to allow 1.693 +// client rendering of distortion. Client-side rendering involves the following steps: 1.694 +// 1.695 +// 1. Setup ovrEyeDesc based on the desired texture size and FOV. 1.696 +// Call ovrHmd_GetRenderDesc to get the necessary rendering parameters for each eye. 1.697 +// 1.698 +// 2. Use ovrHmd_CreateDistortionMesh to generate the distortion mesh. 1.699 +// 1.700 +// 3. Use ovrHmd_BeginFrameTiming, ovrHmd_GetEyePoses, and ovrHmd_BeginFrameTiming in 1.701 +// the rendering loop to obtain timing and predicted head orientation when rendering each eye. 1.702 +// - When using timewarp, use ovr_WaitTillTime after the rendering and gpu flush, followed 1.703 +// by ovrHmd_GetEyeTimewarpMatrices to obtain the timewarp matrices used 1.704 +// by the distortion pixel shader. This will minimize latency. 1.705 +// 1.706 + 1.707 +/// Computes the distortion viewport, view adjust, and other rendering parameters for 1.708 +/// the specified eye. This can be used instead of ovrHmd_ConfigureRendering to do 1.709 +/// setup for client rendered distortion. 1.710 +OVR_EXPORT ovrEyeRenderDesc ovrHmd_GetRenderDesc(ovrHmd hmd, 1.711 + ovrEyeType eyeType, ovrFovPort fov); 1.712 + 1.713 + 1.714 +/// Describes a vertex used by the distortion mesh. This is intended to be converted into 1.715 +/// the engine-specific format. Some fields may be unused based on the ovrDistortionCaps 1.716 +/// flags selected. TexG and TexB, for example, are not used if chromatic correction is 1.717 +/// not requested. 1.718 +typedef struct ovrDistortionVertex_ 1.719 +{ 1.720 + ovrVector2f ScreenPosNDC; ///< [-1,+1],[-1,+1] over the entire framebuffer. 1.721 + float TimeWarpFactor; ///< Lerp factor between time-warp matrices. Can be encoded in Pos.z. 1.722 + float VignetteFactor; ///< Vignette fade factor. Can be encoded in Pos.w. 1.723 + ovrVector2f TanEyeAnglesR; ///< The tangents of the horizontal and vertical eye angles for the red channel. 1.724 + ovrVector2f TanEyeAnglesG; ///< The tangents of the horizontal and vertical eye angles for the green channel. 1.725 + ovrVector2f TanEyeAnglesB; ///< The tangents of the horizontal and vertical eye angles for the blue channel. 1.726 +} ovrDistortionVertex; 1.727 + 1.728 +/// Describes a full set of distortion mesh data, filled in by ovrHmd_CreateDistortionMesh. 1.729 +/// Contents of this data structure, if not null, should be freed by ovrHmd_DestroyDistortionMesh. 1.730 +typedef struct ovrDistortionMesh_ 1.731 +{ 1.732 + ovrDistortionVertex* pVertexData; ///< The distortion vertices representing each point in the mesh. 1.733 + unsigned short* pIndexData; ///< Indices for connecting the mesh vertices into polygons. 1.734 + unsigned int VertexCount; ///< The number of vertices in the mesh. 1.735 + unsigned int IndexCount; ///< The number of indices in the mesh. 1.736 +} ovrDistortionMesh; 1.737 + 1.738 +/// Generate distortion mesh per eye. 1.739 +/// Distortion capabilities will depend on 'distortionCaps' flags. Users should 1.740 +/// render using the appropriate shaders based on their settings. 1.741 +/// Distortion mesh data will be allocated and written into the ovrDistortionMesh data structure, 1.742 +/// which should be explicitly freed with ovrHmd_DestroyDistortionMesh. 1.743 +/// Users should call ovrHmd_GetRenderScaleAndOffset to get uvScale and Offset values for rendering. 1.744 +/// The function shouldn't fail unless theres is a configuration or memory error, in which case 1.745 +/// ovrDistortionMesh values will be set to null. 1.746 +/// This is the only function in the SDK reliant on eye relief, currently imported from profiles, 1.747 +/// or overridden here. 1.748 +OVR_EXPORT ovrBool ovrHmd_CreateDistortionMesh( ovrHmd hmd, 1.749 + ovrEyeType eyeType, ovrFovPort fov, 1.750 + unsigned int distortionCaps, 1.751 + ovrDistortionMesh *meshData); 1.752 +OVR_EXPORT ovrBool ovrHmd_CreateDistortionMeshDebug( ovrHmd hmddesc, 1.753 + ovrEyeType eyeType, ovrFovPort fov, 1.754 + unsigned int distortionCaps, 1.755 + ovrDistortionMesh *meshData, 1.756 + float debugEyeReliefOverrideInMetres); 1.757 + 1.758 + 1.759 +/// Used to free the distortion mesh allocated by ovrHmd_GenerateDistortionMesh. meshData elements 1.760 +/// are set to null and zeroes after the call. 1.761 +OVR_EXPORT void ovrHmd_DestroyDistortionMesh( ovrDistortionMesh* meshData ); 1.762 + 1.763 +/// Computes updated 'uvScaleOffsetOut' to be used with a distortion if render target size or 1.764 +/// viewport changes after the fact. This can be used to adjust render size every frame if desired. 1.765 +OVR_EXPORT void ovrHmd_GetRenderScaleAndOffset( ovrFovPort fov, 1.766 + ovrSizei textureSize, ovrRecti renderViewport, 1.767 + ovrVector2f uvScaleOffsetOut[2] ); 1.768 + 1.769 +/// Thread-safe timing function for the main thread. Caller should increment frameIndex 1.770 +/// with every frame and pass the index where applicable to functions called on the 1.771 +/// rendering thread. 1.772 +OVR_EXPORT ovrFrameTiming ovrHmd_GetFrameTiming(ovrHmd hmd, unsigned int frameIndex); 1.773 + 1.774 +/// Called at the beginning of the frame on the rendering thread. 1.775 +/// Pass frameIndex == 0 if ovrHmd_GetFrameTiming isn't being used. Otherwise, 1.776 +/// pass the same frame index as was used for GetFrameTiming on the main thread. 1.777 +OVR_EXPORT ovrFrameTiming ovrHmd_BeginFrameTiming(ovrHmd hmd, unsigned int frameIndex); 1.778 + 1.779 +/// Marks the end of client distortion rendered frame, tracking the necessary timing information. 1.780 +/// This function must be called immediately after Present/SwapBuffers + GPU sync. GPU sync is 1.781 +/// important before this call to reduce latency and ensure proper timing. 1.782 +OVR_EXPORT void ovrHmd_EndFrameTiming(ovrHmd hmd); 1.783 + 1.784 +/// Initializes and resets frame time tracking. This is typically not necessary, but 1.785 +/// is helpful if game changes vsync state or video mode. vsync is assumed to be on if this 1.786 +/// isn't called. Resets internal frame index to the specified number. 1.787 +OVR_EXPORT void ovrHmd_ResetFrameTiming(ovrHmd hmd, unsigned int frameIndex); 1.788 + 1.789 +/// Computes timewarp matrices used by distortion mesh shader, these are used to adjust 1.790 +/// for head orientation change since the last call to ovrHmd_GetEyePoses 1.791 +/// when rendering this eye. The ovrDistortionVertex::TimeWarpFactor is used to blend between the 1.792 +/// matrices, usually representing two different sides of the screen. 1.793 +/// Must be called on the same thread as ovrHmd_BeginFrameTiming. 1.794 +OVR_EXPORT void ovrHmd_GetEyeTimewarpMatrices (ovrHmd hmd, ovrEyeType eye, 1.795 + ovrPosef renderPose, ovrMatrix4f twmOut[2]); 1.796 +OVR_EXPORT void ovrHmd_GetEyeTimewarpMatricesDebug(ovrHmd hmd, ovrEyeType eye, 1.797 + ovrPosef renderPose, ovrMatrix4f twmOut[2], 1.798 + double debugTimingOffsetInSeconds); 1.799 + 1.800 + 1.801 + 1.802 + 1.803 +//------------------------------------------------------------------------------------- 1.804 +// ***** Stateless math setup functions 1.805 + 1.806 +/// Used to generate projection from ovrEyeDesc::Fov. 1.807 +OVR_EXPORT ovrMatrix4f ovrMatrix4f_Projection( ovrFovPort fov, 1.808 + float znear, float zfar, ovrBool rightHanded ); 1.809 + 1.810 +/// Used for 2D rendering, Y is down 1.811 +/// orthoScale = 1.0f / pixelsPerTanAngleAtCenter 1.812 +/// orthoDistance = distance from camera, such as 0.8m 1.813 +OVR_EXPORT ovrMatrix4f ovrMatrix4f_OrthoSubProjection(ovrMatrix4f projection, ovrVector2f orthoScale, 1.814 + float orthoDistance, float hmdToEyeViewOffsetX); 1.815 + 1.816 +/// Returns global, absolute high-resolution time in seconds. This is the same 1.817 +/// value as used in sensor messages. 1.818 +OVR_EXPORT double ovr_GetTimeInSeconds(); 1.819 + 1.820 +/// Waits until the specified absolute time. 1.821 +OVR_EXPORT double ovr_WaitTillTime(double absTime); 1.822 + 1.823 +// ----------------------------------------------------------------------------------- 1.824 +// ***** Latency Test interface 1.825 + 1.826 +/// Does latency test processing and returns 'TRUE' if specified rgb color should 1.827 +/// be used to clear the screen. 1.828 +OVR_EXPORT ovrBool ovrHmd_ProcessLatencyTest(ovrHmd hmd, unsigned char rgbColorOut[3]); 1.829 + 1.830 +/// Returns non-null string once with latency test result, when it is available. 1.831 +/// Buffer is valid until next call. 1.832 +OVR_EXPORT const char* ovrHmd_GetLatencyTestResult(ovrHmd hmd); 1.833 + 1.834 +/// Returns the latency testing color in rgbColorOut to render when using a DK2 1.835 +/// Returns false if this feature is disabled or not-applicable (e.g. using a DK1) 1.836 +OVR_EXPORT ovrBool ovrHmd_GetLatencyTest2DrawColor(ovrHmd hmddesc, unsigned char rgbColorOut[3]); 1.837 + 1.838 +//------------------------------------------------------------------------------------- 1.839 +// ***** Health and Safety Warning Display interface 1.840 +// 1.841 + 1.842 +/// Used by ovrhmd_GetHSWDisplayState to report the current display state. 1.843 +typedef struct ovrHSWDisplayState_ 1.844 +{ 1.845 + /// If true then the warning should be currently visible 1.846 + /// and the following variables have meaning. Else there is no 1.847 + /// warning being displayed for this application on the given HMD. 1.848 + ovrBool Displayed; ///< True if the Health&Safety Warning is currently displayed. 1.849 + double StartTime; ///< Absolute time when the warning was first displayed. See ovr_GetTimeInSeconds(). 1.850 + double DismissibleTime; ///< Earliest absolute time when the warning can be dismissed. May be a time in the past. 1.851 +} ovrHSWDisplayState; 1.852 + 1.853 +/// Returns the current state of the HSW display. If the application is doing the rendering of 1.854 +/// the HSW display then this function serves to indicate that the warning should be 1.855 +/// currently displayed. If the application is using SDK-based eye rendering then the SDK by 1.856 +/// default automatically handles the drawing of the HSW display. An application that uses 1.857 +/// application-based eye rendering should use this function to know when to start drawing the 1.858 +/// HSW display itself and can optionally use it in conjunction with ovrhmd_DismissHSWDisplay 1.859 +/// as described below. 1.860 +/// 1.861 +/// Example usage for application-based rendering: 1.862 +/// bool HSWDisplayCurrentlyDisplayed = false; // global or class member variable 1.863 +/// ovrHSWDisplayState hswDisplayState; 1.864 +/// ovrhmd_GetHSWDisplayState(Hmd, &hswDisplayState); 1.865 +/// 1.866 +/// if (hswDisplayState.Displayed && !HSWDisplayCurrentlyDisplayed) { 1.867 +/// <insert model into the scene that stays in front of the user> 1.868 +/// HSWDisplayCurrentlyDisplayed = true; 1.869 +/// } 1.870 +OVR_EXPORT void ovrHmd_GetHSWDisplayState(ovrHmd hmd, ovrHSWDisplayState *hasWarningState); 1.871 + 1.872 +/// Dismisses the HSW display if the warning is dismissible and the earliest dismissal time 1.873 +/// has occurred. Returns true if the display is valid and could be dismissed. The application 1.874 +/// should recognize that the HSW display is being displayed (via ovrhmd_GetHSWDisplayState) 1.875 +/// and if so then call this function when the appropriate user input to dismiss the warning 1.876 +/// occurs. 1.877 +/// 1.878 +/// Example usage : 1.879 +/// void ProcessEvent(int key) { 1.880 +/// if (key == escape) { 1.881 +/// ovrHSWDisplayState hswDisplayState; 1.882 +/// ovrhmd_GetHSWDisplayState(hmd, &hswDisplayState); 1.883 +/// 1.884 +/// if (hswDisplayState.Displayed && ovrhmd_DismissHSWDisplay(hmd)) { 1.885 +/// <remove model from the scene> 1.886 +/// HSWDisplayCurrentlyDisplayed = false; 1.887 +/// } 1.888 +/// } 1.889 +/// } 1.890 +OVR_EXPORT ovrBool ovrHmd_DismissHSWDisplay(ovrHmd hmd); 1.891 + 1.892 +/// Get boolean property. Returns first element if property is a boolean array. 1.893 +/// Returns defaultValue if property doesn't exist. 1.894 +OVR_EXPORT ovrBool ovrHmd_GetBool(ovrHmd hmd, const char* propertyName, ovrBool defaultVal); 1.895 + 1.896 +/// Modify bool property; false if property doesn't exist or is readonly. 1.897 +OVR_EXPORT ovrBool ovrHmd_SetBool(ovrHmd hmd, const char* propertyName, ovrBool value); 1.898 + 1.899 +/// Get integer property. Returns first element if property is an integer array. 1.900 +/// Returns defaultValue if property doesn't exist. 1.901 +OVR_EXPORT int ovrHmd_GetInt(ovrHmd hmd, const char* propertyName, int defaultVal); 1.902 + 1.903 +/// Modify integer property; false if property doesn't exist or is readonly. 1.904 +OVR_EXPORT ovrBool ovrHmd_SetInt(ovrHmd hmd, const char* propertyName, int value); 1.905 + 1.906 +/// Get float property. Returns first element if property is a float array. 1.907 +/// Returns defaultValue if property doesn't exist. 1.908 +OVR_EXPORT float ovrHmd_GetFloat(ovrHmd hmd, const char* propertyName, float defaultVal); 1.909 + 1.910 +/// Modify float property; false if property doesn't exist or is readonly. 1.911 +OVR_EXPORT ovrBool ovrHmd_SetFloat(ovrHmd hmd, const char* propertyName, float value); 1.912 + 1.913 +/// Get float[] property. Returns the number of elements filled in, 0 if property doesn't exist. 1.914 +/// Maximum of arraySize elements will be written. 1.915 +OVR_EXPORT unsigned int ovrHmd_GetFloatArray(ovrHmd hmd, const char* propertyName, 1.916 + float values[], unsigned int arraySize); 1.917 + 1.918 +/// Modify float[] property; false if property doesn't exist or is readonly. 1.919 +OVR_EXPORT ovrBool ovrHmd_SetFloatArray(ovrHmd hmd, const char* propertyName, 1.920 + float values[], unsigned int arraySize); 1.921 + 1.922 +/// Get string property. Returns first element if property is a string array. 1.923 +/// Returns defaultValue if property doesn't exist. 1.924 +/// String memory is guaranteed to exist until next call to GetString or GetStringArray, or HMD is destroyed. 1.925 +OVR_EXPORT const char* ovrHmd_GetString(ovrHmd hmd, const char* propertyName, 1.926 + const char* defaultVal); 1.927 + 1.928 +/// Set string property 1.929 +OVR_EXPORT ovrBool ovrHmd_SetString(ovrHmd hmddesc, const char* propertyName, 1.930 + const char* value); 1.931 + 1.932 +// ----------------------------------------------------------------------------------- 1.933 +// ***** Logging 1.934 + 1.935 +/// Start performance logging. guid is optional and if included is written with each file entry. 1.936 +/// If called while logging is already active with the same filename, only the guid will be updated 1.937 +/// If called while logging is already active with a different filename, ovrHmd_StopPerfLog() will be called, followed by ovrHmd_StartPerfLog() 1.938 +OVR_EXPORT ovrBool ovrHmd_StartPerfLog(ovrHmd hmd, const char* fileName, const char* userData1); 1.939 +/// Stop performance logging. 1.940 +OVR_EXPORT ovrBool ovrHmd_StopPerfLog(ovrHmd hmd); 1.941 + 1.942 + 1.943 +#ifdef __cplusplus 1.944 +} // extern "C" 1.945 +#endif 1.946 + 1.947 + 1.948 +#if defined(_MSC_VER) 1.949 + #pragma warning(pop) 1.950 +#endif 1.951 + 1.952 + 1.953 +#endif // OVR_CAPI_h