ovr_sdk

annotate LibOVR/Src/OVR_CAPI.h @ 0:1b39a1b46319

find changesets by author, revision, files, or words in the commit message
initial 0.4.4
author John Tsiombikas <nuclear@member.fsf.org>
date Wed, 14 Jan 2015 06:51:16 +0200
parents
children
rev   line source
nuclear@0 1 /************************************************************************************
nuclear@0 2
nuclear@0 3 Filename : OVR_CAPI.h
nuclear@0 4 Content : C Interface to Oculus tracking and rendering.
nuclear@0 5 Created : November 23, 2013
nuclear@0 6 Authors : Michael Antonov
nuclear@0 7
nuclear@0 8 Copyright : Copyright 2014 Oculus VR, LLC All Rights reserved.
nuclear@0 9
nuclear@0 10 Licensed under the Oculus VR Rift SDK License Version 3.2 (the "License");
nuclear@0 11 you may not use the Oculus VR Rift SDK except in compliance with the License,
nuclear@0 12 which is provided at the time of installation or download, or which
nuclear@0 13 otherwise accompanies this software in either electronic or hard copy form.
nuclear@0 14
nuclear@0 15 You may obtain a copy of the License at
nuclear@0 16
nuclear@0 17 http://www.oculusvr.com/licenses/LICENSE-3.2
nuclear@0 18
nuclear@0 19 Unless required by applicable law or agreed to in writing, the Oculus VR SDK
nuclear@0 20 distributed under the License is distributed on an "AS IS" BASIS,
nuclear@0 21 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
nuclear@0 22 See the License for the specific language governing permissions and
nuclear@0 23 limitations under the License.
nuclear@0 24
nuclear@0 25 ************************************************************************************/
nuclear@0 26
nuclear@0 27 /// @file OVR_CAPI.h
nuclear@0 28 /// Exposes all general Rift functionality.
nuclear@0 29
nuclear@0 30 #ifndef OVR_CAPI_h
nuclear@0 31 #define OVR_CAPI_h
nuclear@0 32
nuclear@0 33 #include <stdint.h>
nuclear@0 34
nuclear@0 35 #include "OVR_CAPI_Keys.h"
nuclear@0 36
nuclear@0 37 typedef char ovrBool;
nuclear@0 38
nuclear@0 39 //-----------------------------------------------------------------------------------
nuclear@0 40 // ***** OVR_EXPORT definition
nuclear@0 41
nuclear@0 42 #if !defined(OVR_EXPORT)
nuclear@0 43 #ifdef OVR_OS_WIN32
nuclear@0 44 #define OVR_EXPORT __declspec(dllexport)
nuclear@0 45 #else
nuclear@0 46 #define OVR_EXPORT
nuclear@0 47 #endif
nuclear@0 48 #endif
nuclear@0 49
nuclear@0 50
nuclear@0 51
nuclear@0 52 //-----------------------------------------------------------------------------------
nuclear@0 53 // ***** OVR_ALIGNAS definition
nuclear@0 54 //
nuclear@0 55 #if !defined(OVR_ALIGNAS)
nuclear@0 56 // C++11 alignas
nuclear@0 57 #if defined(__GNUC__) && (((__GNUC__ * 100) + __GNUC_MINOR__) >= 408) && (defined(__GXX_EXPERIMENTAL_CXX0X__) || (__cplusplus >= 201103L))
nuclear@0 58 #define OVR_ALIGNAS(n) alignas(n)
nuclear@0 59 #elif defined(__clang__) && !defined(__APPLE__) && (((__clang_major__ * 100) + __clang_minor__) >= 300) && (__cplusplus >= 201103L)
nuclear@0 60 #define OVR_ALIGNAS(n) alignas(n)
nuclear@0 61 #elif defined(__clang__) && defined(__APPLE__) && (((__clang_major__ * 100) + __clang_minor__) >= 401) && (__cplusplus >= 201103L)
nuclear@0 62 #define OVR_ALIGNAS(n) alignas(n)
nuclear@0 63 #elif defined(_MSC_VER) && (_MSC_VER >= 1900)
nuclear@0 64 #define OVR_ALIGNAS(n) alignas(n)
nuclear@0 65 #elif defined(__EDG_VERSION__) && (__EDG_VERSION__ >= 408)
nuclear@0 66 #define OVR_ALIGNAS(n) alignas(n)
nuclear@0 67
nuclear@0 68 // Pre-C++11 alignas fallbacks
nuclear@0 69 #elif defined(__GNUC__) || defined(__clang__)
nuclear@0 70 #define OVR_ALIGNAS(n) __attribute__((aligned(n)))
nuclear@0 71 #elif defined(_MSC_VER) || defined(__INTEL_COMPILER)
nuclear@0 72 #define OVR_ALIGNAS(n) __declspec(align(n)) // For Microsoft the alignment must be a literal integer.
nuclear@0 73 #elif defined(__CC_ARM)
nuclear@0 74 #define OVR_ALIGNAS(n) __align(n)
nuclear@0 75 #else
nuclear@0 76 #error Need to define OVR_ALIGNAS
nuclear@0 77 #endif
nuclear@0 78 #endif
nuclear@0 79
nuclear@0 80 #if defined(_MSC_VER)
nuclear@0 81 #pragma warning(push)
nuclear@0 82 #pragma warning(disable: 4324) // structure was padded due to __declspec(align())
nuclear@0 83 #endif
nuclear@0 84
nuclear@0 85
nuclear@0 86 //#define ENABLE_LATENCY_TESTER
nuclear@0 87
nuclear@0 88 //-----------------------------------------------------------------------------------
nuclear@0 89 // ***** Simple Math Structures
nuclear@0 90
nuclear@0 91 /// A 2D vector with integer components.
nuclear@0 92 typedef struct ovrVector2i_
nuclear@0 93 {
nuclear@0 94 int x, y;
nuclear@0 95 } ovrVector2i;
nuclear@0 96
nuclear@0 97 /// A 2D size with integer components.
nuclear@0 98 typedef struct ovrSizei_
nuclear@0 99 {
nuclear@0 100 int w, h;
nuclear@0 101 } ovrSizei;
nuclear@0 102 /// A 2D rectangle with a position and size.
nuclear@0 103 /// All components are integers.
nuclear@0 104 typedef struct ovrRecti_
nuclear@0 105 {
nuclear@0 106 ovrVector2i Pos;
nuclear@0 107 ovrSizei Size;
nuclear@0 108 } ovrRecti;
nuclear@0 109
nuclear@0 110 /// A quaternion rotation.
nuclear@0 111 typedef struct ovrQuatf_
nuclear@0 112 {
nuclear@0 113 float x, y, z, w;
nuclear@0 114 } ovrQuatf;
nuclear@0 115
nuclear@0 116 /// A 2D vector with float components.
nuclear@0 117 typedef struct ovrVector2f_
nuclear@0 118 {
nuclear@0 119 float x, y;
nuclear@0 120 } ovrVector2f;
nuclear@0 121
nuclear@0 122 /// A 3D vector with float components.
nuclear@0 123 typedef struct ovrVector3f_
nuclear@0 124 {
nuclear@0 125 float x, y, z;
nuclear@0 126 } ovrVector3f;
nuclear@0 127
nuclear@0 128 /// A 4x4 matrix with float elements.
nuclear@0 129 typedef struct ovrMatrix4f_
nuclear@0 130 {
nuclear@0 131 float M[4][4];
nuclear@0 132 } ovrMatrix4f;
nuclear@0 133
nuclear@0 134 /// Position and orientation together.
nuclear@0 135 typedef struct ovrPosef_
nuclear@0 136 {
nuclear@0 137 ovrQuatf Orientation;
nuclear@0 138 ovrVector3f Position;
nuclear@0 139 } ovrPosef;
nuclear@0 140
nuclear@0 141 /// A full pose (rigid body) configuration with first and second derivatives.
nuclear@0 142 typedef struct ovrPoseStatef_
nuclear@0 143 {
nuclear@0 144 ovrPosef ThePose; ///< The body's position and orientation.
nuclear@0 145 ovrVector3f AngularVelocity; ///< The body's angular velocity in radians per second.
nuclear@0 146 ovrVector3f LinearVelocity; ///< The body's velocity in meters per second.
nuclear@0 147 ovrVector3f AngularAcceleration; ///< The body's angular acceleration in radians per second per second.
nuclear@0 148 ovrVector3f LinearAcceleration; ///< The body's acceleration in meters per second per second.
nuclear@0 149 double TimeInSeconds; ///< Absolute time of this state sample.
nuclear@0 150 } ovrPoseStatef;
nuclear@0 151
nuclear@0 152 /// Field Of View (FOV) in tangent of the angle units.
nuclear@0 153 /// As an example, for a standard 90 degree vertical FOV, we would
nuclear@0 154 /// have: { UpTan = tan(90 degrees / 2), DownTan = tan(90 degrees / 2) }.
nuclear@0 155 typedef struct ovrFovPort_
nuclear@0 156 {
nuclear@0 157 /// The tangent of the angle between the viewing vector and the top edge of the field of view.
nuclear@0 158 float UpTan;
nuclear@0 159 /// The tangent of the angle between the viewing vector and the bottom edge of the field of view.
nuclear@0 160 float DownTan;
nuclear@0 161 /// The tangent of the angle between the viewing vector and the left edge of the field of view.
nuclear@0 162 float LeftTan;
nuclear@0 163 /// The tangent of the angle between the viewing vector and the right edge of the field of view.
nuclear@0 164 float RightTan;
nuclear@0 165 } ovrFovPort;
nuclear@0 166
nuclear@0 167 //-----------------------------------------------------------------------------------
nuclear@0 168 // ***** HMD Types
nuclear@0 169
nuclear@0 170 /// Enumerates all HMD types that we support.
nuclear@0 171 typedef enum
nuclear@0 172 {
nuclear@0 173 ovrHmd_None = 0,
nuclear@0 174 ovrHmd_DK1 = 3,
nuclear@0 175 ovrHmd_DKHD = 4,
nuclear@0 176 ovrHmd_DK2 = 6,
nuclear@0 177 ovrHmd_Other // Some HMD other then the one in the enumeration.
nuclear@0 178 } ovrHmdType;
nuclear@0 179
nuclear@0 180 /// HMD capability bits reported by device.
nuclear@0 181 typedef enum
nuclear@0 182 {
nuclear@0 183 // Read-only flags.
nuclear@0 184 ovrHmdCap_Present = 0x0001, /// The HMD is plugged in and detected by the system.
nuclear@0 185 ovrHmdCap_Available = 0x0002, /// The HMD and its sensor are available for ownership use.
nuclear@0 186 /// i.e. it is not already owned by another application.
nuclear@0 187 ovrHmdCap_Captured = 0x0004, /// Set to 'true' if we captured ownership of this HMD.
nuclear@0 188
nuclear@0 189 // These flags are intended for use with the new driver display mode.
nuclear@0 190 ovrHmdCap_ExtendDesktop = 0x0008, /// (read only) Means the display driver is in compatibility mode.
nuclear@0 191
nuclear@0 192 // Modifiable flags (through ovrHmd_SetEnabledCaps).
nuclear@0 193 ovrHmdCap_NoMirrorToWindow = 0x2000, /// Disables mirroring of HMD output to the window. This may improve
nuclear@0 194 /// rendering performance slightly (only if 'ExtendDesktop' is off).
nuclear@0 195 ovrHmdCap_DisplayOff = 0x0040, /// Turns off HMD screen and output (only if 'ExtendDesktop' is off).
nuclear@0 196
nuclear@0 197 ovrHmdCap_LowPersistence = 0x0080, /// HMD supports low persistence mode.
nuclear@0 198 ovrHmdCap_DynamicPrediction = 0x0200, /// Adjust prediction dynamically based on internally measured latency.
nuclear@0 199 ovrHmdCap_DirectPentile = 0x0400, /// Write directly in pentile color mapping format
nuclear@0 200 ovrHmdCap_NoVSync = 0x1000, /// Support rendering without VSync for debugging.
nuclear@0 201
nuclear@0 202 // These bits can be modified by ovrHmd_SetEnabledCaps.
nuclear@0 203 ovrHmdCap_Writable_Mask = 0x32F0,
nuclear@0 204
nuclear@0 205 /// These flags are currently passed into the service. May change without notice.
nuclear@0 206 ovrHmdCap_Service_Mask = 0x22F0
nuclear@0 207 } ovrHmdCaps;
nuclear@0 208
nuclear@0 209
nuclear@0 210 /// Tracking capability bits reported by the device.
nuclear@0 211 /// Used with ovrHmd_ConfigureTracking.
nuclear@0 212 typedef enum
nuclear@0 213 {
nuclear@0 214 ovrTrackingCap_Orientation = 0x0010, /// Supports orientation tracking (IMU).
nuclear@0 215 ovrTrackingCap_MagYawCorrection = 0x0020, /// Supports yaw drift correction via a magnetometer or other means.
nuclear@0 216 ovrTrackingCap_Position = 0x0040, /// Supports positional tracking.
nuclear@0 217 /// Overrides the other flags. Indicates that the application
nuclear@0 218 /// doesn't care about tracking settings. This is the internal
nuclear@0 219 /// default before ovrHmd_ConfigureTracking is called.
nuclear@0 220 ovrTrackingCap_Idle = 0x0100,
nuclear@0 221 } ovrTrackingCaps;
nuclear@0 222
nuclear@0 223 /// Distortion capability bits reported by device.
nuclear@0 224 /// Used with ovrHmd_ConfigureRendering and ovrHmd_CreateDistortionMesh.
nuclear@0 225 typedef enum
nuclear@0 226 {
nuclear@0 227 ovrDistortionCap_Chromatic = 0x01, /// Supports chromatic aberration correction.
nuclear@0 228 ovrDistortionCap_TimeWarp = 0x02, /// Supports timewarp.
nuclear@0 229 // 0x04 unused
nuclear@0 230 ovrDistortionCap_Vignette = 0x08, /// Supports vignetting around the edges of the view.
nuclear@0 231 ovrDistortionCap_NoRestore = 0x10, /// Do not save and restore the graphics and compute state when rendering distortion.
nuclear@0 232 ovrDistortionCap_FlipInput = 0x20, /// Flip the vertical texture coordinate of input images.
nuclear@0 233 ovrDistortionCap_SRGB = 0x40, /// Assume input images are in sRGB gamma-corrected color space.
nuclear@0 234 ovrDistortionCap_Overdrive = 0x80, /// Overdrive brightness transitions to reduce artifacts on DK2+ displays
nuclear@0 235 ovrDistortionCap_HqDistortion = 0x100, /// High-quality sampling of distortion buffer for anti-aliasing
nuclear@0 236 ovrDistortionCap_LinuxDevFullscreen = 0x200, /// Indicates window is fullscreen on a device when set. The SDK will automatically apply distortion mesh rotation if needed.
nuclear@0 237 ovrDistortionCap_ComputeShader = 0x400, /// Using compute shader (DX11+ only)
nuclear@0 238
nuclear@0 239 ovrDistortionCap_ProfileNoTimewarpSpinWaits = 0x10000, /// Use when profiling with timewarp to remove false positives
nuclear@0 240 } ovrDistortionCaps;
nuclear@0 241
nuclear@0 242 /// Specifies which eye is being used for rendering.
nuclear@0 243 /// This type explicitly does not include a third "NoStereo" option, as such is
nuclear@0 244 /// not required for an HMD-centered API.
nuclear@0 245 typedef enum
nuclear@0 246 {
nuclear@0 247 ovrEye_Left = 0,
nuclear@0 248 ovrEye_Right = 1,
nuclear@0 249 ovrEye_Count = 2
nuclear@0 250 } ovrEyeType;
nuclear@0 251
nuclear@0 252 /// This is a complete descriptor of the HMD.
nuclear@0 253 typedef struct ovrHmdDesc_
nuclear@0 254 {
nuclear@0 255 /// Internal handle of this HMD.
nuclear@0 256 struct ovrHmdStruct* Handle;
nuclear@0 257
nuclear@0 258 /// This HMD's type.
nuclear@0 259 ovrHmdType Type;
nuclear@0 260
nuclear@0 261 /// Name string describing the product: "Oculus Rift DK1", etc.
nuclear@0 262 const char* ProductName;
nuclear@0 263 const char* Manufacturer;
nuclear@0 264
nuclear@0 265 /// HID Vendor and ProductId of the device.
nuclear@0 266 short VendorId;
nuclear@0 267 short ProductId;
nuclear@0 268 /// Sensor (and display) serial number.
nuclear@0 269 char SerialNumber[24];
nuclear@0 270 /// Sensor firmware version.
nuclear@0 271 short FirmwareMajor;
nuclear@0 272 short FirmwareMinor;
nuclear@0 273 /// External tracking camera frustum dimensions (if present).
nuclear@0 274 float CameraFrustumHFovInRadians;
nuclear@0 275 float CameraFrustumVFovInRadians;
nuclear@0 276 float CameraFrustumNearZInMeters;
nuclear@0 277 float CameraFrustumFarZInMeters;
nuclear@0 278
nuclear@0 279 /// Capability bits described by ovrHmdCaps.
nuclear@0 280 unsigned int HmdCaps;
nuclear@0 281 /// Capability bits described by ovrTrackingCaps.
nuclear@0 282 unsigned int TrackingCaps;
nuclear@0 283 /// Capability bits described by ovrDistortionCaps.
nuclear@0 284 unsigned int DistortionCaps;
nuclear@0 285
nuclear@0 286 /// These define the recommended and maximum optical FOVs for the HMD.
nuclear@0 287 ovrFovPort DefaultEyeFov[ovrEye_Count];
nuclear@0 288 ovrFovPort MaxEyeFov[ovrEye_Count];
nuclear@0 289
nuclear@0 290 /// Preferred eye rendering order for best performance.
nuclear@0 291 /// Can help reduce latency on sideways-scanned screens.
nuclear@0 292 ovrEyeType EyeRenderOrder[ovrEye_Count];
nuclear@0 293
nuclear@0 294 /// Resolution of the full HMD screen (both eyes) in pixels.
nuclear@0 295 ovrSizei Resolution;
nuclear@0 296 /// Location of the application window on the desktop (or 0,0).
nuclear@0 297 ovrVector2i WindowsPos;
nuclear@0 298
nuclear@0 299 /// Display that the HMD should present on.
nuclear@0 300 /// TBD: It may be good to remove this information relying on WindowPos instead.
nuclear@0 301 /// Ultimately, we may need to come up with a more convenient alternative,
nuclear@0 302 /// such as API-specific functions that return adapter, or something that will
nuclear@0 303 /// work with our monitor driver.
nuclear@0 304 /// Windows: (e.g. "\\\\.\\DISPLAY3", can be used in EnumDisplaySettings/CreateDC).
nuclear@0 305 const char* DisplayDeviceName;
nuclear@0 306 /// MacOS:
nuclear@0 307 int DisplayId;
nuclear@0 308
nuclear@0 309 } ovrHmdDesc;
nuclear@0 310
nuclear@0 311 /// Simple type ovrHmd is used in ovrHmd_* calls.
nuclear@0 312 typedef const ovrHmdDesc * ovrHmd;
nuclear@0 313
nuclear@0 314 /// Bit flags describing the current status of sensor tracking.
nuclear@0 315 typedef enum
nuclear@0 316 {
nuclear@0 317 ovrStatus_OrientationTracked = 0x0001, /// Orientation is currently tracked (connected and in use).
nuclear@0 318 ovrStatus_PositionTracked = 0x0002, /// Position is currently tracked (false if out of range).
nuclear@0 319 ovrStatus_CameraPoseTracked = 0x0004, /// Camera pose is currently tracked.
nuclear@0 320 ovrStatus_PositionConnected = 0x0020, /// Position tracking hardware is connected.
nuclear@0 321 ovrStatus_HmdConnected = 0x0080 /// HMD Display is available and connected.
nuclear@0 322 } ovrStatusBits;
nuclear@0 323
nuclear@0 324 /// Specifies a reading we can query from the sensor.
nuclear@0 325 typedef struct ovrSensorData_
nuclear@0 326 {
nuclear@0 327 ovrVector3f Accelerometer; /// Acceleration reading in m/s^2.
nuclear@0 328 ovrVector3f Gyro; /// Rotation rate in rad/s.
nuclear@0 329 ovrVector3f Magnetometer; /// Magnetic field in Gauss.
nuclear@0 330 float Temperature; /// Temperature of the sensor in degrees Celsius.
nuclear@0 331 float TimeInSeconds; /// Time when the reported IMU reading took place, in seconds.
nuclear@0 332 } ovrSensorData;
nuclear@0 333
nuclear@0 334 /// Tracking state at a given absolute time (describes predicted HMD pose etc).
nuclear@0 335 /// Returned by ovrHmd_GetTrackingState.
nuclear@0 336 typedef struct ovrTrackingState_
nuclear@0 337 {
nuclear@0 338 /// Predicted head pose (and derivatives) at the requested absolute time.
nuclear@0 339 /// The look-ahead interval is equal to (HeadPose.TimeInSeconds - RawSensorData.TimeInSeconds).
nuclear@0 340 ovrPoseStatef HeadPose;
nuclear@0 341
nuclear@0 342 /// Current pose of the external camera (if present).
nuclear@0 343 /// This pose includes camera tilt (roll and pitch). For a leveled coordinate
nuclear@0 344 /// system use LeveledCameraPose.
nuclear@0 345 ovrPosef CameraPose;
nuclear@0 346
nuclear@0 347 /// Camera frame aligned with gravity.
nuclear@0 348 /// This value includes position and yaw of the camera, but not roll and pitch.
nuclear@0 349 /// It can be used as a reference point to render real-world objects in the correct location.
nuclear@0 350 ovrPosef LeveledCameraPose;
nuclear@0 351
nuclear@0 352 /// The most recent sensor data received from the HMD.
nuclear@0 353 ovrSensorData RawSensorData;
nuclear@0 354
nuclear@0 355 /// Tracking status described by ovrStatusBits.
nuclear@0 356 unsigned int StatusFlags;
nuclear@0 357
nuclear@0 358 //// 0.4.1
nuclear@0 359
nuclear@0 360 // Measures the time from receiving the camera frame until vision CPU processing completes.
nuclear@0 361 double LastVisionProcessingTime;
nuclear@0 362
nuclear@0 363 //// 0.4.3
nuclear@0 364
nuclear@0 365 // Measures the time from exposure until the pose is available for the frame, including processing time.
nuclear@0 366 double LastVisionFrameLatency;
nuclear@0 367
nuclear@0 368 /// Tag the vision processing results to a certain frame counter number.
nuclear@0 369 uint32_t LastCameraFrameCounter;
nuclear@0 370 } ovrTrackingState;
nuclear@0 371
nuclear@0 372 /// Frame timing data reported by ovrHmd_BeginFrameTiming() or ovrHmd_BeginFrame().
nuclear@0 373 typedef struct ovrFrameTiming_
nuclear@0 374 {
nuclear@0 375 /// The amount of time that has passed since the previous frame's
nuclear@0 376 /// ThisFrameSeconds value (usable for movement scaling).
nuclear@0 377 /// This will be clamped to no more than 0.1 seconds to prevent
nuclear@0 378 /// excessive movement after pauses due to loading or initialization.
nuclear@0 379 float DeltaSeconds;
nuclear@0 380
nuclear@0 381 /// It is generally expected that the following holds:
nuclear@0 382 /// ThisFrameSeconds < TimewarpPointSeconds < NextFrameSeconds <
nuclear@0 383 /// EyeScanoutSeconds[EyeOrder[0]] <= ScanoutMidpointSeconds <= EyeScanoutSeconds[EyeOrder[1]].
nuclear@0 384
nuclear@0 385 /// Absolute time value when rendering of this frame began or is expected to
nuclear@0 386 /// begin. Generally equal to NextFrameSeconds of the previous frame. Can be used
nuclear@0 387 /// for animation timing.
nuclear@0 388 double ThisFrameSeconds;
nuclear@0 389 /// Absolute point when IMU expects to be sampled for this frame.
nuclear@0 390 double TimewarpPointSeconds;
nuclear@0 391 /// Absolute time when frame Present followed by GPU Flush will finish and the next frame begins.
nuclear@0 392 double NextFrameSeconds;
nuclear@0 393
nuclear@0 394 /// Time when half of the screen will be scanned out. Can be passed as an absolute time
nuclear@0 395 /// to ovrHmd_GetTrackingState() to get the predicted general orientation.
nuclear@0 396 double ScanoutMidpointSeconds;
nuclear@0 397 /// Timing points when each eye will be scanned out to display. Used when rendering each eye.
nuclear@0 398 double EyeScanoutSeconds[2];
nuclear@0 399 } ovrFrameTiming;
nuclear@0 400
nuclear@0 401 /// Rendering information for each eye. Computed by either ovrHmd_ConfigureRendering()
nuclear@0 402 /// or ovrHmd_GetRenderDesc() based on the specified FOV. Note that the rendering viewport
nuclear@0 403 /// is not included here as it can be specified separately and modified per frame through:
nuclear@0 404 /// (a) ovrHmd_GetRenderScaleAndOffset in the case of client rendered distortion,
nuclear@0 405 /// or (b) passing different values via ovrTexture in the case of SDK rendered distortion.
nuclear@0 406 typedef struct ovrEyeRenderDesc_
nuclear@0 407 {
nuclear@0 408 ovrEyeType Eye; ///< The eye index this instance corresponds to.
nuclear@0 409 ovrFovPort Fov; ///< The field of view.
nuclear@0 410 ovrRecti DistortedViewport; ///< Distortion viewport.
nuclear@0 411 ovrVector2f PixelsPerTanAngleAtCenter; ///< How many display pixels will fit in tan(angle) = 1.
nuclear@0 412 ovrVector3f HmdToEyeViewOffset; ///< Translation to be applied to view matrix for each eye offset.
nuclear@0 413 } ovrEyeRenderDesc;
nuclear@0 414
nuclear@0 415 //-----------------------------------------------------------------------------------
nuclear@0 416 // ***** Platform-independent Rendering Configuration
nuclear@0 417
nuclear@0 418 /// These types are used to hide platform-specific details when passing
nuclear@0 419 /// render device, OS, and texture data to the API.
nuclear@0 420 ///
nuclear@0 421 /// The benefit of having these wrappers versus platform-specific API functions is
nuclear@0 422 /// that they allow game glue code to be portable. A typical example is an
nuclear@0 423 /// engine that has multiple back ends, say GL and D3D. Portable code that calls
nuclear@0 424 /// these back ends may also use LibOVR. To do this, back ends can be modified
nuclear@0 425 /// to return portable types such as ovrTexture and ovrRenderAPIConfig.
nuclear@0 426 typedef enum
nuclear@0 427 {
nuclear@0 428 ovrRenderAPI_None,
nuclear@0 429 ovrRenderAPI_OpenGL,
nuclear@0 430 ovrRenderAPI_Android_GLES, // May include extra native window pointers, etc.
nuclear@0 431 ovrRenderAPI_D3D9,
nuclear@0 432 ovrRenderAPI_D3D10,
nuclear@0 433 ovrRenderAPI_D3D11,
nuclear@0 434 ovrRenderAPI_Count
nuclear@0 435 } ovrRenderAPIType;
nuclear@0 436
nuclear@0 437 /// Platform-independent part of rendering API-configuration data.
nuclear@0 438 /// It is a part of ovrRenderAPIConfig, passed to ovrHmd_Configure.
nuclear@0 439 typedef struct OVR_ALIGNAS(8) ovrRenderAPIConfigHeader_
nuclear@0 440 {
nuclear@0 441 ovrRenderAPIType API;
nuclear@0 442 ovrSizei BackBufferSize; // Previously named RTSize.
nuclear@0 443 int Multisample;
nuclear@0 444 } ovrRenderAPIConfigHeader;
nuclear@0 445
nuclear@0 446 /// Contains platform-specific information for rendering.
nuclear@0 447 typedef struct OVR_ALIGNAS(8) ovrRenderAPIConfig_
nuclear@0 448 {
nuclear@0 449 ovrRenderAPIConfigHeader Header;
nuclear@0 450 uintptr_t PlatformData[8];
nuclear@0 451 } ovrRenderAPIConfig;
nuclear@0 452
nuclear@0 453 /// Platform-independent part of the eye texture descriptor.
nuclear@0 454 /// It is a part of ovrTexture, passed to ovrHmd_EndFrame.
nuclear@0 455 /// If RenderViewport is all zeros then the full texture will be used.
nuclear@0 456 typedef struct OVR_ALIGNAS(8) ovrTextureHeader_
nuclear@0 457 {
nuclear@0 458 ovrRenderAPIType API;
nuclear@0 459 ovrSizei TextureSize;
nuclear@0 460 ovrRecti RenderViewport; // Pixel viewport in texture that holds eye image.
nuclear@0 461 uint32_t _PAD0_;
nuclear@0 462 } ovrTextureHeader;
nuclear@0 463
nuclear@0 464 /// Contains platform-specific information about a texture.
nuclear@0 465 typedef struct OVR_ALIGNAS(8) ovrTexture_
nuclear@0 466 {
nuclear@0 467 ovrTextureHeader Header;
nuclear@0 468 uintptr_t PlatformData[8];
nuclear@0 469 } ovrTexture;
nuclear@0 470
nuclear@0 471
nuclear@0 472 // -----------------------------------------------------------------------------------
nuclear@0 473 // ***** API Interfaces
nuclear@0 474
nuclear@0 475 // Basic steps to use the API:
nuclear@0 476 //
nuclear@0 477 // Setup:
nuclear@0 478 // * ovrInitialize()
nuclear@0 479 // * ovrHMD hmd = ovrHmd_Create(0)
nuclear@0 480 // * Use hmd members and ovrHmd_GetFovTextureSize() to determine graphics configuration.
nuclear@0 481 // * Call ovrHmd_ConfigureTracking() to configure and initialize tracking.
nuclear@0 482 // * Call ovrHmd_ConfigureRendering() to setup graphics for SDK rendering,
nuclear@0 483 // which is the preferred approach.
nuclear@0 484 // Please refer to "Client Distorton Rendering" below if you prefer to do that instead.
nuclear@0 485 // * If the ovrHmdCap_ExtendDesktop flag is not set, then use ovrHmd_AttachToWindow to
nuclear@0 486 // associate the relevant application window with the hmd.
nuclear@0 487 // * Allocate render target textures as needed.
nuclear@0 488 //
nuclear@0 489 // Game Loop:
nuclear@0 490 // * Call ovrHmd_BeginFrame() to get the current frame timing information.
nuclear@0 491 // * Render each eye using ovrHmd_GetEyePoses or ovrHmd_GetHmdPosePerEye to get
nuclear@0 492 // the predicted hmd pose and each eye pose.
nuclear@0 493 // * Call ovrHmd_EndFrame() to render the distorted textures to the back buffer
nuclear@0 494 // and present them on the hmd.
nuclear@0 495 //
nuclear@0 496 // Shutdown:
nuclear@0 497 // * ovrHmd_Destroy(hmd)
nuclear@0 498 // * ovr_Shutdown()
nuclear@0 499 //
nuclear@0 500
nuclear@0 501 #ifdef __cplusplus
nuclear@0 502 extern "C" {
nuclear@0 503 #endif
nuclear@0 504
nuclear@0 505 // ovr_InitializeRenderingShim initializes the rendering shim appart from everything
nuclear@0 506 // else in LibOVR. This may be helpful if the application prefers to avoid
nuclear@0 507 // creating any OVR resources (allocations, service connections, etc) at this point.
nuclear@0 508 // ovr_InitializeRenderingShim does not bring up anything within LibOVR except the
nuclear@0 509 // necessary hooks to enable the Direct-to-Rift functionality.
nuclear@0 510 //
nuclear@0 511 // Either ovr_InitializeRenderingShim() or ovr_Initialize() must be called before any
nuclear@0 512 // Direct3D or OpenGL initilization is done by applictaion (creation of devices, etc).
nuclear@0 513 // ovr_Initialize() must still be called after to use the rest of LibOVR APIs.
nuclear@0 514 OVR_EXPORT ovrBool ovr_InitializeRenderingShim();
nuclear@0 515
nuclear@0 516 // Library init/shutdown, must be called around all other OVR code.
nuclear@0 517 // No other functions calls besides ovr_InitializeRenderingShim are allowed
nuclear@0 518 // before ovr_Initialize succeeds or after ovr_Shutdown.
nuclear@0 519 /// Initializes all Oculus functionality.
nuclear@0 520 OVR_EXPORT ovrBool ovr_Initialize();
nuclear@0 521 /// Shuts down all Oculus functionality.
nuclear@0 522 OVR_EXPORT void ovr_Shutdown();
nuclear@0 523
nuclear@0 524 /// Returns version string representing libOVR version. Static, so
nuclear@0 525 /// string remains valid for app lifespan
nuclear@0 526 OVR_EXPORT const char* ovr_GetVersionString();
nuclear@0 527
nuclear@0 528 /// Detects or re-detects HMDs and reports the total number detected.
nuclear@0 529 /// Users can get information about each HMD by calling ovrHmd_Create with an index.
nuclear@0 530 OVR_EXPORT int ovrHmd_Detect();
nuclear@0 531
nuclear@0 532 /// Creates a handle to an HMD which doubles as a description structure.
nuclear@0 533 /// Index can [0 .. ovrHmd_Detect()-1]. Index mappings can cange after each ovrHmd_Detect call.
nuclear@0 534 /// If not null, then the returned handle must be freed with ovrHmd_Destroy.
nuclear@0 535 OVR_EXPORT ovrHmd ovrHmd_Create(int index);
nuclear@0 536 OVR_EXPORT void ovrHmd_Destroy(ovrHmd hmd);
nuclear@0 537
nuclear@0 538 /// Creates a 'fake' HMD used for debugging only. This is not tied to specific hardware,
nuclear@0 539 /// but may be used to debug some of the related rendering.
nuclear@0 540 OVR_EXPORT ovrHmd ovrHmd_CreateDebug(ovrHmdType type);
nuclear@0 541
nuclear@0 542 /// Returns last error for HMD state. Returns null for no error.
nuclear@0 543 /// String is valid until next call or GetLastError or HMD is destroyed.
nuclear@0 544 /// Pass null hmd to get global errors (during create etc).
nuclear@0 545 OVR_EXPORT const char* ovrHmd_GetLastError(ovrHmd hmd);
nuclear@0 546
nuclear@0 547 /// Platform specific function to specify the application window whose output will be
nuclear@0 548 /// displayed on the HMD. Only used if the ovrHmdCap_ExtendDesktop flag is false.
nuclear@0 549 /// Windows: SwapChain associated with this window will be displayed on the HMD.
nuclear@0 550 /// Specify 'destMirrorRect' in window coordinates to indicate an area
nuclear@0 551 /// of the render target output that will be mirrored from 'sourceRenderTargetRect'.
nuclear@0 552 /// Null pointers mean "full size".
nuclear@0 553 /// @note Source and dest mirror rects are not yet implemented.
nuclear@0 554 OVR_EXPORT ovrBool ovrHmd_AttachToWindow(ovrHmd hmd, void* window,
nuclear@0 555 const ovrRecti* destMirrorRect,
nuclear@0 556 const ovrRecti* sourceRenderTargetRect);
nuclear@0 557
nuclear@0 558 /// Returns capability bits that are enabled at this time as described by ovrHmdCaps.
nuclear@0 559 /// Note that this value is different font ovrHmdDesc::HmdCaps, which describes what
nuclear@0 560 /// capabilities are available for that HMD.
nuclear@0 561 OVR_EXPORT unsigned int ovrHmd_GetEnabledCaps(ovrHmd hmd);
nuclear@0 562
nuclear@0 563 /// Modifies capability bits described by ovrHmdCaps that can be modified,
nuclear@0 564 /// such as ovrHmdCap_LowPersistance.
nuclear@0 565 OVR_EXPORT void ovrHmd_SetEnabledCaps(ovrHmd hmd, unsigned int hmdCaps);
nuclear@0 566
nuclear@0 567 //-------------------------------------------------------------------------------------
nuclear@0 568 // ***** Tracking Interface
nuclear@0 569
nuclear@0 570 /// All tracking interface functions are thread-safe, allowing tracking state to be sampled
nuclear@0 571 /// from different threads.
nuclear@0 572 /// ConfigureTracking starts sensor sampling, enabling specified capabilities,
nuclear@0 573 /// described by ovrTrackingCaps.
nuclear@0 574 /// - supportedTrackingCaps specifies support that is requested. The function will succeed
nuclear@0 575 /// even if these caps are not available (i.e. sensor or camera is unplugged). Support
nuclear@0 576 /// will automatically be enabled if such device is plugged in later. Software should
nuclear@0 577 /// check ovrTrackingState.StatusFlags for real-time status.
nuclear@0 578 /// - requiredTrackingCaps specify sensor capabilities required at the time of the call.
nuclear@0 579 /// If they are not available, the function will fail. Pass 0 if only specifying
nuclear@0 580 /// supportedTrackingCaps.
nuclear@0 581 /// - Pass 0 for both supportedTrackingCaps and requiredTrackingCaps to disable tracking.
nuclear@0 582 OVR_EXPORT ovrBool ovrHmd_ConfigureTracking(ovrHmd hmd, unsigned int supportedTrackingCaps,
nuclear@0 583 unsigned int requiredTrackingCaps);
nuclear@0 584
nuclear@0 585 /// Re-centers the sensor orientation.
nuclear@0 586 /// Normally this will recenter the (x,y,z) translational components and the yaw
nuclear@0 587 /// component of orientation.
nuclear@0 588 OVR_EXPORT void ovrHmd_RecenterPose(ovrHmd hmd);
nuclear@0 589
nuclear@0 590 /// Returns tracking state reading based on the specified absolute system time.
nuclear@0 591 /// Pass an absTime value of 0.0 to request the most recent sensor reading. In this case
nuclear@0 592 /// both PredictedPose and SamplePose will have the same value.
nuclear@0 593 /// ovrHmd_GetEyePoses relies on this function internally.
nuclear@0 594 /// This may also be used for more refined timing of FrontBuffer rendering logic, etc.
nuclear@0 595 OVR_EXPORT ovrTrackingState ovrHmd_GetTrackingState(ovrHmd hmd, double absTime);
nuclear@0 596
nuclear@0 597 //-------------------------------------------------------------------------------------
nuclear@0 598 // ***** Graphics Setup
nuclear@0 599
nuclear@0 600 /// Calculates the recommended texture size for rendering a given eye within the HMD
nuclear@0 601 /// with a given FOV cone. Higher FOV will generally require larger textures to
nuclear@0 602 /// maintain quality.
nuclear@0 603 /// - pixelsPerDisplayPixel specifies the ratio of the number of render target pixels
nuclear@0 604 /// to display pixels at the center of distortion. 1.0 is the default value. Lower
nuclear@0 605 /// values can improve performance.
nuclear@0 606 OVR_EXPORT ovrSizei ovrHmd_GetFovTextureSize(ovrHmd hmd, ovrEyeType eye, ovrFovPort fov,
nuclear@0 607 float pixelsPerDisplayPixel);
nuclear@0 608
nuclear@0 609 //-------------------------------------------------------------------------------------
nuclear@0 610 // ***** Rendering API Thread Safety
nuclear@0 611
nuclear@0 612 // All of rendering functions including the configure and frame functions
nuclear@0 613 // are *NOT thread safe*. It is ok to use ConfigureRendering on one thread and handle
nuclear@0 614 // frames on another thread, but explicit synchronization must be done since
nuclear@0 615 // functions that depend on configured state are not reentrant.
nuclear@0 616 //
nuclear@0 617 // As an extra requirement, any of the following calls must be done on
nuclear@0 618 // the render thread, which is the same thread that calls ovrHmd_BeginFrame
nuclear@0 619 // or ovrHmd_BeginFrameTiming.
nuclear@0 620 // - ovrHmd_EndFrame
nuclear@0 621 // - ovrHmd_GetEyeTimewarpMatrices
nuclear@0 622
nuclear@0 623 //-------------------------------------------------------------------------------------
nuclear@0 624 // ***** SDK Distortion Rendering Functions
nuclear@0 625
nuclear@0 626 // These functions support rendering of distortion by the SDK through direct
nuclear@0 627 // access to the underlying rendering API, such as D3D or GL.
nuclear@0 628 // This is the recommended approach since it allows better support for future
nuclear@0 629 // Oculus hardware, and enables a range of low-level optimizations.
nuclear@0 630
nuclear@0 631 /// Configures rendering and fills in computed render parameters.
nuclear@0 632 /// This function can be called multiple times to change rendering settings.
nuclear@0 633 /// eyeRenderDescOut is a pointer to an array of two ovrEyeRenderDesc structs
nuclear@0 634 /// that are used to return complete rendering information for each eye.
nuclear@0 635 /// - apiConfig provides D3D/OpenGL specific parameters. Pass null
nuclear@0 636 /// to shutdown rendering and release all resources.
nuclear@0 637 /// - distortionCaps describe desired distortion settings.
nuclear@0 638 OVR_EXPORT ovrBool ovrHmd_ConfigureRendering( ovrHmd hmd,
nuclear@0 639 const ovrRenderAPIConfig* apiConfig,
nuclear@0 640 unsigned int distortionCaps,
nuclear@0 641 const ovrFovPort eyeFovIn[2],
nuclear@0 642 ovrEyeRenderDesc eyeRenderDescOut[2] );
nuclear@0 643
nuclear@0 644
nuclear@0 645 /// Begins a frame, returning timing information.
nuclear@0 646 /// This should be called at the beginning of the game rendering loop (on the render thread).
nuclear@0 647 /// Pass 0 for the frame index if not using ovrHmd_GetFrameTiming.
nuclear@0 648 OVR_EXPORT ovrFrameTiming ovrHmd_BeginFrame(ovrHmd hmd, unsigned int frameIndex);
nuclear@0 649
nuclear@0 650 /// Ends a frame, submitting the rendered textures to the frame buffer.
nuclear@0 651 /// - RenderViewport within each eyeTexture can change per frame if necessary.
nuclear@0 652 /// - 'renderPose' will typically be the value returned from ovrHmd_GetEyePoses,
nuclear@0 653 /// ovrHmd_GetHmdPosePerEye but can be different if a different head pose was
nuclear@0 654 /// used for rendering.
nuclear@0 655 /// - This may perform distortion and scaling internally, assuming is it not
nuclear@0 656 /// delegated to another thread.
nuclear@0 657 /// - Must be called on the same thread as BeginFrame.
nuclear@0 658 /// - *** This Function will call Present/SwapBuffers and potentially wait for GPU Sync ***.
nuclear@0 659 OVR_EXPORT void ovrHmd_EndFrame(ovrHmd hmd,
nuclear@0 660 const ovrPosef renderPose[2],
nuclear@0 661 const ovrTexture eyeTexture[2]);
nuclear@0 662
nuclear@0 663 /// Returns predicted head pose in outHmdTrackingState and offset eye poses in outEyePoses
nuclear@0 664 /// as an atomic operation. Caller need not worry about applying HmdToEyeViewOffset to the
nuclear@0 665 /// returned outEyePoses variables.
nuclear@0 666 /// - Thread-safe function where caller should increment frameIndex with every frame
nuclear@0 667 /// and pass the index where applicable to functions called on the rendering thread.
nuclear@0 668 /// - hmdToEyeViewOffset[2] can be ovrEyeRenderDesc.HmdToEyeViewOffset returned from
nuclear@0 669 /// ovrHmd_ConfigureRendering or ovrHmd_GetRenderDesc. For monoscopic rendering,
nuclear@0 670 /// use a vector that is the average of the two vectors for both eyes.
nuclear@0 671 /// - If frameIndex is not being used, pass in 0.
nuclear@0 672 /// - Assuming outEyePoses are used for rendering, it should be passed into ovrHmd_EndFrame.
nuclear@0 673 /// - If called doesn't need outHmdTrackingState, it can be NULL
nuclear@0 674 OVR_EXPORT void ovrHmd_GetEyePoses(ovrHmd hmd, unsigned int frameIndex, ovrVector3f hmdToEyeViewOffset[2],
nuclear@0 675 ovrPosef outEyePoses[2], ovrTrackingState* outHmdTrackingState);
nuclear@0 676
nuclear@0 677 /// Function was previously called ovrHmd_GetEyePose
nuclear@0 678 /// Returns the predicted head pose to use when rendering the specified eye.
nuclear@0 679 /// - Important: Caller must apply HmdToEyeViewOffset before using ovrPosef for rendering
nuclear@0 680 /// - Must be called between ovrHmd_BeginFrameTiming and ovrHmd_EndFrameTiming.
nuclear@0 681 /// - If the pose is used for rendering the eye, it should be passed to ovrHmd_EndFrame.
nuclear@0 682 /// - Parameter 'eye' is used for prediction timing only
nuclear@0 683 OVR_EXPORT ovrPosef ovrHmd_GetHmdPosePerEye(ovrHmd hmd, ovrEyeType eye);
nuclear@0 684
nuclear@0 685
nuclear@0 686 //-------------------------------------------------------------------------------------
nuclear@0 687 // ***** Client Distortion Rendering Functions
nuclear@0 688
nuclear@0 689 // These functions provide the distortion data and render timing support necessary to allow
nuclear@0 690 // client rendering of distortion. Client-side rendering involves the following steps:
nuclear@0 691 //
nuclear@0 692 // 1. Setup ovrEyeDesc based on the desired texture size and FOV.
nuclear@0 693 // Call ovrHmd_GetRenderDesc to get the necessary rendering parameters for each eye.
nuclear@0 694 //
nuclear@0 695 // 2. Use ovrHmd_CreateDistortionMesh to generate the distortion mesh.
nuclear@0 696 //
nuclear@0 697 // 3. Use ovrHmd_BeginFrameTiming, ovrHmd_GetEyePoses, and ovrHmd_BeginFrameTiming in
nuclear@0 698 // the rendering loop to obtain timing and predicted head orientation when rendering each eye.
nuclear@0 699 // - When using timewarp, use ovr_WaitTillTime after the rendering and gpu flush, followed
nuclear@0 700 // by ovrHmd_GetEyeTimewarpMatrices to obtain the timewarp matrices used
nuclear@0 701 // by the distortion pixel shader. This will minimize latency.
nuclear@0 702 //
nuclear@0 703
nuclear@0 704 /// Computes the distortion viewport, view adjust, and other rendering parameters for
nuclear@0 705 /// the specified eye. This can be used instead of ovrHmd_ConfigureRendering to do
nuclear@0 706 /// setup for client rendered distortion.
nuclear@0 707 OVR_EXPORT ovrEyeRenderDesc ovrHmd_GetRenderDesc(ovrHmd hmd,
nuclear@0 708 ovrEyeType eyeType, ovrFovPort fov);
nuclear@0 709
nuclear@0 710
nuclear@0 711 /// Describes a vertex used by the distortion mesh. This is intended to be converted into
nuclear@0 712 /// the engine-specific format. Some fields may be unused based on the ovrDistortionCaps
nuclear@0 713 /// flags selected. TexG and TexB, for example, are not used if chromatic correction is
nuclear@0 714 /// not requested.
nuclear@0 715 typedef struct ovrDistortionVertex_
nuclear@0 716 {
nuclear@0 717 ovrVector2f ScreenPosNDC; ///< [-1,+1],[-1,+1] over the entire framebuffer.
nuclear@0 718 float TimeWarpFactor; ///< Lerp factor between time-warp matrices. Can be encoded in Pos.z.
nuclear@0 719 float VignetteFactor; ///< Vignette fade factor. Can be encoded in Pos.w.
nuclear@0 720 ovrVector2f TanEyeAnglesR; ///< The tangents of the horizontal and vertical eye angles for the red channel.
nuclear@0 721 ovrVector2f TanEyeAnglesG; ///< The tangents of the horizontal and vertical eye angles for the green channel.
nuclear@0 722 ovrVector2f TanEyeAnglesB; ///< The tangents of the horizontal and vertical eye angles for the blue channel.
nuclear@0 723 } ovrDistortionVertex;
nuclear@0 724
nuclear@0 725 /// Describes a full set of distortion mesh data, filled in by ovrHmd_CreateDistortionMesh.
nuclear@0 726 /// Contents of this data structure, if not null, should be freed by ovrHmd_DestroyDistortionMesh.
nuclear@0 727 typedef struct ovrDistortionMesh_
nuclear@0 728 {
nuclear@0 729 ovrDistortionVertex* pVertexData; ///< The distortion vertices representing each point in the mesh.
nuclear@0 730 unsigned short* pIndexData; ///< Indices for connecting the mesh vertices into polygons.
nuclear@0 731 unsigned int VertexCount; ///< The number of vertices in the mesh.
nuclear@0 732 unsigned int IndexCount; ///< The number of indices in the mesh.
nuclear@0 733 } ovrDistortionMesh;
nuclear@0 734
nuclear@0 735 /// Generate distortion mesh per eye.
nuclear@0 736 /// Distortion capabilities will depend on 'distortionCaps' flags. Users should
nuclear@0 737 /// render using the appropriate shaders based on their settings.
nuclear@0 738 /// Distortion mesh data will be allocated and written into the ovrDistortionMesh data structure,
nuclear@0 739 /// which should be explicitly freed with ovrHmd_DestroyDistortionMesh.
nuclear@0 740 /// Users should call ovrHmd_GetRenderScaleAndOffset to get uvScale and Offset values for rendering.
nuclear@0 741 /// The function shouldn't fail unless theres is a configuration or memory error, in which case
nuclear@0 742 /// ovrDistortionMesh values will be set to null.
nuclear@0 743 /// This is the only function in the SDK reliant on eye relief, currently imported from profiles,
nuclear@0 744 /// or overridden here.
nuclear@0 745 OVR_EXPORT ovrBool ovrHmd_CreateDistortionMesh( ovrHmd hmd,
nuclear@0 746 ovrEyeType eyeType, ovrFovPort fov,
nuclear@0 747 unsigned int distortionCaps,
nuclear@0 748 ovrDistortionMesh *meshData);
nuclear@0 749 OVR_EXPORT ovrBool ovrHmd_CreateDistortionMeshDebug( ovrHmd hmddesc,
nuclear@0 750 ovrEyeType eyeType, ovrFovPort fov,
nuclear@0 751 unsigned int distortionCaps,
nuclear@0 752 ovrDistortionMesh *meshData,
nuclear@0 753 float debugEyeReliefOverrideInMetres);
nuclear@0 754
nuclear@0 755
nuclear@0 756 /// Used to free the distortion mesh allocated by ovrHmd_GenerateDistortionMesh. meshData elements
nuclear@0 757 /// are set to null and zeroes after the call.
nuclear@0 758 OVR_EXPORT void ovrHmd_DestroyDistortionMesh( ovrDistortionMesh* meshData );
nuclear@0 759
nuclear@0 760 /// Computes updated 'uvScaleOffsetOut' to be used with a distortion if render target size or
nuclear@0 761 /// viewport changes after the fact. This can be used to adjust render size every frame if desired.
nuclear@0 762 OVR_EXPORT void ovrHmd_GetRenderScaleAndOffset( ovrFovPort fov,
nuclear@0 763 ovrSizei textureSize, ovrRecti renderViewport,
nuclear@0 764 ovrVector2f uvScaleOffsetOut[2] );
nuclear@0 765
nuclear@0 766 /// Thread-safe timing function for the main thread. Caller should increment frameIndex
nuclear@0 767 /// with every frame and pass the index where applicable to functions called on the
nuclear@0 768 /// rendering thread.
nuclear@0 769 OVR_EXPORT ovrFrameTiming ovrHmd_GetFrameTiming(ovrHmd hmd, unsigned int frameIndex);
nuclear@0 770
nuclear@0 771 /// Called at the beginning of the frame on the rendering thread.
nuclear@0 772 /// Pass frameIndex == 0 if ovrHmd_GetFrameTiming isn't being used. Otherwise,
nuclear@0 773 /// pass the same frame index as was used for GetFrameTiming on the main thread.
nuclear@0 774 OVR_EXPORT ovrFrameTiming ovrHmd_BeginFrameTiming(ovrHmd hmd, unsigned int frameIndex);
nuclear@0 775
nuclear@0 776 /// Marks the end of client distortion rendered frame, tracking the necessary timing information.
nuclear@0 777 /// This function must be called immediately after Present/SwapBuffers + GPU sync. GPU sync is
nuclear@0 778 /// important before this call to reduce latency and ensure proper timing.
nuclear@0 779 OVR_EXPORT void ovrHmd_EndFrameTiming(ovrHmd hmd);
nuclear@0 780
nuclear@0 781 /// Initializes and resets frame time tracking. This is typically not necessary, but
nuclear@0 782 /// is helpful if game changes vsync state or video mode. vsync is assumed to be on if this
nuclear@0 783 /// isn't called. Resets internal frame index to the specified number.
nuclear@0 784 OVR_EXPORT void ovrHmd_ResetFrameTiming(ovrHmd hmd, unsigned int frameIndex);
nuclear@0 785
nuclear@0 786 /// Computes timewarp matrices used by distortion mesh shader, these are used to adjust
nuclear@0 787 /// for head orientation change since the last call to ovrHmd_GetEyePoses
nuclear@0 788 /// when rendering this eye. The ovrDistortionVertex::TimeWarpFactor is used to blend between the
nuclear@0 789 /// matrices, usually representing two different sides of the screen.
nuclear@0 790 /// Must be called on the same thread as ovrHmd_BeginFrameTiming.
nuclear@0 791 OVR_EXPORT void ovrHmd_GetEyeTimewarpMatrices (ovrHmd hmd, ovrEyeType eye,
nuclear@0 792 ovrPosef renderPose, ovrMatrix4f twmOut[2]);
nuclear@0 793 OVR_EXPORT void ovrHmd_GetEyeTimewarpMatricesDebug(ovrHmd hmd, ovrEyeType eye,
nuclear@0 794 ovrPosef renderPose, ovrMatrix4f twmOut[2],
nuclear@0 795 double debugTimingOffsetInSeconds);
nuclear@0 796
nuclear@0 797
nuclear@0 798
nuclear@0 799
nuclear@0 800 //-------------------------------------------------------------------------------------
nuclear@0 801 // ***** Stateless math setup functions
nuclear@0 802
nuclear@0 803 /// Used to generate projection from ovrEyeDesc::Fov.
nuclear@0 804 OVR_EXPORT ovrMatrix4f ovrMatrix4f_Projection( ovrFovPort fov,
nuclear@0 805 float znear, float zfar, ovrBool rightHanded );
nuclear@0 806
nuclear@0 807 /// Used for 2D rendering, Y is down
nuclear@0 808 /// orthoScale = 1.0f / pixelsPerTanAngleAtCenter
nuclear@0 809 /// orthoDistance = distance from camera, such as 0.8m
nuclear@0 810 OVR_EXPORT ovrMatrix4f ovrMatrix4f_OrthoSubProjection(ovrMatrix4f projection, ovrVector2f orthoScale,
nuclear@0 811 float orthoDistance, float hmdToEyeViewOffsetX);
nuclear@0 812
nuclear@0 813 /// Returns global, absolute high-resolution time in seconds. This is the same
nuclear@0 814 /// value as used in sensor messages.
nuclear@0 815 OVR_EXPORT double ovr_GetTimeInSeconds();
nuclear@0 816
nuclear@0 817 /// Waits until the specified absolute time.
nuclear@0 818 OVR_EXPORT double ovr_WaitTillTime(double absTime);
nuclear@0 819
nuclear@0 820 // -----------------------------------------------------------------------------------
nuclear@0 821 // ***** Latency Test interface
nuclear@0 822
nuclear@0 823 /// Does latency test processing and returns 'TRUE' if specified rgb color should
nuclear@0 824 /// be used to clear the screen.
nuclear@0 825 OVR_EXPORT ovrBool ovrHmd_ProcessLatencyTest(ovrHmd hmd, unsigned char rgbColorOut[3]);
nuclear@0 826
nuclear@0 827 /// Returns non-null string once with latency test result, when it is available.
nuclear@0 828 /// Buffer is valid until next call.
nuclear@0 829 OVR_EXPORT const char* ovrHmd_GetLatencyTestResult(ovrHmd hmd);
nuclear@0 830
nuclear@0 831 /// Returns the latency testing color in rgbColorOut to render when using a DK2
nuclear@0 832 /// Returns false if this feature is disabled or not-applicable (e.g. using a DK1)
nuclear@0 833 OVR_EXPORT ovrBool ovrHmd_GetLatencyTest2DrawColor(ovrHmd hmddesc, unsigned char rgbColorOut[3]);
nuclear@0 834
nuclear@0 835 //-------------------------------------------------------------------------------------
nuclear@0 836 // ***** Health and Safety Warning Display interface
nuclear@0 837 //
nuclear@0 838
nuclear@0 839 /// Used by ovrhmd_GetHSWDisplayState to report the current display state.
nuclear@0 840 typedef struct ovrHSWDisplayState_
nuclear@0 841 {
nuclear@0 842 /// If true then the warning should be currently visible
nuclear@0 843 /// and the following variables have meaning. Else there is no
nuclear@0 844 /// warning being displayed for this application on the given HMD.
nuclear@0 845 ovrBool Displayed; ///< True if the Health&Safety Warning is currently displayed.
nuclear@0 846 double StartTime; ///< Absolute time when the warning was first displayed. See ovr_GetTimeInSeconds().
nuclear@0 847 double DismissibleTime; ///< Earliest absolute time when the warning can be dismissed. May be a time in the past.
nuclear@0 848 } ovrHSWDisplayState;
nuclear@0 849
nuclear@0 850 /// Returns the current state of the HSW display. If the application is doing the rendering of
nuclear@0 851 /// the HSW display then this function serves to indicate that the warning should be
nuclear@0 852 /// currently displayed. If the application is using SDK-based eye rendering then the SDK by
nuclear@0 853 /// default automatically handles the drawing of the HSW display. An application that uses
nuclear@0 854 /// application-based eye rendering should use this function to know when to start drawing the
nuclear@0 855 /// HSW display itself and can optionally use it in conjunction with ovrhmd_DismissHSWDisplay
nuclear@0 856 /// as described below.
nuclear@0 857 ///
nuclear@0 858 /// Example usage for application-based rendering:
nuclear@0 859 /// bool HSWDisplayCurrentlyDisplayed = false; // global or class member variable
nuclear@0 860 /// ovrHSWDisplayState hswDisplayState;
nuclear@0 861 /// ovrhmd_GetHSWDisplayState(Hmd, &hswDisplayState);
nuclear@0 862 ///
nuclear@0 863 /// if (hswDisplayState.Displayed && !HSWDisplayCurrentlyDisplayed) {
nuclear@0 864 /// <insert model into the scene that stays in front of the user>
nuclear@0 865 /// HSWDisplayCurrentlyDisplayed = true;
nuclear@0 866 /// }
nuclear@0 867 OVR_EXPORT void ovrHmd_GetHSWDisplayState(ovrHmd hmd, ovrHSWDisplayState *hasWarningState);
nuclear@0 868
nuclear@0 869 /// Dismisses the HSW display if the warning is dismissible and the earliest dismissal time
nuclear@0 870 /// has occurred. Returns true if the display is valid and could be dismissed. The application
nuclear@0 871 /// should recognize that the HSW display is being displayed (via ovrhmd_GetHSWDisplayState)
nuclear@0 872 /// and if so then call this function when the appropriate user input to dismiss the warning
nuclear@0 873 /// occurs.
nuclear@0 874 ///
nuclear@0 875 /// Example usage :
nuclear@0 876 /// void ProcessEvent(int key) {
nuclear@0 877 /// if (key == escape) {
nuclear@0 878 /// ovrHSWDisplayState hswDisplayState;
nuclear@0 879 /// ovrhmd_GetHSWDisplayState(hmd, &hswDisplayState);
nuclear@0 880 ///
nuclear@0 881 /// if (hswDisplayState.Displayed && ovrhmd_DismissHSWDisplay(hmd)) {
nuclear@0 882 /// <remove model from the scene>
nuclear@0 883 /// HSWDisplayCurrentlyDisplayed = false;
nuclear@0 884 /// }
nuclear@0 885 /// }
nuclear@0 886 /// }
nuclear@0 887 OVR_EXPORT ovrBool ovrHmd_DismissHSWDisplay(ovrHmd hmd);
nuclear@0 888
nuclear@0 889 /// Get boolean property. Returns first element if property is a boolean array.
nuclear@0 890 /// Returns defaultValue if property doesn't exist.
nuclear@0 891 OVR_EXPORT ovrBool ovrHmd_GetBool(ovrHmd hmd, const char* propertyName, ovrBool defaultVal);
nuclear@0 892
nuclear@0 893 /// Modify bool property; false if property doesn't exist or is readonly.
nuclear@0 894 OVR_EXPORT ovrBool ovrHmd_SetBool(ovrHmd hmd, const char* propertyName, ovrBool value);
nuclear@0 895
nuclear@0 896 /// Get integer property. Returns first element if property is an integer array.
nuclear@0 897 /// Returns defaultValue if property doesn't exist.
nuclear@0 898 OVR_EXPORT int ovrHmd_GetInt(ovrHmd hmd, const char* propertyName, int defaultVal);
nuclear@0 899
nuclear@0 900 /// Modify integer property; false if property doesn't exist or is readonly.
nuclear@0 901 OVR_EXPORT ovrBool ovrHmd_SetInt(ovrHmd hmd, const char* propertyName, int value);
nuclear@0 902
nuclear@0 903 /// Get float property. Returns first element if property is a float array.
nuclear@0 904 /// Returns defaultValue if property doesn't exist.
nuclear@0 905 OVR_EXPORT float ovrHmd_GetFloat(ovrHmd hmd, const char* propertyName, float defaultVal);
nuclear@0 906
nuclear@0 907 /// Modify float property; false if property doesn't exist or is readonly.
nuclear@0 908 OVR_EXPORT ovrBool ovrHmd_SetFloat(ovrHmd hmd, const char* propertyName, float value);
nuclear@0 909
nuclear@0 910 /// Get float[] property. Returns the number of elements filled in, 0 if property doesn't exist.
nuclear@0 911 /// Maximum of arraySize elements will be written.
nuclear@0 912 OVR_EXPORT unsigned int ovrHmd_GetFloatArray(ovrHmd hmd, const char* propertyName,
nuclear@0 913 float values[], unsigned int arraySize);
nuclear@0 914
nuclear@0 915 /// Modify float[] property; false if property doesn't exist or is readonly.
nuclear@0 916 OVR_EXPORT ovrBool ovrHmd_SetFloatArray(ovrHmd hmd, const char* propertyName,
nuclear@0 917 float values[], unsigned int arraySize);
nuclear@0 918
nuclear@0 919 /// Get string property. Returns first element if property is a string array.
nuclear@0 920 /// Returns defaultValue if property doesn't exist.
nuclear@0 921 /// String memory is guaranteed to exist until next call to GetString or GetStringArray, or HMD is destroyed.
nuclear@0 922 OVR_EXPORT const char* ovrHmd_GetString(ovrHmd hmd, const char* propertyName,
nuclear@0 923 const char* defaultVal);
nuclear@0 924
nuclear@0 925 /// Set string property
nuclear@0 926 OVR_EXPORT ovrBool ovrHmd_SetString(ovrHmd hmddesc, const char* propertyName,
nuclear@0 927 const char* value);
nuclear@0 928
nuclear@0 929 // -----------------------------------------------------------------------------------
nuclear@0 930 // ***** Logging
nuclear@0 931
nuclear@0 932 /// Start performance logging. guid is optional and if included is written with each file entry.
nuclear@0 933 /// If called while logging is already active with the same filename, only the guid will be updated
nuclear@0 934 /// If called while logging is already active with a different filename, ovrHmd_StopPerfLog() will be called, followed by ovrHmd_StartPerfLog()
nuclear@0 935 OVR_EXPORT ovrBool ovrHmd_StartPerfLog(ovrHmd hmd, const char* fileName, const char* userData1);
nuclear@0 936 /// Stop performance logging.
nuclear@0 937 OVR_EXPORT ovrBool ovrHmd_StopPerfLog(ovrHmd hmd);
nuclear@0 938
nuclear@0 939
nuclear@0 940 #ifdef __cplusplus
nuclear@0 941 } // extern "C"
nuclear@0 942 #endif
nuclear@0 943
nuclear@0 944
nuclear@0 945 #if defined(_MSC_VER)
nuclear@0 946 #pragma warning(pop)
nuclear@0 947 #endif
nuclear@0 948
nuclear@0 949
nuclear@0 950 #endif // OVR_CAPI_h