1 /************************************************************************************
\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
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
12 #include "OVR_CAPI_Keys.h"
\r
13 #include "OVR_Version.h"
\r
14 #include "OVR_ErrorCode.h"
\r
16 #if !defined(_WIN32)
\r
17 #include <sys/types.h>
\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
30 //-----------------------------------------------------------------------------------
\r
33 #if !defined(OVR_OS_WIN32) && defined(_WIN32)
\r
34 #define OVR_OS_WIN32
\r
37 #if !defined(OVR_OS_MAC) && defined(__APPLE__)
\r
41 #if !defined(OVR_OS_LINUX) && defined(__linux__)
\r
42 #define OVR_OS_LINUX
\r
45 //-----------------------------------------------------------------------------------
\r
48 #if !defined(OVR_CPP)
\r
49 #if defined(__cplusplus)
\r
50 #define OVR_CPP(x) x
\r
52 #define OVR_CPP(x) /* Not C++ */
\r
56 //-----------------------------------------------------------------------------------
\r
59 /// LibOVR calling convention for 32-bit Windows builds.
\r
61 #if !defined(OVR_CDECL)
\r
63 #define OVR_CDECL __cdecl
\r
69 //-----------------------------------------------------------------------------------
\r
70 // ***** OVR_EXTERN_C
\r
72 /// Defined as extern "C" when built from C++ code.
\r
74 #if !defined(OVR_EXTERN_C)
\r
76 #define OVR_EXTERN_C extern "C"
\r
78 #define OVR_EXTERN_C
\r
82 //-----------------------------------------------------------------------------------
\r
83 // ***** OVR_PUBLIC_FUNCTION / OVR_PRIVATE_FUNCTION
\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
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
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
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
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
119 #define OVR_PUBLIC_FUNCTION(rval) OVR_EXTERN_C rval OVR_CDECL
\r
120 #define OVR_PUBLIC_CLASS
\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
132 //-----------------------------------------------------------------------------------
\r
133 // ***** OVR_EXPORT
\r
135 /// Provided for backward compatibility with older versions of this library.
\r
137 #if !defined(OVR_EXPORT)
\r
138 #ifdef OVR_OS_WIN32
\r
139 #define OVR_EXPORT __declspec(dllexport)
\r
145 //-----------------------------------------------------------------------------------
\r
146 // ***** OVR_ALIGNAS
\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
156 #error Need to define OVR_ALIGNAS
\r
160 //-----------------------------------------------------------------------------------
\r
161 // ***** OVR_CC_HAS_FEATURE
\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
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
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
177 #define OVR_CC_HAS_FEATURE(x) 0
\r
181 // ------------------------------------------------------------------------
\r
182 // ***** OVR_STATIC_ASSERT
\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
189 // OVR_STATIC_ASSERT(sizeof(int32_t) == 4, "int32_t expected to be 4 bytes.");
\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
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
202 #define OVR_SA_UNUSED
\r
204 #define OVR_SA_PASTE(a, b) a##b
\r
205 #define OVR_SA_HELP(a, b) OVR_SA_PASTE(a, b)
\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
212 #define OVR_STATIC_ASSERT(expression, msg) \
\r
213 typedef char OVR_SA_HELP(staticAssert, __LINE__)[((expression) != 0) ? 1 : -1] OVR_SA_UNUSED
\r
217 #define OVR_STATIC_ASSERT(expression, msg) static_assert(expression, msg)
\r
221 //-----------------------------------------------------------------------------------
\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
228 #if !defined(OVR_UNUSED_STRUCT_PAD)
\r
229 #define OVR_UNUSED_STRUCT_PAD(padName, size) char padName[size];
\r
232 //-----------------------------------------------------------------------------------
\r
235 /// Specifies the size of a pointer on the given platform.
\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
246 #define OVR_PTR_SIZE 4
\r
250 //-----------------------------------------------------------------------------------
\r
251 // ***** OVR_ON32 / OVR_ON64
\r
253 #if OVR_PTR_SIZE == 8
\r
254 #define OVR_ON32(x)
\r
255 #define OVR_ON64(x) x
\r
257 #define OVR_ON32(x) x
\r
258 #define OVR_ON64(x)
\r
261 //-----------------------------------------------------------------------------------
\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
268 //-----------------------------------------------------------------------------------
\r
269 // ***** Simple Math Structures
\r
271 /// A RGBA color with normalized float components.
\r
272 typedef struct OVR_ALIGNAS(4) ovrColorf_ {
\r
276 /// A 2D vector with integer components.
\r
277 typedef struct OVR_ALIGNAS(4) ovrVector2i_ {
\r
281 /// A 2D size with integer components.
\r
282 typedef struct OVR_ALIGNAS(4) ovrSizei_ {
\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
293 /// A quaternion rotation.
\r
294 typedef struct OVR_ALIGNAS(4) ovrQuatf_ {
\r
298 /// A 2D vector with float components.
\r
299 typedef struct OVR_ALIGNAS(4) ovrVector2f_ {
\r
303 /// A 3D vector with float components.
\r
304 typedef struct OVR_ALIGNAS(4) ovrVector3f_ {
\r
308 /// A 4x4 matrix with float elements.
\r
309 typedef struct OVR_ALIGNAS(4) ovrMatrix4f_ {
\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
320 /// A full pose (rigid body) configuration with first and second derivatives.
\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
335 /// Describes the up, down, left, and right angles of the field of view.
\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
347 //-----------------------------------------------------------------------------------
\r
350 /// Enumerates all HMD types that we support.
\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
361 ovrHmd_E3_2015 = 10,
\r
367 ovrHmd_EnumSize = 0x7fffffff ///< \internal Force type int32_t.
\r
370 /// HMD capability bits reported by device.
\r
372 typedef enum ovrHmdCaps_ {
\r
375 /// <B>(read only)</B> Specifies that the HMD is a virtual debug device.
\r
376 ovrHmdCap_DebugDevice = 0x0010,
\r
379 ovrHmdCap_EnumSize = 0x7fffffff ///< \internal Force type int32_t.
\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
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
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
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
422 ovrTrackingOrigin_EyeLevel = 0,
\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
434 ovrTrackingOrigin_Count = 2, ///< \internal Count of enumerated elements.
\r
435 ovrTrackingOrigin_EnumSize = 0x7fffffff ///< \internal Force type int32_t.
\r
436 } ovrTrackingOrigin;
\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
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
467 /// Used as an opaque pointer to an OVR session.
\r
468 typedef struct ovrHmdStruct* ovrSession;
\r
470 #ifdef OVR_OS_WIN32
\r
471 typedef uint32_t ovrProcessId;
\r
473 typedef pid_t ovrProcessId;
\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
485 #define VK_DEFINE_NON_DISPATCHABLE_HANDLE(object) typedef uint64_t object;
\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
494 /// Bit flags describing the current status of sensor tracking.
\r
495 /// The values must be the same as in enum StatusBits
\r
497 /// \see ovrTrackingState
\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
505 /// Specifies the description of a single sensor.
\r
507 /// \see ovr_GetTrackerDesc
\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
516 /// Specifies sensor flags.
\r
518 /// /see ovrTrackerPose
\r
520 typedef enum ovrTrackerFlags_ {
\r
521 /// The sensor is present, else the sensor is absent or offline.
\r
522 ovrTracker_Connected = 0x0020,
\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
529 /// Specifies the pose for a single sensor.
\r
531 typedef struct OVR_ALIGNAS(8) _ovrTrackerPose {
\r
532 /// ovrTrackerFlags.
\r
533 unsigned int TrackerFlags;
\r
535 /// The sensor's pose. This pose includes sensor tilt (roll and pitch).
\r
536 /// For a leveled coordinate system use LeveledPose.
\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
544 OVR_UNUSED_STRUCT_PAD(pad0, 4) ///< \internal struct pad.
\r
547 /// Tracking state at a given absolute time (describes predicted HMD pose, etc.).
\r
548 /// Returned by ovr_GetTrackingState.
\r
550 /// \see ovr_GetTrackingState
\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
556 /// HeadPose tracking status described by ovrStatusBits.
\r
557 unsigned int StatusFlags;
\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
564 /// HandPoses status flags described by ovrStatusBits.
\r
565 /// Only ovrStatus_OrientationTracked and ovrStatus_PositionTracked are reported.
\r
566 unsigned int HandStatusFlags[2];
\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
577 } ovrTrackingState;
\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
586 /// \see ovr_GetRenderDesc
\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
596 /// Projection information for ovrLayerEyeFovDepth.
\r
598 /// Use the utility function ovrTimewarpProjectionDesc_FromProjection to
\r
599 /// generate this structure from the application's projection matrix.
\r
601 /// \see ovrLayerEyeFovDepth, ovrTimewarpProjectionDesc_FromProjection
\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
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
622 /// \see ovrEyeRenderDesc, ovr_SubmitFrame
\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
629 //-----------------------------------------------------------------------------------
\r
630 // ***** Platform-independent Rendering Configuration
\r
632 /// The type of texture resource.
\r
634 /// \see ovrTextureSwapChainDesc
\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
641 ovrTexture_EnumSize = 0x7fffffff ///< \internal Force type int32_t.
\r
644 /// The bindings required for texture swap chain.
\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
649 /// \see ovrTextureSwapChainDesc
\r
651 typedef enum ovrTextureBindFlags_ {
\r
652 ovrTextureBind_None,
\r
654 /// The application can write into the chain with pixel shader.
\r
655 ovrTextureBind_DX_RenderTarget = 0x0001,
\r
657 /// The application can write to the chain with compute shader.
\r
658 ovrTextureBind_DX_UnorderedAccess = 0x0002,
\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
664 ovrTextureBind_EnumSize = 0x7fffffff ///< \internal Force type int32_t.
\r
665 } ovrTextureBindFlags;
\r
667 /// The format of a texture.
\r
669 /// \see ovrTextureSwapChainDesc
\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
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
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
705 OVR_FORMAT_ENUMSIZE = 0x7fffffff ///< \internal Force type int32_t.
\r
706 } ovrTextureFormat;
\r
708 /// Misc flags overriding particular
\r
709 /// behaviors of a texture swap chain
\r
711 /// \see ovrTextureSwapChainDesc
\r
713 typedef enum ovrTextureMiscFlags_ {
\r
714 ovrTextureMisc_None,
\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
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
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
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
736 ovrTextureMisc_EnumSize = 0x7fffffff ///< \internal Force type int32_t.
\r
739 /// Description used to create a texture swap chain.
\r
741 /// \see ovr_CreateTextureSwapChainDX
\r
742 /// \see ovr_CreateTextureSwapChainGL
\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
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
757 /// Bit flags used as part of ovrMirrorTextureDesc's MirrorOptions field.
\r
759 /// \see ovr_CreateMirrorTextureWithOptionsDX
\r
760 /// \see ovr_CreateMirrorTextureWithOptionsGL
\r
761 /// \see ovr_CreateMirrorTextureWithOptionsVk
\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
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
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
779 /// Shows the boundary system aka Guardian on the mirror texture
\r
780 ovrMirrorOption_IncludeGuardian = 0x0008,
\r
782 /// Shows system notifications the user receives on the mirror texture
\r
783 ovrMirrorOption_IncludeNotifications = 0x0010,
\r
785 /// Shows the system menu (triggered by hitting the Home button) on the mirror texture
\r
786 ovrMirrorOption_IncludeSystemGui = 0x0020,
\r
789 ovrMirrorOption_EnumSize = 0x7fffffff ///< \internal Force type int32_t.
\r
790 } ovrMirrorOptions;
\r
792 /// Description used to create a mirror texture.
\r
794 /// \see ovr_CreateMirrorTextureWithOptionsDX
\r
795 /// \see ovr_CreateMirrorTextureWithOptionsGL
\r
796 /// \see ovr_CreateMirrorTextureWithOptionsVk
\r
798 typedef struct ovrMirrorTextureDesc_ {
\r
799 ovrTextureFormat Format;
\r
802 unsigned int MiscFlags; ///< ovrTextureFlags
\r
803 unsigned int MirrorOptions; ///< ovrMirrorOptions
\r
804 } ovrMirrorTextureDesc;
\r
806 typedef struct ovrTextureSwapChainData* ovrTextureSwapChain;
\r
807 typedef struct ovrMirrorTextureData* ovrMirrorTexture;
\r
809 //-----------------------------------------------------------------------------------
\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
820 /// B button on XBox controllers and right Touch controller. Back button on Oculus Remote.
\r
821 ovrButton_B = 0x00000002,
\r
823 /// Right thumbstick on XBox controllers and Touch controllers. Not present on Oculus Remote.
\r
824 ovrButton_RThumb = 0x00000004,
\r
826 /// Right shoulder button on XBox controllers. Not present on Touch controllers or Oculus Remote.
\r
827 ovrButton_RShoulder = 0x00000008,
\r
830 /// X button on XBox controllers and left Touch controller. Not present on Oculus Remote.
\r
831 ovrButton_X = 0x00000100,
\r
833 /// Y button on XBox controllers and left Touch controller. Not present on Oculus Remote.
\r
834 ovrButton_Y = 0x00000200,
\r
836 /// Left thumbstick on XBox controllers and Touch controllers. Not present on Oculus Remote.
\r
837 ovrButton_LThumb = 0x00000400,
\r
839 /// Left shoulder button on XBox controllers. Not present on Touch controllers or Oculus Remote.
\r
840 ovrButton_LShoulder = 0x00000800,
\r
842 /// Up button on XBox controllers and Oculus Remote. Not present on Touch controllers.
\r
843 ovrButton_Up = 0x00010000,
\r
845 /// Down button on XBox controllers and Oculus Remote. Not present on Touch controllers.
\r
846 ovrButton_Down = 0x00020000,
\r
848 /// Left button on XBox controllers and Oculus Remote. Not present on Touch controllers.
\r
849 ovrButton_Left = 0x00040000,
\r
851 /// Right button on XBox controllers and Oculus Remote. Not present on Touch controllers.
\r
852 ovrButton_Right = 0x00080000,
\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
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
862 /// Volume button on Oculus Remote. Not present on XBox or Touch controllers.
\r
863 ovrButton_VolUp = 0x00400000,
\r
865 /// Volume button on Oculus Remote. Not present on XBox or Touch controllers.
\r
866 ovrButton_VolDown = 0x00800000,
\r
868 /// Home button on XBox controllers. Oculus button on Touch controllers and Oculus Remote.
\r
869 ovrButton_Home = 0x01000000,
\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
874 // Bit mask of all buttons on the right Touch controller
\r
875 ovrButton_RMask = ovrButton_A | ovrButton_B | ovrButton_RThumb | ovrButton_RShoulder,
\r
877 // Bit mask of all buttons on the left Touch controller
\r
879 ovrButton_X | ovrButton_Y | ovrButton_LThumb | ovrButton_LShoulder | ovrButton_Enter,
\r
881 ovrButton_EnumSize = 0x7fffffff ///< \internal Force type int32_t.
\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
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
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
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
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
915 // Bit mask of all right controller poses
\r
916 ovrTouch_RPoseMask = ovrTouch_RIndexPointing | ovrTouch_RThumbUp,
\r
918 // Bit mask of all left controller poses
\r
919 ovrTouch_LPoseMask = ovrTouch_LIndexPointing | ovrTouch_LThumbUp,
\r
921 ovrTouch_EnumSize = 0x7fffffff ///< \internal Force type int32_t.
\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
929 // Size of each Haptics sample, sample value range is [0, 2^(Bytes*8)-1]
\r
930 int SampleSizeInBytes;
\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
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
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
951 ovrControllerType_XBox = 0x0010,
\r
953 ovrControllerType_Object0 = 0x0100,
\r
954 ovrControllerType_Object1 = 0x0200,
\r
955 ovrControllerType_Object2 = 0x0400,
\r
956 ovrControllerType_Object3 = 0x0800,
\r
958 ovrControllerType_Active = 0xffffffff, ///< Operate on or query whichever controller is active.
\r
960 ovrControllerType_EnumSize = 0x7fffffff ///< \internal Force type int32_t.
\r
961 } ovrControllerType;
\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
969 /// Maximum number of samples in ovrHapticsBuffer
\r
970 #define OVR_HAPTICS_BUFFER_SAMPLES_MAX 256
\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
978 /// How samples are submitted to the hardware
\r
979 ovrHapticsBufferSubmitMode SubmitMode;
\r
980 } ovrHapticsBuffer;
\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
987 // Number of samples currently queued
\r
989 } ovrHapticsPlaybackState;
\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
999 ovrTrackedDevice_Object0 = 0x0010,
\r
1000 ovrTrackedDevice_Object1 = 0x0020,
\r
1001 ovrTrackedDevice_Object2 = 0x0040,
\r
1002 ovrTrackedDevice_Object3 = 0x0080,
\r
1004 ovrTrackedDevice_All = 0xFFFF,
\r
1005 } ovrTrackedDeviceType;
\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
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
1017 /// Boundary system look and feel
\r
1018 typedef struct ovrBoundaryLookAndFeel_ {
\r
1019 /// Boundary color (alpha channel is ignored)
\r
1021 } ovrBoundaryLookAndFeel;
\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
1029 /// Distance to the closest play area or outer boundary surface.
\r
1030 float ClosestDistance;
\r
1032 /// Closest point on the boundary surface.
\r
1033 ovrVector3f ClosestPoint;
\r
1035 /// Unit surface normal of the closest boundary surface.
\r
1036 ovrVector3f ClosestPointNormal;
\r
1037 } ovrBoundaryTestResult;
\r
1039 /// Provides names for the left and right hand array indexes.
\r
1041 /// \see ovrInputState, ovrTrackingState
\r
1043 typedef enum ovrHandType_ {
\r
1045 ovrHand_Right = 1,
\r
1046 ovrHand_Count = 2,
\r
1047 ovrHand_EnumSize = 0x7fffffff ///< \internal Force type int32_t.
\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
1057 /// Values for buttons described by ovrButton.
\r
1058 unsigned int Buttons;
\r
1060 /// Touch values for buttons and sensors as described by ovrTouch.
\r
1061 unsigned int Touches;
\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
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
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
1082 /// The type of the controller this state is for.
\r
1083 ovrControllerType ControllerType;
\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
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
1099 /// Horizontal and vertical thumbstick axis values (ovrHand_Left and ovrHand_Right), in the range
\r
1101 /// Does not apply a deadzone or filter.
\r
1102 ovrVector2f ThumbstickNoDeadzone[ovrHand_Count];
\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
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
1118 /// Horizontal and vertical thumbstick axis values (ovrHand_Left and ovrHand_Right), in the range
\r
1120 /// No deadzone or filter
\r
1121 ovrVector2f ThumbstickRaw[ovrHand_Count];
\r
1124 typedef struct ovrCameraIntrinsics_ {
\r
1125 /// Time in seconds from last change to the parameters
\r
1126 double LastChangedTime;
\r
1128 /// Angles of all 4 sides of viewport
\r
1129 ovrFovPort FOVPort;
\r
1131 /// Near plane of the virtual camera used to match the external camera
\r
1132 float VirtualNearPlaneDistanceMeters;
\r
1134 /// Far plane of the virtual camera used to match the external camera
\r
1135 float VirtualFarPlaneDistanceMeters;
\r
1137 /// Height in pixels of image sensor
\r
1138 ovrSizei ImageSensorPixelResolution;
\r
1140 /// The lens distortion matrix of camera
\r
1141 ovrMatrix4f LensDistortionMatrix;
\r
1143 /// How often, in seconds, the exposure is taken
\r
1144 double ExposurePeriodSeconds;
\r
1146 /// length of the exposure time
\r
1147 double ExposureDurationSeconds;
\r
1149 } ovrCameraIntrinsics;
\r
1151 typedef enum ovrCameraStatusFlags_ {
\r
1152 /// Initial state of camera
\r
1153 ovrCameraStatus_None = 0x0,
\r
1155 /// Bit set when the camera is connected to the system
\r
1156 ovrCameraStatus_Connected = 0x1,
\r
1158 /// Bit set when the camera is undergoing calibration
\r
1159 ovrCameraStatus_Calibrating = 0x2,
\r
1161 /// Bit set when the camera has tried & failed calibration
\r
1162 ovrCameraStatus_CalibrationFailed = 0x4,
\r
1164 /// Bit set when the camera has tried & passed calibration
\r
1165 ovrCameraStatus_Calibrated = 0x8,
\r
1167 /// Bit set when the camera is capturing
\r
1168 ovrCameraStatus_Capturing = 0x10,
\r
1170 ovrCameraStatus_EnumSize = 0x7fffffff ///< \internal Force type int32_t.
\r
1171 } ovrCameraStatusFlags;
\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
1178 /// Current Status of the camera, a mix of bits from ovrCameraStatusFlags
\r
1179 unsigned int CameraStatusFlags;
\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
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
1191 /// The time, in seconds, when the last successful exposure was taken
\r
1192 double LastExposureTimeSeconds;
\r
1194 /// Estimated exposure latency to get from the exposure time to the system
\r
1195 double ExposureLatencySeconds;
\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
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
1210 //-----------------------------------------------------------------------------------
\r
1211 // ***** Initialize structures
\r
1213 /// Initialization flags.
\r
1215 /// \see ovrInitParams, ovr_Initialize
\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
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
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
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
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
1247 /// These bits are writable by user code.
\r
1248 ovrinit_WritableBits = 0x00ffffff,
\r
1250 ovrInit_EnumSize = 0x7fffffff ///< \internal Force type int32_t.
\r
1253 /// Logging levels
\r
1255 /// \see ovrInitParams, ovrLogCallback
\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
1262 ovrLogLevel_EnumSize = 0x7fffffff ///< \internal Force type int32_t.
\r
1265 /// Signature of the logging callback function pointer type.
\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
1272 typedef void(OVR_CDECL* ovrLogCallback)(uintptr_t userData, int level, const char* message);
\r
1274 /// Parameters for ovr_Initialize.
\r
1276 /// \see ovr_Initialize
\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
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
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
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
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
1303 OVR_ON64(OVR_UNUSED_STRUCT_PAD(pad0, 4)) ///< \internal
\r
1307 #ifdef __cplusplus
\r
1311 #if !defined(OVR_EXPORTING_CAPI)
\r
1313 // -----------------------------------------------------------------------------------
\r
1314 // ***** API Interfaces
\r
1316 /// Initializes LibOVR
\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
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
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
1350 /// <b>Example code</b>
\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
1363 /// \see ovr_Shutdown
\r
1365 OVR_PUBLIC_FUNCTION(ovrResult) ovr_Initialize(const ovrInitParams* params);
\r
1367 /// Shuts down LibOVR
\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
1373 /// previously returned by LibOVR functions. The LibOVRRT shared library can be unloaded by
\r
1376 /// \see ovr_Initialize
\r
1378 OVR_PUBLIC_FUNCTION(void) ovr_Shutdown();
\r
1380 /// Returns information about the most recent failed return value by the
\r
1381 /// current thread for this library.
\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
1391 /// \param[out] errorInfo The last ovrErrorInfo for the current thread.
\r
1393 /// \see ovrErrorInfo
\r
1395 OVR_PUBLIC_FUNCTION(void) ovr_GetLastErrorInfo(ovrErrorInfo* errorInfo);
\r
1397 /// Returns the version string representing the LibOVRRT version.
\r
1399 /// The returned string pointer is valid until the next call to ovr_Shutdown.
\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
1405 /// The format of this string is subject to change in future versions and its contents
\r
1406 /// should not be interpreted.
\r
1408 /// \return Returns a UTF8-encoded null-terminated version string.
\r
1410 OVR_PUBLIC_FUNCTION(const char*) ovr_GetVersionString();
\r
1412 /// Writes a message string to the LibOVR tracing mechanism (if enabled).
\r
1414 /// This message will be passed back to the application via the ovrLogCallback if
\r
1415 /// it was registered.
\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
1421 /// \see ovrLogLevel, ovrLogCallback
\r
1423 OVR_PUBLIC_FUNCTION(int) ovr_TraceMessage(int level, const char* message);
\r
1425 /// Identify client application info.
\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
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
1442 /// <b>Example code</b>
\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
1451 OVR_PUBLIC_FUNCTION(ovrResult) ovr_IdentifyClient(const char* identity);
\r
1453 //-------------------------------------------------------------------------------------
\r
1454 /// @name HMD Management
\r
1456 /// Handles the enumeration, creation, destruction, and properties of an HMD (head-mounted display).
\r
1459 /// Returns information about the current HMD.
\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
1465 /// \param[in] session Specifies an ovrSession previously returned by ovr_Create() or NULL.
\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
1470 OVR_PUBLIC_FUNCTION(ovrHmdDesc) ovr_GetHmdDesc(ovrSession session);
\r
1472 /// Returns the number of attached trackers.
\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
1477 /// \param[in] session Specifies an ovrSession previously returned by ovr_Create.
\r
1479 /// \return Returns unsigned int count.
\r
1481 OVR_PUBLIC_FUNCTION(unsigned int) ovr_GetTrackerCount(ovrSession session);
\r
1483 /// Returns a given attached tracker description.
\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
1489 /// \param[in] session Specifies an ovrSession previously returned by ovr_Create.
\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
1494 /// \return Returns ovrTrackerDesc. An empty ovrTrackerDesc will be returned if
\r
1495 /// trackerDescIndex is out of range.
\r
1497 /// \see ovrTrackerDesc, ovr_GetTrackerCount
\r
1499 OVR_PUBLIC_FUNCTION(ovrTrackerDesc)
\r
1500 ovr_GetTrackerDesc(ovrSession session, unsigned int trackerDescIndex);
\r
1502 /// Creates a handle to a VR session.
\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
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
1514 /// application that simply chooses the default adapter will not run reliably on multi-adapter
\r
1516 /// \return Returns an ovrResult indicating success or failure. Upon failure
\r
1517 /// the returned ovrSession will be NULL.
\r
1519 /// <b>Example code</b>
\r
1521 /// ovrSession session;
\r
1522 /// ovrGraphicsLuid luid;
\r
1523 /// ovrResult result = ovr_Create(&session, &luid);
\r
1524 /// if(OVR_FAILURE(result))
\r
1528 /// \see ovr_Destroy
\r
1530 OVR_PUBLIC_FUNCTION(ovrResult) ovr_Create(ovrSession* pSession, ovrGraphicsLuid* pLuid);
\r
1532 /// Destroys the session.
\r
1534 /// \param[in] session Specifies an ovrSession previously returned by ovr_Create.
\r
1535 /// \see ovr_Create
\r
1537 OVR_PUBLIC_FUNCTION(void) ovr_Destroy(ovrSession session);
\r
1539 #endif // !defined(OVR_EXPORTING_CAPI)
\r
1541 /// Specifies status information for the current session.
\r
1543 /// \see ovr_GetSessionStatus
\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
1549 /// True if an HMD is present.
\r
1550 ovrBool HmdPresent;
\r
1552 /// True if the HMD is on the user's head.
\r
1553 ovrBool HmdMounted;
\r
1555 /// True if the session is in a display-lost state. See ovr_SubmitFrame.
\r
1556 ovrBool DisplayLost;
\r
1558 /// True if the application should initiate shutdown.
\r
1559 ovrBool ShouldQuit;
\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
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
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
1575 /// True if runtime is requesting that the application provide depth buffers with projection
\r
1577 ovrBool DepthRequested;
\r
1579 } ovrSessionStatus;
\r
1581 #if !defined(OVR_EXPORTING_CAPI)
\r
1583 /// Returns status information for the application.
\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
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
1595 OVR_PUBLIC_FUNCTION(ovrResult)
\r
1596 ovr_GetSessionStatus(ovrSession session, ovrSessionStatus* sessionStatus);
\r
1599 /// Query extension support status.
\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
1605 /// \return Returns an ovrResult indicating success or failure. In the case of
\r
1606 /// failure use ovr_GetLastErrorInfo to get more information.
\r
1608 /// \see ovrExtensions
\r
1610 OVR_PUBLIC_FUNCTION(ovrResult)
\r
1611 ovr_IsExtensionSupported(
\r
1612 ovrSession session,
\r
1613 ovrExtensions extension,
\r
1614 ovrBool* outExtensionSupported);
\r
1616 /// Enable extension. Extensions must be enabled after ovr_Create is called.
\r
1618 /// \param[in] session Specifies an ovrSession previously returned by ovr_Create.
\r
1619 /// \param[in] extension Extension to enable.
\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
1625 /// \see ovrExtensions
\r
1627 OVR_PUBLIC_FUNCTION(ovrResult)
\r
1628 ovr_EnableExtension(ovrSession session, ovrExtensions extension);
\r
1632 //-------------------------------------------------------------------------------------
\r
1633 /// @name Tracking
\r
1635 /// Tracking functions handle the position, orientation, and movement of the HMD in space.
\r
1637 /// All tracking interface functions are thread-safe, allowing tracking state to be sampled
\r
1638 /// from different threads.
\r
1643 /// Sets the tracking origin type
\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
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
1651 /// \return Returns an ovrResult indicating success or failure. In the case of failure, use
\r
1652 /// ovr_GetLastErrorInfo to get more information.
\r
1654 /// \see ovrTrackingOrigin, ovr_GetTrackingOriginType
\r
1655 OVR_PUBLIC_FUNCTION(ovrResult)
\r
1656 ovr_SetTrackingOriginType(ovrSession session, ovrTrackingOrigin origin);
\r
1658 /// Gets the tracking origin state
\r
1660 /// \param[in] session Specifies an ovrSession previously returned by ovr_Create.
\r
1662 /// \return Returns the ovrTrackingOrigin that was either set by default, or previous set by the
\r
1665 /// \see ovrTrackingOrigin, ovr_SetTrackingOriginType
\r
1666 OVR_PUBLIC_FUNCTION(ovrTrackingOrigin) ovr_GetTrackingOriginType(ovrSession session);
\r
1668 /// Re-centers the sensor position and orientation.
\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
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
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
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
1686 /// \param[in] session Specifies an ovrSession previously returned by ovr_Create.
\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
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
1695 /// \see ovrTrackingOrigin, ovr_GetTrackerPose, ovr_SpecifyTrackingOrigin
\r
1697 OVR_PUBLIC_FUNCTION(ovrResult) ovr_RecenterTrackingOrigin(ovrSession session);
\r
1699 /// Allows manually tweaking the sensor position and orientation.
\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
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
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
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
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
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
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
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
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
1741 /// \see ovrTrackingOrigin, ovr_GetTrackerPose, ovr_RecenterTrackingOrigin
\r
1743 OVR_PUBLIC_FUNCTION(ovrResult) ovr_SpecifyTrackingOrigin(ovrSession session, ovrPosef originPose);
\r
1745 /// Clears the ShouldRecenter status bit in ovrSessionStatus.
\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
1753 /// Returns tracking state reading based on the specified absolute system time.
\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
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
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
1769 /// \see ovrTrackingState, ovr_GetEyePoses, ovr_GetTimeInSeconds
\r
1771 OVR_PUBLIC_FUNCTION(ovrTrackingState)
\r
1772 ovr_GetTrackingState(ovrSession session, double absTime, ovrBool latencyMarker);
\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
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
1786 /// \return Returns an ovrResult for which OVR_SUCCESS(result) is false upon error and
\r
1787 /// true upon success.
\r
1789 OVR_PUBLIC_FUNCTION(ovrResult)
\r
1790 ovr_GetDevicePoses(
\r
1791 ovrSession session,
\r
1792 ovrTrackedDeviceType* deviceTypes,
\r
1795 ovrPoseStatef* outDevicePoses);
\r
1798 /// Returns the ovrTrackerPose for the given attached tracker.
\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
1803 /// \return Returns the requested ovrTrackerPose. An empty ovrTrackerPose will be returned if
\r
1804 /// trackerPoseIndex is out of range.
\r
1806 /// \see ovr_GetTrackerCount
\r
1808 OVR_PUBLIC_FUNCTION(ovrTrackerPose)
\r
1809 ovr_GetTrackerPose(ovrSession session, unsigned int trackerPoseIndex);
\r
1811 /// Returns the most recent input state for controllers, without positional tracking info.
\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
1817 /// \see ovrControllerType
\r
1819 OVR_PUBLIC_FUNCTION(ovrResult)
\r
1820 ovr_GetInputState(ovrSession session, ovrControllerType controllerType, ovrInputState* inputState);
\r
1822 /// Returns controller types connected to the system OR'ed together.
\r
1824 /// \return A bitmask of ovrControllerTypes connected to the system.
\r
1826 /// \see ovrControllerType
\r
1828 OVR_PUBLIC_FUNCTION(unsigned int) ovr_GetConnectedControllerTypes(ovrSession session);
\r
1830 /// Gets information about Haptics engine for the specified Touch controller.
\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
1835 /// \return Returns an ovrTouchHapticsDesc.
\r
1837 OVR_PUBLIC_FUNCTION(ovrTouchHapticsDesc)
\r
1838 ovr_GetTouchHapticsDesc(ovrSession session, ovrControllerType controllerType);
\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
1844 /// This method should be called periodically, vibration lasts for a maximum of 2.5 seconds.
\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
1857 OVR_PUBLIC_FUNCTION(ovrResult)
\r
1858 ovr_SetControllerVibration(
\r
1859 ovrSession session,
\r
1860 ovrControllerType controllerType,
\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
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
1877 /// \see ovrHapticsBuffer
\r
1879 OVR_PUBLIC_FUNCTION(ovrResult)
\r
1880 ovr_SubmitControllerVibration(
\r
1881 ovrSession session,
\r
1882 ovrControllerType controllerType,
\r
1883 const ovrHapticsBuffer* buffer);
\r
1885 /// Gets the Haptics engine playback state of a specific Touch controller.
\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
1896 /// \see ovrHapticsPlaybackState
\r
1898 OVR_PUBLIC_FUNCTION(ovrResult)
\r
1899 ovr_GetControllerVibrationState(
\r
1900 ovrSession session,
\r
1901 ovrControllerType controllerType,
\r
1902 ovrHapticsPlaybackState* outState);
\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
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
1922 /// \see ovrBoundaryTestResult
\r
1924 OVR_PUBLIC_FUNCTION(ovrResult)
\r
1926 ovrSession session,
\r
1927 ovrTrackedDeviceType deviceBitmask,
\r
1928 ovrBoundaryType boundaryType,
\r
1929 ovrBoundaryTestResult* outTestResult);
\r
1931 /// Tests collision/proximity of a 3D point against the Boundary System.
\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
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
1945 /// \see ovrBoundaryTestResult
\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
1954 /// Sets the look and feel of the Boundary System.
\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
1961 OVR_PUBLIC_FUNCTION(ovrResult)
\r
1962 ovr_SetBoundaryLookAndFeel(ovrSession session, const ovrBoundaryLookAndFeel* lookAndFeel);
\r
1964 /// Resets the look and feel of the Boundary System to its default state.
\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
1970 OVR_PUBLIC_FUNCTION(ovrResult) ovr_ResetBoundaryLookAndFeel(ovrSession session);
\r
1972 /// Gets the geometry of the Boundary System's "play area" or "outer boundary" as 3D floor points.
\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
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
1992 /// Gets the dimension of the Boundary System's "play area" or "outer boundary".
\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
2004 OVR_PUBLIC_FUNCTION(ovrResult)
\r
2005 ovr_GetBoundaryDimensions(
\r
2006 ovrSession session,
\r
2007 ovrBoundaryType boundaryType,
\r
2008 ovrVector3f* outDimensions);
\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
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
2023 OVR_PUBLIC_FUNCTION(ovrResult) ovr_GetBoundaryVisible(ovrSession session, ovrBool* outIsVisible);
\r
2025 /// Requests boundary to be visible.
\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
2032 OVR_PUBLIC_FUNCTION(ovrResult) ovr_RequestBoundaryVisible(ovrSession session, ovrBool visible);
\r
2034 // -----------------------------------------------------------------------------------
\r
2035 /// @name Mixed reality capture support
\r
2037 /// Defines functions used for mixed reality capture / third person cameras.
\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
2055 /// Sets the camera intrinsics and/or extrinsics stored for the cameraName camera
\r
2056 /// Names must be < 32 characters and null-terminated.
\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
2069 const ovrCameraIntrinsics* const intrinsics,
\r
2070 const ovrCameraExtrinsics* const extrinsics);
\r
2074 #endif // !defined(OVR_EXPORTING_CAPI)
\r
2076 //-------------------------------------------------------------------------------------
\r
2081 /// Specifies the maximum number of layers supported by ovr_SubmitFrame.
\r
2083 /// /see ovr_SubmitFrame
\r
2085 enum { ovrMaxLayerCount = 16 };
\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
2090 /// \see ovrLayerHeader
\r
2092 typedef enum ovrLayerType_ {
\r
2093 /// Layer is disabled.
\r
2094 ovrLayerType_Disabled = 0,
\r
2096 /// Described by ovrLayerEyeFov.
\r
2097 ovrLayerType_EyeFov = 1,
\r
2099 /// Described by ovrLayerEyeFovDepth.
\r
2100 ovrLayerType_EyeFovDepth = 2,
\r
2102 /// Described by ovrLayerQuad. Previously called ovrLayerType_QuadInWorld.
\r
2103 ovrLayerType_Quad = 3,
\r
2105 // enum 4 used to be ovrLayerType_QuadHeadLocked. Instead, use ovrLayerType_Quad with
\r
2106 // ovrLayerFlag_HeadLocked.
\r
2108 /// Described by ovrLayerEyeMatrix.
\r
2109 ovrLayerType_EyeMatrix = 5,
\r
2112 /// Described by ovrLayerEyeFovMultires.
\r
2113 ovrLayerType_EyeFovMultires = 7,
\r
2115 /// Described by ovrLayerCylinder.
\r
2116 ovrLayerType_Cylinder = 8,
\r
2118 /// Described by ovrLayerCube
\r
2119 ovrLayerType_Cube = 10,
\r
2122 ovrLayerType_EnumSize = 0x7fffffff ///< Force type int32_t.
\r
2126 /// Identifies flags used by ovrLayerHeader and which are passed to ovr_SubmitFrame.
\r
2128 /// \see ovrLayerHeader
\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
2138 /// ovrLayerFlag_TextureOriginAtBottomLeft: the opposite is TopLeft.
\r
2139 /// Generally this is false for D3D, true for OpenGL.
\r
2140 ovrLayerFlag_TextureOriginAtBottomLeft = 0x02,
\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
2152 /// Defines properties shared by all ovrLayer structs, such as ovrLayerEyeFov.
\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
2157 /// \see ovrLayerType, ovrLayerFlags
\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
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
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
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
2177 /// \see ovrTextureSwapChain, ovr_SubmitFrame
\r
2179 typedef struct OVR_ALIGNAS(OVR_PTR_SIZE) ovrLayerEyeFov_ {
\r
2180 /// Header.Type must be ovrLayerType_EyeFov.
\r
2181 ovrLayerHeader Header;
\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
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
2191 /// The viewport field of view.
\r
2192 ovrFovPort Fov[ovrEye_Count];
\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
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
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
2212 /// ProjectionDesc can be created using ovrTimewarpProjectionDesc_FromProjection.
\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
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
2223 /// \see ovrTextureSwapChain, ovr_SubmitFrame
\r
2225 typedef struct OVR_ALIGNAS(OVR_PTR_SIZE) ovrLayerEyeFovDepth_ {
\r
2226 /// Header.Type must be ovrLayerType_EyeFovDepth.
\r
2227 ovrLayerHeader Header;
\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
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
2237 /// The viewport field of view.
\r
2238 ovrFovPort Fov[ovrEye_Count];
\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
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
2251 /// Depth texture for positional timewarp.
\r
2252 /// Must map 1:1 to the ColorTexture.
\r
2253 ovrTextureSwapChain DepthTexture[ovrEye_Count];
\r
2255 /// Specifies how to convert DepthTexture information into meters.
\r
2256 /// \see ovrTimewarpProjectionDesc_FromProjection
\r
2257 ovrTimewarpProjectionDesc ProjectionDesc;
\r
2259 } ovrLayerEyeFovDepth;
\r
2261 /// Describes eye texture layouts. Used with ovrLayerEyeFovMultires.
\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
2269 /// Multiresolution descriptor for Octilinear.
\r
2271 /// Usage of this layer must be successfully enabled via ovr_EnableExtension
\r
2272 /// before it can be used.
\r
2274 /// \see ovrLayerEyeFovMultres
\r
2276 typedef struct OVR_ALIGNAS(OVR_PTR_SIZE) ovrTextureLayoutOctilinear_ {
\r
2283 // Size of W quadrants.
\r
2285 // SizeLeft + SizeRight <= Viewport.Size.w
\r
2286 // SizeUp + sizeDown <= Viewport.Size.h
\r
2288 // Clip space (0,0) is located at Viewport.Pos + (SizeLeft,SizeUp) where
\r
2289 // Viewport is given in the layer description.
\r
2291 // Viewport Top left
\r
2292 // +-----------------------------------------------------+
\r
2295 // | 0 SizeUp 1 | |
\r
2296 // | | |<--Portion of viewport
\r
2297 // | | | determined by sizes
\r
2299 // |<--------SizeLeft-------+-------SizeRight------>| |
\r
2302 // | 2 SizeDown 3 | |
\r
2306 // +------------------------------------------------+ |
\r
2308 // +-----------------------------------------------------+
\r
2309 // Viewport bottom right
\r
2311 // For example, when rendering quadrant 0 its scissor rectangle will be
\r
2315 // Right = SizeLeft
\r
2316 // Bottom = SizeUp
\r
2318 // and the scissor rectangle for quadrant 1 will be:
\r
2321 // Left = SizeLeft
\r
2322 // Right = SizeLeft + SizeRight
\r
2323 // Bottom = SizeUp
\r
2330 } ovrTextureLayoutOctilinear;
\r
2332 /// Combines texture layout descriptors.
\r
2334 typedef union OVR_ALIGNAS(OVR_PTR_SIZE) ovrTextureLayoutDesc_Union_ {
\r
2335 ovrTextureLayoutOctilinear Octilinear[ovrEye_Count];
\r
2336 } ovrTextureLayoutDesc_Union;
\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
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
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
2351 /// \see ovrTextureSwapChain, ovr_SubmitFrame
\r
2353 typedef struct OVR_ALIGNAS(OVR_PTR_SIZE) ovrLayerEyeFovMultires_ {
\r
2354 /// Header.Type must be ovrLayerType_EyeFovMultires.
\r
2355 ovrLayerHeader Header;
\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
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
2365 /// The viewport field of view.
\r
2366 ovrFovPort Fov[ovrEye_Count];
\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
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
2379 /// Specifies layout type of textures.
\r
2380 ovrTextureLayout TextureLayout;
\r
2382 /// Specifies texture layout parameters.
\r
2383 ovrTextureLayoutDesc_Union TextureLayoutDesc;
\r
2385 } ovrLayerEyeFovMultires;
\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
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
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
2403 /// \see ovrTextureSwapChain, ovr_SubmitFrame
\r
2405 typedef struct OVR_ALIGNAS(OVR_PTR_SIZE) ovrLayerEyeMatrix_ {
\r
2406 /// Header.Type must be ovrLayerType_EyeMatrix.
\r
2407 ovrLayerHeader Header;
\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
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
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
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
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
2435 } ovrLayerEyeMatrix;
\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
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
2446 /// Quad layers are visible from both sides; they are not back-face culled.
\r
2448 /// \see ovrTextureSwapChain, ovr_SubmitFrame
\r
2450 typedef struct OVR_ALIGNAS(OVR_PTR_SIZE) ovrLayerQuad_ {
\r
2451 /// Header.Type must be ovrLayerType_Quad.
\r
2452 ovrLayerHeader Header;
\r
2454 /// Contains a single image, never with any stereo view.
\r
2455 ovrTextureSwapChain ColorTexture;
\r
2457 /// Specifies the ColorTexture sub-rect UV coordinates.
\r
2458 ovrRecti Viewport;
\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
2467 /// Width and height (respectively) of the quad in meters.
\r
2468 ovrVector2f QuadSize;
\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
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
2487 /// R = Radius | | |
\r
2488 /// A = Angle (0,2*Pi) | | |
\r
2489 /// C = CylinderPoseCenter | | |
\r
2490 /// U/V = UV Coordinates +-----------------+ - V=1
\r
2492 /// An identity CylinderPoseCenter places the center of the cylinder
\r
2493 /// at the recentered origin unless the headlocked flag is set.
\r
2495 /// Does not utilize HmdSpaceToWorldScaleInMeters. If necessary, adjust
\r
2496 /// translation and radius.
\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
2505 /// \see ovrTextureSwapChain, ovr_SubmitFrame
\r
2507 typedef struct OVR_ALIGNAS(OVR_PTR_SIZE) ovrLayerCylinder_ {
\r
2508 /// Header.Type must be ovrLayerType_Cylinder.
\r
2509 ovrLayerHeader Header;
\r
2511 /// Contains a single image, never with any stereo view.
\r
2512 ovrTextureSwapChain ColorTexture;
\r
2514 /// Specifies the ColorTexture sub-rect UV coordinates.
\r
2515 ovrRecti Viewport;
\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
2523 /// Radius of the cylinder in meters.
\r
2524 float CylinderRadius;
\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
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
2537 } ovrLayerCylinder;
\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
2545 /// ovrLayerFlag_TextureOriginAtBottomLeft flag is not supported by ovrLayerCube.
\r
2547 /// \see ovrTextureSwapChain, ovr_SubmitFrame
\r
2549 typedef struct OVR_ALIGNAS(OVR_PTR_SIZE) ovrLayerCube_ {
\r
2550 /// Header.Type must be ovrLayerType_Cube.
\r
2551 ovrLayerHeader Header;
\r
2553 /// Orientation of the cube.
\r
2554 ovrQuatf Orientation;
\r
2556 /// Contains a single cubemap swapchain (not a stereo pair of swapchains).
\r
2557 ovrTextureSwapChain CubeMapTexture;
\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
2576 #if !defined(OVR_EXPORTING_CAPI)
\r
2578 /// @name SDK Distortion Rendering
\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
2585 /// These functions support rendering of distortion by the SDK.
\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
2593 /// Gets the number of buffers in an ovrTextureSwapChain.
\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
2599 /// \return Returns an ovrResult for which OVR_SUCCESS(result) is false upon error.
\r
2601 /// \see ovr_CreateTextureSwapChainDX, ovr_CreateTextureSwapChainGL
\r
2603 OVR_PUBLIC_FUNCTION(ovrResult)
\r
2604 ovr_GetTextureSwapChainLength(ovrSession session, ovrTextureSwapChain chain, int* out_Length);
\r
2606 /// Gets the current index in an ovrTextureSwapChain.
\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
2612 /// \return Returns an ovrResult for which OVR_SUCCESS(result) is false upon error.
\r
2614 /// \see ovr_CreateTextureSwapChainDX, ovr_CreateTextureSwapChainGL
\r
2616 OVR_PUBLIC_FUNCTION(ovrResult)
\r
2617 ovr_GetTextureSwapChainCurrentIndex(ovrSession session, ovrTextureSwapChain chain, int* out_Index);
\r
2619 /// Gets the description of the buffers in an ovrTextureSwapChain
\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
2626 /// \return Returns an ovrResult for which OVR_SUCCESS(result) is false upon error.
\r
2628 /// \see ovr_CreateTextureSwapChainDX, ovr_CreateTextureSwapChainGL
\r
2630 OVR_PUBLIC_FUNCTION(ovrResult)
\r
2631 ovr_GetTextureSwapChainDesc(
\r
2632 ovrSession session,
\r
2633 ovrTextureSwapChain chain,
\r
2634 ovrTextureSwapChainDesc* out_Desc);
\r
2636 /// Commits any pending changes to an ovrTextureSwapChain, and advances its current index
\r
2638 /// \param[in] session Specifies an ovrSession previously returned by ovr_Create.
\r
2639 /// \param[in] chain Specifies the ovrTextureSwapChain to commit.
\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
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
2652 /// \see ovr_CreateTextureSwapChainDX, ovr_CreateTextureSwapChainGL
\r
2654 OVR_PUBLIC_FUNCTION(ovrResult)
\r
2655 ovr_CommitTextureSwapChain(ovrSession session, ovrTextureSwapChain chain);
\r
2657 /// Destroys an ovrTextureSwapChain and frees all the resources associated with it.
\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
2663 /// \see ovr_CreateTextureSwapChainDX, ovr_CreateTextureSwapChainGL
\r
2665 OVR_PUBLIC_FUNCTION(void)
\r
2666 ovr_DestroyTextureSwapChain(ovrSession session, ovrTextureSwapChain chain);
\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
2672 /// Destroys a mirror texture previously created by one of the mirror texture creation functions.
\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
2678 /// \see ovr_CreateMirrorTextureWithOptionsDX, ovr_CreateMirrorTextureWithOptionsGL
\r
2680 OVR_PUBLIC_FUNCTION(void)
\r
2681 ovr_DestroyMirrorTexture(ovrSession session, ovrMirrorTexture mirrorTexture);
\r
2683 /// Calculates the recommended viewport size for rendering a given eye within the HMD
\r
2684 /// with a given FOV cone.
\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
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
2698 /// <b>Example code</b>
\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
2707 /// \return Returns the texture width and height size.
\r
2709 OVR_PUBLIC_FUNCTION(ovrSizei)
\r
2710 ovr_GetFovTextureSize(
\r
2711 ovrSession session,
\r
2714 float pixelsPerDisplayPixel);
\r
2716 /// Computes the distortion viewport, view adjust, and other rendering parameters for
\r
2717 /// the specified eye.
\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
2723 /// \return Returns the computed ovrEyeRenderDesc for the given eyeType and field of view.
\r
2725 /// \see ovrEyeRenderDesc
\r
2727 OVR_PUBLIC_FUNCTION(ovrEyeRenderDesc)
\r
2728 ovr_GetRenderDesc(ovrSession session, ovrEyeType eyeType, ovrFovPort fov);
\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
2733 /// \param[in] session Specifies an ovrSession previously returned by ovr_Create.
\r
2735 /// \param[in] frameIndex Specifies the targeted application frame index.
\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
2751 /// \see ovr_BeginFrame, ovr_EndFrame, ovr_GetSessionStatus
\r
2753 OVR_PUBLIC_FUNCTION(ovrResult)
\r
2754 ovr_WaitToBeginFrame(ovrSession session, long long frameIndex);
\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
2759 /// \param[in] session Specifies an ovrSession previously returned by ovr_Create.
\r
2761 /// \param[in] frameIndex Specifies the targeted application frame index. It must match what was
\r
2762 /// passed to ovr_WaitToBeginFrame.
\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
2774 /// \see ovr_WaitToBeginFrame, ovr_EndFrame
\r
2776 OVR_PUBLIC_FUNCTION(ovrResult)
\r
2777 ovr_BeginFrame(ovrSession session, long long frameIndex);
\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
2783 /// \param[in] session Specifies an ovrSession previously returned by ovr_Create.
\r
2785 /// \param[in] frameIndex Specifies the targeted application frame index. It must match what was
\r
2786 /// passed to ovr_BeginFrame.
\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
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
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
2802 /// - Layers are drawn in the order they are specified in the array, regardless of the layer type.
\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
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
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
2814 /// <b>Example code</b>
\r
2816 /// ovrLayerEyeFov layer0;
\r
2817 /// ovrLayerQuad layer1;
\r
2819 /// ovrLayerHeader* layers[2] = { &layer0.Header, &layer1.Header };
\r
2820 /// ovrResult result = ovr_EndFrame(session, frameIndex, nullptr, layers, 2);
\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
2832 /// - ovrError_TextureSwapChainInvalid: The ovrTextureSwapChain is in an incomplete or
\r
2833 /// inconsistent state. Ensure ovr_CommitTextureSwapChain was called at least once first.
\r
2835 /// \see ovr_WaitToBeginFrame, ovr_BeginFrame, ovrViewScaleDesc, ovrLayerHeader
\r
2837 OVR_PUBLIC_FUNCTION(ovrResult)
\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
2845 /// Submits layers for distortion and display.
\r
2847 /// Deprecated. Use ovr_WaitToBeginFrame, ovr_BeginFrame, and ovr_EndFrame instead.
\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
2853 /// \param[in] session Specifies an ovrSession previously returned by ovr_Create.
\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
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
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
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
2872 /// - Layers are drawn in the order they are specified in the array, regardless of the layer type.
\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
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
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
2884 /// <b>Example code</b>
\r
2886 /// ovrLayerEyeFov layer0;
\r
2887 /// ovrLayerQuad layer1;
\r
2889 /// ovrLayerHeader* layers[2] = { &layer0.Header, &layer1.Header };
\r
2890 /// ovrResult result = ovr_SubmitFrame(session, frameIndex, nullptr, layers, 2);
\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
2906 /// - ovrError_TextureSwapChainInvalid: The ovrTextureSwapChain is in an incomplete or
\r
2907 /// inconsistent state. Ensure ovr_CommitTextureSwapChain was called at least once first.
\r
2909 /// \see ovr_GetPredictedDisplayTime, ovrViewScaleDesc, ovrLayerHeader, ovr_GetSessionStatus
\r
2911 OVR_PUBLIC_FUNCTION(ovrResult)
\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
2920 #endif // !defined(OVR_EXPORTING_CAPI)
\r
2922 //-------------------------------------------------------------------------------------
\r
2923 /// @name Frame Timing
\r
2928 /// Contains the performance stats for a given SDK compositor frame
\r
2930 /// All of the 'int' typed fields can be reset via the ovr_ResetPerfStats call.
\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
2935 /// If the compositor drops a frame, expect this value to increment more than 1 at a time.
\r
2936 int HmdVsyncIndex;
\r
2939 /// Application stats
\r
2942 /// Index that increments with each successive ovr_SubmitFrame call
\r
2943 int AppFrameIndex;
\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
2949 /// Motion-to-photon latency for the application
\r
2950 /// This value is calculated by either using the SensorSampleTime provided for the ovrLayerEyeFov
\r
2952 /// is not available, then the call to ovr_GetTrackingState which has latencyMarker set to ovrTrue
\r
2953 float AppMotionToPhotonLatency;
\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
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
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
2971 /// SDK Compositor stats
\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
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
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
2988 float CompositorLatency;
\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
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
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
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
3009 /// Async Spacewarp stats (ASW)
\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
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
3020 /// Accumulates the number of frames presented by the compositor which had extrapolated
\r
3021 /// ASW frames presented.
\r
3022 int AswPresentedFrameCount;
\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
3028 } ovrPerfStatsPerCompositorFrame;
\r
3031 /// Maximum number of frames of performance stats provided back to the caller of ovr_GetPerfStats
\r
3033 enum { ovrMaxProvidedFrameStats = 5 };
\r
3036 /// This is a complete descriptor of the performance stats provided by the SDK
\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
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
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
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
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
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
3082 #if !defined(OVR_EXPORTING_CAPI)
\r
3084 /// Retrieves performance stats for the VR app as well as the SDK compositor.
\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
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
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
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
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
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
3112 /// \see ovrPerfStats, ovrPerfStatsPerCompositorFrame, ovr_ResetPerfStats
\r
3114 OVR_PUBLIC_FUNCTION(ovrResult) ovr_GetPerfStats(ovrSession session, ovrPerfStats* outStats);
\r
3116 /// Resets the accumulated stats reported in each ovrPerfStatsPerCompositorFrame back to zero.
\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
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
3126 /// \see ovrPerfStats, ovrPerfStatsPerCompositorFrame, ovr_GetPerfStats
\r
3128 OVR_PUBLIC_FUNCTION(ovrResult) ovr_ResetPerfStats(ovrSession session);
\r
3130 /// Gets the time of the specified frame midpoint.
\r
3132 /// Predicts the time at which the given frame will be displayed. The predicted time
\r
3133 /// is the middle of the time period during which the corresponding eye images will
\r
3136 /// The application should increment frameIndex for each successively targeted frame,
\r
3137 /// and pass that index to any relevant OVR functions that need to apply to the frame
\r
3138 /// identified by that index.
\r
3140 /// This function is thread-safe and allows for multiple application threads to target
\r
3141 /// their processing to the same displayed frame.
\r
3143 /// In the even that prediction fails due to various reasons (e.g. the display being off
\r
3144 /// or app has yet to present any frames), the return value will be current CPU time.
\r
3146 /// \param[in] session Specifies an ovrSession previously returned by ovr_Create.
\r
3147 /// \param[in] frameIndex Identifies the frame the caller wishes to target.
\r
3148 /// A value of zero returns the next frame index.
\r
3149 /// \return Returns the absolute frame midpoint time for the given frameIndex.
\r
3150 /// \see ovr_GetTimeInSeconds
\r
3152 OVR_PUBLIC_FUNCTION(double) ovr_GetPredictedDisplayTime(ovrSession session, long long frameIndex);
\r
3154 /// Returns global, absolute high-resolution time in seconds.
\r
3156 /// The time frame of reference for this function is not specified and should not be
\r
3157 /// depended upon.
\r
3159 /// \return Returns seconds as a floating point value.
\r
3160 /// \see ovrPoseStatef, ovrFrameTiming
\r
3162 OVR_PUBLIC_FUNCTION(double) ovr_GetTimeInSeconds();
\r
3164 #endif // !defined(OVR_EXPORTING_CAPI)
\r
3166 /// Performance HUD enables the HMD user to see information critical to
\r
3167 /// the real-time operation of the VR application such as latency timing,
\r
3168 /// and CPU & GPU performance metrics
\r
3170 /// App can toggle performance HUD modes as such:
\r
3172 /// ovrPerfHudMode PerfHudMode = ovrPerfHud_LatencyTiming;
\r
3173 /// ovr_SetInt(session, OVR_PERF_HUD_MODE, (int)PerfHudMode);
\r
3176 typedef enum ovrPerfHudMode_ {
\r
3177 ovrPerfHud_Off = 0, ///< Turns off the performance HUD
\r
3178 ovrPerfHud_PerfSummary = 1, ///< Shows performance summary and headroom
\r
3179 ovrPerfHud_LatencyTiming = 2, ///< Shows latency related timing info
\r
3180 ovrPerfHud_AppRenderTiming = 3, ///< Shows render timing info for application
\r
3181 ovrPerfHud_CompRenderTiming = 4, ///< Shows render timing info for OVR compositor
\r
3182 ovrPerfHud_AswStats = 6, ///< Shows Async Spacewarp-specific info
\r
3183 ovrPerfHud_VersionInfo = 5, ///< Shows SDK & HMD version Info
\r
3184 ovrPerfHud_Count = 7, ///< \internal Count of enumerated elements.
\r
3185 ovrPerfHud_EnumSize = 0x7fffffff ///< \internal Force type int32_t.
\r
3188 /// Layer HUD enables the HMD user to see information about a layer
\r
3190 /// App can toggle layer HUD modes as such:
\r
3192 /// ovrLayerHudMode LayerHudMode = ovrLayerHud_Info;
\r
3193 /// ovr_SetInt(session, OVR_LAYER_HUD_MODE, (int)LayerHudMode);
\r
3196 typedef enum ovrLayerHudMode_ {
\r
3197 ovrLayerHud_Off = 0, ///< Turns off the layer HUD
\r
3198 ovrLayerHud_Info = 1, ///< Shows info about a specific layer
\r
3199 ovrLayerHud_EnumSize = 0x7fffffff
\r
3200 } ovrLayerHudMode;
\r
3204 /// Debug HUD is provided to help developers gauge and debug the fidelity of their app's
\r
3205 /// stereo rendering characteristics. Using the provided quad and crosshair guides,
\r
3206 /// the developer can verify various aspects such as VR tracking units (e.g. meters),
\r
3207 /// stereo camera-parallax properties (e.g. making sure objects at infinity are rendered
\r
3208 /// with the proper separation), measuring VR geometry sizes and distances and more.
\r
3210 /// App can toggle the debug HUD modes as such:
\r
3212 /// ovrDebugHudStereoMode DebugHudMode = ovrDebugHudStereo_QuadWithCrosshair;
\r
3213 /// ovr_SetInt(session, OVR_DEBUG_HUD_STEREO_MODE, (int)DebugHudMode);
\r
3216 /// The app can modify the visual properties of the stereo guide (i.e. quad, crosshair)
\r
3217 /// using the ovr_SetFloatArray function. For a list of tweakable properties,
\r
3218 /// see the OVR_DEBUG_HUD_STEREO_GUIDE_* keys in the OVR_CAPI_Keys.h header file.
\r
3219 typedef enum ovrDebugHudStereoMode_ {
\r
3220 /// Turns off the Stereo Debug HUD.
\r
3221 ovrDebugHudStereo_Off = 0,
\r
3223 /// Renders Quad in world for Stereo Debugging.
\r
3224 ovrDebugHudStereo_Quad = 1,
\r
3226 /// Renders Quad+crosshair in world for Stereo Debugging
\r
3227 ovrDebugHudStereo_QuadWithCrosshair = 2,
\r
3229 /// Renders screen-space crosshair at infinity for Stereo Debugging
\r
3230 ovrDebugHudStereo_CrosshairAtInfinity = 3,
\r
3232 /// \internal Count of enumerated elements
\r
3233 ovrDebugHudStereo_Count,
\r
3235 ovrDebugHudStereo_EnumSize = 0x7fffffff ///< \internal Force type int32_t
\r
3236 } ovrDebugHudStereoMode;
\r
3238 #if !defined(OVR_EXPORTING_CAPI)
\r
3240 // -----------------------------------------------------------------------------------
\r
3241 /// @name Property Access
\r
3243 /// These functions read and write OVR properties. Supported properties
\r
3244 /// are defined in OVR_CAPI_Keys.h
\r
3248 /// Reads a boolean property.
\r
3250 /// \param[in] session Specifies an ovrSession previously returned by ovr_Create.
\r
3251 /// \param[in] propertyName The name of the property, which needs to be valid for only the call.
\r
3252 /// \param[in] defaultVal specifes the value to return if the property couldn't be read.
\r
3253 /// \return Returns the property interpreted as a boolean value. Returns defaultVal if
\r
3254 /// the property doesn't exist.
\r
3255 OVR_PUBLIC_FUNCTION(ovrBool)
\r
3256 ovr_GetBool(ovrSession session, const char* propertyName, ovrBool defaultVal);
\r
3258 /// Writes or creates a boolean property.
\r
3259 /// If the property wasn't previously a boolean property, it is changed to a boolean property.
\r
3261 /// \param[in] session Specifies an ovrSession previously returned by ovr_Create.
\r
3262 /// \param[in] propertyName The name of the property, which needs to be valid only for the call.
\r
3263 /// \param[in] value The value to write.
\r
3264 /// \return Returns true if successful, otherwise false. A false result should only occur if the
\r
3266 /// name is empty or if the property is read-only.
\r
3267 OVR_PUBLIC_FUNCTION(ovrBool)
\r
3268 ovr_SetBool(ovrSession session, const char* propertyName, ovrBool value);
\r
3270 /// Reads an integer property.
\r
3272 /// \param[in] session Specifies an ovrSession previously returned by ovr_Create.
\r
3273 /// \param[in] propertyName The name of the property, which needs to be valid only for the call.
\r
3274 /// \param[in] defaultVal Specifes the value to return if the property couldn't be read.
\r
3275 /// \return Returns the property interpreted as an integer value. Returns defaultVal if
\r
3276 /// the property doesn't exist.
\r
3277 OVR_PUBLIC_FUNCTION(int) ovr_GetInt(ovrSession session, const char* propertyName, int defaultVal);
\r
3279 /// Writes or creates an integer property.
\r
3281 /// If the property wasn't previously a boolean property, it is changed to an integer property.
\r
3283 /// \param[in] session Specifies an ovrSession previously returned by ovr_Create.
\r
3284 /// \param[in] propertyName The name of the property, which needs to be valid only for the call.
\r
3285 /// \param[in] value The value to write.
\r
3286 /// \return Returns true if successful, otherwise false. A false result should only occur if the
\r
3287 /// property name is empty or if the property is read-only.
\r
3288 OVR_PUBLIC_FUNCTION(ovrBool) ovr_SetInt(ovrSession session, const char* propertyName, int value);
\r
3290 /// Reads a float property.
\r
3292 /// \param[in] session Specifies an ovrSession previously returned by ovr_Create.
\r
3293 /// \param[in] propertyName The name of the property, which needs to be valid only for the call.
\r
3294 /// \param[in] defaultVal specifes the value to return if the property couldn't be read.
\r
3295 /// \return Returns the property interpreted as an float value. Returns defaultVal if
\r
3296 /// the property doesn't exist.
\r
3297 OVR_PUBLIC_FUNCTION(float)
\r
3298 ovr_GetFloat(ovrSession session, const char* propertyName, float defaultVal);
\r
3300 /// Writes or creates a float property.
\r
3301 /// If the property wasn't previously a float property, it's changed to a float property.
\r
3303 /// \param[in] session Specifies an ovrSession previously returned by ovr_Create.
\r
3304 /// \param[in] propertyName The name of the property, which needs to be valid only for the call.
\r
3305 /// \param[in] value The value to write.
\r
3306 /// \return Returns true if successful, otherwise false. A false result should only occur if the
\r
3307 /// property name is empty or if the property is read-only.
\r
3308 OVR_PUBLIC_FUNCTION(ovrBool)
\r
3309 ovr_SetFloat(ovrSession session, const char* propertyName, float value);
\r
3311 /// Reads a float array property.
\r
3313 /// \param[in] session Specifies an ovrSession previously returned by ovr_Create.
\r
3314 /// \param[in] propertyName The name of the property, which needs to be valid only for the call.
\r
3315 /// \param[in] values An array of float to write to.
\r
3316 /// \param[in] valuesCapacity Specifies the maximum number of elements to write to the values array.
\r
3317 /// \return Returns the number of elements read, or 0 if property doesn't exist or is empty.
\r
3318 OVR_PUBLIC_FUNCTION(unsigned int)
\r
3319 ovr_GetFloatArray(
\r
3320 ovrSession session,
\r
3321 const char* propertyName,
\r
3323 unsigned int valuesCapacity);
\r
3325 /// Writes or creates a float array property.
\r
3327 /// \param[in] session Specifies an ovrSession previously returned by ovr_Create.
\r
3328 /// \param[in] propertyName The name of the property, which needs to be valid only for the call.
\r
3329 /// \param[in] values An array of float to write from.
\r
3330 /// \param[in] valuesSize Specifies the number of elements to write.
\r
3331 /// \return Returns true if successful, otherwise false. A false result should only occur if the
\r
3332 /// property name is empty or if the property is read-only.
\r
3333 OVR_PUBLIC_FUNCTION(ovrBool)
\r
3334 ovr_SetFloatArray(
\r
3335 ovrSession session,
\r
3336 const char* propertyName,
\r
3337 const float values[],
\r
3338 unsigned int valuesSize);
\r
3340 /// Reads a string property.
\r
3341 /// Strings are UTF8-encoded and null-terminated.
\r
3343 /// \param[in] session Specifies an ovrSession previously returned by ovr_Create.
\r
3344 /// \param[in] propertyName The name of the property, which needs to be valid only for the call.
\r
3345 /// \param[in] defaultVal Specifes the value to return if the property couldn't be read.
\r
3346 /// \return Returns the string property if it exists. Otherwise returns defaultVal, which can be
\r
3347 /// specified as NULL. The return memory is guaranteed to be valid until next call to
\r
3348 /// ovr_GetString or until the session is destroyed, whichever occurs first.
\r
3349 OVR_PUBLIC_FUNCTION(const char*)
\r
3350 ovr_GetString(ovrSession session, const char* propertyName, const char* defaultVal);
\r
3352 /// Writes or creates a string property.
\r
3353 /// Strings are UTF8-encoded and null-terminated.
\r
3355 /// \param[in] session Specifies an ovrSession previously returned by ovr_Create.
\r
3356 /// \param[in] propertyName The name of the property, which needs to be valid only for the call.
\r
3357 /// \param[in] value The string property, which only needs to be valid for the duration of the call.
\r
3358 /// \return Returns true if successful, otherwise false. A false result should only occur if the
\r
3359 /// property name is empty or if the property is read-only.
\r
3360 OVR_PUBLIC_FUNCTION(ovrBool)
\r
3361 ovr_SetString(ovrSession session, const char* propertyName, const char* value);
\r
3365 #endif // !defined(OVR_EXPORTING_CAPI)
\r
3367 #ifdef __cplusplus
\r
3371 #if defined(_MSC_VER)
\r
3372 #pragma warning(pop)
\r
3375 /// @cond DoxygenIgnore
\r
3378 OVR_STATIC_ASSERT(
\r
3379 sizeof(ovrTextureSwapChainDesc) == 10 * 4,
\r
3380 "ovrTextureSwapChainDesc size mismatch");
\r
3382 // -----------------------------------------------------------------------------------
\r
3383 // ***** Backward compatibility #includes
\r
3385 // This is at the bottom of this file because the following is dependent on the
\r
3386 // declarations above.
\r
3388 #if !defined(OVR_CAPI_NO_UTILS)
\r
3389 #include "Extras/OVR_CAPI_Util.h"
\r
3394 #endif // OVR_CAPI_h
\r