Include/OVR_CAPI.h

   1 /************************************************************************************\r
   2  \file      OVR_CAPI.h\r
   3  \brief     C Interface to the Oculus PC SDK tracking and rendering library.\r
   4  \copyright Copyright 2014 Oculus VR, LLC All Rights reserved.\r
   5  ************************************************************************************/\r
   6 \r
   7 // We don't use version numbers within OVR_CAPI_h, as all versioned variations\r
   8 // of this file are currently mutually exclusive.\r
   9 #ifndef OVR_CAPI_h\r
  10 #define OVR_CAPI_h\r
  11 \r
  12 #include "OVR_CAPI_Keys.h"\r
  13 #include "OVR_Version.h"\r
  14 #include "OVR_ErrorCode.h"\r
  15 \r
  16 #if !defined(_WIN32)\r
  17 #include <sys/types.h>\r
  18 #endif\r
  19 \r
  20 \r
  21 #include <stdint.h>\r
  22 \r
  23 #if defined(_MSC_VER)\r
  24 #pragma warning(push)\r
  25 #pragma warning(disable : 4324) // structure was padded due to __declspec(align())\r
  26 #pragma warning(disable : 4359) // The alignment specified for a type is less than the\r
  27 // alignment of the type of one of its data members\r
  28 #endif\r
  29 \r
  30 //-----------------------------------------------------------------------------------\r
  31 // ***** OVR_OS\r
  32 //\r
  33 #if !defined(OVR_OS_WIN32) && defined(_WIN32)\r
  34 #define OVR_OS_WIN32\r
  35 #endif\r
  36 \r
  37 #if !defined(OVR_OS_MAC) && defined(__APPLE__)\r
  38 #define OVR_OS_MAC\r
  39 #endif\r
  40 \r
  41 #if !defined(OVR_OS_LINUX) && defined(__linux__)\r
  42 #define OVR_OS_LINUX\r
  43 #endif\r
  44 \r
  45 //-----------------------------------------------------------------------------------\r
  46 // ***** OVR_CPP\r
  47 //\r
  48 #if !defined(OVR_CPP)\r
  49 #if defined(__cplusplus)\r
  50 #define OVR_CPP(x) x\r
  51 #else\r
  52 #define OVR_CPP(x) /* Not C++ */\r
  53 #endif\r
  54 #endif\r
  55 \r
  56 //-----------------------------------------------------------------------------------\r
  57 // ***** OVR_CDECL\r
  58 //\r
  59 /// LibOVR calling convention for 32-bit Windows builds.\r
  60 //\r
  61 #if !defined(OVR_CDECL)\r
  62 #if defined(_WIN32)\r
  63 #define OVR_CDECL __cdecl\r
  64 #else\r
  65 #define OVR_CDECL\r
  66 #endif\r
  67 #endif\r
  68 \r
  69 //-----------------------------------------------------------------------------------\r
  70 // ***** OVR_EXTERN_C\r
  71 //\r
  72 /// Defined as extern "C" when built from C++ code.\r
  73 //\r
  74 #if !defined(OVR_EXTERN_C)\r
  75 #ifdef __cplusplus\r
  76 #define OVR_EXTERN_C extern "C"\r
  77 #else\r
  78 #define OVR_EXTERN_C\r
  79 #endif\r
  80 #endif\r
  81 \r
  82 //-----------------------------------------------------------------------------------\r
  83 // ***** OVR_PUBLIC_FUNCTION / OVR_PRIVATE_FUNCTION\r
  84 //\r
  85 // OVR_PUBLIC_FUNCTION  - Functions that externally visible from a shared library.\r
  86 //                        Corresponds to Microsoft __dllexport.\r
  87 // OVR_PUBLIC_CLASS     - C++ structs and classes that are externally visible from a\r
  88 //                        shared library. Corresponds to Microsoft __dllexport.\r
  89 // OVR_PRIVATE_FUNCTION - Functions that are not visible outside of a shared library.\r
  90 //                        They are private to the shared library.\r
  91 // OVR_PRIVATE_CLASS    - C++ structs and classes that are not visible outside of a\r
  92 //                        shared library. They are private to the shared library.\r
  93 //\r
  94 // OVR_DLL_BUILD        - Used to indicate that the current compilation unit is of a shared library.\r
  95 // OVR_DLL_IMPORT       - Used to indicate that the current compilation unit is a\r
  96 //                        user of the corresponding shared library.\r
  97 // OVR_STATIC_BUILD     - used to indicate that the current compilation unit is not a\r
  98 //                        shared library but rather statically linked code.\r
  99 //\r
 100 #if !defined(OVR_PUBLIC_FUNCTION)\r
 101 #if defined(OVR_DLL_BUILD)\r
 102 #if defined(_WIN32)\r
 103 #define OVR_PUBLIC_FUNCTION(rval) OVR_EXTERN_C __declspec(dllexport) rval OVR_CDECL\r
 104 #define OVR_PUBLIC_CLASS __declspec(dllexport)\r
 105 #define OVR_PRIVATE_FUNCTION(rval) rval OVR_CDECL\r
 106 #define OVR_PRIVATE_CLASS\r
 107 #else\r
 108 #define OVR_PUBLIC_FUNCTION(rval) \\r
 109   OVR_EXTERN_C __attribute__((visibility("default"))) rval OVR_CDECL /* Requires GCC 4.0+ */\r
 110 #define OVR_PUBLIC_CLASS __attribute__((visibility("default"))) /* Requires GCC 4.0+ */\r
 111 #define OVR_PRIVATE_FUNCTION(rval) __attribute__((visibility("hidden"))) rval OVR_CDECL\r
 112 #define OVR_PRIVATE_CLASS __attribute__((visibility("hidden")))\r
 113 #endif\r
 114 #elif defined(OVR_DLL_IMPORT)\r
 115 #if defined(_WIN32)\r
 116 #define OVR_PUBLIC_FUNCTION(rval) OVR_EXTERN_C __declspec(dllimport) rval OVR_CDECL\r
 117 #define OVR_PUBLIC_CLASS __declspec(dllimport)\r
 118 #else\r
 119 #define OVR_PUBLIC_FUNCTION(rval) OVR_EXTERN_C rval OVR_CDECL\r
 120 #define OVR_PUBLIC_CLASS\r
 121 #endif\r
 122 #define OVR_PRIVATE_FUNCTION(rval) rval OVR_CDECL\r
 123 #define OVR_PRIVATE_CLASS\r
 124 #else // OVR_STATIC_BUILD\r
 125 #define OVR_PUBLIC_FUNCTION(rval) OVR_EXTERN_C rval OVR_CDECL\r
 126 #define OVR_PUBLIC_CLASS\r
 127 #define OVR_PRIVATE_FUNCTION(rval) rval OVR_CDECL\r
 128 #define OVR_PRIVATE_CLASS\r
 129 #endif\r
 130 #endif\r
 131 \r
 132 //-----------------------------------------------------------------------------------\r
 133 // ***** OVR_EXPORT\r
 134 //\r
 135 /// Provided for backward compatibility with older versions of this library.\r
 136 //\r
 137 #if !defined(OVR_EXPORT)\r
 138 #ifdef OVR_OS_WIN32\r
 139 #define OVR_EXPORT __declspec(dllexport)\r
 140 #else\r
 141 #define OVR_EXPORT\r
 142 #endif\r
 143 #endif\r
 144 \r
 145 //-----------------------------------------------------------------------------------\r
 146 // ***** OVR_ALIGNAS\r
 147 //\r
 148 #if !defined(OVR_ALIGNAS)\r
 149 #if defined(__GNUC__) || defined(__clang__)\r
 150 #define OVR_ALIGNAS(n) __attribute__((aligned(n)))\r
 151 #elif defined(_MSC_VER) || defined(__INTEL_COMPILER)\r
 152 #define OVR_ALIGNAS(n) __declspec(align(n))\r
 153 #elif defined(__CC_ARM)\r
 154 #define OVR_ALIGNAS(n) __align(n)\r
 155 #else\r
 156 #error Need to define OVR_ALIGNAS\r
 157 #endif\r
 158 #endif\r
 159 \r
 160 //-----------------------------------------------------------------------------------\r
 161 // ***** OVR_CC_HAS_FEATURE\r
 162 //\r
 163 // This is a portable way to use compile-time feature identification available\r
 164 // with some compilers in a clean way. Direct usage of __has_feature in preprocessing\r
 165 // statements of non-supporting compilers results in a preprocessing error.\r
 166 //\r
 167 // Example usage:\r
 168 //     #if OVR_CC_HAS_FEATURE(is_pod)\r
 169 //         if(__is_pod(T)) // If the type is plain data then we can safely memcpy it.\r
 170 //             memcpy(&destObject, &srcObject, sizeof(object));\r
 171 //     #endif\r
 172 //\r
 173 #if !defined(OVR_CC_HAS_FEATURE)\r
 174 #if defined(__clang__) // http://clang.llvm.org/docs/LanguageExtensions.html#id2\r
 175 #define OVR_CC_HAS_FEATURE(x) __has_feature(x)\r
 176 #else\r
 177 #define OVR_CC_HAS_FEATURE(x) 0\r
 178 #endif\r
 179 #endif\r
 180 \r
 181 // ------------------------------------------------------------------------\r
 182 // ***** OVR_STATIC_ASSERT\r
 183 //\r
 184 // Portable support for C++11 static_assert().\r
 185 // Acts as if the following were declared:\r
 186 //     void OVR_STATIC_ASSERT(bool const_expression, const char* msg);\r
 187 //\r
 188 // Example usage:\r
 189 //     OVR_STATIC_ASSERT(sizeof(int32_t) == 4, "int32_t expected to be 4 bytes.");\r
 190 \r
 191 #if !defined(OVR_STATIC_ASSERT)\r
 192 #if !(defined(__cplusplus) && (__cplusplus >= 201103L)) /* Other */ && \\r
 193     !(defined(__GXX_EXPERIMENTAL_CXX0X__)) /* GCC */ &&                \\r
 194     !(defined(__clang__) && defined(__cplusplus) &&                    \\r
 195       OVR_CC_HAS_FEATURE(cxx_static_assert)) /* clang */               \\r
 196     && !(defined(_MSC_VER) && (_MSC_VER >= 1600) && defined(__cplusplus)) /* VS2010+  */\r
 197 \r
 198 #if !defined(OVR_SA_UNUSED)\r
 199 #if defined(OVR_CC_GNU) || defined(OVR_CC_CLANG)\r
 200 #define OVR_SA_UNUSED __attribute__((unused))\r
 201 #else\r
 202 #define OVR_SA_UNUSED\r
 203 #endif\r
 204 #define OVR_SA_PASTE(a, b) a##b\r
 205 #define OVR_SA_HELP(a, b) OVR_SA_PASTE(a, b)\r
 206 #endif\r
 207 \r
 208 #if defined(__COUNTER__)\r
 209 #define OVR_STATIC_ASSERT(expression, msg) \\r
 210   typedef char OVR_SA_HELP(staticAssert, __COUNTER__)[((expression) != 0) ? 1 : -1] OVR_SA_UNUSED\r
 211 #else\r
 212 #define OVR_STATIC_ASSERT(expression, msg) \\r
 213   typedef char OVR_SA_HELP(staticAssert, __LINE__)[((expression) != 0) ? 1 : -1] OVR_SA_UNUSED\r
 214 #endif\r
 215 \r
 216 #else\r
 217 #define OVR_STATIC_ASSERT(expression, msg) static_assert(expression, msg)\r
 218 #endif\r
 219 #endif\r
 220 \r
 221 //-----------------------------------------------------------------------------------\r
 222 // ***** Padding\r
 223 //\r
 224 /// Defines explicitly unused space for a struct.\r
 225 /// When used correcly, usage of this macro should not change the size of the struct.\r
 226 /// Compile-time and runtime behavior with and without this defined should be identical.\r
 227 ///\r
 228 #if !defined(OVR_UNUSED_STRUCT_PAD)\r
 229 #define OVR_UNUSED_STRUCT_PAD(padName, size) char padName[size];\r
 230 #endif\r
 231 \r
 232 //-----------------------------------------------------------------------------------\r
 233 // ***** Word Size\r
 234 //\r
 235 /// Specifies the size of a pointer on the given platform.\r
 236 ///\r
 237 #if !defined(OVR_PTR_SIZE)\r
 238 #if defined(__WORDSIZE)\r
 239 #define OVR_PTR_SIZE ((__WORDSIZE) / 8)\r
 240 #elif defined(_WIN64) || defined(__LP64__) || defined(_LP64) || defined(_M_IA64) || \\r
 241     defined(__ia64__) || defined(__arch64__) || defined(__64BIT__) || defined(__Ptr_Is_64)\r
 242 #define OVR_PTR_SIZE 8\r
 243 #elif defined(__CC_ARM) && (__sizeof_ptr == 8)\r
 244 #define OVR_PTR_SIZE 8\r
 245 #else\r
 246 #define OVR_PTR_SIZE 4\r
 247 #endif\r
 248 #endif\r
 249 \r
 250 //-----------------------------------------------------------------------------------\r
 251 // ***** OVR_ON32 / OVR_ON64\r
 252 //\r
 253 #if OVR_PTR_SIZE == 8\r
 254 #define OVR_ON32(x)\r
 255 #define OVR_ON64(x) x\r
 256 #else\r
 257 #define OVR_ON32(x) x\r
 258 #define OVR_ON64(x)\r
 259 #endif\r
 260 \r
 261 //-----------------------------------------------------------------------------------\r
 262 // ***** ovrBool\r
 263 \r
 264 typedef char ovrBool; ///< Boolean type\r
 265 #define ovrFalse 0 ///< ovrBool value of false.\r
 266 #define ovrTrue 1 ///< ovrBool value of true.\r
 267 \r
 268 //-----------------------------------------------------------------------------------\r
 269 // ***** Simple Math Structures\r
 270 \r
 271 /// A RGBA color with normalized float components.\r
 272 typedef struct OVR_ALIGNAS(4) ovrColorf_ {\r
 273   float r, g, b, a;\r
 274 } ovrColorf;\r
 275 \r
 276 /// A 2D vector with integer components.\r
 277 typedef struct OVR_ALIGNAS(4) ovrVector2i_ {\r
 278   int x, y;\r
 279 } ovrVector2i;\r
 280 \r
 281 /// A 2D size with integer components.\r
 282 typedef struct OVR_ALIGNAS(4) ovrSizei_ {\r
 283   int w, h;\r
 284 } ovrSizei;\r
 285 \r
 286 /// A 2D rectangle with a position and size.\r
 287 /// All components are integers.\r
 288 typedef struct OVR_ALIGNAS(4) ovrRecti_ {\r
 289   ovrVector2i Pos;\r
 290   ovrSizei Size;\r
 291 } ovrRecti;\r
 292 \r
 293 /// A quaternion rotation.\r
 294 typedef struct OVR_ALIGNAS(4) ovrQuatf_ {\r
 295   float x, y, z, w;\r
 296 } ovrQuatf;\r
 297 \r
 298 /// A 2D vector with float components.\r
 299 typedef struct OVR_ALIGNAS(4) ovrVector2f_ {\r
 300   float x, y;\r
 301 } ovrVector2f;\r
 302 \r
 303 /// A 3D vector with float components.\r
 304 typedef struct OVR_ALIGNAS(4) ovrVector3f_ {\r
 305   float x, y, z;\r
 306 } ovrVector3f;\r
 307 \r
 308 /// A 4x4 matrix with float elements.\r
 309 typedef struct OVR_ALIGNAS(4) ovrMatrix4f_ {\r
 310   float M[4][4];\r
 311 } ovrMatrix4f;\r
 312 \r
 313 /// Position and orientation together.\r
 314 /// The coordinate system used is right-handed Cartesian.\r
 315 typedef struct OVR_ALIGNAS(4) ovrPosef_ {\r
 316   ovrQuatf Orientation;\r
 317   ovrVector3f Position;\r
 318 } ovrPosef;\r
 319 \r
 320 /// A full pose (rigid body) configuration with first and second derivatives.\r
 321 ///\r
 322 /// Body refers to any object for which ovrPoseStatef is providing data.\r
 323 /// It can be the HMD, Touch controller, sensor or something else. The context\r
 324 /// depends on the usage of the struct.\r
 325 typedef struct OVR_ALIGNAS(8) ovrPoseStatef_ {\r
 326   ovrPosef ThePose; ///< Position and orientation.\r
 327   ovrVector3f AngularVelocity; ///< Angular velocity in radians per second.\r
 328   ovrVector3f LinearVelocity; ///< Velocity in meters per second.\r
 329   ovrVector3f AngularAcceleration; ///< Angular acceleration in radians per second per second.\r
 330   ovrVector3f LinearAcceleration; ///< Acceleration in meters per second per second.\r
 331   OVR_UNUSED_STRUCT_PAD(pad0, 4) ///< \internal struct pad.\r
 332   double TimeInSeconds; ///< Absolute time that this pose refers to. \see ovr_GetTimeInSeconds\r
 333 } ovrPoseStatef;\r
 334 \r
 335 /// Describes the up, down, left, and right angles of the field of view.\r
 336 ///\r
 337 /// Field Of View (FOV) tangent of the angle units.\r
 338 /// \note For a standard 90 degree vertical FOV, we would\r
 339 /// have: { UpTan = tan(90 degrees / 2), DownTan = tan(90 degrees / 2) }.\r
 340 typedef struct OVR_ALIGNAS(4) ovrFovPort_ {\r
 341   float UpTan; ///< Tangent of the angle between the viewing vector and top edge of the FOV.\r
 342   float DownTan; ///< Tangent of the angle between the viewing vector and bottom edge of the FOV.\r
 343   float LeftTan; ///< Tangent of the angle between the viewing vector and left edge of the FOV.\r
 344   float RightTan; ///< Tangent of the angle between the viewing vector and right edge of the FOV.\r
 345 } ovrFovPort;\r
 346 \r
 347 //-----------------------------------------------------------------------------------\r
 348 // ***** HMD Types\r
 349 \r
 350 /// Enumerates all HMD types that we support.\r
 351 ///\r
 352 /// The currently released developer kits are ovrHmd_DK1 and ovrHmd_DK2.\r
 353 /// The other enumerations are for internal use only.\r
 354 typedef enum ovrHmdType_ {\r
 355   ovrHmd_None = 0,\r
 356   ovrHmd_DK1 = 3,\r
 357   ovrHmd_DKHD = 4,\r
 358   ovrHmd_DK2 = 6,\r
 359   ovrHmd_CB = 8,\r
 360   ovrHmd_Other = 9,\r
 361   ovrHmd_E3_2015 = 10,\r
 362   ovrHmd_ES06 = 11,\r
 363   ovrHmd_ES09 = 12,\r
 364   ovrHmd_ES11 = 13,\r
 365   ovrHmd_CV1 = 14,\r
 366 \r
 367   ovrHmd_EnumSize = 0x7fffffff ///< \internal Force type int32_t.\r
 368 } ovrHmdType;\r
 369 \r
 370 /// HMD capability bits reported by device.\r
 371 ///\r
 372 typedef enum ovrHmdCaps_ {\r
 373   // Read-only flags\r
 374 \r
 375   /// <B>(read only)</B> Specifies that the HMD is a virtual debug device.\r
 376   ovrHmdCap_DebugDevice = 0x0010,\r
 377 \r
 378 \r
 379   ovrHmdCap_EnumSize = 0x7fffffff ///< \internal Force type int32_t.\r
 380 } ovrHmdCaps;\r
 381 \r
 382 /// Tracking capability bits reported by the device.\r
 383 /// Used with ovr_GetTrackingCaps.\r
 384 typedef enum ovrTrackingCaps_ {\r
 385   ovrTrackingCap_Orientation = 0x0010, ///< Supports orientation tracking (IMU).\r
 386   ovrTrackingCap_MagYawCorrection = 0x0020, ///< Supports yaw drift correction.\r
 387   ovrTrackingCap_Position = 0x0040, ///< Supports positional tracking.\r
 388   ovrTrackingCap_EnumSize = 0x7fffffff ///< \internal Force type int32_t.\r
 389 } ovrTrackingCaps;\r
 390 \r
 391 /// Optional extensions\r
 392 typedef enum ovrExtensions_ {\r
 393   ovrExtension_TextureLayout_Octilinear = 0, ///< Enable before first layer submission.\r
 394   ovrExtension_Count, ///< \internal Sanity checking\r
 395   ovrExtension_EnumSize = 0x7fffffff ///< \internal Force type int32_t.\r
 396 } ovrExtensions;\r
 397 \r
 398 /// Specifies which eye is being used for rendering.\r
 399 /// This type explicitly does not include a third "NoStereo" monoscopic option,\r
 400 /// as such is not required for an HMD-centered API.\r
 401 typedef enum ovrEyeType_ {\r
 402   ovrEye_Left = 0, ///< The left eye, from the viewer's perspective.\r
 403   ovrEye_Right = 1, ///< The right eye, from the viewer's perspective.\r
 404   ovrEye_Count = 2, ///< \internal Count of enumerated elements.\r
 405   ovrEye_EnumSize = 0x7fffffff ///< \internal Force type int32_t.\r
 406 } ovrEyeType;\r
 407 \r
 408 /// Specifies the coordinate system ovrTrackingState returns tracking poses in.\r
 409 /// Used with ovr_SetTrackingOriginType()\r
 410 typedef enum ovrTrackingOrigin_ {\r
 411   /// \brief Tracking system origin reported at eye (HMD) height\r
 412   /// \details Prefer using this origin when your application requires\r
 413   /// matching user's current physical head pose to a virtual head pose\r
 414   /// without any regards to a the height of the floor. Cockpit-based,\r
 415   /// or 3rd-person experiences are ideal candidates.\r
 416   /// When used, all poses in ovrTrackingState are reported as an offset\r
 417   /// transform from the profile calibrated or recentered HMD pose.\r
 418   /// It is recommended that apps using this origin type call ovr_RecenterTrackingOrigin\r
 419   /// prior to starting the VR experience, but notify the user before doing so\r
 420   /// to make sure the user is in a comfortable pose, facing a comfortable\r
 421   /// direction.\r
 422   ovrTrackingOrigin_EyeLevel = 0,\r
 423 \r
 424   /// \brief Tracking system origin reported at floor height\r
 425   /// \details Prefer using this origin when your application requires the\r
 426   /// physical floor height to match the virtual floor height, such as\r
 427   /// standing experiences.\r
 428   /// When used, all poses in ovrTrackingState are reported as an offset\r
 429   /// transform from the profile calibrated floor pose. Calling ovr_RecenterTrackingOrigin\r
 430   /// will recenter the X & Z axes as well as yaw, but the Y-axis (i.e. height) will continue\r
 431   /// to be reported using the floor height as the origin for all poses.\r
 432   ovrTrackingOrigin_FloorLevel = 1,\r
 433 \r
 434   ovrTrackingOrigin_Count = 2, ///< \internal Count of enumerated elements.\r
 435   ovrTrackingOrigin_EnumSize = 0x7fffffff ///< \internal Force type int32_t.\r
 436 } ovrTrackingOrigin;\r
 437 \r
 438 /// Identifies a graphics device in a platform-specific way.\r
 439 /// For Windows this is a LUID type.\r
 440 typedef struct OVR_ALIGNAS(OVR_PTR_SIZE) ovrGraphicsLuid_ {\r
 441   // Public definition reserves space for graphics API-specific implementation\r
 442   char Reserved[8];\r
 443 } ovrGraphicsLuid;\r
 444 \r
 445 /// This is a complete descriptor of the HMD.\r
 446 typedef struct OVR_ALIGNAS(OVR_PTR_SIZE) ovrHmdDesc_ {\r
 447   ovrHmdType Type; ///< The type of HMD.\r
 448   OVR_ON64(OVR_UNUSED_STRUCT_PAD(pad0, 4)) ///< \internal struct paddding.\r
 449   char ProductName[64]; ///< UTF8-encoded product identification string (e.g. "Oculus Rift DK1").\r
 450   char Manufacturer[64]; ///< UTF8-encoded HMD manufacturer identification string.\r
 451   short VendorId; ///< HID (USB) vendor identifier of the device.\r
 452   short ProductId; ///< HID (USB) product identifier of the device.\r
 453   char SerialNumber[24]; ///< HMD serial number.\r
 454   short FirmwareMajor; ///< HMD firmware major version.\r
 455   short FirmwareMinor; ///< HMD firmware minor version.\r
 456   unsigned int AvailableHmdCaps; ///< Available ovrHmdCaps bits.\r
 457   unsigned int DefaultHmdCaps; ///< Default ovrHmdCaps bits.\r
 458   unsigned int AvailableTrackingCaps; ///< Available ovrTrackingCaps bits.\r
 459   unsigned int DefaultTrackingCaps; ///< Default ovrTrackingCaps bits.\r
 460   ovrFovPort DefaultEyeFov[ovrEye_Count]; ///< Defines the recommended FOVs for the HMD.\r
 461   ovrFovPort MaxEyeFov[ovrEye_Count]; ///< Defines the maximum FOVs for the HMD.\r
 462   ovrSizei Resolution; ///< Resolution of the full HMD screen (both eyes) in pixels.\r
 463   float DisplayRefreshRate; ///< Refresh rate of the display in cycles per second.\r
 464   OVR_ON64(OVR_UNUSED_STRUCT_PAD(pad1, 4)) ///< \internal struct paddding.\r
 465 } ovrHmdDesc;\r
 466 \r
 467 /// Used as an opaque pointer to an OVR session.\r
 468 typedef struct ovrHmdStruct* ovrSession;\r
 469 \r
 470 #ifdef OVR_OS_WIN32\r
 471 typedef uint32_t ovrProcessId;\r
 472 #else\r
 473 typedef pid_t ovrProcessId;\r
 474 #endif\r
 475 \r
 476 /// Fallback definitions for when the vulkan header isn't being included\r
 477 #if !defined(VK_VERSION_1_0)\r
 478 // From <vulkan/vulkan.h>:\r
 479 #define VK_DEFINE_HANDLE(object) typedef struct object##_T* object;\r
 480 #if defined(__LP64__) || defined(_WIN64) || (defined(__x86_64__) && !defined(__ILP32__)) || \\r
 481     defined(_M_X64) || defined(__ia64) || defined(_M_IA64) || defined(__aarch64__) ||       \\r
 482     defined(__powerpc64__)\r
 483 #define VK_DEFINE_NON_DISPATCHABLE_HANDLE(object) typedef struct object##_T* object;\r
 484 #else\r
 485 #define VK_DEFINE_NON_DISPATCHABLE_HANDLE(object) typedef uint64_t object;\r
 486 #endif\r
 487 VK_DEFINE_HANDLE(VkInstance)\r
 488 VK_DEFINE_HANDLE(VkPhysicalDevice)\r
 489 VK_DEFINE_HANDLE(VkDevice)\r
 490 VK_DEFINE_HANDLE(VkQueue)\r
 491 VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkImage)\r
 492 #endif\r
 493 \r
 494 /// Bit flags describing the current status of sensor tracking.\r
 495 ///  The values must be the same as in enum StatusBits\r
 496 ///\r
 497 /// \see ovrTrackingState\r
 498 ///\r
 499 typedef enum ovrStatusBits_ {\r
 500   ovrStatus_OrientationTracked = 0x0001, ///< Orientation is currently tracked (connected & in use).\r
 501   ovrStatus_PositionTracked = 0x0002, ///< Position is currently tracked (false if out of range).\r
 502   ovrStatus_EnumSize = 0x7fffffff ///< \internal Force type int32_t.\r
 503 } ovrStatusBits;\r
 504 \r
 505 ///  Specifies the description of a single sensor.\r
 506 ///\r
 507 /// \see ovr_GetTrackerDesc\r
 508 ///\r
 509 typedef struct OVR_ALIGNAS(OVR_PTR_SIZE) ovrTrackerDesc_ {\r
 510   float FrustumHFovInRadians; ///< Sensor frustum horizontal field-of-view (if present).\r
 511   float FrustumVFovInRadians; ///< Sensor frustum vertical field-of-view (if present).\r
 512   float FrustumNearZInMeters; ///< Sensor frustum near Z (if present).\r
 513   float FrustumFarZInMeters; ///< Sensor frustum far Z (if present).\r
 514 } ovrTrackerDesc;\r
 515 \r
 516 ///  Specifies sensor flags.\r
 517 ///\r
 518 ///  /see ovrTrackerPose\r
 519 ///\r
 520 typedef enum ovrTrackerFlags_ {\r
 521   /// The sensor is present, else the sensor is absent or offline.\r
 522   ovrTracker_Connected = 0x0020,\r
 523 \r
 524   /// The sensor has a valid pose, else the pose is unavailable.\r
 525   /// This will only be set if ovrTracker_Connected is set.\r
 526   ovrTracker_PoseTracked = 0x0004\r
 527 } ovrTrackerFlags;\r
 528 \r
 529 ///  Specifies the pose for a single sensor.\r
 530 ///\r
 531 typedef struct OVR_ALIGNAS(8) _ovrTrackerPose {\r
 532   /// ovrTrackerFlags.\r
 533   unsigned int TrackerFlags;\r
 534 \r
 535   /// The sensor's pose. This pose includes sensor tilt (roll and pitch).\r
 536   /// For a leveled coordinate system use LeveledPose.\r
 537   ovrPosef Pose;\r
 538 \r
 539   /// The sensor's leveled pose, aligned with gravity. This value includes pos and yaw of the\r
 540   /// sensor, but not roll and pitch. It can be used as a reference point to render real-world\r
 541   /// objects in the correct location.\r
 542   ovrPosef LeveledPose;\r
 543 \r
 544   OVR_UNUSED_STRUCT_PAD(pad0, 4) ///< \internal struct pad.\r
 545 } ovrTrackerPose;\r
 546 \r
 547 /// Tracking state at a given absolute time (describes predicted HMD pose, etc.).\r
 548 /// Returned by ovr_GetTrackingState.\r
 549 ///\r
 550 /// \see ovr_GetTrackingState\r
 551 ///\r
 552 typedef struct OVR_ALIGNAS(8) ovrTrackingState_ {\r
 553   /// Predicted head pose (and derivatives) at the requested absolute time.\r
 554   ovrPoseStatef HeadPose;\r
 555 \r
 556   /// HeadPose tracking status described by ovrStatusBits.\r
 557   unsigned int StatusFlags;\r
 558 \r
 559   /// The most recent calculated pose for each hand when hand controller tracking is present.\r
 560   /// HandPoses[ovrHand_Left] refers to the left hand and HandPoses[ovrHand_Right] to the right.\r
 561   /// These values can be combined with ovrInputState for complete hand controller information.\r
 562   ovrPoseStatef HandPoses[2];\r
 563 \r
 564   /// HandPoses status flags described by ovrStatusBits.\r
 565   /// Only ovrStatus_OrientationTracked and ovrStatus_PositionTracked are reported.\r
 566   unsigned int HandStatusFlags[2];\r
 567 \r
 568   /// The pose of the origin captured during calibration.\r
 569   /// Like all other poses here, this is expressed in the space set by ovr_RecenterTrackingOrigin,\r
 570   /// or ovr_SpecifyTrackingOrigin and so will change every time either of those functions are\r
 571   /// called. This pose can be used to calculate where the calibrated origin lands in the new\r
 572   /// recentered space. If an application never calls ovr_RecenterTrackingOrigin or\r
 573   /// ovr_SpecifyTrackingOrigin, expect this value to be the identity pose and as such will point\r
 574   /// respective origin based on ovrTrackingOrigin requested when calling ovr_GetTrackingState.\r
 575   ovrPosef CalibratedOrigin;\r
 576 \r
 577 } ovrTrackingState;\r
 578 \r
 579 \r
 580 \r
 581 /// Rendering information for each eye. Computed by ovr_GetRenderDesc() based on the\r
 582 /// specified FOV. Note that the rendering viewport is not included\r
 583 /// here as it can be specified separately and modified per frame by\r
 584 /// passing different Viewport values in the layer structure.\r
 585 ///\r
 586 /// \see ovr_GetRenderDesc\r
 587 ///\r
 588 typedef struct OVR_ALIGNAS(4) ovrEyeRenderDesc_ {\r
 589   ovrEyeType Eye; ///< The eye index to which this instance corresponds.\r
 590   ovrFovPort Fov; ///< The field of view.\r
 591   ovrRecti DistortedViewport; ///< Distortion viewport.\r
 592   ovrVector2f PixelsPerTanAngleAtCenter; ///< How many display pixels will fit in tan(angle) = 1.\r
 593   ovrPosef HmdToEyePose; ///< Transform of eye from the HMD center, in meters.\r
 594 } ovrEyeRenderDesc;\r
 595 \r
 596 /// Projection information for ovrLayerEyeFovDepth.\r
 597 ///\r
 598 /// Use the utility function ovrTimewarpProjectionDesc_FromProjection to\r
 599 /// generate this structure from the application's projection matrix.\r
 600 ///\r
 601 /// \see ovrLayerEyeFovDepth, ovrTimewarpProjectionDesc_FromProjection\r
 602 ///\r
 603 typedef struct OVR_ALIGNAS(4) ovrTimewarpProjectionDesc_ {\r
 604   float Projection22; ///< Projection matrix element [2][2].\r
 605   float Projection23; ///< Projection matrix element [2][3].\r
 606   float Projection32; ///< Projection matrix element [3][2].\r
 607 } ovrTimewarpProjectionDesc;\r
 608 \r
 609 \r
 610 /// Contains the data necessary to properly calculate position info for various layer types.\r
 611 /// - HmdToEyePose is the same value-pair provided in ovrEyeRenderDesc. Modifying this value is\r
 612 ///   suggested only if the app is forcing monoscopic rendering and requires that all layers\r
 613 ///   including quad layers show up in a monoscopic fashion.\r
 614 /// - HmdSpaceToWorldScaleInMeters is used to scale player motion into in-application units.\r
 615 ///   In other words, it is how big an in-application unit is in the player's physical meters.\r
 616 ///   For example, if the application uses inches as its units then HmdSpaceToWorldScaleInMeters\r
 617 ///   would be 0.0254.\r
 618 ///   Note that if you are scaling the player in size, this must also scale. So if your application\r
 619 ///   units are inches, but you're shrinking the player to half their normal size, then\r
 620 ///   HmdSpaceToWorldScaleInMeters would be 0.0254*2.0.\r
 621 ///\r
 622 /// \see ovrEyeRenderDesc, ovr_SubmitFrame\r
 623 ///\r
 624 typedef struct OVR_ALIGNAS(4) ovrViewScaleDesc_ {\r
 625   ovrPosef HmdToEyePose[ovrEye_Count]; ///< Transform of each eye from the HMD center, in meters.\r
 626   float HmdSpaceToWorldScaleInMeters; ///< Ratio of viewer units to meter units.\r
 627 } ovrViewScaleDesc;\r
 628 \r
 629 //-----------------------------------------------------------------------------------\r
 630 // ***** Platform-independent Rendering Configuration\r
 631 \r
 632 /// The type of texture resource.\r
 633 ///\r
 634 /// \see ovrTextureSwapChainDesc\r
 635 ///\r
 636 typedef enum ovrTextureType_ {\r
 637   ovrTexture_2D, ///< 2D textures.\r
 638   ovrTexture_2D_External, ///< Application-provided 2D texture. Not supported on PC.\r
 639   ovrTexture_Cube, ///< Cube maps. ovrTextureSwapChainDesc::ArraySize must be 6 for this type.\r
 640   ovrTexture_Count,\r
 641   ovrTexture_EnumSize = 0x7fffffff ///< \internal Force type int32_t.\r
 642 } ovrTextureType;\r
 643 \r
 644 /// The bindings required for texture swap chain.\r
 645 ///\r
 646 /// All texture swap chains are automatically bindable as shader\r
 647 /// input resources since the Oculus runtime needs this to read them.\r
 648 ///\r
 649 /// \see ovrTextureSwapChainDesc\r
 650 ///\r
 651 typedef enum ovrTextureBindFlags_ {\r
 652   ovrTextureBind_None,\r
 653 \r
 654   /// The application can write into the chain with pixel shader.\r
 655   ovrTextureBind_DX_RenderTarget = 0x0001,\r
 656 \r
 657   /// The application can write to the chain with compute shader.\r
 658   ovrTextureBind_DX_UnorderedAccess = 0x0002,\r
 659 \r
 660   /// The chain buffers can be bound as depth and/or stencil buffers.\r
 661   /// This flag cannot be combined with ovrTextureBind_DX_RenderTarget.\r
 662   ovrTextureBind_DX_DepthStencil = 0x0004,\r
 663 \r
 664   ovrTextureBind_EnumSize = 0x7fffffff ///< \internal Force type int32_t.\r
 665 } ovrTextureBindFlags;\r
 666 \r
 667 /// The format of a texture.\r
 668 ///\r
 669 /// \see ovrTextureSwapChainDesc\r
 670 ///\r
 671 typedef enum ovrTextureFormat_ {\r
 672   OVR_FORMAT_UNKNOWN = 0,\r
 673   OVR_FORMAT_B5G6R5_UNORM = 1, ///< Not currently supported on PC. Requires a DirectX 11.1 device.\r
 674   OVR_FORMAT_B5G5R5A1_UNORM = 2, ///< Not currently supported on PC. Requires a DirectX 11.1 device.\r
 675   OVR_FORMAT_B4G4R4A4_UNORM = 3, ///< Not currently supported on PC. Requires a DirectX 11.1 device.\r
 676   OVR_FORMAT_R8G8B8A8_UNORM = 4,\r
 677   OVR_FORMAT_R8G8B8A8_UNORM_SRGB = 5,\r
 678   OVR_FORMAT_B8G8R8A8_UNORM = 6,\r
 679   OVR_FORMAT_B8G8R8_UNORM = 27,\r
 680   OVR_FORMAT_B8G8R8A8_UNORM_SRGB = 7, ///< Not supported for OpenGL applications\r
 681   OVR_FORMAT_B8G8R8X8_UNORM = 8, ///< Not supported for OpenGL applications\r
 682   OVR_FORMAT_B8G8R8X8_UNORM_SRGB = 9, ///< Not supported for OpenGL applications\r
 683   OVR_FORMAT_R16G16B16A16_FLOAT = 10,\r
 684   OVR_FORMAT_R11G11B10_FLOAT = 25, ///< Introduced in v1.10\r
 685 \r
 686   // Depth formats\r
 687   OVR_FORMAT_D16_UNORM = 11,\r
 688   OVR_FORMAT_D24_UNORM_S8_UINT = 12,\r
 689   OVR_FORMAT_D32_FLOAT = 13,\r
 690   OVR_FORMAT_D32_FLOAT_S8X24_UINT = 14,\r
 691 \r
 692   // Added in 1.5 compressed formats can be used for static layers\r
 693   OVR_FORMAT_BC1_UNORM = 15,\r
 694   OVR_FORMAT_BC1_UNORM_SRGB = 16,\r
 695   OVR_FORMAT_BC2_UNORM = 17,\r
 696   OVR_FORMAT_BC2_UNORM_SRGB = 18,\r
 697   OVR_FORMAT_BC3_UNORM = 19,\r
 698   OVR_FORMAT_BC3_UNORM_SRGB = 20,\r
 699   OVR_FORMAT_BC6H_UF16 = 21,\r
 700   OVR_FORMAT_BC6H_SF16 = 22,\r
 701   OVR_FORMAT_BC7_UNORM = 23,\r
 702   OVR_FORMAT_BC7_UNORM_SRGB = 24,\r
 703 \r
 704 \r
 705   OVR_FORMAT_ENUMSIZE = 0x7fffffff ///< \internal Force type int32_t.\r
 706 } ovrTextureFormat;\r
 707 \r
 708 /// Misc flags overriding particular\r
 709 ///   behaviors of a texture swap chain\r
 710 ///\r
 711 /// \see ovrTextureSwapChainDesc\r
 712 ///\r
 713 typedef enum ovrTextureMiscFlags_ {\r
 714   ovrTextureMisc_None,\r
 715 \r
 716   /// Vulkan and DX only: The underlying texture is created with a TYPELESS equivalent\r
 717   /// of the format specified in the texture desc. The SDK will still access the\r
 718   /// texture using the format specified in the texture desc, but the app can\r
 719   /// create views with different formats if this is specified.\r
 720   ovrTextureMisc_DX_Typeless = 0x0001,\r
 721 \r
 722   /// DX only: Allow generation of the mip chain on the GPU via the GenerateMips\r
 723   /// call. This flag requires that RenderTarget binding also be specified.\r
 724   ovrTextureMisc_AllowGenerateMips = 0x0002,\r
 725 \r
 726   /// Texture swap chain contains protected content, and requires\r
 727   /// HDCP connection in order to display to HMD. Also prevents\r
 728   /// mirroring or other redirection of any frame containing this contents\r
 729   ovrTextureMisc_ProtectedContent = 0x0004,\r
 730 \r
 731   /// Automatically generate and use the mip chain in composition on each submission.\r
 732   /// Mips are regenerated from highest quality level, ignoring other pre-existing mip levels.\r
 733   /// Not supported for depth or compressed (BC) formats.\r
 734   ovrTextureMisc_AutoGenerateMips = 0x0008,\r
 735 \r
 736   ovrTextureMisc_EnumSize = 0x7fffffff ///< \internal Force type int32_t.\r
 737 } ovrTextureFlags;\r
 738 \r
 739 /// Description used to create a texture swap chain.\r
 740 ///\r
 741 /// \see ovr_CreateTextureSwapChainDX\r
 742 /// \see ovr_CreateTextureSwapChainGL\r
 743 ///\r
 744 typedef struct ovrTextureSwapChainDesc_ {\r
 745   ovrTextureType Type; ///< Must not be ovrTexture_Window\r
 746   ovrTextureFormat Format;\r
 747   int ArraySize; ///< Must be 6 for ovrTexture_Cube, 1 for other types.\r
 748   int Width;\r
 749   int Height;\r
 750   int MipLevels;\r
 751   int SampleCount;\r
 752   ovrBool StaticImage; ///< Not buffered in a chain. For images that don't change\r
 753   OVR_ALIGNAS(4) unsigned int MiscFlags; ///< ovrTextureFlags\r
 754   OVR_ALIGNAS(4) unsigned int BindFlags; ///< ovrTextureBindFlags. Not used for GL.\r
 755 } ovrTextureSwapChainDesc;\r
 756 \r
 757 /// Bit flags used as part of ovrMirrorTextureDesc's MirrorOptions field.\r
 758 ///\r
 759 /// \see ovr_CreateMirrorTextureWithOptionsDX\r
 760 /// \see ovr_CreateMirrorTextureWithOptionsGL\r
 761 /// \see ovr_CreateMirrorTextureWithOptionsVk\r
 762 ///\r
 763 typedef enum ovrMirrorOptions_ {\r
 764   /// By default the mirror texture will be:\r
 765   /// * Pre-distortion (i.e. rectilinear)\r
 766   /// * Contain both eye textures\r
 767   /// * Exclude Guardian, Notifications, System Menu GUI\r
 768   ovrMirrorOption_Default = 0x0000,\r
 769 \r
 770   /// Retrieves the barrel distorted texture contents instead of the rectilinear one\r
 771   /// This is only recommended for debugging purposes, and not for final desktop presentation\r
 772   ovrMirrorOption_PostDistortion = 0x0001,\r
 773 \r
 774   /// Since ovrMirrorOption_Default renders both eyes into the mirror texture,\r
 775   /// these two flags are exclusive (i.e. cannot use them simultaneously)\r
 776   ovrMirrorOption_LeftEyeOnly = 0x0002,\r
 777   ovrMirrorOption_RightEyeOnly = 0x0004,\r
 778 \r
 779   /// Shows the boundary system aka Guardian on the mirror texture\r
 780   ovrMirrorOption_IncludeGuardian = 0x0008,\r
 781 \r
 782   /// Shows system notifications the user receives on the mirror texture\r
 783   ovrMirrorOption_IncludeNotifications = 0x0010,\r
 784 \r
 785   /// Shows the system menu (triggered by hitting the Home button) on the mirror texture\r
 786   ovrMirrorOption_IncludeSystemGui = 0x0020,\r
 787 \r
 788 \r
 789   ovrMirrorOption_EnumSize = 0x7fffffff ///< \internal Force type int32_t.\r
 790 } ovrMirrorOptions;\r
 791 \r
 792 /// Description used to create a mirror texture.\r
 793 ///\r
 794 /// \see ovr_CreateMirrorTextureWithOptionsDX\r
 795 /// \see ovr_CreateMirrorTextureWithOptionsGL\r
 796 /// \see ovr_CreateMirrorTextureWithOptionsVk\r
 797 ///\r
 798 typedef struct ovrMirrorTextureDesc_ {\r
 799   ovrTextureFormat Format;\r
 800   int Width;\r
 801   int Height;\r
 802   unsigned int MiscFlags; ///< ovrTextureFlags\r
 803   unsigned int MirrorOptions; ///< ovrMirrorOptions\r
 804 } ovrMirrorTextureDesc;\r
 805 \r
 806 typedef struct ovrTextureSwapChainData* ovrTextureSwapChain;\r
 807 typedef struct ovrMirrorTextureData* ovrMirrorTexture;\r
 808 \r
 809 //-----------------------------------------------------------------------------------\r
 810 \r
 811 /// Describes button input types.\r
 812 /// Button inputs are combined; that is they will be reported as pressed if they are\r
 813 /// pressed on either one of the two devices.\r
 814 /// The ovrButton_Up/Down/Left/Right map to both XBox D-Pad and directional buttons.\r
 815 /// The ovrButton_Enter and ovrButton_Return map to Start and Back controller buttons, respectively.\r
 816 typedef enum ovrButton_ {\r
 817   /// A button on XBox controllers and right Touch controller. Select button on Oculus Remote.\r
 818   ovrButton_A = 0x00000001,\r
 819 \r
 820   /// B button on XBox controllers and right Touch controller. Back button on Oculus Remote.\r
 821   ovrButton_B = 0x00000002,\r
 822 \r
 823   /// Right thumbstick on XBox controllers and Touch controllers. Not present on Oculus Remote.\r
 824   ovrButton_RThumb = 0x00000004,\r
 825 \r
 826   /// Right shoulder button on XBox controllers. Not present on Touch controllers or Oculus Remote.\r
 827   ovrButton_RShoulder = 0x00000008,\r
 828 \r
 829 \r
 830   /// X button on XBox controllers and left Touch controller. Not present on Oculus Remote.\r
 831   ovrButton_X = 0x00000100,\r
 832 \r
 833   /// Y button on XBox controllers and left Touch controller. Not present on Oculus Remote.\r
 834   ovrButton_Y = 0x00000200,\r
 835 \r
 836   /// Left thumbstick on XBox controllers and Touch controllers. Not present on Oculus Remote.\r
 837   ovrButton_LThumb = 0x00000400,\r
 838 \r
 839   /// Left shoulder button on XBox controllers. Not present on Touch controllers or Oculus Remote.\r
 840   ovrButton_LShoulder = 0x00000800,\r
 841 \r
 842   /// Up button on XBox controllers and Oculus Remote. Not present on Touch controllers.\r
 843   ovrButton_Up = 0x00010000,\r
 844 \r
 845   /// Down button on XBox controllers and Oculus Remote. Not present on Touch controllers.\r
 846   ovrButton_Down = 0x00020000,\r
 847 \r
 848   /// Left button on XBox controllers and Oculus Remote. Not present on Touch controllers.\r
 849   ovrButton_Left = 0x00040000,\r
 850 \r
 851   /// Right button on XBox controllers and Oculus Remote. Not present on Touch controllers.\r
 852   ovrButton_Right = 0x00080000,\r
 853 \r
 854   /// Start on XBox 360 controller. Menu on XBox One controller and Left Touch controller.\r
 855   /// Should be referred to as the Menu button in user-facing documentation.\r
 856   ovrButton_Enter = 0x00100000,\r
 857 \r
 858   /// Back on Xbox 360 controller. View button on XBox One controller. Not present on Touch\r
 859   /// controllers or Oculus Remote.\r
 860   ovrButton_Back = 0x00200000,\r
 861 \r
 862   /// Volume button on Oculus Remote. Not present on XBox or Touch controllers.\r
 863   ovrButton_VolUp = 0x00400000,\r
 864 \r
 865   /// Volume button on Oculus Remote. Not present on XBox or Touch controllers.\r
 866   ovrButton_VolDown = 0x00800000,\r
 867 \r
 868   /// Home button on XBox controllers. Oculus button on Touch controllers and Oculus Remote.\r
 869   ovrButton_Home = 0x01000000,\r
 870 \r
 871   // Bit mask of all buttons that are for private usage by Oculus\r
 872   ovrButton_Private = ovrButton_VolUp | ovrButton_VolDown | ovrButton_Home,\r
 873 \r
 874   // Bit mask of all buttons on the right Touch controller\r
 875   ovrButton_RMask = ovrButton_A | ovrButton_B | ovrButton_RThumb | ovrButton_RShoulder,\r
 876 \r
 877   // Bit mask of all buttons on the left Touch controller\r
 878   ovrButton_LMask =\r
 879       ovrButton_X | ovrButton_Y | ovrButton_LThumb | ovrButton_LShoulder | ovrButton_Enter,\r
 880 \r
 881   ovrButton_EnumSize = 0x7fffffff ///< \internal Force type int32_t.\r
 882 } ovrButton;\r
 883 \r
 884 /// Describes touch input types.\r
 885 /// These values map to capacitive touch values reported ovrInputState::Touch.\r
 886 /// Some of these values are mapped to button bits for consistency.\r
 887 typedef enum ovrTouch_ {\r
 888   ovrTouch_A = ovrButton_A,\r
 889   ovrTouch_B = ovrButton_B,\r
 890   ovrTouch_RThumb = ovrButton_RThumb,\r
 891   ovrTouch_RThumbRest = 0x00000008,\r
 892   ovrTouch_RIndexTrigger = 0x00000010,\r
 893 \r
 894   // Bit mask of all the button touches on the right controller\r
 895   ovrTouch_RButtonMask =\r
 896       ovrTouch_A | ovrTouch_B | ovrTouch_RThumb | ovrTouch_RThumbRest | ovrTouch_RIndexTrigger,\r
 897 \r
 898   ovrTouch_X = ovrButton_X,\r
 899   ovrTouch_Y = ovrButton_Y,\r
 900   ovrTouch_LThumb = ovrButton_LThumb,\r
 901   ovrTouch_LThumbRest = 0x00000800,\r
 902   ovrTouch_LIndexTrigger = 0x00001000,\r
 903 \r
 904   // Bit mask of all the button touches on the left controller\r
 905   ovrTouch_LButtonMask =\r
 906       ovrTouch_X | ovrTouch_Y | ovrTouch_LThumb | ovrTouch_LThumbRest | ovrTouch_LIndexTrigger,\r
 907 \r
 908   // Finger pose state\r
 909   // Derived internally based on distance, proximity to sensors and filtering.\r
 910   ovrTouch_RIndexPointing = 0x00000020,\r
 911   ovrTouch_RThumbUp = 0x00000040,\r
 912   ovrTouch_LIndexPointing = 0x00002000,\r
 913   ovrTouch_LThumbUp = 0x00004000,\r
 914 \r
 915   // Bit mask of all right controller poses\r
 916   ovrTouch_RPoseMask = ovrTouch_RIndexPointing | ovrTouch_RThumbUp,\r
 917 \r
 918   // Bit mask of all left controller poses\r
 919   ovrTouch_LPoseMask = ovrTouch_LIndexPointing | ovrTouch_LThumbUp,\r
 920 \r
 921   ovrTouch_EnumSize = 0x7fffffff ///< \internal Force type int32_t.\r
 922 } ovrTouch;\r
 923 \r
 924 /// Describes the Touch Haptics engine.\r
 925 /// Currently, those values will NOT change during a session.\r
 926 typedef struct OVR_ALIGNAS(OVR_PTR_SIZE) ovrTouchHapticsDesc_ {\r
 927   // Haptics engine frequency/sample-rate, sample time in seconds equals 1.0/sampleRateHz\r
 928   int SampleRateHz;\r
 929   // Size of each Haptics sample, sample value range is [0, 2^(Bytes*8)-1]\r
 930   int SampleSizeInBytes;\r
 931 \r
 932   // Queue size that would guarantee Haptics engine would not starve for data\r
 933   // Make sure size doesn't drop below it for best results\r
 934   int QueueMinSizeToAvoidStarvation;\r
 935 \r
 936   // Minimum, Maximum and Optimal number of samples that can be sent to Haptics through\r
 937   // ovr_SubmitControllerVibration\r
 938   int SubmitMinSamples;\r
 939   int SubmitMaxSamples;\r
 940   int SubmitOptimalSamples;\r
 941 } ovrTouchHapticsDesc;\r
 942 \r
 943 /// Specifies which controller is connected; multiple can be connected at once.\r
 944 typedef enum ovrControllerType_ {\r
 945   ovrControllerType_None = 0x0000,\r
 946   ovrControllerType_LTouch = 0x0001,\r
 947   ovrControllerType_RTouch = 0x0002,\r
 948   ovrControllerType_Touch = (ovrControllerType_LTouch | ovrControllerType_RTouch),\r
 949   ovrControllerType_Remote = 0x0004,\r
 950 \r
 951   ovrControllerType_XBox = 0x0010,\r
 952 \r
 953   ovrControllerType_Object0 = 0x0100,\r
 954   ovrControllerType_Object1 = 0x0200,\r
 955   ovrControllerType_Object2 = 0x0400,\r
 956   ovrControllerType_Object3 = 0x0800,\r
 957 \r
 958   ovrControllerType_Active = 0xffffffff, ///< Operate on or query whichever controller is active.\r
 959 \r
 960   ovrControllerType_EnumSize = 0x7fffffff ///< \internal Force type int32_t.\r
 961 } ovrControllerType;\r
 962 \r
 963 /// Haptics buffer submit mode\r
 964 typedef enum ovrHapticsBufferSubmitMode_ {\r
 965   /// Enqueue buffer for later playback\r
 966   ovrHapticsBufferSubmit_Enqueue\r
 967 } ovrHapticsBufferSubmitMode;\r
 968 \r
 969 /// Maximum number of samples in ovrHapticsBuffer\r
 970 #define OVR_HAPTICS_BUFFER_SAMPLES_MAX 256\r
 971 \r
 972 /// Haptics buffer descriptor, contains amplitude samples used for Touch vibration\r
 973 typedef struct ovrHapticsBuffer_ {\r
 974   /// Samples stored in opaque format\r
 975   const void* Samples;\r
 976   /// Number of samples (up to OVR_HAPTICS_BUFFER_SAMPLES_MAX)\r
 977   int SamplesCount;\r
 978   /// How samples are submitted to the hardware\r
 979   ovrHapticsBufferSubmitMode SubmitMode;\r
 980 } ovrHapticsBuffer;\r
 981 \r
 982 /// State of the Haptics playback for Touch vibration\r
 983 typedef struct ovrHapticsPlaybackState_ {\r
 984   // Remaining space available to queue more samples\r
 985   int RemainingQueueSpace;\r
 986 \r
 987   // Number of samples currently queued\r
 988   int SamplesQueued;\r
 989 } ovrHapticsPlaybackState;\r
 990 \r
 991 /// Position tracked devices\r
 992 typedef enum ovrTrackedDeviceType_ {\r
 993   ovrTrackedDevice_None = 0x0000,\r
 994   ovrTrackedDevice_HMD = 0x0001,\r
 995   ovrTrackedDevice_LTouch = 0x0002,\r
 996   ovrTrackedDevice_RTouch = 0x0004,\r
 997   ovrTrackedDevice_Touch = (ovrTrackedDevice_LTouch | ovrTrackedDevice_RTouch),\r
 998 \r
 999   ovrTrackedDevice_Object0 = 0x0010,\r
1000   ovrTrackedDevice_Object1 = 0x0020,\r
1001   ovrTrackedDevice_Object2 = 0x0040,\r
1002   ovrTrackedDevice_Object3 = 0x0080,\r
1003 \r
1004   ovrTrackedDevice_All = 0xFFFF,\r
1005 } ovrTrackedDeviceType;\r
1006 \r
1007 /// Boundary types that specified while using the boundary system\r
1008 typedef enum ovrBoundaryType_ {\r
1009   /// Outer boundary - closely represents user setup walls\r
1010   ovrBoundary_Outer = 0x0001,\r
1011 \r
1012   /// Play area - safe rectangular area inside outer boundary which can optionally be used to\r
1013   /// restrict user interactions and motion.\r
1014   ovrBoundary_PlayArea = 0x0100,\r
1015 } ovrBoundaryType;\r
1016 \r
1017 /// Boundary system look and feel\r
1018 typedef struct ovrBoundaryLookAndFeel_ {\r
1019   /// Boundary color (alpha channel is ignored)\r
1020   ovrColorf Color;\r
1021 } ovrBoundaryLookAndFeel;\r
1022 \r
1023 /// Provides boundary test information\r
1024 typedef struct ovrBoundaryTestResult_ {\r
1025   /// True if the boundary system is being triggered. Note that due to fade in/out effects this may\r
1026   /// not exactly match visibility.\r
1027   ovrBool IsTriggering;\r
1028 \r
1029   /// Distance to the closest play area or outer boundary surface.\r
1030   float ClosestDistance;\r
1031 \r
1032   /// Closest point on the boundary surface.\r
1033   ovrVector3f ClosestPoint;\r
1034 \r
1035   /// Unit surface normal of the closest boundary surface.\r
1036   ovrVector3f ClosestPointNormal;\r
1037 } ovrBoundaryTestResult;\r
1038 \r
1039 /// Provides names for the left and right hand array indexes.\r
1040 ///\r
1041 /// \see ovrInputState, ovrTrackingState\r
1042 ///\r
1043 typedef enum ovrHandType_ {\r
1044   ovrHand_Left = 0,\r
1045   ovrHand_Right = 1,\r
1046   ovrHand_Count = 2,\r
1047   ovrHand_EnumSize = 0x7fffffff ///< \internal Force type int32_t.\r
1048 } ovrHandType;\r
1049 \r
1050 /// ovrInputState describes the complete controller input state, including Oculus Touch,\r
1051 /// and XBox gamepad. If multiple inputs are connected and used at the same time,\r
1052 /// their inputs are combined.\r
1053 typedef struct ovrInputState_ {\r
1054   /// System type when the controller state was last updated.\r
1055   double TimeInSeconds;\r
1056 \r
1057   /// Values for buttons described by ovrButton.\r
1058   unsigned int Buttons;\r
1059 \r
1060   /// Touch values for buttons and sensors as described by ovrTouch.\r
1061   unsigned int Touches;\r
1062 \r
1063   /// Left and right finger trigger values (ovrHand_Left and ovrHand_Right), in range 0.0 to 1.0f.\r
1064   /// Returns 0 if the value would otherwise be less than 0.1176, for ovrControllerType_XBox.\r
1065   /// This has been formally named simply "Trigger". We retain the name IndexTrigger for backwards\r
1066   /// code compatibility.\r
1067   /// User-facing documentation should refer to it as the Trigger.\r
1068   float IndexTrigger[ovrHand_Count];\r
1069 \r
1070   /// Left and right hand trigger values (ovrHand_Left and ovrHand_Right), in the range 0.0 to 1.0f.\r
1071   /// This has been formally named "Grip Button". We retain the name HandTrigger for backwards code\r
1072   /// compatibility.\r
1073   /// User-facing documentation should refer to it as the Grip Button or simply Grip.\r
1074   float HandTrigger[ovrHand_Count];\r
1075 \r
1076   /// Horizontal and vertical thumbstick axis values (ovrHand_Left and ovrHand_Right), in the range\r
1077   /// of -1.0f to 1.0f.\r
1078   /// Returns a deadzone (value 0) per each axis if the value on that axis would otherwise have been\r
1079   /// between -.2746 to +.2746, for ovrControllerType_XBox\r
1080   ovrVector2f Thumbstick[ovrHand_Count];\r
1081 \r
1082   /// The type of the controller this state is for.\r
1083   ovrControllerType ControllerType;\r
1084 \r
1085   /// Left and right finger trigger values (ovrHand_Left and ovrHand_Right), in range 0.0 to 1.0f.\r
1086   /// Does not apply a deadzone.  Only touch applies a filter.\r
1087   /// This has been formally named simply "Trigger". We retain the name IndexTrigger for backwards\r
1088   /// code compatibility.\r
1089   /// User-facing documentation should refer to it as the Trigger.\r
1090   float IndexTriggerNoDeadzone[ovrHand_Count];\r
1091 \r
1092   /// Left and right hand trigger values (ovrHand_Left and ovrHand_Right), in the range 0.0 to 1.0f.\r
1093   /// Does not apply a deadzone. Only touch applies a filter.\r
1094   /// This has been formally named "Grip Button". We retain the name HandTrigger for backwards code\r
1095   /// compatibility.\r
1096   /// User-facing documentation should refer to it as the Grip Button or simply Grip.\r
1097   float HandTriggerNoDeadzone[ovrHand_Count];\r
1098 \r
1099   /// Horizontal and vertical thumbstick axis values (ovrHand_Left and ovrHand_Right), in the range\r
1100   /// -1.0f to 1.0f\r
1101   /// Does not apply a deadzone or filter.\r
1102   ovrVector2f ThumbstickNoDeadzone[ovrHand_Count];\r
1103 \r
1104   /// Left and right finger trigger values (ovrHand_Left and ovrHand_Right), in range 0.0 to 1.0f.\r
1105   /// No deadzone or filter\r
1106   /// This has been formally named "Grip Button". We retain the name HandTrigger for backwards code\r
1107   /// compatibility.\r
1108   /// User-facing documentation should refer to it as the Grip Button or simply Grip.\r
1109   float IndexTriggerRaw[ovrHand_Count];\r
1110 \r
1111   /// Left and right hand trigger values (ovrHand_Left and ovrHand_Right), in the range 0.0 to 1.0f.\r
1112   /// No deadzone or filter\r
1113   /// This has been formally named "Grip Button". We retain the name HandTrigger for backwards code\r
1114   /// compatibility.\r
1115   /// User-facing documentation should refer to it as the Grip Button or simply Grip.\r
1116   float HandTriggerRaw[ovrHand_Count];\r
1117 \r
1118   /// Horizontal and vertical thumbstick axis values (ovrHand_Left and ovrHand_Right), in the range\r
1119   /// -1.0f to 1.0f\r
1120   /// No deadzone or filter\r
1121   ovrVector2f ThumbstickRaw[ovrHand_Count];\r
1122 } ovrInputState;\r
1123 \r
1124 typedef struct ovrCameraIntrinsics_ {\r
1125   /// Time in seconds from last change to the parameters\r
1126   double LastChangedTime;\r
1127 \r
1128   /// Angles of all 4 sides of viewport\r
1129   ovrFovPort FOVPort;\r
1130 \r
1131   /// Near plane of the virtual camera used to match the external camera\r
1132   float VirtualNearPlaneDistanceMeters;\r
1133 \r
1134   /// Far plane of the virtual camera used to match the external camera\r
1135   float VirtualFarPlaneDistanceMeters;\r
1136 \r
1137   /// Height in pixels of image sensor\r
1138   ovrSizei ImageSensorPixelResolution;\r
1139 \r
1140   /// The lens distortion matrix of camera\r
1141   ovrMatrix4f LensDistortionMatrix;\r
1142 \r
1143   /// How often, in seconds, the exposure is taken\r
1144   double ExposurePeriodSeconds;\r
1145 \r
1146   /// length of the exposure time\r
1147   double ExposureDurationSeconds;\r
1148 \r
1149 } ovrCameraIntrinsics;\r
1150 \r
1151 typedef enum ovrCameraStatusFlags_ {\r
1152   /// Initial state of camera\r
1153   ovrCameraStatus_None = 0x0,\r
1154 \r
1155   /// Bit set when the camera is connected to the system\r
1156   ovrCameraStatus_Connected = 0x1,\r
1157 \r
1158   /// Bit set when the camera is undergoing calibration\r
1159   ovrCameraStatus_Calibrating = 0x2,\r
1160 \r
1161   /// Bit set when the camera has tried & failed calibration\r
1162   ovrCameraStatus_CalibrationFailed = 0x4,\r
1163 \r
1164   /// Bit set when the camera has tried & passed calibration\r
1165   ovrCameraStatus_Calibrated = 0x8,\r
1166 \r
1167   /// Bit set when the camera is capturing\r
1168   ovrCameraStatus_Capturing = 0x10,\r
1169 \r
1170   ovrCameraStatus_EnumSize = 0x7fffffff ///< \internal Force type int32_t.\r
1171 } ovrCameraStatusFlags;\r
1172 \r
1173 typedef struct ovrCameraExtrinsics_ {\r
1174   /// Time in seconds from last change to the parameters.\r
1175   /// For instance, if the pose changes, or a camera exposure happens, this struct will be updated.\r
1176   double LastChangedTimeSeconds;\r
1177 \r
1178   /// Current Status of the camera, a mix of bits from ovrCameraStatusFlags\r
1179   unsigned int CameraStatusFlags;\r
1180 \r
1181   /// Which Tracked device, if any, is the camera rigidly attached to\r
1182   /// If set to ovrTrackedDevice_None, then the camera is not attached to a tracked object.\r
1183   /// If the external camera moves while unattached (i.e. set to ovrTrackedDevice_None), its Pose\r
1184   /// won't be updated\r
1185   ovrTrackedDeviceType AttachedToDevice;\r
1186 \r
1187   /// The relative Pose of the External Camera.\r
1188   /// If AttachedToDevice is ovrTrackedDevice_None, then this is a absolute pose in tracking space\r
1189   ovrPosef RelativePose;\r
1190 \r
1191   /// The time, in seconds, when the last successful exposure was taken\r
1192   double LastExposureTimeSeconds;\r
1193 \r
1194   /// Estimated exposure latency to get from the exposure time to the system\r
1195   double ExposureLatencySeconds;\r
1196 \r
1197   /// Additional latency to get from the exposure time of the real camera to match the render time\r
1198   /// of the virtual camera\r
1199   double AdditionalLatencySeconds;\r
1200 \r
1201 } ovrCameraExtrinsics;\r
1202 #define OVR_MAX_EXTERNAL_CAMERA_COUNT 16\r
1203 #define OVR_EXTERNAL_CAMERA_NAME_SIZE 32\r
1204 typedef struct ovrExternalCamera_ {\r
1205   char Name[OVR_EXTERNAL_CAMERA_NAME_SIZE]; // camera identifier: vid + pid + serial number etc.\r
1206   ovrCameraIntrinsics Intrinsics;\r
1207   ovrCameraExtrinsics Extrinsics;\r
1208 } ovrExternalCamera;\r
1209 \r
1210 //-----------------------------------------------------------------------------------\r
1211 // ***** Initialize structures\r
1212 \r
1213 /// Initialization flags.\r
1214 ///\r
1215 /// \see ovrInitParams, ovr_Initialize\r
1216 ///\r
1217 typedef enum ovrInitFlags_ {\r
1218   /// When a debug library is requested, a slower debugging version of the library will\r
1219   /// run which can be used to help solve problems in the library and debug application code.\r
1220   ovrInit_Debug = 0x00000001,\r
1221 \r
1222 \r
1223   /// When a version is requested, the LibOVR runtime respects the RequestedMinorVersion\r
1224   /// field and verifies that the RequestedMinorVersion is supported. Normally when you\r
1225   /// specify this flag you simply use OVR_MINOR_VERSION for ovrInitParams::RequestedMinorVersion,\r
1226   /// though you could use a lower version than OVR_MINOR_VERSION to specify previous\r
1227   /// version behavior.\r
1228   ovrInit_RequestVersion = 0x00000004,\r
1229 \r
1230 \r
1231   /// This client will not be visible in the HMD.\r
1232   /// Typically set by diagnostic or debugging utilities.\r
1233   ovrInit_Invisible = 0x00000010,\r
1234 \r
1235   /// This client will alternate between VR and 2D rendering.\r
1236   /// Typically set by game engine editors and VR-enabled web browsers.\r
1237   ovrInit_MixedRendering = 0x00000020,\r
1238 \r
1239   /// This client is aware of ovrSessionStatus focus states (e.g. ovrSessionStatus::HasInputFocus),\r
1240   /// and responds to them appropriately (e.g. pauses and stops drawing hands when lacking focus).\r
1241   ovrInit_FocusAware = 0x00000040,\r
1242 \r
1243 \r
1244 \r
1245 \r
1246 \r
1247   /// These bits are writable by user code.\r
1248   ovrinit_WritableBits = 0x00ffffff,\r
1249 \r
1250   ovrInit_EnumSize = 0x7fffffff ///< \internal Force type int32_t.\r
1251 } ovrInitFlags;\r
1252 \r
1253 /// Logging levels\r
1254 ///\r
1255 /// \see ovrInitParams, ovrLogCallback\r
1256 ///\r
1257 typedef enum ovrLogLevel_ {\r
1258   ovrLogLevel_Debug = 0, ///< Debug-level log event.\r
1259   ovrLogLevel_Info = 1, ///< Info-level log event.\r
1260   ovrLogLevel_Error = 2, ///< Error-level log event.\r
1261 \r
1262   ovrLogLevel_EnumSize = 0x7fffffff ///< \internal Force type int32_t.\r
1263 } ovrLogLevel;\r
1264 \r
1265 /// Signature of the logging callback function pointer type.\r
1266 ///\r
1267 /// \param[in] userData is an arbitrary value specified by the user of ovrInitParams.\r
1268 /// \param[in] level is one of the ovrLogLevel constants.\r
1269 /// \param[in] message is a UTF8-encoded null-terminated string.\r
1270 /// \see ovrInitParams, ovrLogLevel, ovr_Initialize\r
1271 ///\r
1272 typedef void(OVR_CDECL* ovrLogCallback)(uintptr_t userData, int level, const char* message);\r
1273 \r
1274 /// Parameters for ovr_Initialize.\r
1275 ///\r
1276 /// \see ovr_Initialize\r
1277 ///\r
1278 typedef struct OVR_ALIGNAS(8) ovrInitParams_ {\r
1279   /// Flags from ovrInitFlags to override default behavior.\r
1280   /// Use 0 for the defaults.\r
1281   uint32_t Flags;\r
1282 \r
1283   /// Requests a specific minor version of the LibOVR runtime.\r
1284   /// Flags must include ovrInit_RequestVersion or this will be ignored and OVR_MINOR_VERSION\r
1285   /// will be used. If you are directly calling the LibOVRRT version of ovr_Initialize\r
1286   /// in the LibOVRRT DLL then this must be valid and include ovrInit_RequestVersion.\r
1287   uint32_t RequestedMinorVersion;\r
1288 \r
1289   /// User-supplied log callback function, which may be called at any time\r
1290   /// asynchronously from multiple threads until ovr_Shutdown completes.\r
1291   /// Use NULL to specify no log callback.\r
1292   ovrLogCallback LogCallback;\r
1293 \r
1294   /// User-supplied data which is passed as-is to LogCallback. Typically this\r
1295   /// is used to store an application-specific pointer which is read in the\r
1296   /// callback function.\r
1297   uintptr_t UserData;\r
1298 \r
1299   /// Relative number of milliseconds to wait for a connection to the server\r
1300   /// before failing. Use 0 for the default timeout.\r
1301   uint32_t ConnectionTimeoutMS;\r
1302 \r
1303   OVR_ON64(OVR_UNUSED_STRUCT_PAD(pad0, 4)) ///< \internal\r
1304 \r
1305 } ovrInitParams;\r
1306 \r
1307 #ifdef __cplusplus\r
1308 extern "C" {\r
1309 #endif\r
1310 \r
1311 #if !defined(OVR_EXPORTING_CAPI)\r
1312 \r
1313 // -----------------------------------------------------------------------------------\r
1314 // ***** API Interfaces\r
1315 \r
1316 /// Initializes LibOVR\r
1317 ///\r
1318 /// Initialize LibOVR for application usage. This includes finding and loading the LibOVRRT\r
1319 /// shared library. No LibOVR API functions, other than ovr_GetLastErrorInfo and ovr_Detect, can\r
1320 /// be called unless ovr_Initialize succeeds. A successful call to ovr_Initialize must be eventually\r
1321 /// followed by a call to ovr_Shutdown. ovr_Initialize calls are idempotent.\r
1322 /// Calling ovr_Initialize twice does not require two matching calls to ovr_Shutdown.\r
1323 /// If already initialized, the return value is ovr_Success.\r
1324 ///\r
1325 /// LibOVRRT shared library search order:\r
1326 ///      -# Current working directory (often the same as the application directory).\r
1327 ///      -# Module directory (usually the same as the application directory,\r
1328 ///         but not if the module is a separate shared library).\r
1329 ///      -# Application directory\r
1330 ///      -# Development directory (only if OVR_ENABLE_DEVELOPER_SEARCH is enabled,\r
1331 ///         which is off by default).\r
1332 ///      -# Standard OS shared library search location(s) (OS-specific).\r
1333 ///\r
1334 /// \param params Specifies custom initialization options. May be NULL to indicate default options\r
1335 ///        when using the CAPI shim. If you are directly calling the LibOVRRT version of\r
1336 ///        ovr_Initialize in the LibOVRRT DLL then this must be valid and\r
1337 ///        include ovrInit_RequestVersion.\r
1338 /// \return Returns an ovrResult indicating success or failure. In the case of failure, use\r
1339 ///         ovr_GetLastErrorInfo to get more information. Example failed results include:\r
1340 ///     - ovrError_Initialize: Generic initialization error.\r
1341 ///     - ovrError_LibLoad: Couldn't load LibOVRRT.\r
1342 ///     - ovrError_LibVersion: LibOVRRT version incompatibility.\r
1343 ///     - ovrError_ServiceConnection: Couldn't connect to the OVR Service.\r
1344 ///     - ovrError_ServiceVersion: OVR Service version incompatibility.\r
1345 ///     - ovrError_IncompatibleOS: The operating system version is incompatible.\r
1346 ///     - ovrError_DisplayInit: Unable to initialize the HMD display.\r
1347 ///     - ovrError_ServerStart:  Unable to start the server. Is it already running?\r
1348 ///     - ovrError_Reinitialization: Attempted to re-initialize with a different version.\r
1349 ///\r
1350 /// <b>Example code</b>\r
1351 ///     \code{.cpp}\r
1352 ///         ovrInitParams initParams = { ovrInit_RequestVersion, OVR_MINOR_VERSION, NULL, 0, 0 };\r
1353 ///         ovrResult result = ovr_Initialize(&initParams);\r
1354 ///         if(OVR_FAILURE(result)) {\r
1355 ///             ovrErrorInfo errorInfo;\r
1356 ///             ovr_GetLastErrorInfo(&errorInfo);\r
1357 ///             DebugLog("ovr_Initialize failed: %s", errorInfo.ErrorString);\r
1358 ///             return false;\r
1359 ///         }\r
1360 ///         [...]\r
1361 ///     \endcode\r
1362 ///\r
1363 /// \see ovr_Shutdown\r
1364 ///\r
1365 OVR_PUBLIC_FUNCTION(ovrResult) ovr_Initialize(const ovrInitParams* params);\r
1366 \r
1367 /// Shuts down LibOVR\r
1368 ///\r
1369 /// A successful call to ovr_Initialize must be eventually matched by a call to ovr_Shutdown.\r
1370 /// After calling ovr_Shutdown, no LibOVR functions can be called except ovr_GetLastErrorInfo\r
1371 /// or another ovr_Initialize. ovr_Shutdown invalidates all pointers, references, and created\r
1372 /// objects\r
1373 /// previously returned by LibOVR functions. The LibOVRRT shared library can be unloaded by\r
1374 /// ovr_Shutdown.\r
1375 ///\r
1376 /// \see ovr_Initialize\r
1377 ///\r
1378 OVR_PUBLIC_FUNCTION(void) ovr_Shutdown();\r
1379 \r
1380 /// Returns information about the most recent failed return value by the\r
1381 /// current thread for this library.\r
1382 ///\r
1383 /// This function itself can never generate an error.\r
1384 /// The last error is never cleared by LibOVR, but will be overwritten by new errors.\r
1385 /// Do not use this call to determine if there was an error in the last API\r
1386 /// call as successful API calls don't clear the last ovrErrorInfo.\r
1387 /// To avoid any inconsistency, ovr_GetLastErrorInfo should be called immediately\r
1388 /// after an API function that returned a failed ovrResult, with no other API\r
1389 /// functions called in the interim.\r
1390 ///\r
1391 /// \param[out] errorInfo The last ovrErrorInfo for the current thread.\r
1392 ///\r
1393 /// \see ovrErrorInfo\r
1394 ///\r
1395 OVR_PUBLIC_FUNCTION(void) ovr_GetLastErrorInfo(ovrErrorInfo* errorInfo);\r
1396 \r
1397 /// Returns the version string representing the LibOVRRT version.\r
1398 ///\r
1399 /// The returned string pointer is valid until the next call to ovr_Shutdown.\r
1400 ///\r
1401 /// Note that the returned version string doesn't necessarily match the current\r
1402 /// OVR_MAJOR_VERSION, etc., as the returned string refers to the LibOVRRT shared\r
1403 /// library version and not the locally compiled interface version.\r
1404 ///\r
1405 /// The format of this string is subject to change in future versions and its contents\r
1406 /// should not be interpreted.\r
1407 ///\r
1408 /// \return Returns a UTF8-encoded null-terminated version string.\r
1409 ///\r
1410 OVR_PUBLIC_FUNCTION(const char*) ovr_GetVersionString();\r
1411 \r
1412 /// Writes a message string to the LibOVR tracing mechanism (if enabled).\r
1413 ///\r
1414 /// This message will be passed back to the application via the ovrLogCallback if\r
1415 /// it was registered.\r
1416 ///\r
1417 /// \param[in] level One of the ovrLogLevel constants.\r
1418 /// \param[in] message A UTF8-encoded null-terminated string.\r
1419 /// \return returns the strlen of the message or a negative value if the message is too large.\r
1420 ///\r
1421 /// \see ovrLogLevel, ovrLogCallback\r
1422 ///\r
1423 OVR_PUBLIC_FUNCTION(int) ovr_TraceMessage(int level, const char* message);\r
1424 \r
1425 /// Identify client application info.\r
1426 ///\r
1427 /// The string is one or more newline-delimited lines of optional info\r
1428 /// indicating engine name, engine version, engine plugin name, engine plugin\r
1429 /// version, engine editor. The order of the lines is not relevant. Individual\r
1430 /// lines are optional. A newline is not necessary at the end of the last line.\r
1431 /// Call after ovr_Initialize and before the first call to ovr_Create.\r
1432 /// Each value is limited to 20 characters. Key names such as 'EngineName:'\r
1433 /// 'EngineVersion:' do not count towards this limit.\r
1434 ///\r
1435 /// \param[in] identity Specifies one or more newline-delimited lines of optional info:\r
1436 ///             EngineName: %s\n\r
1437 ///             EngineVersion: %s\n\r
1438 ///             EnginePluginName: %s\n\r
1439 ///             EnginePluginVersion: %s\n\r
1440 ///             EngineEditor: <boolean> ('true' or 'false')\n\r
1441 ///\r
1442 /// <b>Example code</b>\r
1443 ///     \code{.cpp}\r
1444 ///     ovr_IdentifyClient("EngineName: Unity\n"\r
1445 ///                        "EngineVersion: 5.3.3\n"\r
1446 ///                        "EnginePluginName: OVRPlugin\n"\r
1447 ///                        "EnginePluginVersion: 1.2.0\n"\r
1448 ///                        "EngineEditor: true");\r
1449 ///     \endcode\r
1450 ///\r
1451 OVR_PUBLIC_FUNCTION(ovrResult) ovr_IdentifyClient(const char* identity);\r
1452 \r
1453 //-------------------------------------------------------------------------------------\r
1454 /// @name HMD Management\r
1455 ///\r
1456 /// Handles the enumeration, creation, destruction, and properties of an HMD (head-mounted display).\r
1457 ///@{\r
1458 \r
1459 /// Returns information about the current HMD.\r
1460 ///\r
1461 /// ovr_Initialize must be called prior to calling this function,\r
1462 /// otherwise ovrHmdDesc::Type will be set to ovrHmd_None without\r
1463 /// checking for the HMD presence.\r
1464 ///\r
1465 /// \param[in] session Specifies an ovrSession previously returned by ovr_Create() or NULL.\r
1466 ///\r
1467 /// \return Returns an ovrHmdDesc. If invoked with NULL session argument, ovrHmdDesc::Type\r
1468 ///         set to ovrHmd_None indicates that the HMD is not connected.\r
1469 ///\r
1470 OVR_PUBLIC_FUNCTION(ovrHmdDesc) ovr_GetHmdDesc(ovrSession session);\r
1471 \r
1472 /// Returns the number of attached trackers.\r
1473 ///\r
1474 /// The number of trackers may change at any time, so this function should be called before use\r
1475 /// as opposed to once on startup.\r
1476 ///\r
1477 /// \param[in] session Specifies an ovrSession previously returned by ovr_Create.\r
1478 ///\r
1479 /// \return Returns unsigned int count.\r
1480 ///\r
1481 OVR_PUBLIC_FUNCTION(unsigned int) ovr_GetTrackerCount(ovrSession session);\r
1482 \r
1483 /// Returns a given attached tracker description.\r
1484 ///\r
1485 /// ovr_Initialize must have first been called in order for this to succeed, otherwise the returned\r
1486 /// trackerDescArray will be zero-initialized. The data returned by this function can change at\r
1487 /// runtime.\r
1488 ///\r
1489 /// \param[in] session Specifies an ovrSession previously returned by ovr_Create.\r
1490 ///\r
1491 /// \param[in] trackerDescIndex Specifies a tracker index. The valid indexes are in the\r
1492 ///            range of 0 to the tracker count returned by ovr_GetTrackerCount.\r
1493 ///\r
1494 /// \return Returns ovrTrackerDesc. An empty ovrTrackerDesc will be returned if\r
1495 ///           trackerDescIndex is out of range.\r
1496 ///\r
1497 /// \see ovrTrackerDesc, ovr_GetTrackerCount\r
1498 ///\r
1499 OVR_PUBLIC_FUNCTION(ovrTrackerDesc)\r
1500 ovr_GetTrackerDesc(ovrSession session, unsigned int trackerDescIndex);\r
1501 \r
1502 /// Creates a handle to a VR session.\r
1503 ///\r
1504 /// Upon success the returned ovrSession must be eventually freed with ovr_Destroy when it is no\r
1505 /// longer needed.\r
1506 /// A second call to ovr_Create will result in an error return value if the previous session has not\r
1507 /// been destroyed.\r
1508 ///\r
1509 /// \param[out] pSession Provides a pointer to an ovrSession which will be written to upon success.\r
1510 /// \param[out] pLuid Provides a system specific graphics adapter identifier that locates which\r
1511 /// graphics adapter has the HMD attached. This must match the adapter used by the application\r
1512 /// or no rendering output will be possible. This is important for stability on multi-adapter\r
1513 /// systems. An\r
1514 /// application that simply chooses the default adapter will not run reliably on multi-adapter\r
1515 /// systems.\r
1516 /// \return Returns an ovrResult indicating success or failure. Upon failure\r
1517 ///         the returned ovrSession will be NULL.\r
1518 ///\r
1519 /// <b>Example code</b>\r
1520 ///     \code{.cpp}\r
1521 ///         ovrSession session;\r
1522 ///         ovrGraphicsLuid luid;\r
1523 ///         ovrResult result = ovr_Create(&session, &luid);\r
1524 ///         if(OVR_FAILURE(result))\r
1525 ///            ...\r
1526 ///     \endcode\r
1527 ///\r
1528 /// \see ovr_Destroy\r
1529 ///\r
1530 OVR_PUBLIC_FUNCTION(ovrResult) ovr_Create(ovrSession* pSession, ovrGraphicsLuid* pLuid);\r
1531 \r
1532 /// Destroys the session.\r
1533 ///\r
1534 /// \param[in] session Specifies an ovrSession previously returned by ovr_Create.\r
1535 /// \see ovr_Create\r
1536 ///\r
1537 OVR_PUBLIC_FUNCTION(void) ovr_Destroy(ovrSession session);\r
1538 \r
1539 #endif // !defined(OVR_EXPORTING_CAPI)\r
1540 \r
1541 /// Specifies status information for the current session.\r
1542 ///\r
1543 /// \see ovr_GetSessionStatus\r
1544 ///\r
1545 typedef struct ovrSessionStatus_ {\r
1546   /// True if the process has VR focus and thus is visible in the HMD.\r
1547   ovrBool IsVisible;\r
1548 \r
1549   /// True if an HMD is present.\r
1550   ovrBool HmdPresent;\r
1551 \r
1552   /// True if the HMD is on the user's head.\r
1553   ovrBool HmdMounted;\r
1554 \r
1555   /// True if the session is in a display-lost state. See ovr_SubmitFrame.\r
1556   ovrBool DisplayLost;\r
1557 \r
1558   /// True if the application should initiate shutdown.\r
1559   ovrBool ShouldQuit;\r
1560 \r
1561   /// True if UX has requested re-centering. Must call ovr_ClearShouldRecenterFlag,\r
1562   /// ovr_RecenterTrackingOrigin or ovr_SpecifyTrackingOrigin.\r
1563   ovrBool ShouldRecenter;\r
1564 \r
1565   /// True if the application is the foreground application and receives input (e.g. Touch\r
1566   /// controller state). If this is false then the application is in the background (but possibly\r
1567   /// still visible) should hide any input representations such as hands.\r
1568   ovrBool HasInputFocus;\r
1569 \r
1570   /// True if a system overlay is present, such as a dashboard. In this case the application\r
1571   /// (if visible) should pause while still drawing, avoid drawing near-field graphics so they\r
1572   /// don't visually fight with the system overlay, and consume fewer CPU and GPU resources.\r
1573   ovrBool OverlayPresent;\r
1574 \r
1575   /// True if runtime is requesting that the application provide depth buffers with projection\r
1576   /// layers.\r
1577   ovrBool DepthRequested;\r
1578 \r
1579 } ovrSessionStatus;\r
1580 \r
1581 #if !defined(OVR_EXPORTING_CAPI)\r
1582 \r
1583 /// Returns status information for the application.\r
1584 ///\r
1585 /// \param[in] session Specifies an ovrSession previously returned by ovr_Create.\r
1586 /// \param[out] sessionStatus Provides an ovrSessionStatus that is filled in.\r
1587 ///\r
1588 /// \return Returns an ovrResult indicating success or failure. In the case of\r
1589 ///         failure, use ovr_GetLastErrorInfo to get more information.\r
1590 ///         Return values include but aren't limited to:\r
1591 ///     - ovrSuccess: Completed successfully.\r
1592 ///     - ovrError_ServiceConnection: The service connection was lost and the application\r
1593 ///       must destroy the session.\r
1594 ///\r
1595 OVR_PUBLIC_FUNCTION(ovrResult)\r
1596 ovr_GetSessionStatus(ovrSession session, ovrSessionStatus* sessionStatus);\r
1597 \r
1598 \r
1599 /// Query extension support status.\r
1600 ///\r
1601 /// \param[in] session Specifies an ovrSession previously returned by ovr_Create.\r
1602 /// \param[in] extension Extension to query.\r
1603 /// \param[out] outExtensionSupported Set to extension support status. ovrTrue if supported.\r
1604 ///\r
1605 /// \return Returns an ovrResult indicating success or failure. In the case of\r
1606 ///         failure use ovr_GetLastErrorInfo to get more information.\r
1607 ///\r
1608 /// \see ovrExtensions\r
1609 ///\r
1610 OVR_PUBLIC_FUNCTION(ovrResult)\r
1611 ovr_IsExtensionSupported(\r
1612     ovrSession session,\r
1613     ovrExtensions extension,\r
1614     ovrBool* outExtensionSupported);\r
1615 \r
1616 /// Enable extension. Extensions must be enabled after ovr_Create is called.\r
1617 ///\r
1618 /// \param[in] session Specifies an ovrSession previously returned by ovr_Create.\r
1619 /// \param[in] extension Extension to enable.\r
1620 ///\r
1621 /// \return Returns an ovrResult indicating success or failure. Extension is only\r
1622 ///         enabled if successful. In the case of failure use ovr_GetLastErrorInfo\r
1623 ///         to get more information.\r
1624 ///\r
1625 /// \see ovrExtensions\r
1626 ///\r
1627 OVR_PUBLIC_FUNCTION(ovrResult)\r
1628 ovr_EnableExtension(ovrSession session, ovrExtensions extension);\r
1629 \r
1630 //@}\r
1631 \r
1632 //-------------------------------------------------------------------------------------\r
1633 /// @name Tracking\r
1634 ///\r
1635 /// Tracking functions handle the position, orientation, and movement of the HMD in space.\r
1636 ///\r
1637 /// All tracking interface functions are thread-safe, allowing tracking state to be sampled\r
1638 /// from different threads.\r
1639 ///\r
1640 ///@{\r
1641 \r
1642 \r
1643 /// Sets the tracking origin type\r
1644 ///\r
1645 /// When the tracking origin is changed, all of the calls that either provide\r
1646 /// or accept ovrPosef will use the new tracking origin provided.\r
1647 ///\r
1648 /// \param[in] session Specifies an ovrSession previously returned by ovr_Create.\r
1649 /// \param[in] origin Specifies an ovrTrackingOrigin to be used for all ovrPosef\r
1650 ///\r
1651 /// \return Returns an ovrResult indicating success or failure. In the case of failure, use\r
1652 ///         ovr_GetLastErrorInfo to get more information.\r
1653 ///\r
1654 /// \see ovrTrackingOrigin, ovr_GetTrackingOriginType\r
1655 OVR_PUBLIC_FUNCTION(ovrResult)\r
1656 ovr_SetTrackingOriginType(ovrSession session, ovrTrackingOrigin origin);\r
1657 \r
1658 /// Gets the tracking origin state\r
1659 ///\r
1660 /// \param[in] session Specifies an ovrSession previously returned by ovr_Create.\r
1661 ///\r
1662 /// \return Returns the ovrTrackingOrigin that was either set by default, or previous set by the\r
1663 /// application.\r
1664 ///\r
1665 /// \see ovrTrackingOrigin, ovr_SetTrackingOriginType\r
1666 OVR_PUBLIC_FUNCTION(ovrTrackingOrigin) ovr_GetTrackingOriginType(ovrSession session);\r
1667 \r
1668 /// Re-centers the sensor position and orientation.\r
1669 ///\r
1670 /// This resets the (x,y,z) positional components and the yaw orientation component of the\r
1671 /// tracking space for the HMD and controllers using the HMD's current tracking pose.\r
1672 /// If the caller requires some tweaks on top of the HMD's current tracking pose, consider using\r
1673 /// ovr_SpecifyTrackingOrigin instead.\r
1674 ///\r
1675 /// The roll and pitch orientation components are always determined by gravity and cannot\r
1676 /// be redefined. All future tracking will report values relative to this new reference position.\r
1677 /// If you are using ovrTrackerPoses then you will need to call ovr_GetTrackerPose after\r
1678 /// this, because the sensor position(s) will change as a result of this.\r
1679 ///\r
1680 /// The headset cannot be facing vertically upward or downward but rather must be roughly\r
1681 /// level otherwise this function will fail with ovrError_InvalidHeadsetOrientation.\r
1682 ///\r
1683 /// For more info, see the notes on each ovrTrackingOrigin enumeration to understand how\r
1684 /// recenter will vary slightly in its behavior based on the current ovrTrackingOrigin setting.\r
1685 ///\r
1686 /// \param[in] session Specifies an ovrSession previously returned by ovr_Create.\r
1687 ///\r
1688 /// \return Returns an ovrResult indicating success or failure. In the case of failure, use\r
1689 ///         ovr_GetLastErrorInfo to get more information. Return values include but aren't limited\r
1690 ///         to:\r
1691 ///     - ovrSuccess: Completed successfully.\r
1692 ///     - ovrError_InvalidHeadsetOrientation: The headset was facing an invalid direction when\r
1693 ///       attempting recentering, such as facing vertically.\r
1694 ///\r
1695 /// \see ovrTrackingOrigin, ovr_GetTrackerPose, ovr_SpecifyTrackingOrigin\r
1696 ///\r
1697 OVR_PUBLIC_FUNCTION(ovrResult) ovr_RecenterTrackingOrigin(ovrSession session);\r
1698 \r
1699 /// Allows manually tweaking the sensor position and orientation.\r
1700 ///\r
1701 /// This function is similar to ovr_RecenterTrackingOrigin in that it modifies the\r
1702 /// (x,y,z) positional components and the yaw orientation component of the tracking space for\r
1703 /// the HMD and controllers.\r
1704 ///\r
1705 /// While ovr_RecenterTrackingOrigin resets the tracking origin in reference to the HMD's\r
1706 /// current pose, ovr_SpecifyTrackingOrigin allows the caller to explicitly specify a transform\r
1707 /// for the tracking origin. This transform is expected to be an offset to the most recent\r
1708 /// recentered origin, so calling this function repeatedly with the same originPose will keep\r
1709 /// nudging the recentered origin in that direction.\r
1710 ///\r
1711 /// There are several use cases for this function. For example, if the application decides to\r
1712 /// limit the yaw, or translation of the recentered pose instead of directly using the HMD pose\r
1713 /// the application can query the current tracking state via ovr_GetTrackingState, and apply\r
1714 /// some limitations to the HMD pose because feeding this pose back into this function.\r
1715 /// Similarly, this can be used to "adjust the seating position" incrementally in apps that\r
1716 /// feature seated experiences such as cockpit-based games.\r
1717 ///\r
1718 /// This function can emulate ovr_RecenterTrackingOrigin as such:\r
1719 ///     ovrTrackingState ts = ovr_GetTrackingState(session, 0.0, ovrFalse);\r
1720 ///     ovr_SpecifyTrackingOrigin(session, ts.HeadPose.ThePose);\r
1721 ///\r
1722 /// The roll and pitch orientation components are determined by gravity and cannot be redefined.\r
1723 /// If you are using ovrTrackerPoses then you will need to call ovr_GetTrackerPose after\r
1724 /// this, because the sensor position(s) will change as a result of this.\r
1725 ///\r
1726 /// For more info, see the notes on each ovrTrackingOrigin enumeration to understand how\r
1727 /// recenter will vary slightly in its behavior based on the current ovrTrackingOrigin setting.\r
1728 ///\r
1729 /// \param[in] session Specifies an ovrSession previously returned by ovr_Create.\r
1730 /// \param[in] originPose Specifies a pose that will be used to transform the current tracking\r
1731 /// origin.\r
1732 ///\r
1733 /// \return Returns an ovrResult indicating success or failure. In the case of failure, use\r
1734 ///         ovr_GetLastErrorInfo to get more information. Return values include but aren't limited\r
1735 ///         to:\r
1736 ///     - ovrSuccess: Completed successfully.\r
1737 ///     - ovrError_InvalidParameter: The heading direction in originPose was invalid,\r
1738 ///         such as facing vertically. This can happen if the caller is directly feeding the pose\r
1739 ///         of a position-tracked device such as an HMD or controller into this function.\r
1740 ///\r
1741 /// \see ovrTrackingOrigin, ovr_GetTrackerPose, ovr_RecenterTrackingOrigin\r
1742 ///\r
1743 OVR_PUBLIC_FUNCTION(ovrResult) ovr_SpecifyTrackingOrigin(ovrSession session, ovrPosef originPose);\r
1744 \r
1745 /// Clears the ShouldRecenter status bit in ovrSessionStatus.\r
1746 ///\r
1747 /// Clears the ShouldRecenter status bit in ovrSessionStatus, allowing further recenter requests to\r
1748 /// be detected. Since this is automatically done by ovr_RecenterTrackingOrigin and\r
1749 /// ovr_SpecifyTrackingOrigin, this function only needs to be called when application is doing\r
1750 /// its own re-centering logic.\r
1751 OVR_PUBLIC_FUNCTION(void) ovr_ClearShouldRecenterFlag(ovrSession session);\r
1752 \r
1753 /// Returns tracking state reading based on the specified absolute system time.\r
1754 ///\r
1755 /// Pass an absTime value of 0.0 to request the most recent sensor reading. In this case\r
1756 /// both PredictedPose and SamplePose will have the same value.\r
1757 ///\r
1758 /// This may also be used for more refined timing of front buffer rendering logic, and so on.\r
1759 /// This may be called by multiple threads.\r
1760 ///\r
1761 /// \param[in] session Specifies an ovrSession previously returned by ovr_Create.\r
1762 /// \param[in] absTime Specifies the absolute future time to predict the return\r
1763 ///            ovrTrackingState value. Use 0 to request the most recent tracking state.\r
1764 /// \param[in] latencyMarker Specifies that this call is the point in time where\r
1765 ///            the "App-to-Mid-Photon" latency timer starts from. If a given ovrLayer\r
1766 ///            provides "SensorSampleTime", that will override the value stored here.\r
1767 /// \return Returns the ovrTrackingState that is predicted for the given absTime.\r
1768 ///\r
1769 /// \see ovrTrackingState, ovr_GetEyePoses, ovr_GetTimeInSeconds\r
1770 ///\r
1771 OVR_PUBLIC_FUNCTION(ovrTrackingState)\r
1772 ovr_GetTrackingState(ovrSession session, double absTime, ovrBool latencyMarker);\r
1773 \r
1774 /// Returns an array of poses, where each pose matches a device type provided by the deviceTypes\r
1775 /// array parameter.  If any pose cannot be retrieved, it will return a reason for the missing\r
1776 /// pose and the device pose will be zeroed out with a pose quaternion [x=0, y=0, z=0, w=1].\r
1777 ///\r
1778 /// \param[in] session Specifies an ovrSession previously returned by ovr_Create.\r
1779 /// \param[in] deviceTypes Array of device types to query for their poses.\r
1780 /// \param[in] deviceCount Number of queried poses. This number must match the length of the\r
1781 /// outDevicePoses and deviceTypes array.\r
1782 /// \param[in] absTime Specifies the absolute future time to predict the return\r
1783 ///             ovrTrackingState value. Use 0 to request the most recent tracking state.\r
1784 /// \param[out] outDevicePoses Array of poses, one for each device type in deviceTypes arrays.\r
1785 ///\r
1786 /// \return Returns an ovrResult for which OVR_SUCCESS(result) is false upon error and\r
1787 ///         true upon success.\r
1788 ///\r
1789 OVR_PUBLIC_FUNCTION(ovrResult)\r
1790 ovr_GetDevicePoses(\r
1791     ovrSession session,\r
1792     ovrTrackedDeviceType* deviceTypes,\r
1793     int deviceCount,\r
1794     double absTime,\r
1795     ovrPoseStatef* outDevicePoses);\r
1796 \r
1797 \r
1798 /// Returns the ovrTrackerPose for the given attached tracker.\r
1799 ///\r
1800 /// \param[in] session Specifies an ovrSession previously returned by ovr_Create.\r
1801 /// \param[in] trackerPoseIndex Index of the tracker being requested.\r
1802 ///\r
1803 /// \return Returns the requested ovrTrackerPose. An empty ovrTrackerPose will be returned if\r
1804 /// trackerPoseIndex is out of range.\r
1805 ///\r
1806 /// \see ovr_GetTrackerCount\r
1807 ///\r
1808 OVR_PUBLIC_FUNCTION(ovrTrackerPose)\r
1809 ovr_GetTrackerPose(ovrSession session, unsigned int trackerPoseIndex);\r
1810 \r
1811 /// Returns the most recent input state for controllers, without positional tracking info.\r
1812 ///\r
1813 /// \param[out] inputState Input state that will be filled in.\r
1814 /// \param[in] ovrControllerType Specifies which controller the input will be returned for.\r
1815 /// \return Returns ovrSuccess if the new state was successfully obtained.\r
1816 ///\r
1817 /// \see ovrControllerType\r
1818 ///\r
1819 OVR_PUBLIC_FUNCTION(ovrResult)\r
1820 ovr_GetInputState(ovrSession session, ovrControllerType controllerType, ovrInputState* inputState);\r
1821 \r
1822 /// Returns controller types connected to the system OR'ed together.\r
1823 ///\r
1824 /// \return A bitmask of ovrControllerTypes connected to the system.\r
1825 ///\r
1826 /// \see ovrControllerType\r
1827 ///\r
1828 OVR_PUBLIC_FUNCTION(unsigned int) ovr_GetConnectedControllerTypes(ovrSession session);\r
1829 \r
1830 /// Gets information about Haptics engine for the specified Touch controller.\r
1831 ///\r
1832 /// \param[in] session Specifies an ovrSession previously returned by ovr_Create.\r
1833 /// \param[in] controllerType The controller to retrieve the information from.\r
1834 ///\r
1835 /// \return Returns an ovrTouchHapticsDesc.\r
1836 ///\r
1837 OVR_PUBLIC_FUNCTION(ovrTouchHapticsDesc)\r
1838 ovr_GetTouchHapticsDesc(ovrSession session, ovrControllerType controllerType);\r
1839 \r
1840 /// Sets constant vibration (with specified frequency and amplitude) to a controller.\r
1841 /// Note: ovr_SetControllerVibration cannot be used interchangeably with\r
1842 /// ovr_SubmitControllerVibration.\r
1843 ///\r
1844 /// This method should be called periodically, vibration lasts for a maximum of 2.5 seconds.\r
1845 ///\r
1846 /// \param[in] session Specifies an ovrSession previously returned by ovr_Create.\r
1847 /// \param[in] controllerType The controller to set the vibration to.\r
1848 /// \param[in] frequency Vibration frequency. Supported values are: 0.0 (disabled), 0.5 and 1.0. Non\r
1849 /// valid values will be clamped.\r
1850 /// \param[in] amplitude Vibration amplitude in the [0.0, 1.0] range.\r
1851 /// \return Returns an ovrResult for which OVR_SUCCESS(result) is false upon error and true\r
1852 ///         upon success. Return values include but aren't limited to:\r
1853 ///     - ovrSuccess: The call succeeded and a result was returned.\r
1854 ///     - ovrSuccess_DeviceUnavailable: The call succeeded but the device referred to by\r
1855 ///     controllerType is not available.\r
1856 ///\r
1857 OVR_PUBLIC_FUNCTION(ovrResult)\r
1858 ovr_SetControllerVibration(\r
1859     ovrSession session,\r
1860     ovrControllerType controllerType,\r
1861     float frequency,\r
1862     float amplitude);\r
1863 \r
1864 /// Submits a Haptics buffer (used for vibration) to Touch (only) controllers.\r
1865 /// Note: ovr_SubmitControllerVibration cannot be used interchangeably with\r
1866 /// ovr_SetControllerVibration.\r
1867 ///\r
1868 /// \param[in] session Specifies an ovrSession previously returned by ovr_Create.\r
1869 /// \param[in] controllerType Controller where the Haptics buffer will be played.\r
1870 /// \param[in] buffer Haptics buffer containing amplitude samples to be played.\r
1871 /// \return Returns an ovrResult for which OVR_SUCCESS(result) is false upon error and true\r
1872 ///         upon success. Return values include but aren't limited to:\r
1873 ///     - ovrSuccess: The call succeeded and a result was returned.\r
1874 ///     - ovrSuccess_DeviceUnavailable: The call succeeded but the device referred to by\r
1875 ///     controllerType is not available.\r
1876 ///\r
1877 /// \see ovrHapticsBuffer\r
1878 ///\r
1879 OVR_PUBLIC_FUNCTION(ovrResult)\r
1880 ovr_SubmitControllerVibration(\r
1881     ovrSession session,\r
1882     ovrControllerType controllerType,\r
1883     const ovrHapticsBuffer* buffer);\r
1884 \r
1885 /// Gets the Haptics engine playback state of a specific Touch controller.\r
1886 ///\r
1887 /// \param[in] session Specifies an ovrSession previously returned by ovr_Create.\r
1888 /// \param[in] controllerType Controller where the Haptics buffer wil be played.\r
1889 /// \param[in] outState State of the haptics engine.\r
1890 /// \return Returns an ovrResult for which OVR_SUCCESS(result) is false upon error and true\r
1891 ///         upon success. Return values include but aren't limited to:\r
1892 ///     - ovrSuccess: The call succeeded and a result was returned.\r
1893 ///     - ovrSuccess_DeviceUnavailable: The call succeeded but the device referred to by\r
1894 ///     controllerType is not available.\r
1895 ///\r
1896 /// \see ovrHapticsPlaybackState\r
1897 ///\r
1898 OVR_PUBLIC_FUNCTION(ovrResult)\r
1899 ovr_GetControllerVibrationState(\r
1900     ovrSession session,\r
1901     ovrControllerType controllerType,\r
1902     ovrHapticsPlaybackState* outState);\r
1903 \r
1904 /// Tests collision/proximity of position tracked devices (e.g. HMD and/or Touch) against the\r
1905 /// Boundary System.\r
1906 /// Note: this method is similar to ovr_BoundaryTestPoint but can be more precise as it may take\r
1907 /// into account device acceleration/momentum.\r
1908 ///\r
1909 /// \param[in] session Specifies an ovrSession previously returned by ovr_Create.\r
1910 /// \param[in] deviceBitmask Bitmask of one or more tracked devices to test.\r
1911 /// \param[in] boundaryType Must be either ovrBoundary_Outer or ovrBoundary_PlayArea.\r
1912 /// \param[out] outTestResult Result of collision/proximity test, contains information such as\r
1913 /// distance and closest point.\r
1914 /// \return Returns an ovrResult for which OVR_SUCCESS(result) is false upon error and true\r
1915 ///         upon success. Return values include but aren't limited to:\r
1916 ///     - ovrSuccess: The call succeeded and a result was returned.\r
1917 ///     - ovrSuccess_BoundaryInvalid: The call succeeded but the result is not a valid boundary due\r
1918 ///     to not being set up.\r
1919 ///     - ovrSuccess_DeviceUnavailable: The call succeeded but the device referred to by\r
1920 ///     deviceBitmask is not available.\r
1921 ///\r
1922 /// \see ovrBoundaryTestResult\r
1923 ///\r
1924 OVR_PUBLIC_FUNCTION(ovrResult)\r
1925 ovr_TestBoundary(\r
1926     ovrSession session,\r
1927     ovrTrackedDeviceType deviceBitmask,\r
1928     ovrBoundaryType boundaryType,\r
1929     ovrBoundaryTestResult* outTestResult);\r
1930 \r
1931 /// Tests collision/proximity of a 3D point against the Boundary System.\r
1932 ///\r
1933 /// \param[in] session Specifies an ovrSession previously returned by ovr_Create.\r
1934 /// \param[in] point 3D point to test.\r
1935 /// \param[in] singleBoundaryType Must be either ovrBoundary_Outer or ovrBoundary_PlayArea to test\r
1936 /// against\r
1937 /// \param[out] outTestResult Result of collision/proximity test, contains information such as\r
1938 /// distance and closest point.\r
1939 /// \return Returns an ovrResult for which OVR_SUCCESS(result) is false upon error and true\r
1940 ///         upon success. Return values include but aren't limited to:\r
1941 ///     - ovrSuccess: The call succeeded and a result was returned.\r
1942 ///     - ovrSuccess_BoundaryInvalid: The call succeeded but the result is not a valid boundary due\r
1943 ///     to not being set up.\r
1944 ///\r
1945 /// \see ovrBoundaryTestResult\r
1946 ///\r
1947 OVR_PUBLIC_FUNCTION(ovrResult)\r
1948 ovr_TestBoundaryPoint(\r
1949     ovrSession session,\r
1950     const ovrVector3f* point,\r
1951     ovrBoundaryType singleBoundaryType,\r
1952     ovrBoundaryTestResult* outTestResult);\r
1953 \r
1954 /// Sets the look and feel of the Boundary System.\r
1955 ///\r
1956 /// \param[in] session Specifies an ovrSession previously returned by ovr_Create.\r
1957 /// \param[in] lookAndFeel Look and feel parameters.\r
1958 /// \return Returns ovrSuccess upon success.\r
1959 /// \see ovrBoundaryLookAndFeel\r
1960 ///\r
1961 OVR_PUBLIC_FUNCTION(ovrResult)\r
1962 ovr_SetBoundaryLookAndFeel(ovrSession session, const ovrBoundaryLookAndFeel* lookAndFeel);\r
1963 \r
1964 /// Resets the look and feel of the Boundary System to its default state.\r
1965 ///\r
1966 /// \param[in] session Specifies an ovrSession previously returned by ovr_Create.\r
1967 /// \return Returns ovrSuccess upon success.\r
1968 /// \see ovrBoundaryLookAndFeel\r
1969 ///\r
1970 OVR_PUBLIC_FUNCTION(ovrResult) ovr_ResetBoundaryLookAndFeel(ovrSession session);\r
1971 \r
1972 /// Gets the geometry of the Boundary System's "play area" or "outer boundary" as 3D floor points.\r
1973 ///\r
1974 /// \param[in] session Specifies an ovrSession previously returned by ovr_Create.\r
1975 /// \param[in] boundaryType Must be either ovrBoundary_Outer or ovrBoundary_PlayArea.\r
1976 /// \param[out] outFloorPoints Array of 3D points (in clockwise order) defining the boundary at\r
1977 /// floor height (can be NULL to retrieve only the number of points).\r
1978 /// \param[out] outFloorPointsCount Number of 3D points returned in the array.\r
1979 /// \return Returns an ovrResult for which OVR_SUCCESS(result) is false upon error and true\r
1980 ///         upon success. Return values include but aren't limited to:\r
1981 ///     - ovrSuccess: The call succeeded and a result was returned.\r
1982 ///     - ovrSuccess_BoundaryInvalid: The call succeeded but the result is not a valid boundary due\r
1983 ///     to not being set up.\r
1984 ///\r
1985 OVR_PUBLIC_FUNCTION(ovrResult)\r
1986 ovr_GetBoundaryGeometry(\r
1987     ovrSession session,\r
1988     ovrBoundaryType boundaryType,\r
1989     ovrVector3f* outFloorPoints,\r
1990     int* outFloorPointsCount);\r
1991 \r
1992 /// Gets the dimension of the Boundary System's "play area" or "outer boundary".\r
1993 ///\r
1994 /// \param[in] session Specifies an ovrSession previously returned by ovr_Create.\r
1995 /// \param[in] boundaryType Must be either ovrBoundary_Outer or ovrBoundary_PlayArea.\r
1996 /// \param[out] outDimensions Dimensions of the axis aligned bounding box that encloses the area in\r
1997 /// meters (width, height and length).\r
1998 /// \return Returns an ovrResult for which OVR_SUCCESS(result) is false upon error and true\r
1999 ///         upon success. Return values include but aren't limited to:\r
2000 ///     - ovrSuccess: The call succeeded and a result was returned.\r
2001 ///     - ovrSuccess_BoundaryInvalid: The call succeeded but the result is not a valid boundary due\r
2002 ///     to not being set up.\r
2003 ///\r
2004 OVR_PUBLIC_FUNCTION(ovrResult)\r
2005 ovr_GetBoundaryDimensions(\r
2006     ovrSession session,\r
2007     ovrBoundaryType boundaryType,\r
2008     ovrVector3f* outDimensions);\r
2009 \r
2010 /// Returns if the boundary is currently visible.\r
2011 /// Note: visibility is false if the user has turned off boundaries, otherwise, it's true if\r
2012 /// the app has requested boundaries to be visible or if any tracked device is currently\r
2013 /// triggering it. This may not exactly match rendering due to fade-in and fade-out effects.\r
2014 ///\r
2015 /// \param[in] session Specifies an ovrSession previously returned by ovr_Create.\r
2016 /// \param[out] outIsVisible ovrTrue, if the boundary is visible.\r
2017 /// \return Returns an ovrResult for which OVR_SUCCESS(result) is false upon error and true\r
2018 ///         upon success. Return values include but aren't limited to:\r
2019 ///     - ovrSuccess: Result was successful and a result was returned.\r
2020 ///     - ovrSuccess_BoundaryInvalid: The call succeeded but the result is not a valid boundary due\r
2021 ///     to not being set up.\r
2022 ///\r
2023 OVR_PUBLIC_FUNCTION(ovrResult) ovr_GetBoundaryVisible(ovrSession session, ovrBool* outIsVisible);\r
2024 \r
2025 /// Requests boundary to be visible.\r
2026 ///\r
2027 /// \param[in] session Specifies an ovrSession previously returned by ovr_Create.\r
2028 /// \param[in] visible forces the outer boundary to be visible. An application can't force it\r
2029 ///            to be invisible, but can cancel its request by passing false.\r
2030 /// \return Returns ovrSuccess upon success.\r
2031 ///\r
2032 OVR_PUBLIC_FUNCTION(ovrResult) ovr_RequestBoundaryVisible(ovrSession session, ovrBool visible);\r
2033 \r
2034 // -----------------------------------------------------------------------------------\r
2035 /// @name Mixed reality capture support\r
2036 ///\r
2037 /// Defines functions used for mixed reality capture / third person cameras.\r
2038 ///\r
2039 \r
2040 /// Returns the number of camera properties of all cameras\r
2041 /// \param[in] session Specifies an ovrSession previously returned by ovr_Create.\r
2042 /// \param[in out] cameras Pointer to the array. If null and the provided array capacity is\r
2043 /// sufficient, will return ovrError_NullArrayPointer.\r
2044 /// \param[in out] inoutCameraCount Supply the\r
2045 /// array capacity, will return the actual # of cameras defined. If *inoutCameraCount is too small,\r
2046 /// will return ovrError_InsufficientArraySize.\r
2047 /// \return Returns the list of external cameras the system knows about.\r
2048 /// Returns ovrError_NoExternalCameraInfo if there is not any eternal camera information.\r
2049 OVR_PUBLIC_FUNCTION(ovrResult)\r
2050 ovr_GetExternalCameras(\r
2051     ovrSession session,\r
2052     ovrExternalCamera* cameras,\r
2053     unsigned int* inoutCameraCount);\r
2054 \r
2055 /// Sets the camera intrinsics and/or extrinsics stored for the cameraName camera\r
2056 /// Names must be < 32 characters and null-terminated.\r
2057 ///\r
2058 /// \param[in] session Specifies an ovrSession previously returned by ovr_Create.\r
2059 /// \param[in] name Specifies which camera to set the intrinsics or extrinsics for.\r
2060 /// The name must be at most OVR_EXTERNAL_CAMERA_NAME_SIZE - 1\r
2061 /// characters. Otherwise, ovrError_ExternalCameraNameWrongSize is returned.\r
2062 /// \param[in] intrinsics Contains the intrinsic parameters to set, can be null\r
2063 /// \param[in] extrinsics Contains the extrinsic parameters to set, can be null\r
2064 /// \return Returns ovrSuccess or an ovrError code\r
2065 OVR_PUBLIC_FUNCTION(ovrResult)\r
2066 ovr_SetExternalCameraProperties(\r
2067     ovrSession session,\r
2068     const char* name,\r
2069     const ovrCameraIntrinsics* const intrinsics,\r
2070     const ovrCameraExtrinsics* const extrinsics);\r
2071 \r
2072 ///@}\r
2073 \r
2074 #endif // !defined(OVR_EXPORTING_CAPI)\r
2075 \r
2076 //-------------------------------------------------------------------------------------\r
2077 // @name Layers\r
2078 //\r
2079 ///@{\r
2080 \r
2081 ///  Specifies the maximum number of layers supported by ovr_SubmitFrame.\r
2082 ///\r
2083 ///  /see ovr_SubmitFrame\r
2084 ///\r
2085 enum { ovrMaxLayerCount = 16 };\r
2086 \r
2087 /// Describes layer types that can be passed to ovr_SubmitFrame.\r
2088 /// Each layer type has an associated struct, such as ovrLayerEyeFov.\r
2089 ///\r
2090 /// \see ovrLayerHeader\r
2091 ///\r
2092 typedef enum ovrLayerType_ {\r
2093   /// Layer is disabled.\r
2094   ovrLayerType_Disabled = 0,\r
2095 \r
2096   /// Described by ovrLayerEyeFov.\r
2097   ovrLayerType_EyeFov = 1,\r
2098 \r
2099   /// Described by ovrLayerEyeFovDepth.\r
2100   ovrLayerType_EyeFovDepth = 2,\r
2101 \r
2102   /// Described by ovrLayerQuad. Previously called ovrLayerType_QuadInWorld.\r
2103   ovrLayerType_Quad = 3,\r
2104 \r
2105   // enum 4 used to be ovrLayerType_QuadHeadLocked. Instead, use ovrLayerType_Quad with\r
2106   // ovrLayerFlag_HeadLocked.\r
2107 \r
2108   /// Described by ovrLayerEyeMatrix.\r
2109   ovrLayerType_EyeMatrix = 5,\r
2110 \r
2111 \r
2112   /// Described by ovrLayerEyeFovMultires.\r
2113   ovrLayerType_EyeFovMultires = 7,\r
2114 \r
2115   /// Described by ovrLayerCylinder.\r
2116   ovrLayerType_Cylinder = 8,\r
2117 \r
2118   /// Described by ovrLayerCube\r
2119   ovrLayerType_Cube = 10,\r
2120 \r
2121 \r
2122   ovrLayerType_EnumSize = 0x7fffffff ///< Force type int32_t.\r
2123 \r
2124 } ovrLayerType;\r
2125 \r
2126 /// Identifies flags used by ovrLayerHeader and which are passed to ovr_SubmitFrame.\r
2127 ///\r
2128 /// \see ovrLayerHeader\r
2129 ///\r
2130 typedef enum ovrLayerFlags_ {\r
2131   /// ovrLayerFlag_HighQuality enables 4x anisotropic sampling during the composition of the layer.\r
2132   /// The benefits are mostly visible at the periphery for high-frequency & high-contrast visuals.\r
2133   /// For best results consider combining this flag with an ovrTextureSwapChain that has mipmaps and\r
2134   /// instead of using arbitrary sized textures, prefer texture sizes that are powers-of-two.\r
2135   /// Actual rendered viewport and doesn't necessarily have to fill the whole texture.\r
2136   ovrLayerFlag_HighQuality = 0x01,\r
2137 \r
2138   /// ovrLayerFlag_TextureOriginAtBottomLeft: the opposite is TopLeft.\r
2139   /// Generally this is false for D3D, true for OpenGL.\r
2140   ovrLayerFlag_TextureOriginAtBottomLeft = 0x02,\r
2141 \r
2142   /// Mark this surface as "headlocked", which means it is specified\r
2143   /// relative to the HMD and moves with it, rather than being specified\r
2144   /// relative to sensor/torso space and remaining still while the head moves.\r
2145   /// What used to be ovrLayerType_QuadHeadLocked is now ovrLayerType_Quad plus this flag.\r
2146   /// However the flag can be applied to any layer type to achieve a similar effect.\r
2147   ovrLayerFlag_HeadLocked = 0x04,\r
2148 \r
2149 \r
2150 } ovrLayerFlags;\r
2151 \r
2152 /// Defines properties shared by all ovrLayer structs, such as ovrLayerEyeFov.\r
2153 ///\r
2154 /// ovrLayerHeader is used as a base member in these larger structs.\r
2155 /// This struct cannot be used by itself except for the case that Type is ovrLayerType_Disabled.\r
2156 ///\r
2157 /// \see ovrLayerType, ovrLayerFlags\r
2158 ///\r
2159 typedef struct OVR_ALIGNAS(OVR_PTR_SIZE) ovrLayerHeader_ {\r
2160   ovrLayerType Type; ///< Described by ovrLayerType.\r
2161   unsigned Flags; ///< Described by ovrLayerFlags.\r
2162 } ovrLayerHeader;\r
2163 \r
2164 /// Describes a layer that specifies a monoscopic or stereoscopic view.\r
2165 /// This is the kind of layer that's typically used as layer 0 to ovr_SubmitFrame,\r
2166 /// as it is the kind of layer used to render a 3D stereoscopic view.\r
2167 ///\r
2168 /// Three options exist with respect to mono/stereo texture usage:\r
2169 ///    - ColorTexture[0] and ColorTexture[1] contain the left and right stereo renderings,\r
2170 ///      respectively.\r
2171 ///      Viewport[0] and Viewport[1] refer to ColorTexture[0] and ColorTexture[1], respectively.\r
2172 ///    - ColorTexture[0] contains both the left and right renderings, ColorTexture[1] is NULL,\r
2173 ///      and Viewport[0] and Viewport[1] refer to sub-rects with ColorTexture[0].\r
2174 ///    - ColorTexture[0] contains a single monoscopic rendering, and Viewport[0] and\r
2175 ///      Viewport[1] both refer to that rendering.\r
2176 ///\r
2177 /// \see ovrTextureSwapChain, ovr_SubmitFrame\r
2178 ///\r
2179 typedef struct OVR_ALIGNAS(OVR_PTR_SIZE) ovrLayerEyeFov_ {\r
2180   /// Header.Type must be ovrLayerType_EyeFov.\r
2181   ovrLayerHeader Header;\r
2182 \r
2183   /// ovrTextureSwapChains for the left and right eye respectively.\r
2184   /// The second one of which can be NULL for cases described above.\r
2185   ovrTextureSwapChain ColorTexture[ovrEye_Count];\r
2186 \r
2187   /// Specifies the ColorTexture sub-rect UV coordinates.\r
2188   /// Both Viewport[0] and Viewport[1] must be valid.\r
2189   ovrRecti Viewport[ovrEye_Count];\r
2190 \r
2191   /// The viewport field of view.\r
2192   ovrFovPort Fov[ovrEye_Count];\r
2193 \r
2194   /// Specifies the position and orientation of each eye view, with position specified in meters.\r
2195   /// RenderPose will typically be the value returned from ovr_CalcEyePoses,\r
2196   /// but can be different in special cases if a different head pose is used for rendering.\r
2197   ovrPosef RenderPose[ovrEye_Count];\r
2198 \r
2199   /// Specifies the timestamp when the source ovrPosef (used in calculating RenderPose)\r
2200   /// was sampled from the SDK. Typically retrieved by calling ovr_GetTimeInSeconds\r
2201   /// around the instant the application calls ovr_GetTrackingState\r
2202   /// The main purpose for this is to accurately track app tracking latency.\r
2203   double SensorSampleTime;\r
2204 \r
2205 } ovrLayerEyeFov;\r
2206 \r
2207 /// Describes a layer that specifies a monoscopic or stereoscopic view,\r
2208 /// with depth textures in addition to color textures. This is typically used to support\r
2209 /// positional time warp. This struct is the same as ovrLayerEyeFov, but with the addition\r
2210 /// of DepthTexture and ProjectionDesc.\r
2211 ///\r
2212 /// ProjectionDesc can be created using ovrTimewarpProjectionDesc_FromProjection.\r
2213 ///\r
2214 /// Three options exist with respect to mono/stereo texture usage:\r
2215 ///    - ColorTexture[0] and ColorTexture[1] contain the left and right stereo renderings,\r
2216 ///      respectively.\r
2217 ///      Viewport[0] and Viewport[1] refer to ColorTexture[0] and ColorTexture[1], respectively.\r
2218 ///    - ColorTexture[0] contains both the left and right renderings, ColorTexture[1] is NULL,\r
2219 ///      and Viewport[0] and Viewport[1] refer to sub-rects with ColorTexture[0].\r
2220 ///    - ColorTexture[0] contains a single monoscopic rendering, and Viewport[0] and\r
2221 ///      Viewport[1] both refer to that rendering.\r
2222 ///\r
2223 /// \see ovrTextureSwapChain, ovr_SubmitFrame\r
2224 ///\r
2225 typedef struct OVR_ALIGNAS(OVR_PTR_SIZE) ovrLayerEyeFovDepth_ {\r
2226   /// Header.Type must be ovrLayerType_EyeFovDepth.\r
2227   ovrLayerHeader Header;\r
2228 \r
2229   /// ovrTextureSwapChains for the left and right eye respectively.\r
2230   /// The second one of which can be NULL for cases described above.\r
2231   ovrTextureSwapChain ColorTexture[ovrEye_Count];\r
2232 \r
2233   /// Specifies the ColorTexture sub-rect UV coordinates.\r
2234   /// Both Viewport[0] and Viewport[1] must be valid.\r
2235   ovrRecti Viewport[ovrEye_Count];\r
2236 \r
2237   /// The viewport field of view.\r
2238   ovrFovPort Fov[ovrEye_Count];\r
2239 \r
2240   /// Specifies the position and orientation of each eye view, with position specified in meters.\r
2241   /// RenderPose will typically be the value returned from ovr_CalcEyePoses,\r
2242   /// but can be different in special cases if a different head pose is used for rendering.\r
2243   ovrPosef RenderPose[ovrEye_Count];\r
2244 \r
2245   /// Specifies the timestamp when the source ovrPosef (used in calculating RenderPose)\r
2246   /// was sampled from the SDK. Typically retrieved by calling ovr_GetTimeInSeconds\r
2247   /// around the instant the application calls ovr_GetTrackingState\r
2248   /// The main purpose for this is to accurately track app tracking latency.\r
2249   double SensorSampleTime;\r
2250 \r
2251   /// Depth texture for positional timewarp.\r
2252   /// Must map 1:1 to the ColorTexture.\r
2253   ovrTextureSwapChain DepthTexture[ovrEye_Count];\r
2254 \r
2255   /// Specifies how to convert DepthTexture information into meters.\r
2256   /// \see ovrTimewarpProjectionDesc_FromProjection\r
2257   ovrTimewarpProjectionDesc ProjectionDesc;\r
2258 \r
2259 } ovrLayerEyeFovDepth;\r
2260 \r
2261 /// Describes eye texture layouts. Used with ovrLayerEyeFovMultires.\r
2262 ///\r
2263 typedef enum ovrTextureLayout_ {\r
2264   ovrTextureLayout_Rectilinear = 0, ///< Regular eyeFov layer.\r
2265   ovrTextureLayout_Octilinear = 1, ///< Octilinear extension must be enabled.\r
2266   ovrTextureLayout_EnumSize = 0x7fffffff ///< Force type int32_t.\r
2267 } ovrTextureLayout;\r
2268 \r
2269 /// Multiresolution descriptor for Octilinear.\r
2270 ///\r
2271 /// Usage of this layer must be successfully enabled via ovr_EnableExtension\r
2272 /// before it can be used.\r
2273 ///\r
2274 /// \see ovrLayerEyeFovMultres\r
2275 ///\r
2276 typedef struct OVR_ALIGNAS(OVR_PTR_SIZE) ovrTextureLayoutOctilinear_ {\r
2277   // W warping\r
2278   float WarpLeft;\r
2279   float WarpRight;\r
2280   float WarpUp;\r
2281   float WarpDown;\r
2282 \r
2283   // Size of W quadrants.\r
2284   //\r
2285   // SizeLeft + SizeRight <= Viewport.Size.w\r
2286   // SizeUp   + sizeDown  <= Viewport.Size.h\r
2287   //\r
2288   // Clip space (0,0) is located at Viewport.Pos + (SizeLeft,SizeUp) where\r
2289   // Viewport is given in the layer description.\r
2290   //\r
2291   // Viewport Top left\r
2292   // +-----------------------------------------------------+\r
2293   // |                        ^                       |    |\r
2294   // |                        |                       |    |\r
2295   // |           0          SizeUp         1          |    |\r
2296   // |                        |                       |<--Portion of viewport\r
2297   // |                        |                       |   determined by sizes\r
2298   // |                        |                       |    |\r
2299   // |<--------SizeLeft-------+-------SizeRight------>|    |\r
2300   // |                        |                       |    |\r
2301   // |                        |                       |    |\r
2302   // |           2         SizeDown        3          |    |\r
2303   // |                        |                       |    |\r
2304   // |                        |                       |    |\r
2305   // |                        v                       |    |\r
2306   // +------------------------------------------------+    |\r
2307   // |                                                     |\r
2308   // +-----------------------------------------------------+\r
2309   //                                                       Viewport bottom right\r
2310   //\r
2311   // For example, when rendering quadrant 0 its scissor rectangle will be\r
2312   //\r
2313   //  Top    = 0\r
2314   //  Left   = 0\r
2315   //  Right  = SizeLeft\r
2316   //  Bottom = SizeUp\r
2317   //\r
2318   // and the scissor rectangle for quadrant 1 will be:\r
2319   //\r
2320   //  Top    = 0\r
2321   //  Left   = SizeLeft\r
2322   //  Right  = SizeLeft + SizeRight\r
2323   //  Bottom = SizeUp\r
2324   //\r
2325   float SizeLeft;\r
2326   float SizeRight;\r
2327   float SizeUp;\r
2328   float SizeDown;\r
2329 \r
2330 } ovrTextureLayoutOctilinear;\r
2331 \r
2332 /// Combines texture layout descriptors.\r
2333 ///\r
2334 typedef union OVR_ALIGNAS(OVR_PTR_SIZE) ovrTextureLayoutDesc_Union_ {\r
2335   ovrTextureLayoutOctilinear Octilinear[ovrEye_Count];\r
2336 } ovrTextureLayoutDesc_Union;\r
2337 \r
2338 /// Describes a layer that specifies a monoscopic or stereoscopic view with\r
2339 /// support for optional multiresolution textures. This struct is the same as\r
2340 /// ovrLayerEyeFov plus texture layout parameters.\r
2341 ///\r
2342 /// Three options exist with respect to mono/stereo texture usage:\r
2343 ///    - ColorTexture[0] and ColorTexture[1] contain the left and right stereo renderings,\r
2344 ///      respectively.\r
2345 ///      Viewport[0] and Viewport[1] refer to ColorTexture[0] and ColorTexture[1], respectively.\r
2346 ///    - ColorTexture[0] contains both the left and right renderings, ColorTexture[1] is NULL,\r
2347 ///      and Viewport[0] and Viewport[1] refer to sub-rects with ColorTexture[0].\r
2348 ///    - ColorTexture[0] contains a single monoscopic rendering, and Viewport[0] and\r
2349 ///      Viewport[1] both refer to that rendering.\r
2350 ///\r
2351 /// \see ovrTextureSwapChain, ovr_SubmitFrame\r
2352 ///\r
2353 typedef struct OVR_ALIGNAS(OVR_PTR_SIZE) ovrLayerEyeFovMultires_ {\r
2354   /// Header.Type must be ovrLayerType_EyeFovMultires.\r
2355   ovrLayerHeader Header;\r
2356 \r
2357   /// ovrTextureSwapChains for the left and right eye respectively.\r
2358   /// The second one of which can be NULL for cases described above.\r
2359   ovrTextureSwapChain ColorTexture[ovrEye_Count];\r
2360 \r
2361   /// Specifies the ColorTexture sub-rect UV coordinates.\r
2362   /// Both Viewport[0] and Viewport[1] must be valid.\r
2363   ovrRecti Viewport[ovrEye_Count];\r
2364 \r
2365   /// The viewport field of view.\r
2366   ovrFovPort Fov[ovrEye_Count];\r
2367 \r
2368   /// Specifies the position and orientation of each eye view, with position specified in meters.\r
2369   /// RenderPose will typically be the value returned from ovr_CalcEyePoses,\r
2370   /// but can be different in special cases if a different head pose is used for rendering.\r
2371   ovrPosef RenderPose[ovrEye_Count];\r
2372 \r
2373   /// Specifies the timestamp when the source ovrPosef (used in calculating RenderPose)\r
2374   /// was sampled from the SDK. Typically retrieved by calling ovr_GetTimeInSeconds\r
2375   /// around the instant the application calls ovr_GetTrackingState\r
2376   /// The main purpose for this is to accurately track app tracking latency.\r
2377   double SensorSampleTime;\r
2378 \r
2379   /// Specifies layout type of textures.\r
2380   ovrTextureLayout TextureLayout;\r
2381 \r
2382   /// Specifies texture layout parameters.\r
2383   ovrTextureLayoutDesc_Union TextureLayoutDesc;\r
2384 \r
2385 } ovrLayerEyeFovMultires;\r
2386 \r
2387 /// Describes a layer that specifies a monoscopic or stereoscopic view.\r
2388 /// This uses a direct 3x4 matrix to map from view space to the UV coordinates.\r
2389 /// It is essentially the same thing as ovrLayerEyeFov but using a much\r
2390 /// lower level. This is mainly to provide compatibility with specific apps.\r
2391 /// Unless the application really requires this flexibility, it is usually better\r
2392 /// to use ovrLayerEyeFov.\r
2393 ///\r
2394 /// Three options exist with respect to mono/stereo texture usage:\r
2395 ///    - ColorTexture[0] and ColorTexture[1] contain the left and right stereo renderings,\r
2396 ///      respectively.\r
2397 ///      Viewport[0] and Viewport[1] refer to ColorTexture[0] and ColorTexture[1], respectively.\r
2398 ///    - ColorTexture[0] contains both the left and right renderings, ColorTexture[1] is NULL,\r
2399 ///      and Viewport[0] and Viewport[1] refer to sub-rects with ColorTexture[0].\r
2400 ///    - ColorTexture[0] contains a single monoscopic rendering, and Viewport[0] and\r
2401 ///      Viewport[1] both refer to that rendering.\r
2402 ///\r
2403 /// \see ovrTextureSwapChain, ovr_SubmitFrame\r
2404 ///\r
2405 typedef struct OVR_ALIGNAS(OVR_PTR_SIZE) ovrLayerEyeMatrix_ {\r
2406   /// Header.Type must be ovrLayerType_EyeMatrix.\r
2407   ovrLayerHeader Header;\r
2408 \r
2409   /// ovrTextureSwapChains for the left and right eye respectively.\r
2410   /// The second one of which can be NULL for cases described above.\r
2411   ovrTextureSwapChain ColorTexture[ovrEye_Count];\r
2412 \r
2413   /// Specifies the ColorTexture sub-rect UV coordinates.\r
2414   /// Both Viewport[0] and Viewport[1] must be valid.\r
2415   ovrRecti Viewport[ovrEye_Count];\r
2416 \r
2417   /// Specifies the position and orientation of each eye view, with position specified in meters.\r
2418   /// RenderPose will typically be the value returned from ovr_CalcEyePoses,\r
2419   /// but can be different in special cases if a different head pose is used for rendering.\r
2420   ovrPosef RenderPose[ovrEye_Count];\r
2421 \r
2422   /// Specifies the mapping from a view-space vector\r
2423   /// to a UV coordinate on the textures given above.\r
2424   /// P = (x,y,z,1)*Matrix\r
2425   /// TexU  = P.x/P.z\r
2426   /// TexV  = P.y/P.z\r
2427   ovrMatrix4f Matrix[ovrEye_Count];\r
2428 \r
2429   /// Specifies the timestamp when the source ovrPosef (used in calculating RenderPose)\r
2430   /// was sampled from the SDK. Typically retrieved by calling ovr_GetTimeInSeconds\r
2431   /// around the instant the application calls ovr_GetTrackingState\r
2432   /// The main purpose for this is to accurately track app tracking latency.\r
2433   double SensorSampleTime;\r
2434 \r
2435 } ovrLayerEyeMatrix;\r
2436 \r
2437 /// Describes a layer of Quad type, which is a single quad in world or viewer space.\r
2438 /// It is used for ovrLayerType_Quad. This type of layer represents a single\r
2439 /// object placed in the world and not a stereo view of the world itself.\r
2440 ///\r
2441 /// A typical use of ovrLayerType_Quad is to draw a television screen in a room\r
2442 /// that for some reason is more convenient to draw as a layer than as part of the main\r
2443 /// view in layer 0. For example, it could implement a 3D popup GUI that is drawn at a\r
2444 /// higher resolution than layer 0 to improve fidelity of the GUI.\r
2445 ///\r
2446 /// Quad layers are visible from both sides; they are not back-face culled.\r
2447 ///\r
2448 /// \see ovrTextureSwapChain, ovr_SubmitFrame\r
2449 ///\r
2450 typedef struct OVR_ALIGNAS(OVR_PTR_SIZE) ovrLayerQuad_ {\r
2451   /// Header.Type must be ovrLayerType_Quad.\r
2452   ovrLayerHeader Header;\r
2453 \r
2454   /// Contains a single image, never with any stereo view.\r
2455   ovrTextureSwapChain ColorTexture;\r
2456 \r
2457   /// Specifies the ColorTexture sub-rect UV coordinates.\r
2458   ovrRecti Viewport;\r
2459 \r
2460   /// Specifies the orientation and position of the center point of a Quad layer type.\r
2461   /// The supplied direction is the vector perpendicular to the quad.\r
2462   /// The position is in real-world meters (not the application's virtual world,\r
2463   /// the physical world the user is in) and is relative to the "zero" position\r
2464   /// set by ovr_RecenterTrackingOrigin unless the ovrLayerFlag_HeadLocked flag is used.\r
2465   ovrPosef QuadPoseCenter;\r
2466 \r
2467   /// Width and height (respectively) of the quad in meters.\r
2468   ovrVector2f QuadSize;\r
2469 \r
2470 } ovrLayerQuad;\r
2471 \r
2472 /// Describes a layer of type ovrLayerType_Cylinder which is a single cylinder\r
2473 /// relative to the recentered origin. This type of layer represents a single\r
2474 /// object placed in the world and not a stereo view of the world itself.\r
2475 ///\r
2476 ///                -Z                                       +Y\r
2477 ///         U=0  +--+--+  U=1\r
2478 ///          +---+  |  +---+            +-----------------+  - V=0\r
2479 ///       +--+ \    |    / +--+         |                 |  |\r
2480 ///     +-+     \       /     +-+       |                 |  |\r
2481 ///    ++        \  A  /        ++      |                 |  |\r
2482 ///   ++          \---/          ++     |                 |  |\r
2483 ///   |            \ /            |     |              +X |  |\r
2484 ///   +-------------C------R------+ +X  +--------C--------+  | <--- Height\r
2485 ///       (+Y is out of screen)         |                 |  |\r
2486 ///                                     |                 |  |\r
2487 ///   R = Radius                        |                 |  |\r
2488 ///   A = Angle (0,2*Pi)                |                 |  |\r
2489 ///   C = CylinderPoseCenter            |                 |  |\r
2490 ///   U/V = UV Coordinates              +-----------------+  - V=1\r
2491 ///\r
2492 /// An identity CylinderPoseCenter places the center of the cylinder\r
2493 /// at the recentered origin unless the headlocked flag is set.\r
2494 ///\r
2495 /// Does not utilize HmdSpaceToWorldScaleInMeters. If necessary, adjust\r
2496 /// translation and radius.\r
2497 ///\r
2498 /// \note Only the interior surface of the cylinder is visible. Use cylinder\r
2499 /// layers when the user cannot leave the extents of the cylinder. Artifacts may\r
2500 /// appear when viewing the cylinder's exterior surface. Additionally, while the\r
2501 /// interface supports an Angle that ranges from [0,2*Pi] the angle should\r
2502 /// remain less than 1.9*PI to avoid artifacts where the cylinder edges\r
2503 /// converge.\r
2504 ///\r
2505 /// \see ovrTextureSwapChain, ovr_SubmitFrame\r
2506 ///\r
2507 typedef struct OVR_ALIGNAS(OVR_PTR_SIZE) ovrLayerCylinder_ {\r
2508   /// Header.Type must be ovrLayerType_Cylinder.\r
2509   ovrLayerHeader Header;\r
2510 \r
2511   /// Contains a single image, never with any stereo view.\r
2512   ovrTextureSwapChain ColorTexture;\r
2513 \r
2514   /// Specifies the ColorTexture sub-rect UV coordinates.\r
2515   ovrRecti Viewport;\r
2516 \r
2517   /// Specifies the orientation and position of the center point of a cylinder layer type.\r
2518   /// The position is in real-world meters not the application's virtual world,\r
2519   /// but the physical world the user is in. It is relative to the "zero" position\r
2520   /// set by ovr_RecenterTrackingOrigin unless the ovrLayerFlag_HeadLocked flag is used.\r
2521   ovrPosef CylinderPoseCenter;\r
2522 \r
2523   /// Radius of the cylinder in meters.\r
2524   float CylinderRadius;\r
2525 \r
2526   /// Angle in radians. Range is from 0 to 2*Pi exclusive covering the entire\r
2527   /// cylinder (see diagram and note above).\r
2528   float CylinderAngle;\r
2529 \r
2530   /// Custom aspect ratio presumably set based on 'Viewport'. Used to\r
2531   /// calculate the height of the cylinder based on the arc-length (CylinderAngle)\r
2532   /// and radius (CylinderRadius) given above. The height of the cylinder is\r
2533   /// given by: height = (CylinderRadius * CylinderAngle) / CylinderAspectRatio.\r
2534   /// Aspect ratio is width / height.\r
2535   float CylinderAspectRatio;\r
2536 \r
2537 } ovrLayerCylinder;\r
2538 \r
2539 /// Describes a layer of type ovrLayerType_Cube which is a single timewarped\r
2540 /// cubemap at infinity. When looking down the recentered origin's -Z axis, +X\r
2541 /// face is left and +Y face is up. Similarly, if headlocked the +X face is\r
2542 /// left, +Y face is up and -Z face is forward. Note that the coordinate system\r
2543 /// is left-handed.\r
2544 ///\r
2545 /// ovrLayerFlag_TextureOriginAtBottomLeft flag is not supported by ovrLayerCube.\r
2546 ///\r
2547 /// \see ovrTextureSwapChain, ovr_SubmitFrame\r
2548 ///\r
2549 typedef struct OVR_ALIGNAS(OVR_PTR_SIZE) ovrLayerCube_ {\r
2550   /// Header.Type must be ovrLayerType_Cube.\r
2551   ovrLayerHeader Header;\r
2552 \r
2553   /// Orientation of the cube.\r
2554   ovrQuatf Orientation;\r
2555 \r
2556   /// Contains a single cubemap swapchain (not a stereo pair of swapchains).\r
2557   ovrTextureSwapChain CubeMapTexture;\r
2558 } ovrLayerCube;\r
2559 \r
2560 \r
2561 \r
2562 /// Union that combines ovrLayer types in a way that allows them\r
2563 /// to be used in a polymorphic way.\r
2564 typedef union ovrLayer_Union_ {\r
2565   ovrLayerHeader Header;\r
2566   ovrLayerEyeFov EyeFov;\r
2567   ovrLayerEyeFovDepth EyeFovDepth;\r
2568   ovrLayerQuad Quad;\r
2569   ovrLayerEyeFovMultires Multires;\r
2570   ovrLayerCylinder Cylinder;\r
2571   ovrLayerCube Cube;\r
2572 } ovrLayer_Union;\r
2573 \r
2574 //@}\r
2575 \r
2576 #if !defined(OVR_EXPORTING_CAPI)\r
2577 \r
2578 /// @name SDK Distortion Rendering\r
2579 ///\r
2580 /// All of rendering functions including the configure and frame functions\r
2581 /// are not thread safe. It is OK to use ConfigureRendering on one thread and handle\r
2582 /// frames on another thread, but explicit synchronization must be done since\r
2583 /// functions that depend on configured state are not reentrant.\r
2584 ///\r
2585 /// These functions support rendering of distortion by the SDK.\r
2586 ///\r
2587 //@{\r
2588 \r
2589 /// TextureSwapChain creation is rendering API-specific.\r
2590 /// ovr_CreateTextureSwapChainDX and ovr_CreateTextureSwapChainGL can be found in the\r
2591 /// rendering API-specific headers, such as OVR_CAPI_D3D.h and OVR_CAPI_GL.h\r
2592 \r
2593 /// Gets the number of buffers in an ovrTextureSwapChain.\r
2594 ///\r
2595 /// \param[in]  session Specifies an ovrSession previously returned by ovr_Create.\r
2596 /// \param[in]  chain Specifies the ovrTextureSwapChain for which the length should be retrieved.\r
2597 /// \param[out] out_Length Returns the number of buffers in the specified chain.\r
2598 ///\r
2599 /// \return Returns an ovrResult for which OVR_SUCCESS(result) is false upon error.\r
2600 ///\r
2601 /// \see ovr_CreateTextureSwapChainDX, ovr_CreateTextureSwapChainGL\r
2602 ///\r
2603 OVR_PUBLIC_FUNCTION(ovrResult)\r
2604 ovr_GetTextureSwapChainLength(ovrSession session, ovrTextureSwapChain chain, int* out_Length);\r
2605 \r
2606 /// Gets the current index in an ovrTextureSwapChain.\r
2607 ///\r
2608 /// \param[in]  session Specifies an ovrSession previously returned by ovr_Create.\r
2609 /// \param[in]  chain Specifies the ovrTextureSwapChain for which the index should be retrieved.\r
2610 /// \param[out] out_Index Returns the current (free) index in specified chain.\r
2611 ///\r
2612 /// \return Returns an ovrResult for which OVR_SUCCESS(result) is false upon error.\r
2613 ///\r
2614 /// \see ovr_CreateTextureSwapChainDX, ovr_CreateTextureSwapChainGL\r
2615 ///\r
2616 OVR_PUBLIC_FUNCTION(ovrResult)\r
2617 ovr_GetTextureSwapChainCurrentIndex(ovrSession session, ovrTextureSwapChain chain, int* out_Index);\r
2618 \r
2619 /// Gets the description of the buffers in an ovrTextureSwapChain\r
2620 ///\r
2621 /// \param[in]  session Specifies an ovrSession previously returned by ovr_Create.\r
2622 /// \param[in]  chain Specifies the ovrTextureSwapChain for which the description\r
2623 ///                   should be retrieved.\r
2624 /// \param[out] out_Desc Returns the description of the specified chain.\r
2625 ///\r
2626 /// \return Returns an ovrResult for which OVR_SUCCESS(result) is false upon error.\r
2627 ///\r
2628 /// \see ovr_CreateTextureSwapChainDX, ovr_CreateTextureSwapChainGL\r
2629 ///\r
2630 OVR_PUBLIC_FUNCTION(ovrResult)\r
2631 ovr_GetTextureSwapChainDesc(\r
2632     ovrSession session,\r
2633     ovrTextureSwapChain chain,\r
2634     ovrTextureSwapChainDesc* out_Desc);\r
2635 \r
2636 /// Commits any pending changes to an ovrTextureSwapChain, and advances its current index\r
2637 ///\r
2638 /// \param[in]  session Specifies an ovrSession previously returned by ovr_Create.\r
2639 /// \param[in]  chain Specifies the ovrTextureSwapChain to commit.\r
2640 ///\r
2641 /// \note When Commit is called, the texture at the current index is considered ready for use by the\r
2642 /// runtime, and further writes to it should be avoided. The swap chain's current index is advanced,\r
2643 /// providing there's room in the chain. The next time the SDK dereferences this texture swap chain,\r
2644 /// it will synchronize with the app's graphics context and pick up the submitted index, opening up\r
2645 /// room in the swap chain for further commits.\r
2646 ///\r
2647 /// \return Returns an ovrResult for which OVR_SUCCESS(result) is false upon error.\r
2648 ///         Failures include but aren't limited to:\r
2649 ///     - ovrError_TextureSwapChainFull: ovr_CommitTextureSwapChain was called too many times on a\r
2650 ///         texture swapchain without calling submit to use the chain.\r
2651 ///\r
2652 /// \see ovr_CreateTextureSwapChainDX, ovr_CreateTextureSwapChainGL\r
2653 ///\r
2654 OVR_PUBLIC_FUNCTION(ovrResult)\r
2655 ovr_CommitTextureSwapChain(ovrSession session, ovrTextureSwapChain chain);\r
2656 \r
2657 /// Destroys an ovrTextureSwapChain and frees all the resources associated with it.\r
2658 ///\r
2659 /// \param[in] session Specifies an ovrSession previously returned by ovr_Create.\r
2660 /// \param[in] chain Specifies the ovrTextureSwapChain to destroy. If it is NULL then\r
2661 ///            this function has no effect.\r
2662 ///\r
2663 /// \see ovr_CreateTextureSwapChainDX, ovr_CreateTextureSwapChainGL\r
2664 ///\r
2665 OVR_PUBLIC_FUNCTION(void)\r
2666 ovr_DestroyTextureSwapChain(ovrSession session, ovrTextureSwapChain chain);\r
2667 \r
2668 /// MirrorTexture creation is rendering API-specific.\r
2669 /// ovr_CreateMirrorTextureWithOptionsDX and ovr_CreateMirrorTextureWithOptionsGL can be found in\r
2670 /// rendering API-specific headers, such as OVR_CAPI_D3D.h and OVR_CAPI_GL.h\r
2671 \r
2672 /// Destroys a mirror texture previously created by one of the mirror texture creation functions.\r
2673 ///\r
2674 /// \param[in] session Specifies an ovrSession previously returned by ovr_Create.\r
2675 /// \param[in] mirrorTexture Specifies the ovrTexture to destroy. If it is NULL then\r
2676 ///            this function has no effect.\r
2677 ///\r
2678 /// \see ovr_CreateMirrorTextureWithOptionsDX, ovr_CreateMirrorTextureWithOptionsGL\r
2679 ///\r
2680 OVR_PUBLIC_FUNCTION(void)\r
2681 ovr_DestroyMirrorTexture(ovrSession session, ovrMirrorTexture mirrorTexture);\r
2682 \r
2683 /// Calculates the recommended viewport size for rendering a given eye within the HMD\r
2684 /// with a given FOV cone.\r
2685 ///\r
2686 /// Higher FOV will generally require larger textures to maintain quality.\r
2687 /// Apps packing multiple eye views together on the same texture should ensure there are\r
2688 /// at least 8 pixels of padding between them to prevent texture filtering and chromatic\r
2689 /// aberration causing images to leak between the two eye views.\r
2690 ///\r
2691 /// \param[in] session Specifies an ovrSession previously returned by ovr_Create.\r
2692 /// \param[in] eye Specifies which eye (left or right) to calculate for.\r
2693 /// \param[in] fov Specifies the ovrFovPort to use.\r
2694 /// \param[in] pixelsPerDisplayPixel Specifies the ratio of the number of render target pixels\r
2695 ///            to display pixels at the center of distortion. 1.0 is the default value. Lower\r
2696 ///            values can improve performance, higher values give improved quality.\r
2697 ///\r
2698 /// <b>Example code</b>\r
2699 ///     \code{.cpp}\r
2700 ///         ovrHmdDesc hmdDesc = ovr_GetHmdDesc(session);\r
2701 ///         ovrSizei eyeSizeLeft  = ovr_GetFovTextureSize(session, ovrEye_Left,\r
2702 ///         hmdDesc.DefaultEyeFov[ovrEye_Left],  1.0f);\r
2703 ///         ovrSizei eyeSizeRight = ovr_GetFovTextureSize(session, ovrEye_Right,\r
2704 ///         hmdDesc.DefaultEyeFov[ovrEye_Right], 1.0f);\r
2705 ///     \endcode\r
2706 ///\r
2707 /// \return Returns the texture width and height size.\r
2708 ///\r
2709 OVR_PUBLIC_FUNCTION(ovrSizei)\r
2710 ovr_GetFovTextureSize(\r
2711     ovrSession session,\r
2712     ovrEyeType eye,\r
2713     ovrFovPort fov,\r
2714     float pixelsPerDisplayPixel);\r
2715 \r
2716 /// Computes the distortion viewport, view adjust, and other rendering parameters for\r
2717 /// the specified eye.\r
2718 ///\r
2719 /// \param[in] session Specifies an ovrSession previously returned by ovr_Create.\r
2720 /// \param[in] eyeType Specifies which eye (left or right) for which to perform calculations.\r
2721 /// \param[in] fov Specifies the ovrFovPort to use.\r
2722 ///\r
2723 /// \return Returns the computed ovrEyeRenderDesc for the given eyeType and field of view.\r
2724 ///\r
2725 /// \see ovrEyeRenderDesc\r
2726 ///\r
2727 OVR_PUBLIC_FUNCTION(ovrEyeRenderDesc)\r
2728 ovr_GetRenderDesc(ovrSession session, ovrEyeType eyeType, ovrFovPort fov);\r
2729 \r
2730 /// Waits until surfaces are available and it is time to begin rendering the frame.  Must be\r
2731 /// called before ovr_BeginFrame, but not necessarily from the same thread.\r
2732 ///\r
2733 /// \param[in] session Specifies an ovrSession previously returned by ovr_Create.\r
2734 ///\r
2735 /// \param[in] frameIndex Specifies the targeted application frame index.\r
2736 ///\r
2737 /// \return Returns an ovrResult for which OVR_SUCCESS(result) is false upon error and true\r
2738 ///         upon success. Return values include but aren't limited to:\r
2739 ///     - ovrSuccess: command completed successfully.\r
2740 ///     - ovrSuccess_NotVisible: rendering of a previous frame completed successfully but was not\r
2741 ///       displayed on the HMD, usually because another application currently has ownership of the\r
2742 ///       HMD. Applications receiving this result should stop rendering new content and call\r
2743 ///       ovr_GetSessionStatus to detect visibility.\r
2744 ///     - ovrError_DisplayLost: The session has become invalid (such as due to a device removal)\r
2745 ///       and the shared resources need to be released (ovr_DestroyTextureSwapChain), the session\r
2746 ///       needs to destroyed (ovr_Destroy) and recreated (ovr_Create), and new resources need to be\r
2747 ///       created (ovr_CreateTextureSwapChainXXX). The application's existing private graphics\r
2748 ///       resources do not need to be recreated unless the new ovr_Create call returns a different\r
2749 ///       GraphicsLuid.\r
2750 ///\r
2751 /// \see ovr_BeginFrame, ovr_EndFrame, ovr_GetSessionStatus\r
2752 ///\r
2753 OVR_PUBLIC_FUNCTION(ovrResult)\r
2754 ovr_WaitToBeginFrame(ovrSession session, long long frameIndex);\r
2755 \r
2756 /// Called from render thread before application begins rendering.  Must be called after\r
2757 /// ovr_WaitToBeginFrame and before ovr_EndFrame, but not necessarily from the same threads.\r
2758 ///\r
2759 /// \param[in] session Specifies an ovrSession previously returned by ovr_Create.\r
2760 ///\r
2761 /// \param[in] frameIndex Specifies the targeted application frame index.  It must match what was\r
2762 ///        passed to ovr_WaitToBeginFrame.\r
2763 ///\r
2764 /// \return Returns an ovrResult for which OVR_SUCCESS(result) is false upon error and true\r
2765 ///         upon success. Return values include but aren't limited to:\r
2766 ///     - ovrSuccess: command completed successfully.\r
2767 ///     - ovrError_DisplayLost: The session has become invalid (such as due to a device removal)\r
2768 ///       and the shared resources need to be released (ovr_DestroyTextureSwapChain), the session\r
2769 ///       needs to destroyed (ovr_Destroy) and recreated (ovr_Create), and new resources need to be\r
2770 ///       created (ovr_CreateTextureSwapChainXXX). The application's existing private graphics\r
2771 ///       resources do not need to be recreated unless the new ovr_Create call returns a different\r
2772 ///       GraphicsLuid.\r
2773 ///\r
2774 /// \see ovr_WaitToBeginFrame, ovr_EndFrame\r
2775 ///\r
2776 OVR_PUBLIC_FUNCTION(ovrResult)\r
2777 ovr_BeginFrame(ovrSession session, long long frameIndex);\r
2778 \r
2779 /// Called from render thread after application has finished rendering.  Must be called after\r
2780 /// ovr_BeginFrame, but not necessarily from the same thread.  Submits layers for distortion and\r
2781 /// display, which will happen asynchronously.\r
2782 ///\r
2783 /// \param[in] session Specifies an ovrSession previously returned by ovr_Create.\r
2784 ///\r
2785 /// \param[in] frameIndex Specifies the targeted application frame index.  It must match what was\r
2786 ///        passed to ovr_BeginFrame.\r
2787 ///\r
2788 /// \param[in] viewScaleDesc Provides additional information needed only if layerPtrList contains\r
2789 ///        an ovrLayerType_Quad. If NULL, a default version is used based on the current\r
2790 ///        configuration and a 1.0 world scale.\r
2791 ///\r
2792 /// \param[in] layerPtrList Specifies a list of ovrLayer pointers, which can include NULL entries to\r
2793 ///        indicate that any previously shown layer at that index is to not be displayed.\r
2794 ///        Each layer header must be a part of a layer structure such as ovrLayerEyeFov or\r
2795 ///        ovrLayerQuad, with Header.Type identifying its type. A NULL layerPtrList entry in the\r
2796 ///        array indicates the absence of the given layer.\r
2797 ///\r
2798 /// \param[in] layerCount Indicates the number of valid elements in layerPtrList. The maximum\r
2799 ///        supported layerCount is not currently specified, but may be specified in a future\r
2800 ///        version.\r
2801 ///\r
2802 /// - Layers are drawn in the order they are specified in the array, regardless of the layer type.\r
2803 ///\r
2804 /// - Layers are not remembered between successive calls to ovr_SubmitFrame. A layer must be\r
2805 ///   specified in every call to ovr_SubmitFrame or it won't be displayed.\r
2806 ///\r
2807 /// - If a layerPtrList entry that was specified in a previous call to ovr_SubmitFrame is\r
2808 ///   passed as NULL or is of type ovrLayerType_Disabled, that layer is no longer displayed.\r
2809 ///\r
2810 /// - A layerPtrList entry can be of any layer type and multiple entries of the same layer type\r
2811 ///   are allowed. No layerPtrList entry may be duplicated (i.e. the same pointer as an earlier\r
2812 ///   entry).\r
2813 ///\r
2814 /// <b>Example code</b>\r
2815 ///     \code{.cpp}\r
2816 ///         ovrLayerEyeFov  layer0;\r
2817 ///         ovrLayerQuad    layer1;\r
2818 ///           ...\r
2819 ///         ovrLayerHeader* layers[2] = { &layer0.Header, &layer1.Header };\r
2820 ///         ovrResult result = ovr_EndFrame(session, frameIndex, nullptr, layers, 2);\r
2821 ///     \endcode\r
2822 ///\r
2823 /// \return Returns an ovrResult for which OVR_SUCCESS(result) is false upon error and true\r
2824 ///         upon success. Return values include but aren't limited to:\r
2825 ///     - ovrSuccess: rendering completed successfully.\r
2826 ///     - ovrError_DisplayLost: The session has become invalid (such as due to a device removal)\r
2827 ///       and the shared resources need to be released (ovr_DestroyTextureSwapChain), the session\r
2828 ///       needs to destroyed (ovr_Destroy) and recreated (ovr_Create), and new resources need to be\r
2829 ///       created (ovr_CreateTextureSwapChainXXX). The application's existing private graphics\r
2830 ///       resources do not need to be recreated unless the new ovr_Create call returns a different\r
2831 ///       GraphicsLuid.\r
2832 ///     - ovrError_TextureSwapChainInvalid: The ovrTextureSwapChain is in an incomplete or\r
2833 ///       inconsistent state. Ensure ovr_CommitTextureSwapChain was called at least once first.\r
2834 ///\r
2835 /// \see ovr_WaitToBeginFrame, ovr_BeginFrame, ovrViewScaleDesc, ovrLayerHeader\r
2836 ///\r
2837 OVR_PUBLIC_FUNCTION(ovrResult)\r
2838 ovr_EndFrame(\r
2839     ovrSession session,\r
2840     long long frameIndex,\r
2841     const ovrViewScaleDesc* viewScaleDesc,\r
2842     ovrLayerHeader const* const* layerPtrList,\r
2843     unsigned int layerCount);\r
2844 \r
2845 /// Submits layers for distortion and display.\r
2846 ///\r
2847 /// Deprecated.  Use ovr_WaitToBeginFrame, ovr_BeginFrame, and ovr_EndFrame instead.\r
2848 ///\r
2849 /// ovr_SubmitFrame triggers distortion and processing which might happen asynchronously.\r
2850 /// The function will return when there is room in the submission queue and surfaces\r
2851 /// are available. Distortion might or might not have completed.\r
2852 ///\r
2853 /// \param[in] session Specifies an ovrSession previously returned by ovr_Create.\r
2854 ///\r
2855 /// \param[in] frameIndex Specifies the targeted application frame index, or 0 to refer to one frame\r
2856 ///        after the last time ovr_SubmitFrame was called.\r
2857 ///\r
2858 /// \param[in] viewScaleDesc Provides additional information needed only if layerPtrList contains\r
2859 ///        an ovrLayerType_Quad. If NULL, a default version is used based on the current\r
2860 ///        configuration and a 1.0 world scale.\r
2861 ///\r
2862 /// \param[in] layerPtrList Specifies a list of ovrLayer pointers, which can include NULL entries to\r
2863 ///        indicate that any previously shown layer at that index is to not be displayed.\r
2864 ///        Each layer header must be a part of a layer structure such as ovrLayerEyeFov or\r
2865 ///        ovrLayerQuad, with Header.Type identifying its type. A NULL layerPtrList entry in the\r
2866 ///        array indicates the absence of the given layer.\r
2867 ///\r
2868 /// \param[in] layerCount Indicates the number of valid elements in layerPtrList. The maximum\r
2869 ///        supported layerCount is not currently specified, but may be specified in a future\r
2870 ///        version.\r
2871 ///\r
2872 /// - Layers are drawn in the order they are specified in the array, regardless of the layer type.\r
2873 ///\r
2874 /// - Layers are not remembered between successive calls to ovr_SubmitFrame. A layer must be\r
2875 ///   specified in every call to ovr_SubmitFrame or it won't be displayed.\r
2876 ///\r
2877 /// - If a layerPtrList entry that was specified in a previous call to ovr_SubmitFrame is\r
2878 ///   passed as NULL or is of type ovrLayerType_Disabled, that layer is no longer displayed.\r
2879 ///\r
2880 /// - A layerPtrList entry can be of any layer type and multiple entries of the same layer type\r
2881 ///   are allowed. No layerPtrList entry may be duplicated (i.e. the same pointer as an earlier\r
2882 ///   entry).\r
2883 ///\r
2884 /// <b>Example code</b>\r
2885 ///     \code{.cpp}\r
2886 ///         ovrLayerEyeFov  layer0;\r
2887 ///         ovrLayerQuad    layer1;\r
2888 ///           ...\r
2889 ///         ovrLayerHeader* layers[2] = { &layer0.Header, &layer1.Header };\r
2890 ///         ovrResult result = ovr_SubmitFrame(session, frameIndex, nullptr, layers, 2);\r
2891 ///     \endcode\r
2892 ///\r
2893 /// \return Returns an ovrResult for which OVR_SUCCESS(result) is false upon error and true\r
2894 ///         upon success. Return values include but aren't limited to:\r
2895 ///     - ovrSuccess: rendering completed successfully.\r
2896 ///     - ovrSuccess_NotVisible: rendering completed successfully but was not displayed on the HMD,\r
2897 ///       usually because another application currently has ownership of the HMD. Applications\r
2898 ///       receiving this result should stop rendering new content, call ovr_GetSessionStatus\r
2899 ///       to detect visibility.\r
2900 ///     - ovrError_DisplayLost: The session has become invalid (such as due to a device removal)\r
2901 ///       and the shared resources need to be released (ovr_DestroyTextureSwapChain), the session\r
2902 ///       needs to destroyed (ovr_Destroy) and recreated (ovr_Create), and new resources need to be\r
2903 ///       created (ovr_CreateTextureSwapChainXXX). The application's existing private graphics\r
2904 ///       resources do not need to be recreated unless the new ovr_Create call returns a different\r
2905 ///       GraphicsLuid.\r
2906 ///     - ovrError_TextureSwapChainInvalid: The ovrTextureSwapChain is in an incomplete or\r
2907 ///       inconsistent state. Ensure ovr_CommitTextureSwapChain was called at least once first.\r
2908 ///\r
2909 /// \see ovr_GetPredictedDisplayTime, ovrViewScaleDesc, ovrLayerHeader, ovr_GetSessionStatus\r
2910 ///\r
2911 OVR_PUBLIC_FUNCTION(ovrResult)\r
2912 ovr_SubmitFrame(\r
2913     ovrSession session,\r
2914     long long frameIndex,\r
2915     const ovrViewScaleDesc* viewScaleDesc,\r
2916     ovrLayerHeader const* const* layerPtrList,\r
2917     unsigned int layerCount);\r
2918 ///@}\r
2919 \r
2920 #endif // !defined(OVR_EXPORTING_CAPI)\r
2921 \r
2922 //-------------------------------------------------------------------------------------\r
2923 /// @name Frame Timing\r
2924 ///\r
2925 //@{\r
2926 \r
2927 ///\r
2928 /// Contains the performance stats for a given SDK compositor frame\r
2929 ///\r
2930 /// All of the 'int' typed fields can be reset via the ovr_ResetPerfStats call.\r
2931 ///\r
2932 typedef struct OVR_ALIGNAS(4) ovrPerfStatsPerCompositorFrame_ {\r
2933   /// Vsync Frame Index - increments with each HMD vertical synchronization signal (i.e. vsync or\r
2934   /// refresh rate)\r
2935   /// If the compositor drops a frame, expect this value to increment more than 1 at a time.\r
2936   int HmdVsyncIndex;\r
2937 \r
2938   ///\r
2939   /// Application stats\r
2940   ///\r
2941 \r
2942   /// Index that increments with each successive ovr_SubmitFrame call\r
2943   int AppFrameIndex;\r
2944 \r
2945   /// If the app fails to call ovr_SubmitFrame on time, then expect this value to increment with\r
2946   /// each missed frame\r
2947   int AppDroppedFrameCount;\r
2948 \r
2949   /// Motion-to-photon latency for the application\r
2950   /// This value is calculated by either using the SensorSampleTime provided for the ovrLayerEyeFov\r
2951   /// or if that\r
2952   /// is not available, then the call to ovr_GetTrackingState which has latencyMarker set to ovrTrue\r
2953   float AppMotionToPhotonLatency;\r
2954 \r
2955   /// Amount of queue-ahead in seconds provided to the app based on performance and overlap of\r
2956   /// CPU and  GPU utilization. A value of 0.0 would mean the CPU & GPU workload is being completed\r
2957   /// in 1 frame's worth of time, while 11 ms (on the CV1) of queue ahead would indicate that the\r
2958   /// app's CPU workload for the next frame is overlapping the GPU workload for the current frame.\r
2959   float AppQueueAheadTime;\r
2960 \r
2961   /// Amount of time in seconds spent on the CPU by the app's render-thread that calls\r
2962   /// ovr_SubmitFram.  Measured as elapsed time between from when app regains control from\r
2963   /// ovr_SubmitFrame to the next time the app calls ovr_SubmitFrame.\r
2964   float AppCpuElapsedTime;\r
2965 \r
2966   /// Amount of time in seconds spent on the GPU by the app.\r
2967   /// Measured as elapsed time between each ovr_SubmitFrame call using GPU timing queries.\r
2968   float AppGpuElapsedTime;\r
2969 \r
2970   ///\r
2971   /// SDK Compositor stats\r
2972   ///\r
2973 \r
2974   /// Index that increments each time the SDK compositor completes a distortion and timewarp pass\r
2975   /// Since the compositor operates asynchronously, even if the app calls ovr_SubmitFrame too late,\r
2976   /// the compositor will kick off for each vsync.\r
2977   int CompositorFrameIndex;\r
2978 \r
2979   /// Increments each time the SDK compositor fails to complete in time\r
2980   /// This is not tied to the app's performance, but failure to complete can be related to other\r
2981   /// factors such as OS capabilities, overall available hardware cycles to execute the compositor\r
2982   /// in time and other factors outside of the app's control.\r
2983   int CompositorDroppedFrameCount;\r
2984 \r
2985   /// Motion-to-photon latency of the SDK compositor in seconds.\r
2986   /// This is the latency of timewarp which corrects the higher app latency as well as dropped app\r
2987   /// frames.\r
2988   float CompositorLatency;\r
2989 \r
2990   /// The amount of time in seconds spent on the CPU by the SDK compositor. Unless the\r
2991   /// VR app is utilizing all of the CPU cores at their peak performance, there is a good chance the\r
2992   /// compositor CPU times will not affect the app's CPU performance in a major way.\r
2993   float CompositorCpuElapsedTime;\r
2994 \r
2995   /// The amount of time in seconds spent on the GPU by the SDK compositor. Any time spent on the\r
2996   /// compositor will eat away from the available GPU time for the app.\r
2997   float CompositorGpuElapsedTime;\r
2998 \r
2999   /// The amount of time in seconds spent from the point the CPU kicks off the compositor to the\r
3000   /// point in time the compositor completes the distortion & timewarp on the GPU. In the event the\r
3001   /// GPU time is not available, expect this value to be -1.0f.\r
3002   float CompositorCpuStartToGpuEndElapsedTime;\r
3003 \r
3004   /// The amount of time in seconds left after the compositor is done on the GPU to the associated\r
3005   /// V-Sync time. In the event the GPU time is not available, expect this value to be -1.0f.\r
3006   float CompositorGpuEndToVsyncElapsedTime;\r
3007 \r
3008   ///\r
3009   /// Async Spacewarp stats (ASW)\r
3010   ///\r
3011 \r
3012   /// Will be true if ASW is active for the given frame such that the application is being forced\r
3013   /// into half the frame-rate while the compositor continues to run at full frame-rate.\r
3014   ovrBool AswIsActive;\r
3015 \r
3016   /// Increments each time ASW it activated where the app was forced in and out of\r
3017   /// half-rate rendering.\r
3018   int AswActivatedToggleCount;\r
3019 \r
3020   /// Accumulates the number of frames presented by the compositor which had extrapolated\r
3021   /// ASW frames presented.\r
3022   int AswPresentedFrameCount;\r
3023 \r
3024   /// Accumulates the number of frames that the compositor tried to present when ASW is\r
3025   /// active but failed.\r
3026   int AswFailedFrameCount;\r
3027 \r
3028 } ovrPerfStatsPerCompositorFrame;\r
3029 \r
3030 ///\r
3031 /// Maximum number of frames of performance stats provided back to the caller of ovr_GetPerfStats\r
3032 ///\r
3033 enum { ovrMaxProvidedFrameStats = 5 };\r
3034 \r
3035 ///\r
3036 /// This is a complete descriptor of the performance stats provided by the SDK\r
3037 ///\r
3038 /// \see ovr_GetPerfStats, ovrPerfStatsPerCompositorFrame\r
3039 typedef struct OVR_ALIGNAS(4) ovrPerfStats_ {\r
3040   /// FrameStatsCount will have a maximum value set by ovrMaxProvidedFrameStats\r
3041   /// If the application calls ovr_GetPerfStats at the native refresh rate of the HMD\r
3042   /// then FrameStatsCount will be 1. If the app's workload happens to force\r
3043   /// ovr_GetPerfStats to be called at a lower rate, then FrameStatsCount will be 2 or more.\r
3044   /// If the app does not want to miss any performance data for any frame, it needs to\r
3045   /// ensure that it is calling ovr_SubmitFrame and ovr_GetPerfStats at a rate that is at least:\r
3046   /// "HMD_refresh_rate / ovrMaxProvidedFrameStats". On the Oculus Rift CV1 HMD, this will\r
3047   /// be equal to 18 times per second.\r
3048   ///\r
3049   /// The performance entries will be ordered in reverse chronological order such that the\r
3050   /// first entry will be the most recent one.\r
3051   ovrPerfStatsPerCompositorFrame FrameStats[ovrMaxProvidedFrameStats];\r
3052   int FrameStatsCount;\r
3053 \r
3054   /// If the app calls ovr_GetPerfStats at less than 18 fps for CV1, then AnyFrameStatsDropped\r
3055   /// will be ovrTrue and FrameStatsCount will be equal to ovrMaxProvidedFrameStats.\r
3056   ovrBool AnyFrameStatsDropped;\r
3057 \r
3058   /// AdaptiveGpuPerformanceScale is an edge-filtered value that a caller can use to adjust\r
3059   /// the graphics quality of the application to keep the GPU utilization in check. The value\r
3060   /// is calculated as: (desired_GPU_utilization / current_GPU_utilization)\r
3061   /// As such, when this value is 1.0, the GPU is doing the right amount of work for the app.\r
3062   /// Lower values mean the app needs to pull back on the GPU utilization.\r
3063   /// If the app is going to directly drive render-target resolution using this value, then\r
3064   /// be sure to take the square-root of the value before scaling the resolution with it.\r
3065   /// Changing render target resolutions however is one of the many things an app can do\r
3066   /// increase or decrease the amount of GPU utilization.\r
3067   /// Since AdaptiveGpuPerformanceScale is edge-filtered and does not change rapidly\r
3068   /// (i.e. reports non-1.0 values once every couple of seconds) the app can make the\r
3069   /// necessary adjustments and then keep watching the value to see if it has been satisfied.\r
3070   float AdaptiveGpuPerformanceScale;\r
3071 \r
3072   /// Will be true if Async Spacewarp (ASW) is available for this system which is dependent on\r
3073   /// several factors such as choice of GPU, OS and debug overrides\r
3074   ovrBool AswIsAvailable;\r
3075 \r
3076   /// Contains the Process ID of the VR application the stats are being polled for\r
3077   /// If an app continues to grab perf stats even when it is not visible, then expect this\r
3078   /// value to point to the other VR app that has grabbed focus (i.e. became visible)\r
3079   ovrProcessId VisibleProcessId;\r
3080 } ovrPerfStats;\r
3081 \r
3082 #if !defined(OVR_EXPORTING_CAPI)\r
3083 \r
3084 /// Retrieves performance stats for the VR app as well as the SDK compositor.\r
3085 ///\r
3086 /// This function will return stats for the VR app that is currently visible in the HMD\r
3087 /// regardless of what VR app is actually calling this function.\r
3088 ///\r
3089 /// If the VR app is trying to make sure the stats returned belong to the same application,\r
3090 /// the caller can compare the VisibleProcessId with their own process ID. Normally this will\r
3091 /// be the case if the caller is only calling ovr_GetPerfStats when ovr_GetSessionStatus has\r
3092 /// IsVisible flag set to be true.\r
3093 ///\r
3094 /// If the VR app calling ovr_GetPerfStats is actually the one visible in the HMD,\r
3095 /// then new perf stats will only be populated after a new call to ovr_SubmitFrame.\r
3096 /// That means subsequent calls to ovr_GetPerfStats after the first one without calling\r
3097 /// ovr_SubmitFrame will receive a FrameStatsCount of zero.\r
3098 ///\r
3099 /// If the VR app is not visible, or was initially marked as ovrInit_Invisible, then each call\r
3100 /// to ovr_GetPerfStats will immediately fetch new perf stats from the compositor without\r
3101 /// a need for the ovr_SubmitFrame call.\r
3102 ///\r
3103 /// Even though invisible VR apps do not require ovr_SubmitFrame to be called to gather new\r
3104 /// perf stats, since stats are generated at the native refresh rate of the HMD (i.e. 90 Hz\r
3105 /// for CV1), calling it at a higher rate than that would be unnecessary.\r
3106 ///\r
3107 /// \param[in] session Specifies an ovrSession previously returned by ovr_Create.\r
3108 /// \param[out] outStats Contains the performance stats for the application and SDK compositor\r
3109 /// \return Returns an ovrResult for which OVR_SUCCESS(result) is false upon error and true\r
3110 ///         upon success.\r
3111 ///\r
3112 /// \see ovrPerfStats, ovrPerfStatsPerCompositorFrame, ovr_ResetPerfStats\r
3113 ///\r
3114 OVR_PUBLIC_FUNCTION(ovrResult) ovr_GetPerfStats(ovrSession session, ovrPerfStats* outStats);\r
3115 \r
3116 /// Resets the accumulated stats reported in each ovrPerfStatsPerCompositorFrame back to zero.\r
3117 ///\r
3118 /// Only the integer values such as HmdVsyncIndex, AppDroppedFrameCount etc. will be reset\r
3119 /// as the other fields such as AppMotionToPhotonLatency are independent timing values updated\r
3120 /// per-frame.\r
3121 ///\r
3122 /// \param[in] session Specifies an ovrSession previously returned by ovr_Create.\r
3123 /// \return Returns an ovrResult for which OVR_SUCCESS(result) is false upon error and true\r
3124 ///         upon success.\r
3125 ///\r
3126 /// \see ovrPerfStats, ovrPerfStatsPerCompositorFrame, ovr_GetPerfStats\r
3127 ///\r
3128 OVR_PUBLIC_FUNCTION(ovrResult) ovr_ResetPerfStats(ovrSession session);\r
3129 \r
3130 /// Gets the time of the specified frame midpoint.\r
3131 ///\r
3132 /// Predicts the time at which the given frame will be displayed. The predicted time\r
3133 /// is the middle of the time period during which the corresponding eye images will\r
3134 /// be displayed.\r
3135 ///\r
3136 /// The application should increment frameIndex for each successively targeted frame,\r
3137 /// and pass that index to any relevant OVR functions that need to apply to the frame\r
3138 /// identified by that index.\r
3139 ///\r
3140 /// This function is thread-safe and allows for multiple application threads to target\r
3141 /// their processing to the same displayed frame.\r
3142 ///\r
3143 /// In the even that prediction fails due to various reasons (e.g. the display being off\r
3144 /// or app has yet to present any frames), the return value will be current CPU time.\r
3145 ///\r
3146 /// \param[in] session Specifies an ovrSession previously returned by ovr_Create.\r
3147 /// \param[in] frameIndex Identifies the frame the caller wishes to target.\r
3148 ///            A value of zero returns the next frame index.\r
3149 /// \return Returns the absolute frame midpoint time for the given frameIndex.\r
3150 /// \see ovr_GetTimeInSeconds\r
3151 ///\r
3152 OVR_PUBLIC_FUNCTION(double) ovr_GetPredictedDisplayTime(ovrSession session, long long frameIndex);\r
3153 \r
3154 /// Returns global, absolute high-resolution time in seconds.\r
3155 ///\r
3156 /// The time frame of reference for this function is not specified and should not be\r
3157 /// depended upon.\r
3158 ///\r
3159 /// \return Returns seconds as a floating point value.\r
3160 /// \see ovrPoseStatef, ovrFrameTiming\r
3161 ///\r
3162 OVR_PUBLIC_FUNCTION(double) ovr_GetTimeInSeconds();\r
3163 \r
3164 #endif // !defined(OVR_EXPORTING_CAPI)\r
3165 \r
3166 /// Performance HUD enables the HMD user to see information critical to\r
3167 /// the real-time operation of the VR application such as latency timing,\r
3168 /// and CPU & GPU performance metrics\r
3169 ///\r
3170 ///     App can toggle performance HUD modes as such:\r
3171 ///     \code{.cpp}\r
3172 ///         ovrPerfHudMode PerfHudMode = ovrPerfHud_LatencyTiming;\r
3173 ///         ovr_SetInt(session, OVR_PERF_HUD_MODE, (int)PerfHudMode);\r
3174 ///     \endcode\r
3175 ///\r
3176 typedef enum ovrPerfHudMode_ {\r
3177   ovrPerfHud_Off = 0, ///< Turns off the performance HUD\r
3178   ovrPerfHud_PerfSummary = 1, ///< Shows performance summary and headroom\r
3179   ovrPerfHud_LatencyTiming = 2, ///< Shows latency related timing info\r
3180   ovrPerfHud_AppRenderTiming = 3, ///< Shows render timing info for application\r
3181   ovrPerfHud_CompRenderTiming = 4, ///< Shows render timing info for OVR compositor\r
3182   ovrPerfHud_AswStats = 6, ///< Shows Async Spacewarp-specific info\r
3183   ovrPerfHud_VersionInfo = 5, ///< Shows SDK & HMD version Info\r
3184   ovrPerfHud_Count = 7, ///< \internal Count of enumerated elements.\r
3185   ovrPerfHud_EnumSize = 0x7fffffff ///< \internal Force type int32_t.\r
3186 } ovrPerfHudMode;\r
3187 \r
3188 /// Layer HUD enables the HMD user to see information about a layer\r
3189 ///\r
3190 ///     App can toggle layer HUD modes as such:\r
3191 ///     \code{.cpp}\r
3192 ///         ovrLayerHudMode LayerHudMode = ovrLayerHud_Info;\r
3193 ///         ovr_SetInt(session, OVR_LAYER_HUD_MODE, (int)LayerHudMode);\r
3194 ///     \endcode\r
3195 ///\r
3196 typedef enum ovrLayerHudMode_ {\r
3197   ovrLayerHud_Off = 0, ///< Turns off the layer HUD\r
3198   ovrLayerHud_Info = 1, ///< Shows info about a specific layer\r
3199   ovrLayerHud_EnumSize = 0x7fffffff\r
3200 } ovrLayerHudMode;\r
3201 \r
3202 ///@}\r
3203 \r
3204 /// Debug HUD is provided to help developers gauge and debug the fidelity of their app's\r
3205 /// stereo rendering characteristics. Using the provided quad and crosshair guides,\r
3206 /// the developer can verify various aspects such as VR tracking units (e.g. meters),\r
3207 /// stereo camera-parallax properties (e.g. making sure objects at infinity are rendered\r
3208 /// with the proper separation), measuring VR geometry sizes and distances and more.\r
3209 ///\r
3210 ///     App can toggle the debug HUD modes as such:\r
3211 ///     \code{.cpp}\r
3212 ///         ovrDebugHudStereoMode DebugHudMode = ovrDebugHudStereo_QuadWithCrosshair;\r
3213 ///         ovr_SetInt(session, OVR_DEBUG_HUD_STEREO_MODE, (int)DebugHudMode);\r
3214 ///     \endcode\r
3215 ///\r
3216 /// The app can modify the visual properties of the stereo guide (i.e. quad, crosshair)\r
3217 /// using the ovr_SetFloatArray function. For a list of tweakable properties,\r
3218 /// see the OVR_DEBUG_HUD_STEREO_GUIDE_* keys in the OVR_CAPI_Keys.h header file.\r
3219 typedef enum ovrDebugHudStereoMode_ {\r
3220   /// Turns off the Stereo Debug HUD.\r
3221   ovrDebugHudStereo_Off = 0,\r
3222 \r
3223   /// Renders Quad in world for Stereo Debugging.\r
3224   ovrDebugHudStereo_Quad = 1,\r
3225 \r
3226   /// Renders Quad+crosshair in world for Stereo Debugging\r
3227   ovrDebugHudStereo_QuadWithCrosshair = 2,\r
3228 \r
3229   /// Renders screen-space crosshair at infinity for Stereo Debugging\r
3230   ovrDebugHudStereo_CrosshairAtInfinity = 3,\r
3231 \r
3232   /// \internal Count of enumerated elements\r
3233   ovrDebugHudStereo_Count,\r
3234 \r
3235   ovrDebugHudStereo_EnumSize = 0x7fffffff ///< \internal Force type int32_t\r
3236 } ovrDebugHudStereoMode;\r
3237 \r
3238 #if !defined(OVR_EXPORTING_CAPI)\r
3239 \r
3240 // -----------------------------------------------------------------------------------\r
3241 /// @name Property Access\r
3242 ///\r
3243 /// These functions read and write OVR properties. Supported properties\r
3244 /// are defined in OVR_CAPI_Keys.h\r
3245 ///\r
3246 //@{\r
3247 \r
3248 /// Reads a boolean property.\r
3249 ///\r
3250 /// \param[in] session Specifies an ovrSession previously returned by ovr_Create.\r
3251 /// \param[in] propertyName The name of the property, which needs to be valid for only the call.\r
3252 /// \param[in] defaultVal specifes the value to return if the property couldn't be read.\r
3253 /// \return Returns the property interpreted as a boolean value. Returns defaultVal if\r
3254 ///         the property doesn't exist.\r
3255 OVR_PUBLIC_FUNCTION(ovrBool)\r
3256 ovr_GetBool(ovrSession session, const char* propertyName, ovrBool defaultVal);\r
3257 \r
3258 /// Writes or creates a boolean property.\r
3259 /// If the property wasn't previously a boolean property, it is changed to a boolean property.\r
3260 ///\r
3261 /// \param[in] session Specifies an ovrSession previously returned by ovr_Create.\r
3262 /// \param[in] propertyName The name of the property, which needs to be valid only for the call.\r
3263 /// \param[in] value The value to write.\r
3264 /// \return Returns true if successful, otherwise false. A false result should only occur if the\r
3265 /// property\r
3266 ///         name is empty or if the property is read-only.\r
3267 OVR_PUBLIC_FUNCTION(ovrBool)\r
3268 ovr_SetBool(ovrSession session, const char* propertyName, ovrBool value);\r
3269 \r
3270 /// Reads an integer property.\r
3271 ///\r
3272 /// \param[in] session Specifies an ovrSession previously returned by ovr_Create.\r
3273 /// \param[in] propertyName The name of the property, which needs to be valid only for the call.\r
3274 /// \param[in] defaultVal Specifes the value to return if the property couldn't be read.\r
3275 /// \return Returns the property interpreted as an integer value. Returns defaultVal if\r
3276 ///         the property doesn't exist.\r
3277 OVR_PUBLIC_FUNCTION(int) ovr_GetInt(ovrSession session, const char* propertyName, int defaultVal);\r
3278 \r
3279 /// Writes or creates an integer property.\r
3280 ///\r
3281 /// If the property wasn't previously a boolean property, it is changed to an integer property.\r
3282 ///\r
3283 /// \param[in] session Specifies an ovrSession previously returned by ovr_Create.\r
3284 /// \param[in] propertyName The name of the property, which needs to be valid only for the call.\r
3285 /// \param[in] value The value to write.\r
3286 /// \return Returns true if successful, otherwise false. A false result should only occur if the\r
3287 ///         property name is empty or if the property is read-only.\r
3288 OVR_PUBLIC_FUNCTION(ovrBool) ovr_SetInt(ovrSession session, const char* propertyName, int value);\r
3289 \r
3290 /// Reads a float property.\r
3291 ///\r
3292 /// \param[in] session Specifies an ovrSession previously returned by ovr_Create.\r
3293 /// \param[in] propertyName The name of the property, which needs to be valid only for the call.\r
3294 /// \param[in] defaultVal specifes the value to return if the property couldn't be read.\r
3295 /// \return Returns the property interpreted as an float value. Returns defaultVal if\r
3296 ///         the property doesn't exist.\r
3297 OVR_PUBLIC_FUNCTION(float)\r
3298 ovr_GetFloat(ovrSession session, const char* propertyName, float defaultVal);\r
3299 \r
3300 /// Writes or creates a float property.\r
3301 /// If the property wasn't previously a float property, it's changed to a float property.\r
3302 ///\r
3303 /// \param[in] session Specifies an ovrSession previously returned by ovr_Create.\r
3304 /// \param[in] propertyName The name of the property, which needs to be valid only for the call.\r
3305 /// \param[in] value The value to write.\r
3306 /// \return Returns true if successful, otherwise false. A false result should only occur if the\r
3307 ///         property name is empty or if the property is read-only.\r
3308 OVR_PUBLIC_FUNCTION(ovrBool)\r
3309 ovr_SetFloat(ovrSession session, const char* propertyName, float value);\r
3310 \r
3311 /// Reads a float array property.\r
3312 ///\r
3313 /// \param[in] session Specifies an ovrSession previously returned by ovr_Create.\r
3314 /// \param[in] propertyName The name of the property, which needs to be valid only for the call.\r
3315 /// \param[in] values An array of float to write to.\r
3316 /// \param[in] valuesCapacity Specifies the maximum number of elements to write to the values array.\r
3317 /// \return Returns the number of elements read, or 0 if property doesn't exist or is empty.\r
3318 OVR_PUBLIC_FUNCTION(unsigned int)\r
3319 ovr_GetFloatArray(\r
3320     ovrSession session,\r
3321     const char* propertyName,\r
3322     float values[],\r
3323     unsigned int valuesCapacity);\r
3324 \r
3325 /// Writes or creates a float array property.\r
3326 ///\r
3327 /// \param[in] session Specifies an ovrSession previously returned by ovr_Create.\r
3328 /// \param[in] propertyName The name of the property, which needs to be valid only for the call.\r
3329 /// \param[in] values An array of float to write from.\r
3330 /// \param[in] valuesSize Specifies the number of elements to write.\r
3331 /// \return Returns true if successful, otherwise false. A false result should only occur if the\r
3332 ///         property name is empty or if the property is read-only.\r
3333 OVR_PUBLIC_FUNCTION(ovrBool)\r
3334 ovr_SetFloatArray(\r
3335     ovrSession session,\r
3336     const char* propertyName,\r
3337     const float values[],\r
3338     unsigned int valuesSize);\r
3339 \r
3340 /// Reads a string property.\r
3341 /// Strings are UTF8-encoded and null-terminated.\r
3342 ///\r
3343 /// \param[in] session Specifies an ovrSession previously returned by ovr_Create.\r
3344 /// \param[in] propertyName The name of the property, which needs to be valid only for the call.\r
3345 /// \param[in] defaultVal Specifes the value to return if the property couldn't be read.\r
3346 /// \return Returns the string property if it exists. Otherwise returns defaultVal, which can be\r
3347 ///         specified as NULL. The return memory is guaranteed to be valid until next call to\r
3348 ///         ovr_GetString or until the session is destroyed, whichever occurs first.\r
3349 OVR_PUBLIC_FUNCTION(const char*)\r
3350 ovr_GetString(ovrSession session, const char* propertyName, const char* defaultVal);\r
3351 \r
3352 /// Writes or creates a string property.\r
3353 /// Strings are UTF8-encoded and null-terminated.\r
3354 ///\r
3355 /// \param[in] session Specifies an ovrSession previously returned by ovr_Create.\r
3356 /// \param[in] propertyName The name of the property, which needs to be valid only for the call.\r
3357 /// \param[in] value The string property, which only needs to be valid for the duration of the call.\r
3358 /// \return Returns true if successful, otherwise false. A false result should only occur if the\r
3359 ///         property name is empty or if the property is read-only.\r
3360 OVR_PUBLIC_FUNCTION(ovrBool)\r
3361 ovr_SetString(ovrSession session, const char* propertyName, const char* value);\r
3362 \r
3363 ///@}\r
3364 \r
3365 #endif // !defined(OVR_EXPORTING_CAPI)\r
3366 \r
3367 #ifdef __cplusplus\r
3368 } // extern "C"\r
3369 #endif\r
3370 \r
3371 #if defined(_MSC_VER)\r
3372 #pragma warning(pop)\r
3373 #endif\r
3374 \r
3375 /// @cond DoxygenIgnore\r
3376 \r
3377 \r
3378 OVR_STATIC_ASSERT(\r
3379     sizeof(ovrTextureSwapChainDesc) == 10 * 4,\r
3380     "ovrTextureSwapChainDesc size mismatch");\r
3381 \r
3382 // -----------------------------------------------------------------------------------\r
3383 // ***** Backward compatibility #includes\r
3384 //\r
3385 // This is at the bottom of this file because the following is dependent on the\r
3386 // declarations above.\r
3387 \r
3388 #if !defined(OVR_CAPI_NO_UTILS)\r
3389 #include "Extras/OVR_CAPI_Util.h"\r
3390 #endif\r
3391 \r
3392 /// @endcond\r
3393 \r
3394 #endif // OVR_CAPI_h\r