Version 1.24
[libovr-mingw-w64-jolly.git] / 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&