diff options
Diffstat (limited to 'ovr_sdk_win_23.0.0/LibOVR/Include/OVR_CAPI.h')
| -rw-r--r-- | ovr_sdk_win_23.0.0/LibOVR/Include/OVR_CAPI.h | 3715 |
1 files changed, 3715 insertions, 0 deletions
diff --git a/ovr_sdk_win_23.0.0/LibOVR/Include/OVR_CAPI.h b/ovr_sdk_win_23.0.0/LibOVR/Include/OVR_CAPI.h new file mode 100644 index 0000000..4e0b251 --- /dev/null +++ b/ovr_sdk_win_23.0.0/LibOVR/Include/OVR_CAPI.h @@ -0,0 +1,3715 @@ +/************************************************************************************ + \file OVR_CAPI.h + \brief C Interface to the Oculus PC SDK tracking and rendering library. + \copyright Copyright (c) Facebook Technologies, LLC and its affiliates. All rights reserved. + ************************************************************************************/ + +// We don't use version numbers within OVR_CAPI_h, as all versioned variations +// of this file are currently mutually exclusive. +#ifndef OVR_CAPI_h +#define OVR_CAPI_h + +#include "OVR_CAPI_Keys.h" +#include "OVR_ErrorCode.h" +#include "OVR_Version.h" + +#if !defined(_WIN32) +#include <sys/types.h> +#endif + + +#include <stdint.h> + +#if defined(_MSC_VER) +#pragma warning(push) +#pragma warning(disable : 4324) // structure was padded due to __declspec(align()) +#pragma warning(disable : 4359) // The alignment specified for a type is less than the +// alignment of the type of one of its data members +#endif + +//----------------------------------------------------------------------------------- +// ***** OVR_OS +// +#if !defined(OVR_OS_WIN32) && defined(_WIN32) +#define OVR_OS_WIN32 +#endif + +#if !defined(OVR_OS_MAC) && defined(__APPLE__) +#define OVR_OS_MAC +#endif + +#if !defined(OVR_OS_LINUX) && defined(__linux__) +#define OVR_OS_LINUX +#endif + +//----------------------------------------------------------------------------------- +// ***** OVR_CPP +// +#if !defined(OVR_CPP) +#if defined(__cplusplus) +#define OVR_CPP(x) x +#else +#define OVR_CPP(x) /* Not C++ */ +#endif +#endif + +//----------------------------------------------------------------------------------- +// ***** OVR_CDECL +// +/// LibOVR calling convention for 32-bit Windows builds. +// +#if !defined(OVR_CDECL) +#if defined(_WIN32) +#define OVR_CDECL __cdecl +#else +#define OVR_CDECL +#endif +#endif + +//----------------------------------------------------------------------------------- +// ***** OVR_EXTERN_C +// +/// Defined as extern "C" when built from C++ code. +// +#if !defined(OVR_EXTERN_C) +#ifdef __cplusplus +#define OVR_EXTERN_C extern "C" +#else +#define OVR_EXTERN_C +#endif +#endif + +//----------------------------------------------------------------------------------- +// ***** OVR_PUBLIC_FUNCTION / OVR_PRIVATE_FUNCTION +// +// OVR_PUBLIC_FUNCTION - Functions that externally visible from a shared library. +// Corresponds to Microsoft __dllexport. +// OVR_PUBLIC_CLASS - C++ structs and classes that are externally visible from a +// shared library. Corresponds to Microsoft __dllexport. +// OVR_PRIVATE_FUNCTION - Functions that are not visible outside of a shared library. +// They are private to the shared library. +// OVR_PRIVATE_CLASS - C++ structs and classes that are not visible outside of a +// shared library. They are private to the shared library. +// +// OVR_DLL_BUILD - Used to indicate that the current compilation unit is of a shared library. +// OVR_DLL_IMPORT - Used to indicate that the current compilation unit is a +// user of the corresponding shared library. +// OVR_STATIC_BUILD - used to indicate that the current compilation unit is not a +// shared library but rather statically linked code. +// +#if !defined(OVR_PUBLIC_FUNCTION) +#if defined(OVR_DLL_BUILD) +#if defined(_WIN32) +#define OVR_PUBLIC_FUNCTION(rval) OVR_EXTERN_C __declspec(dllexport) rval OVR_CDECL +#define OVR_PUBLIC_CLASS __declspec(dllexport) +#define OVR_PRIVATE_FUNCTION(rval) rval OVR_CDECL +#define OVR_PRIVATE_CLASS +#else +#define OVR_PUBLIC_FUNCTION(rval) \ + OVR_EXTERN_C __attribute__((visibility("default"))) rval OVR_CDECL /* Requires GCC 4.0+ */ +#define OVR_PUBLIC_CLASS __attribute__((visibility("default"))) /* Requires GCC 4.0+ */ +#define OVR_PRIVATE_FUNCTION(rval) __attribute__((visibility("hidden"))) rval OVR_CDECL +#define OVR_PRIVATE_CLASS __attribute__((visibility("hidden"))) +#endif +#elif defined(OVR_DLL_IMPORT) +#if defined(_WIN32) +#define OVR_PUBLIC_FUNCTION(rval) OVR_EXTERN_C __declspec(dllimport) rval OVR_CDECL +#define OVR_PUBLIC_CLASS __declspec(dllimport) +#else +#define OVR_PUBLIC_FUNCTION(rval) OVR_EXTERN_C rval OVR_CDECL +#define OVR_PUBLIC_CLASS +#endif +#define OVR_PRIVATE_FUNCTION(rval) rval OVR_CDECL +#define OVR_PRIVATE_CLASS +#else // OVR_STATIC_BUILD +#define OVR_PUBLIC_FUNCTION(rval) OVR_EXTERN_C rval OVR_CDECL +#define OVR_PUBLIC_CLASS +#define OVR_PRIVATE_FUNCTION(rval) rval OVR_CDECL +#define OVR_PRIVATE_CLASS +#endif +#endif + +//----------------------------------------------------------------------------------- +// ***** OVR_EXPORT +// +/// Provided for backward compatibility with older versions of this library. +// +#if !defined(OVR_EXPORT) +#ifdef OVR_OS_WIN32 +#define OVR_EXPORT __declspec(dllexport) +#else +#define OVR_EXPORT +#endif +#endif + +//----------------------------------------------------------------------------------- +// ***** OVR_ALIGNAS +// +#if !defined(OVR_ALIGNAS) +#if defined(__GNUC__) || defined(__clang__) +#define OVR_ALIGNAS(n) __attribute__((aligned(n))) +#elif defined(_MSC_VER) || defined(__INTEL_COMPILER) +#define OVR_ALIGNAS(n) __declspec(align(n)) +#elif defined(__CC_ARM) +#define OVR_ALIGNAS(n) __align(n) +#else +#error Need to define OVR_ALIGNAS +#endif +#endif + +//----------------------------------------------------------------------------------- +// ***** OVR_CC_HAS_FEATURE +// +// This is a portable way to use compile-time feature identification available +// with some compilers in a clean way. Direct usage of __has_feature in preprocessing +// statements of non-supporting compilers results in a preprocessing error. +// +// Example usage: +// #if OVR_CC_HAS_FEATURE(is_pod) +// if(__is_pod(T)) // If the type is plain data then we can safely memcpy it. +// memcpy(&destObject, &srcObject, sizeof(object)); +// #endif +// +#if !defined(OVR_CC_HAS_FEATURE) +#if defined(__clang__) // http://clang.llvm.org/docs/LanguageExtensions.html#id2 +#define OVR_CC_HAS_FEATURE(x) __has_feature(x) +#else +#define OVR_CC_HAS_FEATURE(x) 0 +#endif +#endif + +// ------------------------------------------------------------------------ +// ***** OVR_STATIC_ASSERT +// +// Portable support for C++11 static_assert(). +// Acts as if the following were declared: +// void OVR_STATIC_ASSERT(bool const_expression, const char* msg); +// +// Example usage: +// OVR_STATIC_ASSERT(sizeof(int32_t) == 4, "int32_t expected to be 4 bytes."); + +#if !defined(OVR_STATIC_ASSERT) +#if !(defined(__cplusplus) && (__cplusplus >= 201103L)) /* Other */ && \ + !(defined(__GXX_EXPERIMENTAL_CXX0X__)) /* GCC */ && \ + !(defined(__clang__) && defined(__cplusplus) && \ + OVR_CC_HAS_FEATURE(cxx_static_assert)) /* clang */ \ + && !(defined(_MSC_VER) && (_MSC_VER >= 1600) && defined(__cplusplus)) /* VS2010+ */ + +#if !defined(OVR_SA_UNUSED) +#if defined(OVR_CC_GNU) || defined(OVR_CC_CLANG) +#define OVR_SA_UNUSED __attribute__((unused)) +#else +#define OVR_SA_UNUSED +#endif +#define OVR_SA_PASTE(a, b) a##b +#define OVR_SA_HELP(a, b) OVR_SA_PASTE(a, b) +#endif + +#if defined(__COUNTER__) +#define OVR_STATIC_ASSERT(expression, msg) \ + typedef char OVR_SA_HELP(staticAssert, __COUNTER__)[((expression) != 0) ? 1 : -1] OVR_SA_UNUSED +#else +#define OVR_STATIC_ASSERT(expression, msg) \ + typedef char OVR_SA_HELP(staticAssert, __LINE__)[((expression) != 0) ? 1 : -1] OVR_SA_UNUSED +#endif + +#else +#define OVR_STATIC_ASSERT(expression, msg) static_assert(expression, msg) +#endif +#endif + +// OVR_STATIC_ASSERT_OFFSETOF statically asserts offsetof(Type.member) == expected_offset +#define OVR_STATIC_ASSERT_OFFSETOF(Type, member, expected_offset) \ + OVR_STATIC_ASSERT( \ + offsetof(Type, member) == (expected_offset), \ + "Expected " #Type "." #member " offset == " #expected_offset) + +// OVR_STATIC_ASSERT_SIZEOF statically asserts sizeof(Type) == expected_size +#define OVR_STATIC_ASSERT_SIZEOF(Type, expected_size) \ + OVR_STATIC_ASSERT( \ + sizeof(Type) == (expected_size), "Expected sizeof(" #Type ") == " #expected_size) + +//----------------------------------------------------------------------------------- +// ***** Padding +// +/// Defines explicitly unused space for a struct. +/// When used correcly, usage of this macro should not change the size of the struct. +/// Compile-time and runtime behavior with and without this defined should be identical. +/// +#if !defined(OVR_UNUSED_STRUCT_PAD) +#define OVR_UNUSED_STRUCT_PAD(padName, size) char padName[size]; +#endif + +//----------------------------------------------------------------------------------- +// ***** Word Size +// +/// Specifies the size of a pointer on the given platform. +/// +#if !defined(OVR_PTR_SIZE) +#if defined(__WORDSIZE) +#define OVR_PTR_SIZE ((__WORDSIZE) / 8) +#elif defined(_WIN64) || defined(__LP64__) || defined(_LP64) || defined(_M_IA64) || \ + defined(__ia64__) || defined(__arch64__) || defined(__64BIT__) || defined(__Ptr_Is_64) +#define OVR_PTR_SIZE 8 +#elif defined(__CC_ARM) && (__sizeof_ptr == 8) +#define OVR_PTR_SIZE 8 +#else +#define OVR_PTR_SIZE 4 +#endif +#endif + +//----------------------------------------------------------------------------------- +// ***** OVR_ON32 / OVR_ON64 +// +#if OVR_PTR_SIZE == 8 +#define OVR_ON32(x) +#define OVR_ON64(x) x +#else +#define OVR_ON32(x) x +#define OVR_ON64(x) +#endif + +//----------------------------------------------------------------------------------- +// ***** ovrBool + +typedef char ovrBool; ///< Boolean type +#define ovrFalse 0 ///< ovrBool value of false. +#define ovrTrue 1 ///< ovrBool value of true. + +//----------------------------------------------------------------------------------- +// ***** PFN_ovrVoidFunction +// +/// Defines a generic function pointer. +/// +/// \see ovr_GetInstanceProcAddr +/// +typedef void (*PFN_ovrVoidFunction)(void); + +//----------------------------------------------------------------------------------- +// ***** Simple Math Structures + +/// A RGBA color with normalized float components. +typedef struct OVR_ALIGNAS(4) ovrColorf_ { + float r, g, b, a; +} ovrColorf; + +/// A 2D vector with integer components. +typedef struct OVR_ALIGNAS(4) ovrVector2i_ { + int x, y; +} ovrVector2i; + +/// A 2D size with integer components. +typedef struct OVR_ALIGNAS(4) ovrSizei_ { + int w, h; +} ovrSizei; + +/// A 2D rectangle with a position and size. +/// All components are integers. +typedef struct OVR_ALIGNAS(4) ovrRecti_ { + ovrVector2i Pos; + ovrSizei Size; +} ovrRecti; + +/// A quaternion rotation. +typedef struct OVR_ALIGNAS(4) ovrQuatf_ { + float x, y, z, w; +} ovrQuatf; + +/// A 2D vector with float components. +typedef struct OVR_ALIGNAS(4) ovrVector2f_ { + float x, y; +} ovrVector2f; + +/// A 3D vector with float components. +typedef struct OVR_ALIGNAS(4) ovrVector3f_ { + float x, y, z; +} ovrVector3f; + +/// A 4D vector with float components. +typedef struct OVR_ALIGNAS(4) ovrVector4f_ { + float x, y, z, w; +} ovrVector4f; + +/// A 4D vector with int16_t components. +typedef struct OVR_ALIGNAS(4) ovrVector4s_ { + int16_t x, y, z, w; +} ovrVector4s; + +/// A 4x4 matrix with float elements. +typedef struct OVR_ALIGNAS(4) ovrMatrix4f_ { + float M[4][4]; +} ovrMatrix4f; + +/// Position and orientation together. +/// The coordinate system used is right-handed Cartesian. +typedef struct OVR_ALIGNAS(4) ovrPosef_ { + ovrQuatf Orientation; + ovrVector3f Position; +} ovrPosef; + +/// A full pose (rigid body) configuration with first and second derivatives. +/// +/// Body refers to any object for which ovrPoseStatef is providing data. +/// It can be the HMD, Touch controller, sensor or something else. The context +/// depends on the usage of the struct. +typedef struct OVR_ALIGNAS(8) ovrPoseStatef_ { + ovrPosef ThePose; ///< Position and orientation. + ovrVector3f AngularVelocity; ///< Angular velocity in radians per second. + ovrVector3f LinearVelocity; ///< Velocity in meters per second. + ovrVector3f AngularAcceleration; ///< Angular acceleration in radians per second per second. + ovrVector3f LinearAcceleration; ///< Acceleration in meters per second per second. + OVR_UNUSED_STRUCT_PAD(pad0, 4) ///< \internal struct pad. + double TimeInSeconds; ///< Absolute time that this pose refers to. \see ovr_GetTimeInSeconds +} ovrPoseStatef; + +/// Describes the up, down, left, and right angles of the field of view. +/// +/// Field Of View (FOV) tangent of the angle units. +/// \note For a standard 90 degree vertical FOV, we would +/// have: { UpTan = tan(90 degrees / 2), DownTan = tan(90 degrees / 2) }. +typedef struct OVR_ALIGNAS(4) ovrFovPort_ { + float UpTan; ///< Tangent of the angle between the viewing vector and top edge of the FOV. + float DownTan; ///< Tangent of the angle between the viewing vector and bottom edge of the FOV. + float LeftTan; ///< Tangent of the angle between the viewing vector and left edge of the FOV. + float RightTan; ///< Tangent of the angle between the viewing vector and right edge of the FOV. +} ovrFovPort; + +//----------------------------------------------------------------------------------- +// ***** HMD Types + +/// Enumerates all HMD types that we support. +/// +/// The currently released developer kits are ovrHmd_DK1 and ovrHmd_DK2. +/// The other enumerations are for internal use only. +typedef enum ovrHmdType_ { + ovrHmd_None = 0, + ovrHmd_DK1 = 3, + ovrHmd_DKHD = 4, + ovrHmd_DK2 = 6, + ovrHmd_CB = 8, + ovrHmd_Other = 9, + ovrHmd_E3_2015 = 10, + ovrHmd_ES06 = 11, + ovrHmd_ES09 = 12, + ovrHmd_ES11 = 13, + ovrHmd_CV1 = 14, + ovrHmd_RiftS = 16, + ovrHmd_Quest = 19, + ovrHmd_Quest2 = 20, + ovrHmd_EnumSize = 0x7fffffff ///< \internal Force type int32_t. +} ovrHmdType; + +/// HMD capability bits reported by device. +/// +typedef enum ovrHmdCaps_ { + // Read-only flags + + /// <B>(read only)</B> Specifies that the HMD is a virtual debug device. + ovrHmdCap_DebugDevice = 0x0010, + + + ovrHmdCap_EnumSize = 0x7fffffff ///< \internal Force type int32_t. +} ovrHmdCaps; + +/// Tracking capability bits reported by the device. +/// Used with ovr_GetTrackingCaps. +typedef enum ovrTrackingCaps_ { + ovrTrackingCap_Orientation = 0x0010, ///< Supports orientation tracking (IMU). + ovrTrackingCap_MagYawCorrection = 0x0020, ///< Supports yaw drift correction. + ovrTrackingCap_Position = 0x0040, ///< Supports positional tracking. + ovrTrackingCap_EnumSize = 0x7fffffff ///< \internal Force type int32_t. +} ovrTrackingCaps; + +/// Defines the largest size for an extension name string, including the '\0' terminator. +/// +/// \see ovrExtensionProperties +/// +#define OVR_MAX_EXTENSION_NAME_SIZE 128 + +/// Describes the properties of an API extension. +/// +/// \see ovr_EnumerateInstanceExtensionProperties +/// +typedef struct ovrExtensionProperties_ { + int extensionId; // One of enum ovrExtensions or a dynamic value. + char extensionName[OVR_MAX_EXTENSION_NAME_SIZE]; + uint32_t extensionVersion; // OpenXR-like version. Version compatibility is identified by the + // extension documentation. +} ovrExtensionProperties; + +/// Optional extensions +typedef enum ovrExtensions_ { + ovrExtension_TextureLayout_Octilinear = 0, ///< Enable before first layer submission. + ovrExtension_Count, ///< \internal Sanity checking + ovrExtension_EnumSize = 0x7fffffff ///< \internal Force type int32_t. +} ovrExtensions; + +/// Specifies which eye is being used for rendering. +/// This type explicitly does not include a third "NoStereo" monoscopic option, +/// as such is not required for an HMD-centered API. +typedef enum ovrEyeType_ { + ovrEye_Left = 0, ///< The left eye, from the viewer's perspective. + ovrEye_Right = 1, ///< The right eye, from the viewer's perspective. + ovrEye_Count = 2, ///< \internal Count of enumerated elements. + ovrEye_EnumSize = 0x7fffffff ///< \internal Force type int32_t. +} ovrEyeType; + +/// Specifies the coordinate system ovrTrackingState returns tracking poses in. +/// Used with ovr_SetTrackingOriginType() +typedef enum ovrTrackingOrigin_ { + /// \brief Tracking system origin reported at eye (HMD) height + /// \details Prefer using this origin when your application requires + /// matching user's current physical head pose to a virtual head pose + /// without any regards to a the height of the floor. Cockpit-based, + /// or 3rd-person experiences are ideal candidates. + /// When used, all poses in ovrTrackingState are reported as an offset + /// transform from the profile calibrated or recentered HMD pose. + /// It is recommended that apps using this origin type call ovr_RecenterTrackingOrigin + /// prior to starting the VR experience, but notify the user before doing so + /// to make sure the user is in a comfortable pose, facing a comfortable + /// direction. + ovrTrackingOrigin_EyeLevel = 0, + + /// \brief Tracking system origin reported at floor height + /// \details Prefer using this origin when your application requires the + /// physical floor height to match the virtual floor height, such as + /// standing experiences. + /// When used, all poses in ovrTrackingState are reported as an offset + /// transform from the profile calibrated floor pose. Calling ovr_RecenterTrackingOrigin + /// will recenter the X & Z axes as well as yaw, but the Y-axis (i.e. height) will continue + /// to be reported using the floor height as the origin for all poses. + ovrTrackingOrigin_FloorLevel = 1, + + ovrTrackingOrigin_Count = 2, ///< \internal Count of enumerated elements. + ovrTrackingOrigin_EnumSize = 0x7fffffff ///< \internal Force type int32_t. +} ovrTrackingOrigin; + +/// Color space types for HMDs +/// +/// Until ovr_SetClientColorDesc is called, for backwards compatibility, a new session will start +/// with 'ovrColorSpace_Unknown' which will default to 'ovrColorSpace_Rift_CV1'. This assumes the +/// app visuals were authored to be viewed in a Rift CV1 HMD. Therefore it does the following: +/// - For Rift CV1, assumes submitted images are authored for CV1 color space, and keeps them as is. +/// - For Rift S and Quest (via Oculus Link), converts images to reproduce CV1's color space. +/// +/// This API only handles color-space remapping. Unless specified, all color spaces use D65 white +/// point. This API will not affect brightness, contrast or gamma curves. Some of these aspects such +/// as gamma, is handled by the texture format being used. From the GPU samplers' point-of-view, +/// each texture will continue to be treated as linear luminance including the sRGB format which is +/// converted to linear by the texture sampler. +/// +/// It is recommended that content is authored for the Rift CV1 color space as it has a wider color +/// gamut than the Rift S. If content is authored to a narrow color space such as "Rec. 709" or +/// "Rift S", this can lead to content looking "dull", "washed out" or "desaturated" when viewed in +/// a wider-color-space-capable device such as Rift CV1 and Quest. This is because the colors stored +/// in the submitted images will no longer be able to hit the deeper saturated chromaticity values. +/// +/// Using 'ovrColorSpace_Unmanaged' will force the runtime to skip color correction on to the +/// provided content. This is not recommended unless the app developer is sure about what they're +/// doing. 'ovrColorSpace_Unmanaged' is mostly useful for research & experimentation, but not for +/// software distribution. This is because unless the client is applying the necessary corrections +/// for each HMD type, the results seen in the HMD will be uncalibrated. This is especially true for +/// future HMDs where the color space is not yet known or defined, leading to colors that might look +/// too dull or saturated. +/// +/// Requested rectilinear-mirror outputs are composited without any color space adjustment. +/// However, if client requests a post-distortion (i.e. non-rectilinear) mirror output, it will be +/// provided with the same color adjustment that was applied for the HMD output. Therefore, +/// post-distortion mirror output are not guaranteed to have acceptable color-space accuracy +/// for desktop viewing. +/// +/// Color Space Details with Chromaticity Primaries in CIE 1931 xy: +/// +/// Color Space: Rift CV1 between P3 & Adobe RGB using D75 white point +/// Red : (0.666, 0.334) +/// Green: (0.238, 0.714) +/// Blue : (0.139, 0.053) +/// White: (0.298, 0.318) +/// +/// Color Space: Quest similar to Rift CV1 using D75 white point +/// Red : (0.661, 0.338) +/// Green: (0.228, 0.718) +/// Blue : (0.142, 0.042) +/// White: (0.298, 0.318) +/// +/// Color Space: Rift S similar to Rec 709 using D75 +/// Red : (0.640, 0.330) +/// Green: (0.292, 0.586) +/// Blue : (0.156, 0.058) +/// White: (0.298, 0.318) +/// +/// Color Space: P3, similar to DCI-P3, but using D65 white point instead. +/// Red : (0.680, 0.320) +/// Green: (0.265, 0.690) +/// Blue : (0.150, 0.060) +/// White: (0.313, 0.329) +/// +/// Note: Due to LCD limitations, the Rift S display will not be able to meaningfully differentiate +/// brightness levels below 13 out of 255 for 8-bit sRGB or 0.0015 out of 1.0 max for linear-RGB +/// shader output values. To that end, it is recommended that reliance on a dark and narrow gamut is +/// avoided, and the content is instead spread across a larger brightness range when possible. +/// +typedef enum ovrColorSpace_ { + ovrColorSpace_Unknown = 0, ///< Default value until client sets calls ovr_SetClientColorDesc + ovrColorSpace_Unmanaged = 1, ///< See notes above. No correction, i.e. color space of active HMD + ovrColorSpace_Rift_CV1 = 2, ///< See notes above. Unique color space. + ovrColorSpace_Rift_S = 3, ///< See notes above. Unique color space. + ovrColorSpace_Quest = 4, ///< See notes above. Unique color space. + ovrColorSpace_Rec_2020 = 5, ///< Standard Rec. 2020 chromaticities + ovrColorSpace_Rec_709 = 6, ///< Standard Rec. 709 chromaticities, similar to sRGB + ovrColorSpace_P3 = 7, ///< See notes above + ovrColorSpace_Adobe_RGB = 8, ///< Standard AdobeRGB chromaticities + ovrColorSpace_Count = 9, + + ovrColorSpace_EnumSize = 0x7fffffff ///< \internal Force type int32_t. +} ovrColorSpace; + +typedef struct OVR_ALIGNAS(OVR_PTR_SIZE) ovrHmdColorDesc_ { + /// Approximate color space the HMD display can output. + /// Use ColorPrimaries for more precise color space definition including white point (e.g. DN75) + ovrColorSpace ColorSpace; + OVR_UNUSED_STRUCT_PAD(pad0, 4) ///< \internal struct pad. +} ovrHmdColorDesc; + +/// Identifies a graphics device in a platform-specific way. +/// For Windows this is a LUID type. +typedef struct OVR_ALIGNAS(OVR_PTR_SIZE) ovrGraphicsLuid_ { + // Public definition reserves space for graphics API-specific implementation + char Reserved[8]; +} ovrGraphicsLuid; + +/// This is a complete descriptor of the HMD. +typedef struct OVR_ALIGNAS(OVR_PTR_SIZE) ovrHmdDesc_ { + ovrHmdType Type; ///< The type of HMD. + OVR_ON64(OVR_UNUSED_STRUCT_PAD(pad0, 4)) ///< \internal struct padding. + char ProductName[64]; ///< UTF8-encoded product identification string (e.g. "Oculus Rift DK1"). + char Manufacturer[64]; ///< UTF8-encoded HMD manufacturer identification string. + short VendorId; ///< HID (USB) vendor identifier of the device. + short ProductId; ///< HID (USB) product identifier of the device. + char SerialNumber[24]; ///< HMD serial number. + short FirmwareMajor; ///< HMD firmware major version. + short FirmwareMinor; ///< HMD firmware minor version. + unsigned int AvailableHmdCaps; ///< Available ovrHmdCaps bits. + unsigned int DefaultHmdCaps; ///< Default ovrHmdCaps bits. + unsigned int AvailableTrackingCaps; ///< Available ovrTrackingCaps bits. + unsigned int DefaultTrackingCaps; ///< Default ovrTrackingCaps bits. + ovrFovPort DefaultEyeFov[ovrEye_Count]; ///< Defines the recommended FOVs for the HMD. + ovrFovPort MaxEyeFov[ovrEye_Count]; ///< Defines the maximum FOVs for the HMD. + ovrSizei Resolution; ///< Resolution of the full HMD screen (both eyes) in pixels. + float DisplayRefreshRate; ///< Refresh rate of the display in cycles per second. + OVR_ON64(OVR_UNUSED_STRUCT_PAD(pad1, 4)) ///< \internal struct padding. +} ovrHmdDesc; + +/// Used as an opaque pointer to an OVR session. +typedef struct ovrHmdStruct* ovrSession; + +#ifdef OVR_OS_WIN32 +typedef uint32_t ovrProcessId; +#else +typedef pid_t ovrProcessId; +#endif + +/// Fallback definitions for when the vulkan header isn't being included +#if !defined(VK_VERSION_1_0) +// From <vulkan/vulkan.h>: +#define VK_DEFINE_HANDLE(object) typedef struct object##_T* object; +#if defined(__LP64__) || defined(_WIN64) || (defined(__x86_64__) && !defined(__ILP32__)) || \ + defined(_M_X64) || defined(__ia64) || defined(_M_IA64) || defined(__aarch64__) || \ + defined(__powerpc64__) +#define VK_DEFINE_NON_DISPATCHABLE_HANDLE(object) typedef struct object##_T* object; +#else +#define VK_DEFINE_NON_DISPATCHABLE_HANDLE(object) typedef uint64_t object; +#endif +VK_DEFINE_HANDLE(VkInstance) +VK_DEFINE_HANDLE(VkPhysicalDevice) +VK_DEFINE_HANDLE(VkDevice) +VK_DEFINE_HANDLE(VkQueue) +VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkImage) +#endif + +/// Bit flags describing the current status of sensor tracking. +/// The values must be the same as in enum StatusBits +/// +/// \see ovrTrackingState +/// +typedef enum ovrStatusBits_ { + // Device orientation is currently tracked. It's possible that the device orientation is not + // tracked, + // but its reported orientation is nevertheless valid (e.g. due to estimation) + ovrStatus_OrientationTracked = 0x0001, + + // Device position is currently tracked. It's possible that the device position is not tracked, + // but its reported position is nevertheless valid (e.g. due to estimation). + ovrStatus_PositionTracked = 0x0002, + + // The reported device orientation is valid for application use. In the case that OrientationValid + // is true and + // OrientationTracked is false, the runtime may be estimating the orientation of the device. + // In the case that OrientationValid is false, the application should not use the returned + // orientation value. + ovrStatus_OrientationValid = 0x0004, + + // The reported device orientation is valid for application use. In the case that PositionValid is + // true and + // PositionTracked is false, the runtime may be estimating the position of the device. + // In the case that PositionValid is false, the application should not use the returned position + // value. + ovrStatus_PositionValid = 0x0008 +} ovrStatusBits; + +/// Specifies the description of a single sensor. +/// +/// \see ovr_GetTrackerDesc +/// +typedef struct OVR_ALIGNAS(OVR_PTR_SIZE) ovrTrackerDesc_ { + float FrustumHFovInRadians; ///< Sensor frustum horizontal field-of-view (if present). + float FrustumVFovInRadians; ///< Sensor frustum vertical field-of-view (if present). + float FrustumNearZInMeters; ///< Sensor frustum near Z (if present). + float FrustumFarZInMeters; ///< Sensor frustum far Z (if present). +} ovrTrackerDesc; + +/// Specifies sensor flags. +/// +/// /see ovrTrackerPose +/// +typedef enum ovrTrackerFlags_ { + /// The sensor is present, else the sensor is absent or offline. + ovrTracker_Connected = 0x0020, + + /// The sensor has a valid pose, else the pose is unavailable. + /// This will only be set if ovrTracker_Connected is set. + ovrTracker_PoseTracked = 0x0004 +} ovrTrackerFlags; + +/// Specifies the pose for a single sensor. +/// +typedef struct OVR_ALIGNAS(8) _ovrTrackerPose { + /// ovrTrackerFlags. + unsigned int TrackerFlags; + + /// The sensor's pose. This pose includes sensor tilt (roll and pitch). + /// For a leveled coordinate system use LeveledPose. + ovrPosef Pose; + + /// The sensor's leveled pose, aligned with gravity. This value includes pos and yaw of the + /// sensor, but not roll and pitch. It can be used as a reference point to render real-world + /// objects in the correct location. + ovrPosef LeveledPose; + + OVR_UNUSED_STRUCT_PAD(pad0, 4) ///< \internal struct pad. +} ovrTrackerPose; + +/// Tracking state at a given absolute time (describes predicted HMD pose, etc.). +/// Returned by ovr_GetTrackingState. +/// +/// \see ovr_GetTrackingState +/// +typedef struct OVR_ALIGNAS(8) ovrTrackingState_ { + /// Predicted head pose (and derivatives) at the requested absolute time. + ovrPoseStatef HeadPose; + + /// HeadPose tracking status described by ovrStatusBits. + unsigned int StatusFlags; + + /// The most recent calculated pose for each hand when hand controller tracking is present. + /// HandPoses[ovrHand_Left] refers to the left hand and HandPoses[ovrHand_Right] to the right. + /// These values can be combined with ovrInputState for complete hand controller information. + ovrPoseStatef HandPoses[2]; + + /// HandPoses status flags described by ovrStatusBits. + unsigned int HandStatusFlags[2]; + + /// The pose of the origin captured during calibration. + /// Like all other poses here, this is expressed in the space set by ovr_RecenterTrackingOrigin, + /// or ovr_SpecifyTrackingOrigin and so will change every time either of those functions are + /// called. This pose can be used to calculate where the calibrated origin lands in the new + /// recentered space. If an application never calls ovr_RecenterTrackingOrigin or + /// ovr_SpecifyTrackingOrigin, expect this value to be the identity pose and as such will point + /// respective origin based on ovrTrackingOrigin requested when calling ovr_GetTrackingState. + ovrPosef CalibratedOrigin; + +} ovrTrackingState; + + + +/// Rendering information for each eye. Computed by ovr_GetRenderDesc() based on the +/// specified FOV. Note that the rendering viewport is not included +/// here as it can be specified separately and modified per frame by +/// passing different Viewport values in the layer structure. +/// +/// \see ovr_GetRenderDesc +/// +typedef struct OVR_ALIGNAS(4) ovrEyeRenderDesc_ { + ovrEyeType Eye; ///< The eye index to which this instance corresponds. + ovrFovPort Fov; ///< The field of view. + ovrRecti DistortedViewport; ///< Distortion viewport. + ovrVector2f PixelsPerTanAngleAtCenter; ///< How many display pixels will fit in tan(angle) = 1. + ovrPosef HmdToEyePose; ///< Transform of eye from the HMD center, in meters. +} ovrEyeRenderDesc; + +/// Projection information for ovrLayerEyeFovDepth. +/// +/// Use the utility function ovrTimewarpProjectionDesc_FromProjection to +/// generate this structure from the application's projection matrix. +/// +/// \see ovrLayerEyeFovDepth, ovrTimewarpProjectionDesc_FromProjection +/// +typedef struct OVR_ALIGNAS(4) ovrTimewarpProjectionDesc_ { + float Projection22; ///< Projection matrix element [2][2]. + float Projection23; ///< Projection matrix element [2][3]. + float Projection32; ///< Projection matrix element [3][2]. +} ovrTimewarpProjectionDesc; + + +/// Contains the data necessary to properly calculate position info for various layer types. +/// - HmdToEyePose is the same value-pair provided in ovrEyeRenderDesc. Modifying this value is +/// suggested only if the app is forcing monoscopic rendering and requires that all layers +/// including quad layers show up in a monoscopic fashion. +/// - HmdSpaceToWorldScaleInMeters is used to scale player motion into in-application units. +/// In other words, it is how big an in-application unit is in the player's physical meters. +/// For example, if the application uses inches as its units then HmdSpaceToWorldScaleInMeters +/// would be 0.0254. +/// Note that if you are scaling the player in size, this must also scale. So if your application +/// units are inches, but you're shrinking the player to half their normal size, then +/// HmdSpaceToWorldScaleInMeters would be 0.0254*2.0. +/// +/// \see ovrEyeRenderDesc, ovr_SubmitFrame +/// +typedef struct OVR_ALIGNAS(4) ovrViewScaleDesc_ { + ovrPosef HmdToEyePose[ovrEye_Count]; ///< Transform of each eye from the HMD center, in meters. + float HmdSpaceToWorldScaleInMeters; ///< Ratio of viewer units to meter units. +} ovrViewScaleDesc; + +//----------------------------------------------------------------------------------- +// ***** Platform-independent Rendering Configuration + +/// The type of texture resource. +/// +/// \see ovrTextureSwapChainDesc +/// +typedef enum ovrTextureType_ { + ovrTexture_2D = 0, ///< 2D textures or texture arrays. + ovrTexture_2D_External = 1, ///< Application-provided 2D texture. Not supported on PC. + ovrTexture_Cube = 2, ///< Cube maps. ovrTextureSwapChainDesc::ArraySize must be 6 for this type. + ovrTexture_Count, + ovrTexture_EnumSize = 0x7fffffff ///< \internal Force type int32_t. +} ovrTextureType; + +/// The bindings required for texture swap chain. +/// +/// All texture swap chains are automatically bindable as shader +/// input resources since the Oculus runtime needs this to read them. +/// +/// \see ovrTextureSwapChainDesc +/// +typedef enum ovrTextureBindFlags_ { + ovrTextureBind_None, + + /// The application can write into the chain with pixel shader. + ovrTextureBind_DX_RenderTarget = 0x0001, + + /// The application can write to the chain with compute shader. + ovrTextureBind_DX_UnorderedAccess = 0x0002, + + /// The chain buffers can be bound as depth and/or stencil buffers. + /// This flag cannot be combined with ovrTextureBind_DX_RenderTarget. + ovrTextureBind_DX_DepthStencil = 0x0004, + + + ovrTextureBind_EnumSize = 0x7fffffff ///< \internal Force type int32_t. +} ovrTextureBindFlags; + +/// The format of a texture. +/// +/// \see ovrTextureSwapChainDesc +/// +typedef enum ovrTextureFormat_ { + OVR_FORMAT_UNKNOWN = 0, + OVR_FORMAT_B5G6R5_UNORM = 1, ///< Not currently supported on PC. Requires a DirectX 11.1 device. + OVR_FORMAT_B5G5R5A1_UNORM = 2, ///< Not currently supported on PC. Requires a DirectX 11.1 device. + OVR_FORMAT_B4G4R4A4_UNORM = 3, ///< Not currently supported on PC. Requires a DirectX 11.1 device. + OVR_FORMAT_R8G8B8A8_UNORM = 4, + OVR_FORMAT_R8G8B8A8_UNORM_SRGB = 5, + OVR_FORMAT_B8G8R8A8_UNORM = 6, + OVR_FORMAT_B8G8R8_UNORM = 27, ///< Not currently supported. + OVR_FORMAT_B8G8R8A8_UNORM_SRGB = 7, ///< Not supported for OpenGL applications + OVR_FORMAT_B8G8R8X8_UNORM = 8, ///< Not supported for OpenGL applications + OVR_FORMAT_B8G8R8X8_UNORM_SRGB = 9, ///< Not supported for OpenGL applications + OVR_FORMAT_R16G16B16A16_FLOAT = 10, + OVR_FORMAT_R11G11B10_FLOAT = 25, ///< Not supported for D3D12 applications. Introduced in v1.10 + + // Depth formats + OVR_FORMAT_D16_UNORM = 11, + OVR_FORMAT_D24_UNORM_S8_UINT = 12, + OVR_FORMAT_D32_FLOAT = 13, + OVR_FORMAT_D32_FLOAT_S8X24_UINT = 14, + + // Added in 1.5 compressed formats can be used for static layers + OVR_FORMAT_BC1_UNORM = 15, + OVR_FORMAT_BC1_UNORM_SRGB = 16, + OVR_FORMAT_BC2_UNORM = 17, + OVR_FORMAT_BC2_UNORM_SRGB = 18, + OVR_FORMAT_BC3_UNORM = 19, + OVR_FORMAT_BC3_UNORM_SRGB = 20, + OVR_FORMAT_BC6H_UF16 = 21, + OVR_FORMAT_BC6H_SF16 = 22, + OVR_FORMAT_BC7_UNORM = 23, + OVR_FORMAT_BC7_UNORM_SRGB = 24, + + + OVR_FORMAT_LAST, + OVR_FORMAT_ENUMSIZE = 0x7fffffff ///< \internal Force type int32_t. +} ovrTextureFormat; + +/// Misc flags overriding particular +/// behaviors of a texture swap chain +/// +/// \see ovrTextureSwapChainDesc +/// +typedef enum ovrTextureMiscFlags_ { + ovrTextureMisc_None, + + /// Vulkan and DX only: The underlying texture is created with a TYPELESS equivalent + /// of the format specified in the texture desc. The SDK will still access the + /// texture using the format specified in the texture desc, but the app can + /// create views with different formats if this is specified. + ovrTextureMisc_DX_Typeless = 0x0001, + + /// DX only: Allow generation of the mip chain on the GPU via the GenerateMips + /// call. This flag requires that RenderTarget binding also be specified. + ovrTextureMisc_AllowGenerateMips = 0x0002, + + /// Texture swap chain contains protected content, and requires + /// HDCP connection in order to display to HMD. Also prevents + /// mirroring or other redirection of any frame containing this contents + ovrTextureMisc_ProtectedContent = 0x0004, + + /// Automatically generate and use the mip chain in composition on each submission. + /// Mips are regenerated from highest quality level, ignoring other pre-existing mip levels. + /// Not supported for depth or compressed (BC) formats. + ovrTextureMisc_AutoGenerateMips = 0x0008, + + + ovrTextureMisc_EnumSize = 0x7fffffff ///< \internal Force type int32_t. +} ovrTextureFlags; + +/// Description used to create a texture swap chain. +/// +/// \see ovr_CreateTextureSwapChainDX +/// \see ovr_CreateTextureSwapChainGL +/// \see ovr_CreateTextureSwapChainVk +/// +typedef struct ovrTextureSwapChainDesc_ { + ovrTextureType Type; ///< Must be ovrTexture_2D or ovrTexture_Cube. + ovrTextureFormat Format; + int ArraySize; ///< Must be 6 for ovrTexture_Cube, size of texture array otherwise. + int Width; + int Height; + int MipLevels; + int SampleCount; + ovrBool StaticImage; ///< Not buffered in a chain. For images that don't change + OVR_ALIGNAS(4) unsigned int MiscFlags; ///< ovrTextureFlags + OVR_ALIGNAS(4) unsigned int BindFlags; ///< ovrTextureBindFlags. Not used for GL. +} ovrTextureSwapChainDesc; + +/// Bit flags used as part of ovrMirrorTextureDesc's MirrorOptions field. +/// +/// \see ovr_CreateMirrorTextureWithOptionsDX +/// \see ovr_CreateMirrorTextureWithOptionsGL +/// \see ovr_CreateMirrorTextureWithOptionsVk +/// +typedef enum ovrMirrorOptions_ { + /// By default the mirror texture will be: + /// * Pre-distortion (i.e. rectilinear) + /// * Contain both eye textures + /// * Exclude Guardian, Notifications, System Menu GUI + ovrMirrorOption_Default = 0x0000, + + /// Retrieves the barrel distorted texture contents instead of the rectilinear one + /// This is only recommended for debugging purposes, and not for final desktop presentation + ovrMirrorOption_PostDistortion = 0x0001, + + /// Since ovrMirrorOption_Default renders both eyes into the mirror texture, + /// these two flags are exclusive (i.e. cannot use them simultaneously) + ovrMirrorOption_LeftEyeOnly = 0x0002, + ovrMirrorOption_RightEyeOnly = 0x0004, + + /// Shows the boundary system aka Guardian on the mirror texture + ovrMirrorOption_IncludeGuardian = 0x0008, + + /// Shows system notifications the user receives on the mirror texture + ovrMirrorOption_IncludeNotifications = 0x0010, + + /// Shows the system menu (triggered by hitting the Home button) on the mirror texture + ovrMirrorOption_IncludeSystemGui = 0x0020, + + /// Forces mirror output to use max symmetric FOV instead of asymmetric full FOV used by HMD. + /// Only valid for rectilinear mirrors i.e. using ovrMirrorOption_PostDistortion with + /// ovrMirrorOption_ForceSymmetricFov will result in ovrError_InvalidParameter error. + ovrMirrorOption_ForceSymmetricFov = 0x0040, + + + ovrMirrorOption_EnumSize = 0x7fffffff ///< \internal Force type int32_t. +} ovrMirrorOptions; + +/// Description used to create a mirror texture. +/// +/// \see ovr_CreateMirrorTextureWithOptionsDX +/// \see ovr_CreateMirrorTextureWithOptionsGL +/// \see ovr_CreateMirrorTextureWithOptionsVk +/// +typedef struct ovrMirrorTextureDesc_ { + ovrTextureFormat Format; + int Width; + int Height; + unsigned int MiscFlags; ///< ovrTextureFlags + unsigned int MirrorOptions; ///< ovrMirrorOptions +} ovrMirrorTextureDesc; + +typedef struct ovrTextureSwapChainData* ovrTextureSwapChain; +typedef struct ovrMirrorTextureData* ovrMirrorTexture; + +//----------------------------------------------------------------------------------- + +/// Fov-stencil mesh for assisting in rendering efficiency for clients using EyeFov layers + +/// A fov-stencil mesh is used to cull out the parts of the eye render target used in +/// ovrLayerType_EyeFov & ovrLayerType_EyeFovDepth layers that would not normally be visible to +/// the user wearing the HMD. +/// +/// A rasterized eye render target is rectangular, but the parts of the render target visible to the +/// user do not necessarily follow a rectangular region. This is where the fov-stencil mesh +/// helps designate the boundaries of the visible parts for a given eye render target. +/// +/// To make effective use of this mesh, the client should render the mesh before kicking off any +/// other rendering work. Ideally the mesh would be rendered at the near-depth plane distance, or +/// into the stencil buffer right after clearing the depth-stencil buffer. The choice of using +/// depth vs. stencil is left up to the client, but the client should make sure that the mesh is +/// rendered in a way that it can make use of Hierarchical-Z or Hierarchical-Stencil for better +/// performance on rejected geometry post-vertex shading. + +/// Viewport stencil types provided by the ovr_GetFovStencil call. +/// \see ovr_GetFovStencil +typedef enum ovrFovStencilType_ { + ovrFovStencil_HiddenArea = 0, ///< Triangle list covering parts that are hidden to users + ovrFovStencil_VisibleArea = 1, ///< Triangle list covering parts that are visible to users + ovrFovStencil_BorderLine = 2, ///< Line list that draws the boundary visible to users + ovrFovStencil_VisibleRectangle = 3, ///< Axis-aligned rectangle fit in visible region + ///< 4x vertices: TopLeft, TopRight, BottomRight, BottomLeft + + ovrFovStencilType_EnumSize = 0x7fffffff ///< \internal Force type int32_t. +} ovrFovStencilType; + +/// Identifies flags used by ovrFovStencilDesc and which are passed to ovr_GetFovStencil. +/// \see ovrFovStencilDesc +typedef enum ovrFovStencilFlags_ { + + /// When used, flips the Y component of the provided 2D mesh coordinates, such that Y increases + /// upwards. When not used, places mesh origin at top-left where Y increases downwards. + ovrFovStencilFlag_MeshOriginAtBottomLeft = 0x01, + + ovrFovStencilFlag_EnumSize = 0x7fffffff ///< \internal Force type int32_t. +} ovrFovStencilFlags; + +/// Fov-stencil mesh descriptor passed into the function ovr_GetFovStencil +/// \see ovr_GetFovStencil +typedef struct OVR_ALIGNAS(OVR_PTR_SIZE) ovrFovStencilDesc_ { + ovrFovStencilType StencilType; + uint32_t StencilFlags; ///< Bit flag combination of ovrFovStencilFlags + ovrEyeType Eye; + ovrFovPort FovPort; ///< Typically FOV obtained from ovrEyeRenderDesc + ovrQuatf HmdToEyeRotation; ///< Typically HmdToEyePose.Orientation obtained from ovrEyeRenderDesc + ///< Note: Currently unsupported, always treated as identity +} ovrFovStencilDesc; + +/// Contains the data for the fov-stencil mesh. Parts of the struct are filled by the caller +/// while some parts are filled by the SDK. +/// \see ovr_GetFovStencil +typedef struct OVR_ALIGNAS(OVR_PTR_SIZE) ovrFovStencilMeshBuffer_ { + /// Vertex info + int AllocVertexCount; ///< To be filled in by caller of ovr_GetFovStencil + int UsedVertexCount; ///< To be filled in by SDK and returned to caller + ovrVector2f* VertexBuffer; ///< To be allocated by caller and filled in by SDK + + /// Index info + int AllocIndexCount; ///< To be filled in by caller of ovr_GetFovStencil + int UsedIndexCount; ///< To be filled in by SDK and returned to caller + uint16_t* IndexBuffer; ///< To be allocated by caller and filled in by SDK +} ovrFovStencilMeshBuffer; + +/// Returns a viewport stencil mesh to be used for defining the area or outline the user +/// can see through the lens on an area defined by a given ovrFovPort. +/// +/// \param[in] session Specifies an ovrSession previously returned by ovr_Create. +/// \param[in] fovStencilDesc Info provided by caller necessary to generate a stencil mesh. +/// \param[in] meshBuffer Mesh buffer to be partially filled in and returned by the SDK. +/// +/// \return Returns an ovrResult indicating success or failure. In the case of +/// failure, use ovr_GetLastErrorInfo to get more information. +/// Return values include but aren't limited to: +/// - ovrSuccess: Completed successfully. +/// - ovrError_ServiceConnection: The service connection was lost and the application +/// must destroy the session. +/// - ovrError_InvalidParameter: One or more of the parameters +/// +/// To find out how big the vertex and index buffers in meshBuffer buffer should be, first call +/// this function setting AllocVertexCount & AllocIndexCount to 0 while also sending in nullptr +/// for VertexBuffer & IndexBuffer. The SDK will populate UsedVertexCount & UsedIndexCount values. +/// +/// If Alloc*Count fields in meshBuffer are smaller than the expected Used*Count fields, +/// (except when they are 0) then the SDK will return ovrError_InvalidParameter and leave +/// VertexBuffer and IndexBuffer untouched. +/// +/// 2D positions provided in the buffer will be in the [0,1] range where Y increases downward, +/// similar to texture-UV space. If Y coordinates need to be flipped upside down, use the +/// ovrFovStencilFlag_MeshOriginAtBottomLeft. +/// +OVR_PUBLIC_FUNCTION(ovrResult) +ovr_GetFovStencil( + ovrSession session, + const ovrFovStencilDesc* fovStencilDesc, + ovrFovStencilMeshBuffer* meshBuffer); + +//----------------------------------------------------------------------------------- + +/// Describes button input types. +/// Button inputs are combined; that is they will be reported as pressed if they are +/// pressed on either one of the two devices. +/// The ovrButton_Up/Down/Left/Right map to both XBox D-Pad and directional buttons. +/// The ovrButton_Enter and ovrButton_Return map to Start and Back controller buttons, respectively. +typedef enum ovrButton_ { + /// A button on XBox controllers and right Touch controller. Not present on Oculus Remote. + ovrButton_A = 0x00000001, + + /// B button on XBox controllers and right Touch controller. Not present on Oculus Remote. + ovrButton_B = 0x00000002, + + /// Right thumbstick on XBox controllers and Touch controllers. Not present on Oculus Remote. + ovrButton_RThumb = 0x00000004, + + /// Right shoulder button on XBox controllers. Not present on Touch controllers or Oculus Remote. + ovrButton_RShoulder = 0x00000008, + + + /// X button on XBox controllers and left Touch controller. Not present on Oculus Remote. + ovrButton_X = 0x00000100, + + /// Y button on XBox controllers and left Touch controller. Not present on Oculus Remote. + ovrButton_Y = 0x00000200, + + /// Left thumbstick on XBox controllers and Touch controllers. Not present on Oculus Remote. + ovrButton_LThumb = 0x00000400, + + /// Left shoulder button on XBox controllers. Not present on Touch controllers or Oculus Remote. + ovrButton_LShoulder = 0x00000800, + + /// Up button on XBox controllers and Oculus Remote. Not present on Touch controllers. + ovrButton_Up = 0x00010000, + + /// Down button on XBox controllers and Oculus Remote. Not present on Touch controllers. + ovrButton_Down = 0x00020000, + + /// Left button on XBox controllers and Oculus Remote. Not present on Touch controllers. + ovrButton_Left = 0x00040000, + + /// Right button on XBox controllers and Oculus Remote. Not present on Touch controllers. + ovrButton_Right = 0x00080000, + + /// Start on XBox 360 controller. Menu on XBox One controller and Left Touch controller. + /// Select button on Oculus Remote. + /// Should be referred to as the Menu button in user-facing documentation. + ovrButton_Enter = 0x00100000, + + /// Back on Xbox 360 controller and Oculus Remote. View button on XBox One controller. + /// Not present on Touch controllers. + ovrButton_Back = 0x00200000, + + /// Volume button on Oculus Remote. Not present on XBox or Touch controllers. + ovrButton_VolUp = 0x00400000, + + /// Volume button on Oculus Remote. Not present on XBox or Touch controllers. + ovrButton_VolDown = 0x00800000, + + /// Home button on XBox controllers. Oculus button on Touch controllers and Oculus Remote. + ovrButton_Home = 0x01000000, + + // Bit mask of all buttons that are for private usage by Oculus + ovrButton_Private = ovrButton_VolUp | ovrButton_VolDown | ovrButton_Home, + + // Bit mask of all buttons on the right Touch controller + ovrButton_RMask = ovrButton_A | ovrButton_B | ovrButton_RThumb | ovrButton_RShoulder, + + // Bit mask of all buttons on the left Touch controller + ovrButton_LMask = + ovrButton_X | ovrButton_Y | ovrButton_LThumb | ovrButton_LShoulder | ovrButton_Enter, + + ovrButton_EnumSize = 0x7fffffff ///< \internal Force type int32_t. +} ovrButton; + +/// Describes touch input types. +/// These values map to capacitive touch values reported ovrInputState::Touch. +/// Some of these values are mapped to button bits for consistency. +typedef enum ovrTouch_ { + ovrTouch_A = ovrButton_A, + ovrTouch_B = ovrButton_B, + ovrTouch_RThumb = ovrButton_RThumb, + ovrTouch_RThumbRest = 0x00000008, + ovrTouch_RIndexTrigger = 0x00000010, + + // Bit mask of all the button touches on the right controller + ovrTouch_RButtonMask = + ovrTouch_A | ovrTouch_B | ovrTouch_RThumb | ovrTouch_RThumbRest | ovrTouch_RIndexTrigger, + + ovrTouch_X = ovrButton_X, + ovrTouch_Y = ovrButton_Y, + ovrTouch_LThumb = ovrButton_LThumb, + ovrTouch_LThumbRest = 0x00000800, + ovrTouch_LIndexTrigger = 0x00001000, + + // Bit mask of all the button touches on the left controller + ovrTouch_LButtonMask = + ovrTouch_X | ovrTouch_Y | ovrTouch_LThumb | ovrTouch_LThumbRest | ovrTouch_LIndexTrigger, + + // Finger pose state + // Derived internally based on distance, proximity to sensors and filtering. + ovrTouch_RIndexPointing = 0x00000020, + ovrTouch_RThumbUp = 0x00000040, + ovrTouch_LIndexPointing = 0x00002000, + ovrTouch_LThumbUp = 0x00004000, + + // Bit mask of all right controller poses + ovrTouch_RPoseMask = ovrTouch_RIndexPointing | ovrTouch_RThumbUp, + + // Bit mask of all left controller poses + ovrTouch_LPoseMask = ovrTouch_LIndexPointing | ovrTouch_LThumbUp, + + ovrTouch_EnumSize = 0x7fffffff ///< \internal Force type int32_t. +} ovrTouch; + +/// Describes the Touch Haptics engine. +/// Currently, those values will NOT change during a session. +typedef struct OVR_ALIGNAS(OVR_PTR_SIZE) ovrTouchHapticsDesc_ { + // Haptics engine frequency/sample-rate, sample time in seconds equals 1.0/sampleRateHz + int SampleRateHz; + // Size of each Haptics sample, sample value range is [0, 2^(Bytes*8)-1] + int SampleSizeInBytes; + + // Queue size that would guarantee Haptics engine would not starve for data + // Make sure size doesn't drop below it for best results + int QueueMinSizeToAvoidStarvation; + + // Minimum, Maximum and Optimal number of samples that can be sent to Haptics through + // ovr_SubmitControllerVibration + int SubmitMinSamples; + int SubmitMaxSamples; + int SubmitOptimalSamples; +} ovrTouchHapticsDesc; + +/// Specifies which controller is connected; multiple can be connected at once. +typedef enum ovrControllerType_ { + ovrControllerType_None = 0x0000, + ovrControllerType_LTouch = 0x0001, + ovrControllerType_RTouch = 0x0002, + ovrControllerType_Touch = (ovrControllerType_LTouch | ovrControllerType_RTouch), + ovrControllerType_Remote = 0x0004, + + ovrControllerType_XBox = 0x0010, + + ovrControllerType_Object0 = 0x0100, + ovrControllerType_Object1 = 0x0200, + ovrControllerType_Object2 = 0x0400, + ovrControllerType_Object3 = 0x0800, + + + ovrControllerType_Active = 0xffffffff, ///< Operate on or query whichever controller is active. + + ovrControllerType_EnumSize = 0x7fffffff ///< \internal Force type int32_t. +} ovrControllerType; + +/// Haptics buffer submit mode +typedef enum ovrHapticsBufferSubmitMode_ { + /// Enqueue buffer for later playback + ovrHapticsBufferSubmit_Enqueue +} ovrHapticsBufferSubmitMode; + +/// Maximum number of samples in ovrHapticsBuffer +#define OVR_HAPTICS_BUFFER_SAMPLES_MAX 256 + +/// Haptics buffer descriptor, contains amplitude samples used for Touch vibration +typedef struct ovrHapticsBuffer_ { + /// Samples stored in opaque format + const void* Samples; + /// Number of samples (up to OVR_HAPTICS_BUFFER_SAMPLES_MAX) + int SamplesCount; + /// How samples are submitted to the hardware + ovrHapticsBufferSubmitMode SubmitMode; +} ovrHapticsBuffer; + +/// State of the Haptics playback for Touch vibration +typedef struct ovrHapticsPlaybackState_ { + // Remaining space available to queue more samples + int RemainingQueueSpace; + + // Number of samples currently queued + int SamplesQueued; +} ovrHapticsPlaybackState; + +/// Position tracked devices +typedef enum ovrTrackedDeviceType_ { + ovrTrackedDevice_None = 0x0000, + ovrTrackedDevice_HMD = 0x0001, + ovrTrackedDevice_LTouch = 0x0002, + ovrTrackedDevice_RTouch = 0x0004, + ovrTrackedDevice_Touch = (ovrTrackedDevice_LTouch | ovrTrackedDevice_RTouch), + + ovrTrackedDevice_Object0 = 0x0010, + ovrTrackedDevice_Object1 = 0x0020, + ovrTrackedDevice_Object2 = 0x0040, + ovrTrackedDevice_Object3 = 0x0080, + + ovrTrackedDevice_All = 0xFFFF, +} ovrTrackedDeviceType; + +/// Boundary types that specified while using the boundary system +typedef enum ovrBoundaryType_ { + /// Outer boundary - closely represents user setup walls + ovrBoundary_Outer = 0x0001, + + /// Play area - safe rectangular area inside outer boundary which can optionally be used to + /// restrict user interactions and motion. + ovrBoundary_PlayArea = 0x0100, +} ovrBoundaryType; + +/// Boundary system look and feel +typedef struct ovrBoundaryLookAndFeel_ { + /// Boundary color (alpha channel is ignored) + ovrColorf Color; +} ovrBoundaryLookAndFeel; + +/// Provides boundary test information +typedef struct ovrBoundaryTestResult_ { + /// True if the boundary system is being triggered. Note that due to fade in/out effects this may + /// not exactly match visibility. + ovrBool IsTriggering; + + /// Distance to the closest play area or outer boundary surface. + float ClosestDistance; + + /// Closest point on the boundary surface. + ovrVector3f ClosestPoint; + + /// Unit surface normal of the closest boundary surface. + ovrVector3f ClosestPointNormal; +} ovrBoundaryTestResult; + +/// Provides names for the left and right hand array indexes. +/// +/// \see ovrInputState, ovrTrackingState +/// +typedef enum ovrHandType_ { + ovrHand_Left = 0, + ovrHand_Right = 1, + ovrHand_Count = 2, + ovrHand_EnumSize = 0x7fffffff ///< \internal Force type int32_t. +} ovrHandType; + +/// ovrInputState describes the complete controller input state, including Oculus Touch, +/// and XBox gamepad. If multiple inputs are connected and used at the same time, +/// their inputs are combined. +typedef struct ovrInputState_ { + /// System type when the controller state was last updated. + double TimeInSeconds; + + /// Values for buttons described by ovrButton. + unsigned int Buttons; + + /// Touch values for buttons and sensors as described by ovrTouch. + unsigned int Touches; + + /// Left and right finger trigger values (ovrHand_Left and ovrHand_Right), in range 0.0 to 1.0f. + /// Returns 0 if the value would otherwise be less than 0.1176, for ovrControllerType_XBox. + /// This has been formally named simply "Trigger". We retain the name IndexTrigger for backwards + /// code compatibility. + /// User-facing documentation should refer to it as the Trigger. + float IndexTrigger[ovrHand_Count]; + + /// Left and right hand trigger values (ovrHand_Left and ovrHand_Right), in the range 0.0 to 1.0f. + /// This has been formally named "Grip Button". We retain the name HandTrigger for backwards code + /// compatibility. + /// User-facing documentation should refer to it as the Grip Button or simply Grip. + float HandTrigger[ovrHand_Count]; + + /// Horizontal and vertical thumbstick axis values (ovrHand_Left and ovrHand_Right), in the range + /// of -1.0f to 1.0f. + /// Returns a deadzone (value 0) per each axis if the value on that axis would otherwise have been + /// between -.2746 to +.2746, for ovrControllerType_XBox + ovrVector2f Thumbstick[ovrHand_Count]; + + /// The type of the controller this state is for. + ovrControllerType ControllerType; + + /// Left and right finger trigger values (ovrHand_Left and ovrHand_Right), in range 0.0 to 1.0f. + /// Does not apply a deadzone. Only touch applies a filter. + /// This has been formally named simply "Trigger". We retain the name IndexTrigger for backwards + /// code compatibility. + /// User-facing documentation should refer to it as the Trigger. + float IndexTriggerNoDeadzone[ovrHand_Count]; + + /// Left and right hand trigger values (ovrHand_Left and ovrHand_Right), in the range 0.0 to 1.0f. + /// Does not apply a deadzone. Only touch applies a filter. + /// This has been formally named "Grip Button". We retain the name HandTrigger for backwards code + /// compatibility. + /// User-facing documentation should refer to it as the Grip Button or simply Grip. + float HandTriggerNoDeadzone[ovrHand_Count]; + + /// Horizontal and vertical thumbstick axis values (ovrHand_Left and ovrHand_Right), in the range + /// -1.0f to 1.0f + /// Does not apply a deadzone or filter. + ovrVector2f ThumbstickNoDeadzone[ovrHand_Count]; + + /// Left and right finger trigger values (ovrHand_Left and ovrHand_Right), in range 0.0 to 1.0f. + /// No deadzone or filter + /// This has been formally named "Grip Button". We retain the name HandTrigger for backwards code + /// compatibility. + /// User-facing documentation should refer to it as the Grip Button or simply Grip. + float IndexTriggerRaw[ovrHand_Count]; + + /// Left and right hand trigger values (ovrHand_Left and ovrHand_Right), in the range 0.0 to 1.0f. + /// No deadzone or filter + /// This has been formally named "Grip Button". We retain the name HandTrigger for backwards code + /// compatibility. + /// User-facing documentation should refer to it as the Grip Button or simply Grip. + float HandTriggerRaw[ovrHand_Count]; + + /// Horizontal and vertical thumbstick axis values (ovrHand_Left and ovrHand_Right), in the range + /// -1.0f to 1.0f + /// No deadzone or filter + ovrVector2f ThumbstickRaw[ovrHand_Count]; + +} ovrInputState; + + +typedef struct ovrCameraIntrinsics_ { + /// Time in seconds from last change to the parameters + double LastChangedTime; + + /// Angles of all 4 sides of viewport + ovrFovPort FOVPort; + + /// Near plane of the virtual camera used to match the external camera + float VirtualNearPlaneDistanceMeters; + + /// Far plane of the virtual camera used to match the external camera + float VirtualFarPlaneDistanceMeters; + + /// Height in pixels of image sensor + ovrSizei ImageSensorPixelResolution; + + /// The lens distortion matrix of camera + ovrMatrix4f LensDistortionMatrix; + + /// How often, in seconds, the exposure is taken + double ExposurePeriodSeconds; + + /// length of the exposure time + double ExposureDurationSeconds; + +} ovrCameraIntrinsics; + +typedef enum ovrCameraStatusFlags_ { + /// Initial state of camera + ovrCameraStatus_None = 0x0, + + /// Bit set when the camera is connected to the system + ovrCameraStatus_Connected = 0x1, + + /// Bit set when the camera is undergoing calibration + ovrCameraStatus_Calibrating = 0x2, + + /// Bit set when the camera has tried & failed calibration + ovrCameraStatus_CalibrationFailed = 0x4, + + /// Bit set when the camera has tried & passed calibration + ovrCameraStatus_Calibrated = 0x8, + + /// Bit set when the camera is capturing + ovrCameraStatus_Capturing = 0x10, + + ovrCameraStatus_EnumSize = 0x7fffffff ///< \internal Force type int32_t. +} ovrCameraStatusFlags; + +typedef struct ovrCameraExtrinsics_ { + /// Time in seconds from last change to the parameters. + /// For instance, if the pose changes, or a camera exposure happens, this struct will be updated. + double LastChangedTimeSeconds; + + /// Current Status of the camera, a mix of bits from ovrCameraStatusFlags + unsigned int CameraStatusFlags; + + /// Which Tracked device, if any, is the camera rigidly attached to + /// If set to ovrTrackedDevice_None, then the camera is not attached to a tracked object. + /// If the external camera moves while unattached (i.e. set to ovrTrackedDevice_None), its Pose + /// won't be updated + ovrTrackedDeviceType AttachedToDevice; + + /// The relative Pose of the External Camera. + /// If AttachedToDevice is ovrTrackedDevice_None, then this is a absolute pose in tracking space + ovrPosef RelativePose; + + /// The time, in seconds, when the last successful exposure was taken + double LastExposureTimeSeconds; + + /// Estimated exposure latency to get from the exposure time to the system + double ExposureLatencySeconds; + + /// Additional latency to get from the exposure time of the real camera to match the render time + /// of the virtual camera + double AdditionalLatencySeconds; + +} ovrCameraExtrinsics; +#define OVR_MAX_EXTERNAL_CAMERA_COUNT 16 +#define OVR_EXTERNAL_CAMERA_NAME_SIZE 32 +typedef struct ovrExternalCamera_ { + char Name[OVR_EXTERNAL_CAMERA_NAME_SIZE]; // camera identifier: vid + pid + serial number etc. + ovrCameraIntrinsics Intrinsics; + ovrCameraExtrinsics Extrinsics; +} ovrExternalCamera; + +//----------------------------------------------------------------------------------- +// ***** Initialize structures + +/// Initialization flags. +/// +/// \see ovrInitParams, ovr_Initialize +/// +typedef enum ovrInitFlags_ { + /// When a debug library is requested, a slower debugging version of the library will + /// run which can be used to help solve problems in the library and debug application code. + ovrInit_Debug = 0x00000001, + + + /// When a version is requested, the LibOVR runtime respects the RequestedMinorVersion + /// field and verifies that the RequestedMinorVersion is supported. Normally when you + /// specify this flag you simply use OVR_MINOR_VERSION for ovrInitParams::RequestedMinorVersion, + /// though you could use a lower version than OVR_MINOR_VERSION to specify previous + /// version behavior. + ovrInit_RequestVersion = 0x00000004, + + + /// This client will not be visible in the HMD. + /// Typically set by diagnostic or debugging utilities. + ovrInit_Invisible = 0x00000010, + + /// This client will alternate between VR and 2D rendering. + /// Typically set by game engine editors and VR-enabled web browsers. + ovrInit_MixedRendering = 0x00000020, + + /// This client is aware of ovrSessionStatus focus states (e.g. ovrSessionStatus::HasInputFocus), + /// and responds to them appropriately (e.g. pauses and stops drawing hands when lacking focus). + ovrInit_FocusAware = 0x00000040, + + + + + + + /// These bits are writable by user code. + ovrinit_WritableBits = 0x00ffffff, + + ovrInit_EnumSize = 0x7fffffff ///< \internal Force type int32_t. +} ovrInitFlags; + +/// Logging levels +/// +/// \see ovrInitParams, ovrLogCallback +/// +typedef enum ovrLogLevel_ { + ovrLogLevel_Debug = 0, ///< Debug-level log event. + ovrLogLevel_Info = 1, ///< Info-level log event. + ovrLogLevel_Error = 2, ///< Error-level log event. + + ovrLogLevel_EnumSize = 0x7fffffff ///< \internal Force type int32_t. +} ovrLogLevel; + +/// Signature of the logging callback function pointer type. +/// +/// \param[in] userData is an arbitrary value specified by the user of ovrInitParams. +/// \param[in] level is one of the ovrLogLevel constants. +/// \param[in] message is a UTF8-encoded null-terminated string. +/// \see ovrInitParams, ovrLogLevel, ovr_Initialize +/// +typedef void(OVR_CDECL* ovrLogCallback)(uintptr_t userData, int level, const char* message); + +/// Parameters for ovr_Initialize. +/// +/// \see ovr_Initialize +/// +typedef struct OVR_ALIGNAS(8) ovrInitParams_ { + /// Flags from ovrInitFlags to override default behavior. + /// Use 0 for the defaults. + uint32_t Flags; + + /// Requests a specific minor version of the LibOVR runtime. + /// Flags must include ovrInit_RequestVersion or this will be ignored and OVR_MINOR_VERSION + /// will be used. If you are directly calling the LibOVRRT version of ovr_Initialize + /// in the LibOVRRT DLL then this must be valid and include ovrInit_RequestVersion. + uint32_t RequestedMinorVersion; + + /// User-supplied log callback function, which may be called at any time + /// asynchronously from multiple threads until ovr_Shutdown completes. + /// Use NULL to specify no log callback. + ovrLogCallback LogCallback; + + /// User-supplied data which is passed as-is to LogCallback. Typically this + /// is used to store an application-specific pointer which is read in the + /// callback function. + uintptr_t UserData; + + /// Relative number of milliseconds to wait for a connection to the server + /// before failing. Use 0 for the default timeout. + uint32_t ConnectionTimeoutMS; + + OVR_ON64(OVR_UNUSED_STRUCT_PAD(pad0, 4)) ///< \internal + +} ovrInitParams; + + +#ifdef __cplusplus +extern "C" { +#endif + + +#if !defined(OVR_EXPORTING_CAPI) + +// ----------------------------------------------------------------------------------- +// ***** API Interfaces + +/// Initializes LibOVR +/// +/// Initialize LibOVR for application usage. This includes finding and loading the LibOVRRT +/// shared library. No LibOVR API functions, other than ovr_GetLastErrorInfo and ovr_Detect, can +/// be called unless ovr_Initialize succeeds. A successful call to ovr_Initialize must be eventually +/// followed by a call to ovr_Shutdown. ovr_Initialize calls are idempotent. +/// Calling ovr_Initialize twice does not require two matching calls to ovr_Shutdown. +/// If already initialized, the return value is ovr_Success. +/// +/// LibOVRRT shared library search order: +/// -# Current working directory (often the same as the application directory). +/// -# Module directory (usually the same as the application directory, +/// but not if the module is a separate shared library). +/// -# Application directory +/// -# Standard OS shared library search location(s) (OS-specific). +/// +/// \param params Specifies custom initialization options. May be NULL to indicate default options +/// when using the CAPI shim. If you are directly calling the LibOVRRT version of +/// ovr_Initialize in the LibOVRRT DLL then this must be valid and +/// include ovrInit_RequestVersion. +/// \return Returns an ovrResult indicating success or failure. In the case of failure, use +/// ovr_GetLastErrorInfo to get more information. Example failed results include: +/// - ovrError_Initialize: Generic initialization error. +/// - ovrError_LibLoad: Couldn't load LibOVRRT. +/// - ovrError_LibVersion: LibOVRRT version incompatibility. +/// - ovrError_ServiceConnection: Couldn't connect to the OVR Service. +/// - ovrError_ServiceVersion: OVR Service version incompatibility. +/// - ovrError_IncompatibleOS: The operating system version is incompatible. +/// - ovrError_DisplayInit: Unable to initialize the HMD display. +/// - ovrError_ServerStart: Unable to start the server. Is it already running? +/// - ovrError_Reinitialization: Attempted to re-initialize with a different version. +/// +/// <b>Example code</b> +/// \code{.cpp} +/// ovrInitParams initParams = { ovrInit_RequestVersion, OVR_MINOR_VERSION, NULL, 0, 0 }; +/// ovrResult result = ovr_Initialize(&initParams); +/// if(OVR_FAILURE(result)) { +/// ovrErrorInfo errorInfo; +/// ovr_GetLastErrorInfo(&errorInfo); +/// DebugLog("ovr_Initialize failed: %s", errorInfo.ErrorString); +/// return false; +/// } +/// [...] +/// \endcode +/// +/// \see ovr_Shutdown +/// +OVR_PUBLIC_FUNCTION(ovrResult) ovr_Initialize(const ovrInitParams* params); + +/// Shuts down LibOVR +/// +/// A successful call to ovr_Initialize must be eventually matched by a call to ovr_Shutdown. +/// After calling ovr_Shutdown, no LibOVR functions can be called except ovr_GetLastErrorInfo +/// or another ovr_Initialize. ovr_Shutdown invalidates all pointers, references, and created +/// objects +/// previously returned by LibOVR functions. The LibOVRRT shared library can be unloaded by +/// ovr_Shutdown. +/// +/// \see ovr_Initialize +/// +OVR_PUBLIC_FUNCTION(void) ovr_Shutdown(); + +/// Returns information about the most recent failed return value by the +/// current thread for this library. +/// +/// This function itself can never generate an error. +/// The last error is never cleared by LibOVR, but will be overwritten by new errors. +/// Do not use this call to determine if there was an error in the last API +/// call as successful API calls don't clear the last ovrErrorInfo. +/// To avoid any inconsistency, ovr_GetLastErrorInfo should be called immediately +/// after an API function that returned a failed ovrResult, with no other API +/// functions called in the interim. +/// +/// \param[out] errorInfo The last ovrErrorInfo for the current thread. +/// +/// \see ovrErrorInfo +/// +OVR_PUBLIC_FUNCTION(void) ovr_GetLastErrorInfo(ovrErrorInfo* errorInfo); + +/// Returns the version string representing the LibOVRRT version. +/// +/// The returned string pointer is valid until the next call to ovr_Shutdown. +/// +/// Note that the returned version string doesn't necessarily match the current +/// OVR_MAJOR_VERSION, etc., as the returned string refers to the LibOVRRT shared +/// library version and not the locally compiled interface version. +/// +/// The format of this string is subject to change in future versions and its contents +/// should not be interpreted. +/// +/// \return Returns a UTF8-encoded null-terminated version string. +/// +OVR_PUBLIC_FUNCTION(const char*) ovr_GetVersionString(); + +/// Writes a message string to the LibOVR tracing mechanism (if enabled). +/// +/// This message will be passed back to the application via the ovrLogCallback if +/// it was registered. +/// +/// \param[in] level One of the ovrLogLevel constants. +/// \param[in] message A UTF8-encoded null-terminated string. +/// \return returns the strlen of the message or a negative value if the message is too large. +/// +/// \see ovrLogLevel, ovrLogCallback +/// +OVR_PUBLIC_FUNCTION(int) ovr_TraceMessage(int level, const char* message); + +/// Identify client application info. +/// +/// The string is one or more newline-delimited lines of optional info +/// indicating engine name, engine version, engine plugin name, engine plugin +/// version, engine editor. The order of the lines is not relevant. Individual +/// lines are optional. A newline is not necessary at the end of the last line. +/// Call after ovr_Initialize and before the first call to ovr_Create. +/// Each value is limited to 20 characters. Key names such as 'EngineName:' +/// 'EngineVersion:' do not count towards this limit. +/// +/// \param[in] identity Specifies one or more newline-delimited lines of optional info: +/// EngineName: %s\n +/// EngineVersion: %s\n +/// EnginePluginName: %s\n +/// EnginePluginVersion: %s\n +/// EngineEditor: <boolean> ('true' or 'false')\n +/// +/// <b>Example code</b> +/// \code{.cpp} +/// ovr_IdentifyClient("EngineName: Unity\n" +/// "EngineVersion: 5.3.3\n" +/// "EnginePluginName: OVRPlugin\n" +/// "EnginePluginVersion: 1.2.0\n" +/// "EngineEditor: true"); +/// \endcode +/// +OVR_PUBLIC_FUNCTION(ovrResult) ovr_IdentifyClient(const char* identity); + +//------------------------------------------------------------------------------------- +/// @name HMD Management +/// +/// Handles the enumeration, creation, destruction, and properties of an HMD (head-mounted display). +///@{ + +/// Returns native color space information about the current HMD. +/// +/// ovr_Initialize must be called prior to calling this function, otherwise call will fail. +/// +/// \param[in] session Specifies an ovrSession previously returned by ovr_Create() or NULL. +/// +/// \return Returns an ovrHmdColorDesc. +/// +OVR_PUBLIC_FUNCTION(ovrHmdColorDesc) ovr_GetHmdColorDesc(ovrSession session); + +/// Sets the color space actively being used by the client app. +/// +/// This value does not have to follow the color space provided in ovr_GetHmdColorDesc. It should +/// reflect the color space the final rendered frame the client has submitted to the SDK. +/// If this function is never called, the session will keep using the default color space deemed +/// appropriate by the runtime. See remarks in ovrColorSpace enum for more info on default behavior. +/// +/// ovr_Initialize must be called prior to calling this function, otherwise call will fail. +/// +/// \param[in] session Specifies an ovrSession previously returned by ovr_Create() or NULL. +/// \param[in] colorDesc Specifies the color description to use for the current HMD. +/// +/// \return Returns an ovrResult indicating success or failure. +/// +OVR_PUBLIC_FUNCTION(ovrResult) +ovr_SetClientColorDesc(ovrSession session, const ovrHmdColorDesc* colorDesc); + +/// Returns information about the current HMD. +/// +/// ovr_Initialize must be called prior to calling this function, +/// otherwise ovrHmdDesc::Type will be set to ovrHmd_None without +/// checking for the HMD presence. +/// +/// For newer headsets being used on a game built against an old SDK version, +/// we may return the ovrHmdType as ovrHmd_CV1 for backwards compatibility. +/// +/// \param[in] session Specifies an ovrSession previously returned by ovr_Create() or NULL. +/// +/// \return Returns an ovrHmdDesc. If invoked with NULL session argument, ovrHmdDesc::Type +/// set to ovrHmd_None indicates that the HMD is not connected. +/// +OVR_PUBLIC_FUNCTION(ovrHmdDesc) ovr_GetHmdDesc(ovrSession session); + +/// Returns the number of attached trackers. +/// +/// The number of trackers may change at any time, so this function should be called before use +/// as opposed to once on startup. +/// +/// For newer headsets being used on a game built against an old SDK version, +/// we may simulate three CV1 trackers to maintain backwards compatibility. +/// +/// \param[in] session Specifies an ovrSession previously returned by ovr_Create. +/// +/// \return Returns unsigned int count. +/// +OVR_PUBLIC_FUNCTION(unsigned int) ovr_GetTrackerCount(ovrSession session); + +/// Returns a given attached tracker description. +/// +/// ovr_Initialize must have first been called in order for this to succeed, otherwise the returned +/// trackerDescArray will be zero-initialized. The data returned by this function can change at +/// runtime. +/// +/// For newer headsets being used on a game built against an old SDK version, +/// we may simulate three CV1 trackers to maintain backwards compatibility. +/// +/// \param[in] session Specifies an ovrSession previously returned by ovr_Create. +/// +/// \param[in] trackerDescIndex Specifies a tracker index. The valid indexes are in the +/// range of 0 to the tracker count returned by ovr_GetTrackerCount. +/// +/// \return Returns ovrTrackerDesc. An empty ovrTrackerDesc will be returned if +/// trackerDescIndex is out of range. +/// +/// \see ovrTrackerDesc, ovr_GetTrackerCount +/// +OVR_PUBLIC_FUNCTION(ovrTrackerDesc) +ovr_GetTrackerDesc(ovrSession session, unsigned int trackerDescIndex); + +/// Creates a handle to a VR session. +/// +/// Upon success the returned ovrSession must be eventually freed with ovr_Destroy when it is no +/// longer needed. +/// A second call to ovr_Create will result in an error return value if the previous session has not +/// been destroyed. +/// +/// \param[out] pSession Provides a pointer to an ovrSession which will be written to upon success. +/// \param[out] pLuid Provides a system specific graphics adapter identifier that locates which +/// graphics adapter has the HMD attached. This must match the adapter used by the application +/// or no rendering output will be possible. This is important for stability on multi-adapter +/// systems. An +/// application that simply chooses the default adapter will not run reliably on multi-adapter +/// systems. +/// \return Returns an ovrResult indicating success or failure. Upon failure +/// the returned ovrSession will be NULL. +/// +/// <b>Example code</b> +/// \code{.cpp} +/// ovrSession session; +/// ovrGraphicsLuid luid; +/// ovrResult result = ovr_Create(&session, &luid); +/// if(OVR_FAILURE(result)) +/// ... +/// \endcode +/// +/// \see ovr_Destroy +/// +OVR_PUBLIC_FUNCTION(ovrResult) ovr_Create(ovrSession* pSession, ovrGraphicsLuid* pLuid); + +/// Destroys the session. +/// +/// \param[in] session Specifies an ovrSession previously returned by ovr_Create. +/// \see ovr_Create +/// +OVR_PUBLIC_FUNCTION(void) ovr_Destroy(ovrSession session); + + +#endif // !defined(OVR_EXPORTING_CAPI) + +/// Specifies status information for the current session. +/// +/// \see ovr_GetSessionStatus +/// +typedef struct ovrSessionStatus_ { + /// True if the process has VR focus and thus is visible in the HMD. + ovrBool IsVisible; + + /// True if an HMD is present. + ovrBool HmdPresent; + + /// True if the HMD is on the user's head. + ovrBool HmdMounted; + + /// True if the session is in a display-lost state. See ovr_SubmitFrame. + ovrBool DisplayLost; + + /// True if the application should initiate shutdown. + ovrBool ShouldQuit; + + /// True if UX has requested re-centering. Must call ovr_ClearShouldRecenterFlag, + /// ovr_RecenterTrackingOrigin or ovr_SpecifyTrackingOrigin. + ovrBool ShouldRecenter; + + /// True if the application is the foreground application and receives input (e.g. Touch + /// controller state). If this is false then the application is in the background (but possibly + /// still visible) should hide any input representations such as hands. + ovrBool HasInputFocus; + + /// True if a system overlay is present, such as a dashboard. In this case the application + /// (if visible) should pause while still drawing, avoid drawing near-field graphics so they + /// don't visually fight with the system overlay, and consume fewer CPU and GPU resources. + /// \deprecated Do not use. + ovrBool OverlayPresent; + + /// True if runtime is requesting that the application provide depth buffers with projection + /// layers. + ovrBool DepthRequested; + +} ovrSessionStatus; + +#if !defined(OVR_EXPORTING_CAPI) + +/// Returns status information for the application. +/// +/// \param[in] session Specifies an ovrSession previously returned by ovr_Create. +/// \param[out] sessionStatus Provides an ovrSessionStatus that is filled in. +/// +/// \return Returns an ovrResult indicating success or failure. In the case of +/// failure, use ovr_GetLastErrorInfo to get more information. +/// Return values include but aren't limited to: +/// - ovrSuccess: Completed successfully. +/// - ovrError_ServiceConnection: The service connection was lost and the application +/// must destroy the session. +/// +OVR_PUBLIC_FUNCTION(ovrResult) +ovr_GetSessionStatus(ovrSession session, ovrSessionStatus* sessionStatus); + + +/// Query extension support status. +/// +/// \param[in] session Specifies an ovrSession previously returned by ovr_Create. +/// \param[in] extension Extension to query. +/// \param[out] outExtensionSupported Set to extension support status. ovrTrue if supported. +/// +/// \return Returns an ovrResult indicating success or failure. In the case of +/// failure use ovr_GetLastErrorInfo to get more information. +/// +/// \see ovrExtensions +/// +OVR_PUBLIC_FUNCTION(ovrResult) +ovr_IsExtensionSupported( + ovrSession session, + ovrExtensions extension, + ovrBool* outExtensionSupported); + +/// Enable extension. Extensions must be enabled after ovr_Create is called. +/// +/// \param[in] session Specifies an ovrSession previously returned by ovr_Create. +/// \param[in] extension Extension to enable. +/// +/// \return Returns an ovrResult indicating success or failure. Extension is only +/// enabled if successful. In the case of failure use ovr_GetLastErrorInfo +/// to get more information. +/// +/// \see ovrExtensions +/// +OVR_PUBLIC_FUNCTION(ovrResult) +ovr_EnableExtension(ovrSession session, ovrExtensions extension); + + +//@} + +//------------------------------------------------------------------------------------- +/// @name Tracking +/// +/// Tracking functions handle the position, orientation, and movement of the HMD in space. +/// +/// All tracking interface functions are thread-safe, allowing tracking state to be sampled +/// from different threads. +/// +///@{ + + +/// Sets the tracking origin type +/// +/// When the tracking origin is changed, all of the calls that either provide +/// or accept ovrPosef will use the new tracking origin provided. +/// +/// \param[in] session Specifies an ovrSession previously returned by ovr_Create. +/// \param[in] origin Specifies an ovrTrackingOrigin to be used for all ovrPosef +/// +/// \return Returns an ovrResult indicating success or failure. In the case of failure, use +/// ovr_GetLastErrorInfo to get more information. +/// +/// \see ovrTrackingOrigin, ovr_GetTrackingOriginType +OVR_PUBLIC_FUNCTION(ovrResult) +ovr_SetTrackingOriginType(ovrSession session, ovrTrackingOrigin origin); + +/// Gets the tracking origin state +/// +/// \param[in] session Specifies an ovrSession previously returned by ovr_Create. +/// +/// \return Returns the ovrTrackingOrigin that was either set by default, or previous set by the +/// application. +/// +/// \see ovrTrackingOrigin, ovr_SetTrackingOriginType +OVR_PUBLIC_FUNCTION(ovrTrackingOrigin) ovr_GetTrackingOriginType(ovrSession session); + +/// Re-centers the sensor position and orientation. +/// +/// This resets the (x,y,z) positional components and the yaw orientation component of the +/// tracking space for the HMD and controllers using the HMD's current tracking pose. +/// If the caller requires some tweaks on top of the HMD's current tracking pose, consider using +/// ovr_SpecifyTrackingOrigin instead. +/// +/// The roll and pitch orientation components are always determined by gravity and cannot +/// be redefined. All future tracking will report values relative to this new reference position. +/// If you are using ovrTrackerPoses then you will need to call ovr_GetTrackerPose after +/// this, because the sensor position(s) will change as a result of this. +/// +/// The headset cannot be facing vertically upward or downward but rather must be roughly +/// level otherwise this function will fail with ovrError_InvalidHeadsetOrientation. +/// +/// For more info, see the notes on each ovrTrackingOrigin enumeration to understand how +/// recenter will vary slightly in its behavior based on the current ovrTrackingOrigin setting. +/// +/// \param[in] session Specifies an ovrSession previously returned by ovr_Create. +/// +/// \return Returns an ovrResult indicating success or failure. In the case of failure, use +/// ovr_GetLastErrorInfo to get more information. Return values include but aren't limited +/// to: +/// - ovrSuccess: Completed successfully. +/// - ovrError_InvalidHeadsetOrientation: The headset was facing an invalid direction when +/// attempting recentering, such as facing vertically. +/// +/// \see ovrTrackingOrigin, ovr_GetTrackerPose, ovr_SpecifyTrackingOrigin +/// +OVR_PUBLIC_FUNCTION(ovrResult) ovr_RecenterTrackingOrigin(ovrSession session); + +/// Allows manually tweaking the sensor position and orientation. +/// +/// This function is similar to ovr_RecenterTrackingOrigin in that it modifies the +/// (x,y,z) positional components and the yaw orientation component of the tracking space for +/// the HMD and controllers. +/// +/// While ovr_RecenterTrackingOrigin resets the tracking origin in reference to the HMD's +/// current pose, ovr_SpecifyTrackingOrigin allows the caller to explicitly specify a transform +/// for the tracking origin. This transform is expected to be an offset to the most recent +/// recentered origin, so calling this function repeatedly with the same originPose will keep +/// nudging the recentered origin in that direction. +/// +/// There are several use cases for this function. For example, if the application decides to +/// limit the yaw, or translation of the recentered pose instead of directly using the HMD pose +/// the application can query the current tracking state via ovr_GetTrackingState, and apply +/// some limitations to the HMD pose because feeding this pose back into this function. +/// Similarly, this can be used to "adjust the seating position" incrementally in apps that +/// feature seated experiences such as cockpit-based games. +/// +/// This function can emulate ovr_RecenterTrackingOrigin as such: +/// ovrTrackingState ts = ovr_GetTrackingState(session, 0.0, ovrFalse); +/// ovr_SpecifyTrackingOrigin(session, ts.HeadPose.ThePose); +/// +/// The roll and pitch orientation components are determined by gravity and cannot be redefined. +/// If you are using ovrTrackerPoses then you will need to call ovr_GetTrackerPose after +/// this, because the sensor position(s) will change as a result of this. +/// +/// For more info, see the notes on each ovrTrackingOrigin enumeration to understand how +/// recenter will vary slightly in its behavior based on the current ovrTrackingOrigin setting. +/// +/// \param[in] session Specifies an ovrSession previously returned by ovr_Create. +/// \param[in] originPose Specifies a pose that will be used to transform the current tracking +/// origin. +/// +/// \return Returns an ovrResult indicating success or failure. In the case of failure, use +/// ovr_GetLastErrorInfo to get more information. Return values include but aren't limited +/// to: +/// - ovrSuccess: Completed successfully. +/// - ovrError_InvalidParameter: The heading direction in originPose was invalid, +/// such as facing vertically. This can happen if the caller is directly feeding the pose +/// of a position-tracked device such as an HMD or controller into this function. +/// +/// \see ovrTrackingOrigin, ovr_GetTrackerPose, ovr_RecenterTrackingOrigin +/// +OVR_PUBLIC_FUNCTION(ovrResult) ovr_SpecifyTrackingOrigin(ovrSession session, ovrPosef originPose); + +/// Clears the ShouldRecenter status bit in ovrSessionStatus. +/// +/// Clears the ShouldRecenter status bit in ovrSessionStatus, allowing further recenter requests to +/// be detected. Since this is automatically done by ovr_RecenterTrackingOrigin and +/// ovr_SpecifyTrackingOrigin, this function only needs to be called when application is doing +/// its own re-centering logic. +OVR_PUBLIC_FUNCTION(void) ovr_ClearShouldRecenterFlag(ovrSession session); + +/// Returns tracking state reading based on the specified absolute system time. +/// +/// Pass an absTime value of 0.0 to request the most recent sensor reading. In this case +/// both PredictedPose and SamplePose will have the same value. +/// +/// This may also be used for more refined timing of front buffer rendering logic, and so on. +/// This may be called by multiple threads. +/// +/// \param[in] session Specifies an ovrSession previously returned by ovr_Create. +/// \param[in] absTime Specifies the absolute future time to predict the return +/// ovrTrackingState value. Use 0 to request the most recent tracking state. +/// \param[in] latencyMarker Specifies that this call is the point in time where +/// the "App-to-Mid-Photon" latency timer starts from. If a given ovrLayer +/// provides "SensorSampleTime", that will override the value stored here. +/// \return Returns the ovrTrackingState that is predicted for the given absTime. +/// +/// \see ovrTrackingState, ovr_GetEyePoses, ovr_GetTimeInSeconds +/// +OVR_PUBLIC_FUNCTION(ovrTrackingState) +ovr_GetTrackingState(ovrSession session, double absTime, ovrBool latencyMarker); + +/// Returns an array of poses, where each pose matches a device type provided by the deviceTypes +/// array parameter. If any pose cannot be retrieved, it will return a reason for the missing +/// pose and the device pose will be zeroed out with a pose quaternion [x=0, y=0, z=0, w=1]. +/// +/// \param[in] session Specifies an ovrSession previously returned by ovr_Create. +/// \param[in] deviceTypes Array of device types to query for their poses. +/// \param[in] deviceCount Number of queried poses. This number must match the length of the +/// outDevicePoses and deviceTypes array. +/// \param[in] absTime Specifies the absolute future time to predict the return +/// ovrTrackingState value. Use 0 to request the most recent tracking state. +/// \param[out] outDevicePoses Array of poses, one for each device type in deviceTypes arrays. +/// +/// \return Returns an ovrResult for which OVR_SUCCESS(result) is false upon error and +/// true upon success. +/// +OVR_PUBLIC_FUNCTION(ovrResult) +ovr_GetDevicePoses( + ovrSession session, + ovrTrackedDeviceType* deviceTypes, + int deviceCount, + double absTime, + ovrPoseStatef* outDevicePoses); + + +/// Returns the ovrTrackerPose for the given attached tracker. +/// +/// For newer headsets being used on a game built against an old SDK version, +/// we may simulate three CV1 trackers to maintain backwards compatibility. +/// +/// \param[in] session Specifies an ovrSession previously returned by ovr_Create. +/// \param[in] trackerPoseIndex Index of the tracker being requested. +/// +/// \return Returns the requested ovrTrackerPose. An empty ovrTrackerPose will be returned if +/// trackerPoseIndex is out of range. +/// +/// \see ovr_GetTrackerCount +/// +OVR_PUBLIC_FUNCTION(ovrTrackerPose) +ovr_GetTrackerPose(ovrSession session, unsigned int trackerPoseIndex); + +/// Returns the most recent input state for controllers, without positional tracking info. +/// +/// \param[out] inputState Input state that will be filled in. +/// \param[in] controllerType Specifies which controller the input will be returned for. +/// \return Returns ovrSuccess if the new state was successfully obtained. +/// +/// \see ovrControllerType +/// +OVR_PUBLIC_FUNCTION(ovrResult) +ovr_GetInputState(ovrSession session, ovrControllerType controllerType, ovrInputState* inputState); + + +/// Returns controller types connected to the system OR'ed together. +/// +/// \return A bitmask of ovrControllerTypes connected to the system. +/// +/// \see ovrControllerType +/// +OVR_PUBLIC_FUNCTION(unsigned int) ovr_GetConnectedControllerTypes(ovrSession session); + +/// Gets information about Haptics engine for the specified Touch controller. +/// +/// \param[in] session Specifies an ovrSession previously returned by ovr_Create. +/// \param[in] controllerType The controller to retrieve the information from. +/// +/// \return Returns an ovrTouchHapticsDesc. +/// +OVR_PUBLIC_FUNCTION(ovrTouchHapticsDesc) +ovr_GetTouchHapticsDesc(ovrSession session, ovrControllerType controllerType); + +/// Sets constant vibration (with specified frequency and amplitude) to a controller. +/// Note: ovr_SetControllerVibration cannot be used interchangeably with +/// ovr_SubmitControllerVibration. +/// +/// This method should be called periodically, vibration lasts for a maximum of 2.5 seconds. +/// +/// \param[in] session Specifies an ovrSession previously returned by ovr_Create. +/// \param[in] controllerType The controller to set the vibration to. +/// \param[in] frequency Vibration frequency. Supported values are: 0.0 (disabled), 0.5 and 1.0. Non +/// valid values will be clamped. +/// \param[in] amplitude Vibration amplitude in the [0.0, 1.0] range. +/// \return Returns an ovrResult for which OVR_SUCCESS(result) is false upon error and true +/// upon success. Return values include but aren't limited to: +/// - ovrSuccess: The call succeeded and a result was returned. +/// - ovrSuccess_DeviceUnavailable: The call succeeded but the device referred to by +/// controllerType is not available. +/// +OVR_PUBLIC_FUNCTION(ovrResult) +ovr_SetControllerVibration( + ovrSession session, + ovrControllerType controllerType, + float frequency, + float amplitude); + +/// Submits a Haptics buffer (used for vibration) to Touch (only) controllers. +/// Note: ovr_SubmitControllerVibration cannot be used interchangeably with +/// ovr_SetControllerVibration. +/// +/// \param[in] session Specifies an ovrSession previously returned by ovr_Create. +/// \param[in] controllerType Controller where the Haptics buffer will be played. +/// \param[in] buffer Haptics buffer containing amplitude samples to be played. +/// \return Returns an ovrResult for which OVR_SUCCESS(result) is false upon error and true +/// upon success. Return values include but aren't limited to: +/// - ovrSuccess: The call succeeded and a result was returned. +/// - ovrSuccess_DeviceUnavailable: The call succeeded but the device referred to by +/// controllerType is not available. +/// +/// \see ovrHapticsBuffer +/// +OVR_PUBLIC_FUNCTION(ovrResult) +ovr_SubmitControllerVibration( + ovrSession session, + ovrControllerType controllerType, + const ovrHapticsBuffer* buffer); + +/// Gets the Haptics engine playback state of a specific Touch controller. +/// +/// \param[in] session Specifies an ovrSession previously returned by ovr_Create. +/// \param[in] controllerType Controller where the Haptics buffer wil be played. +/// \param[in] outState State of the haptics engine. +/// \return Returns an ovrResult for which OVR_SUCCESS(result) is false upon error and true +/// upon success. Return values include but aren't limited to: +/// - ovrSuccess: The call succeeded and a result was returned. +/// - ovrSuccess_DeviceUnavailable: The call succeeded but the device referred to by +/// controllerType is not available. +/// +/// \see ovrHapticsPlaybackState +/// +OVR_PUBLIC_FUNCTION(ovrResult) +ovr_GetControllerVibrationState( + ovrSession session, + ovrControllerType controllerType, + ovrHapticsPlaybackState* outState); + + +/// Tests collision/proximity of position tracked devices (e.g. HMD and/or Touch) against the +/// Boundary System. +/// Note: this method is similar to ovr_BoundaryTestPoint but can be more precise as it may take +/// into account device acceleration/momentum. +/// +/// \param[in] session Specifies an ovrSession previously returned by ovr_Create. +/// \param[in] deviceBitmask Bitmask of one or more tracked devices to test. +/// \param[in] boundaryType Must be either ovrBoundary_Outer or ovrBoundary_PlayArea. +/// \param[out] outTestResult Result of collision/proximity test, contains information such as +/// distance and closest point. +/// \return Returns an ovrResult for which OVR_SUCCESS(result) is false upon error and true +/// upon success. Return values include but aren't limited to: +/// - ovrSuccess: The call succeeded and a result was returned. +/// - ovrSuccess_BoundaryInvalid: The call succeeded but the result is not a valid boundary due +/// to not being set up. +/// - ovrSuccess_DeviceUnavailable: The call succeeded but the device referred to by +/// deviceBitmask is not available. +/// +/// \see ovrBoundaryTestResult +/// +OVR_PUBLIC_FUNCTION(ovrResult) +ovr_TestBoundary( + ovrSession session, + ovrTrackedDeviceType deviceBitmask, + ovrBoundaryType boundaryType, + ovrBoundaryTestResult* outTestResult); + +/// Tests collision/proximity of a 3D point against the Boundary System. +/// +/// \param[in] session Specifies an ovrSession previously returned by ovr_Create. +/// \param[in] point 3D point to test. +/// \param[in] singleBoundaryType Must be either ovrBoundary_Outer or ovrBoundary_PlayArea to test +/// against +/// \param[out] outTestResult Result of collision/proximity test, contains information such as +/// distance and closest point. +/// \return Returns an ovrResult for which OVR_SUCCESS(result) is false upon error and true +/// upon success. Return values include but aren't limited to: +/// - ovrSuccess: The call succeeded and a result was returned. +/// - ovrSuccess_BoundaryInvalid: The call succeeded but the result is not a valid boundary due +/// to not being set up. +/// +/// \see ovrBoundaryTestResult +/// +OVR_PUBLIC_FUNCTION(ovrResult) +ovr_TestBoundaryPoint( + ovrSession session, + const ovrVector3f* point, + ovrBoundaryType singleBoundaryType, + ovrBoundaryTestResult* outTestResult); + +/// Compatibility stub. +/// +/// \deprecated Previously set the look and feel of the Boundary System - this functionality has +/// been removed. +/// +/// +/// \param[in] session Specifies an ovrSession previously returned by ovr_Create. +/// \param[in] lookAndFeel Look and feel parameters. +/// \return Returns ovrSuccess upon success. +/// \see ovrBoundaryLookAndFeel +/// +OVR_PUBLIC_FUNCTION(ovrResult) +ovr_SetBoundaryLookAndFeel(ovrSession session, const ovrBoundaryLookAndFeel* lookAndFeel); + +/// Resets the look and feel of the Boundary System to its default state. +/// +/// \param[in] session Specifies an ovrSession previously returned by ovr_Create. +/// \return Returns ovrSuccess upon success. +/// \see ovrBoundaryLookAndFeel +/// +OVR_PUBLIC_FUNCTION(ovrResult) ovr_ResetBoundaryLookAndFeel(ovrSession session); + +/// Gets the geometry of the Boundary System's "play area" or "outer boundary" as 3D floor points. +/// +/// \param[in] session Specifies an ovrSession previously returned by ovr_Create. +/// \param[in] boundaryType Must be either ovrBoundary_Outer or ovrBoundary_PlayArea. +/// \param[out] outFloorPoints Array of 3D points (in clockwise order) defining the boundary at +/// floor height (can be NULL to retrieve only the number of points). +/// \param[out] outFloorPointsCount Number of 3D points returned in the array. +/// \return Returns an ovrResult for which OVR_SUCCESS(result) is false upon error and true +/// upon success. Return values include but aren't limited to: +/// - ovrSuccess: The call succeeded and a result was returned. +/// - ovrSuccess_BoundaryInvalid: The call succeeded but the result is not a valid boundary due +/// to not being set up. +/// +OVR_PUBLIC_FUNCTION(ovrResult) +ovr_GetBoundaryGeometry( + ovrSession session, + ovrBoundaryType boundaryType, + ovrVector3f* outFloorPoints, + int* outFloorPointsCount); + +/// Gets the dimension of the Boundary System's "play area" or "outer boundary". +/// +/// \param[in] session Specifies an ovrSession previously returned by ovr_Create. +/// \param[in] boundaryType Must be either ovrBoundary_Outer or ovrBoundary_PlayArea. +/// \param[out] outDimensions Dimensions of the axis aligned bounding box that encloses the area in +/// meters (width, height and length). +/// \return Returns an ovrResult for which OVR_SUCCESS(result) is false upon error and true +/// upon success. Return values include but aren't limited to: +/// - ovrSuccess: The call succeeded and a result was returned. +/// - ovrSuccess_BoundaryInvalid: The call succeeded but the result is not a valid boundary due +/// to not being set up. +/// +OVR_PUBLIC_FUNCTION(ovrResult) +ovr_GetBoundaryDimensions( + ovrSession session, + ovrBoundaryType boundaryType, + ovrVector3f* outDimensions); + +/// Returns if the boundary is currently visible. +/// Note: visibility is false if the user has turned off boundaries, otherwise, it's true if +/// the app has requested boundaries to be visible or if any tracked device is currently +/// triggering it. This may not exactly match rendering due to fade-in and fade-out effects. +/// +/// \param[in] session Specifies an ovrSession previously returned by ovr_Create. +/// \param[out] outIsVisible ovrTrue, if the boundary is visible. +/// \return Returns an ovrResult for which OVR_SUCCESS(result) is false upon error and true +/// upon success. Return values include but aren't limited to: +/// - ovrSuccess: Result was successful and a result was returned. +/// - ovrSuccess_BoundaryInvalid: The call succeeded but the result is not a valid boundary due +/// to not being set up. +/// +OVR_PUBLIC_FUNCTION(ovrResult) ovr_GetBoundaryVisible(ovrSession session, ovrBool* outIsVisible); + +/// Requests boundary to be visible. +/// +/// \param[in] session Specifies an ovrSession previously returned by ovr_Create. +/// \param[in] visible forces the outer boundary to be visible. An application can't force it +/// to be invisible, but can cancel its request by passing false. +/// \return Returns ovrSuccess upon success. +/// +OVR_PUBLIC_FUNCTION(ovrResult) ovr_RequestBoundaryVisible(ovrSession session, ovrBool visible); + +// ----------------------------------------------------------------------------------- +/// @name Mixed reality capture support +/// +/// Defines functions used for mixed reality capture / third person cameras. +/// + +/// Returns the number of camera properties of all cameras +/// \param[in] session Specifies an ovrSession previously returned by ovr_Create. +/// \param[in, out] cameras Pointer to the array. If null and the provided array capacity is +/// sufficient, will return ovrError_NullArrayPointer. +/// \param[in, out] inoutCameraCount Supply the +/// array capacity, will return the actual # of cameras defined. If *inoutCameraCount is too small, +/// will return ovrError_InsufficientArraySize. +/// \return Returns the list of external cameras the system knows about. +/// Returns ovrError_NoExternalCameraInfo if there is not any eternal camera information. +OVR_PUBLIC_FUNCTION(ovrResult) +ovr_GetExternalCameras( + ovrSession session, + ovrExternalCamera* cameras, + unsigned int* inoutCameraCount); + +/// Sets the camera intrinsics and/or extrinsics stored for the cameraName camera +/// Names must be < 32 characters and null-terminated. +/// +/// \param[in] session Specifies an ovrSession previously returned by ovr_Create. +/// \param[in] name Specifies which camera to set the intrinsics or extrinsics for. +/// The name must be at most OVR_EXTERNAL_CAMERA_NAME_SIZE - 1 +/// characters. Otherwise, ovrError_ExternalCameraNameWrongSize is returned. +/// \param[in] intrinsics Contains the intrinsic parameters to set, can be null +/// \param[in] extrinsics Contains the extrinsic parameters to set, can be null +/// \return Returns ovrSuccess or an ovrError code +OVR_PUBLIC_FUNCTION(ovrResult) +ovr_SetExternalCameraProperties( + ovrSession session, + const char* name, + const ovrCameraIntrinsics* const intrinsics, + const ovrCameraExtrinsics* const extrinsics); + +///@} + +#endif // !defined(OVR_EXPORTING_CAPI) + +//------------------------------------------------------------------------------------- +// @name Layers +// +///@{ + +/// Specifies the maximum number of layers supported by ovr_SubmitFrame. +/// +/// /see ovr_SubmitFrame +/// +enum { ovrMaxLayerCount = 16 }; + +/// Describes layer types that can be passed to ovr_SubmitFrame. +/// Each layer type has an associated struct, such as ovrLayerEyeFov. +/// +/// \see ovrLayerHeader +/// +typedef enum ovrLayerType_ { + /// Layer is disabled. + ovrLayerType_Disabled = 0, + + /// Described by ovrLayerEyeFov. + ovrLayerType_EyeFov = 1, + + /// Described by ovrLayerEyeFovDepth. + ovrLayerType_EyeFovDepth = 2, + + /// Described by ovrLayerQuad. Previously called ovrLayerType_QuadInWorld. + ovrLayerType_Quad = 3, + + // enum 4 used to be ovrLayerType_QuadHeadLocked. Instead, use ovrLayerType_Quad with + // ovrLayerFlag_HeadLocked. + + /// Described by ovrLayerEyeMatrix. + ovrLayerType_EyeMatrix = 5, + + + /// Described by ovrLayerEyeFovMultires. + ovrLayerType_EyeFovMultires = 7, + + /// Described by ovrLayerCylinder. + ovrLayerType_Cylinder = 8, + + /// Described by ovrLayerCube + ovrLayerType_Cube = 10, + + + + + ovrLayerType_EnumSize = 0x7fffffff ///< Force type int32_t. + +} ovrLayerType; + +/// Identifies flags used by ovrLayerHeader and which are passed to ovr_SubmitFrame. +/// +/// \see ovrLayerHeader +/// +typedef enum ovrLayerFlags_ { + /// ovrLayerFlag_HighQuality enables 4x anisotropic sampling during the composition of the layer. + /// The benefits are mostly visible at the periphery for high-frequency & high-contrast visuals. + /// For best results consider combining this flag with an ovrTextureSwapChain that has mipmaps and + /// instead of using arbitrary sized textures, prefer texture sizes that are powers-of-two. + /// Actual rendered viewport and doesn't necessarily have to fill the whole texture. + ovrLayerFlag_HighQuality = 0x01, + + /// ovrLayerFlag_TextureOriginAtBottomLeft: the opposite is TopLeft. + /// Generally this is false for D3D, true for OpenGL. + ovrLayerFlag_TextureOriginAtBottomLeft = 0x02, + + /// Mark this surface as "headlocked", which means it is specified + /// relative to the HMD and moves with it, rather than being specified + /// relative to sensor/torso space and remaining still while the head moves. + /// What used to be ovrLayerType_QuadHeadLocked is now ovrLayerType_Quad plus this flag. + /// However the flag can be applied to any layer type to achieve a similar effect. + ovrLayerFlag_HeadLocked = 0x04, + + + ovrLayerFlags_EnumSize = 0x7fffffff ///< \internal Force type int32_t. +} ovrLayerFlags; + +/// Defines properties shared by all ovrLayer structs, such as ovrLayerEyeFov. +/// +/// ovrLayerHeader is used as a base member in these larger structs. +/// This struct cannot be used by itself except for the case that Type is ovrLayerType_Disabled. +/// +/// \see ovrLayerType, ovrLayerFlags +/// +typedef struct ovrLayerHeader_ ovrLayerHeader; +struct OVR_ALIGNAS(OVR_PTR_SIZE) ovrLayerHeader_ { + ovrLayerType Type; ///< Described by ovrLayerType. + unsigned Flags; ///< Described by ovrLayerFlags. + + char Reserved[128]; +}; + +/// Describes a layer that specifies a monoscopic or stereoscopic view. +/// This is the kind of layer that's typically used as layer 0 to ovr_SubmitFrame, +/// as it is the kind of layer used to render a 3D stereoscopic view. +/// +/// Three options exist with respect to mono/stereo texture usage: +/// - ColorTexture[0] and ColorTexture[1] contain the left and right stereo renderings, +/// respectively. +/// Viewport[0] and Viewport[1] refer to ColorTexture[0] and ColorTexture[1], respectively. +/// - ColorTexture[0] contains both the left and right renderings, ColorTexture[1] is NULL, +/// and Viewport[0] and Viewport[1] refer to sub-rects with ColorTexture[0]. +/// - ColorTexture[0] contains a single monoscopic rendering, and Viewport[0] and +/// Viewport[1] both refer to that rendering. +/// +/// \see ovrTextureSwapChain, ovr_SubmitFrame +/// +typedef struct OVR_ALIGNAS(OVR_PTR_SIZE) ovrLayerEyeFov_ { + /// Header.Type must be ovrLayerType_EyeFov. + ovrLayerHeader Header; + + /// ovrTextureSwapChains for the left and right eye respectively. + /// The second one of which can be NULL for cases described above. + ovrTextureSwapChain ColorTexture[ovrEye_Count]; + + /// Specifies the ColorTexture sub-rect UV coordinates. + /// Both Viewport[0] and Viewport[1] must be valid. + ovrRecti Viewport[ovrEye_Count]; + + /// The viewport field of view. + ovrFovPort Fov[ovrEye_Count]; + + /// Specifies the position and orientation of each eye view, with position specified in meters. + /// RenderPose will typically be the value returned from ovr_CalcEyePoses, + /// but can be different in special cases if a different head pose is used for rendering. + ovrPosef RenderPose[ovrEye_Count]; + + /// Specifies the timestamp when the source ovrPosef (used in calculating RenderPose) + /// was sampled from the SDK. Typically retrieved by calling ovr_GetTimeInSeconds + /// around the instant the application calls ovr_GetTrackingState + /// The main purpose for this is to accurately track app tracking latency. + double SensorSampleTime; +} ovrLayerEyeFov; + +/// Describes a layer that specifies a monoscopic or stereoscopic view, +/// with depth textures in addition to color textures. This is typically used to support +/// positional time warp. This struct is the same as ovrLayerEyeFov, but with the addition +/// of DepthTexture and ProjectionDesc. +/// +/// ProjectionDesc can be created using ovrTimewarpProjectionDesc_FromProjection. +/// +/// Three options exist with respect to mono/stereo texture usage: +/// - ColorTexture[0] and ColorTexture[1] contain the left and right stereo renderings, +/// respectively. +/// Viewport[0] and Viewport[1] refer to ColorTexture[0] and ColorTexture[1], respectively. +/// - ColorTexture[0] contains both the left and right renderings, ColorTexture[1] is NULL, +/// and Viewport[0] and Viewport[1] refer to sub-rects with ColorTexture[0]. +/// - ColorTexture[0] contains a single monoscopic rendering, and Viewport[0] and +/// Viewport[1] both refer to that rendering. +/// +/// \see ovrTextureSwapChain, ovr_SubmitFrame +/// +typedef struct OVR_ALIGNAS(OVR_PTR_SIZE) ovrLayerEyeFovDepth_ { + /// Header.Type must be ovrLayerType_EyeFovDepth. + ovrLayerHeader Header; + + /// ovrTextureSwapChains for the left and right eye respectively. + /// The second one of which can be NULL for cases described above. + ovrTextureSwapChain ColorTexture[ovrEye_Count]; + + /// Specifies the ColorTexture sub-rect UV coordinates. + /// Both Viewport[0] and Viewport[1] must be valid. + ovrRecti Viewport[ovrEye_Count]; + + /// The viewport field of view. + ovrFovPort Fov[ovrEye_Count]; + + /// Specifies the position and orientation of each eye view, with position specified in meters. + /// RenderPose will typically be the value returned from ovr_CalcEyePoses, + /// but can be different in special cases if a different head pose is used for rendering. + ovrPosef RenderPose[ovrEye_Count]; + + /// Specifies the timestamp when the source ovrPosef (used in calculating RenderPose) + /// was sampled from the SDK. Typically retrieved by calling ovr_GetTimeInSeconds + /// around the instant the application calls ovr_GetTrackingState + /// The main purpose for this is to accurately track app tracking latency. + double SensorSampleTime; + + /// Depth texture for depth composition with overlays + /// Must map 1:1 to the ColorTexture. + ovrTextureSwapChain DepthTexture[ovrEye_Count]; + + /// Specifies how to convert DepthTexture information into meters. + /// \see ovrTimewarpProjectionDesc_FromProjection + ovrTimewarpProjectionDesc ProjectionDesc; +} ovrLayerEyeFovDepth; + + +/// Describes eye texture layouts. Used with ovrLayerEyeFovMultires. +/// +typedef enum ovrTextureLayout_ { + ovrTextureLayout_Rectilinear = 0, ///< Regular eyeFov layer. + ovrTextureLayout_Octilinear = 1, ///< Octilinear extension must be enabled. + ovrTextureLayout_EnumSize = 0x7fffffff ///< \internal Force type int32_t. +} ovrTextureLayout; + +/// Multiresolution descriptor for Octilinear. +/// +/// Usage of this layer must be successfully enabled via ovr_EnableExtension +/// before it can be used. +/// +/// \see ovrLayerEyeFovMultres +/// +typedef struct OVR_ALIGNAS(OVR_PTR_SIZE) ovrTextureLayoutOctilinear_ { + // W warping + float WarpLeft; + float WarpRight; + float WarpUp; + float WarpDown; + + // Size of W quadrants. + // + // SizeLeft + SizeRight <= Viewport.Size.w + // SizeUp + sizeDown <= Viewport.Size.h + // + // Clip space (0,0) is located at Viewport.Pos + (SizeLeft,SizeUp) where + // Viewport is given in the layer description. + // + // Viewport Top left + // +-----------------------------------------------------+ + // | ^ | | + // | | | | + // | 0 SizeUp 1 | | + // | | |<--Portion of viewport + // | | | determined by sizes + // | | | | + // |<--------SizeLeft-------+-------SizeRight------>| | + // | | | | + // | | | | + // | 2 SizeDown 3 | | + // | | | | + // | | | | + // | v | | + // +------------------------------------------------+ | + // | | + // +-----------------------------------------------------+ + // Viewport bottom right + // + // For example, when rendering quadrant 0 its scissor rectangle will be + // + // Top = 0 + // Left = 0 + // Right = SizeLeft + // Bottom = SizeUp + // + // and the scissor rectangle for quadrant 1 will be: + // + // Top = 0 + // Left = SizeLeft + // Right = SizeLeft + SizeRight + // Bottom = SizeUp + // + float SizeLeft; + float SizeRight; + float SizeUp; + float SizeDown; + +} ovrTextureLayoutOctilinear; + +/// Combines texture layout descriptors. +/// +typedef union OVR_ALIGNAS(OVR_PTR_SIZE) ovrTextureLayoutDesc_Union_ { + ovrTextureLayoutOctilinear Octilinear[ovrEye_Count]; +} ovrTextureLayoutDesc_Union; + +/// Describes a layer that specifies a monoscopic or stereoscopic view with +/// support for optional multiresolution textures. This struct is the same as +/// ovrLayerEyeFov plus texture layout parameters. +/// +/// Three options exist with respect to mono/stereo texture usage: +/// - ColorTexture[0] and ColorTexture[1] contain the left and right stereo renderings, +/// respectively. +/// Viewport[0] and Viewport[1] refer to ColorTexture[0] and ColorTexture[1], respectively. +/// - ColorTexture[0] contains both the left and right renderings, ColorTexture[1] is NULL, +/// and Viewport[0] and Viewport[1] refer to sub-rects with ColorTexture[0]. +/// - ColorTexture[0] contains a single monoscopic rendering, and Viewport[0] and +/// Viewport[1] both refer to that rendering. +/// +/// \see ovrTextureSwapChain, ovr_SubmitFrame +/// +typedef struct OVR_ALIGNAS(OVR_PTR_SIZE) ovrLayerEyeFovMultires_ { + /// Header.Type must be ovrLayerType_EyeFovMultires. + ovrLayerHeader Header; + + /// ovrTextureSwapChains for the left and right eye respectively. + /// The second one of which can be NULL for cases described above. + ovrTextureSwapChain ColorTexture[ovrEye_Count]; + + /// Specifies the ColorTexture sub-rect UV coordinates. + /// Both Viewport[0] and Viewport[1] must be valid. + ovrRecti Viewport[ovrEye_Count]; + + /// The viewport field of view. + ovrFovPort Fov[ovrEye_Count]; + + /// Specifies the position and orientation of each eye view, with position specified in meters. + /// RenderPose will typically be the value returned from ovr_CalcEyePoses, + /// but can be different in special cases if a different head pose is used for rendering. + ovrPosef RenderPose[ovrEye_Count]; + + /// Specifies the timestamp when the source ovrPosef (used in calculating RenderPose) + /// was sampled from the SDK. Typically retrieved by calling ovr_GetTimeInSeconds + /// around the instant the application calls ovr_GetTrackingState + /// The main purpose for this is to accurately track app tracking latency. + double SensorSampleTime; + + /// Specifies layout type of textures. + ovrTextureLayout TextureLayout; + + /// Specifies texture layout parameters. + ovrTextureLayoutDesc_Union TextureLayoutDesc; +} ovrLayerEyeFovMultires; + +/// Describes a layer that specifies a monoscopic or stereoscopic view. +/// This uses a direct 3x4 matrix to map from view space to the UV coordinates. +/// It is essentially the same thing as ovrLayerEyeFov but using a much +/// lower level. This is mainly to provide compatibility with specific apps. +/// Unless the application really requires this flexibility, it is usually better +/// to use ovrLayerEyeFov. +/// +/// Three options exist with respect to mono/stereo texture usage: +/// - ColorTexture[0] and ColorTexture[1] contain the left and right stereo renderings, +/// respectively. +/// Viewport[0] and Viewport[1] refer to ColorTexture[0] and ColorTexture[1], respectively. +/// - ColorTexture[0] contains both the left and right renderings, ColorTexture[1] is NULL, +/// and Viewport[0] and Viewport[1] refer to sub-rects with ColorTexture[0]. +/// - ColorTexture[0] contains a single monoscopic rendering, and Viewport[0] and +/// Viewport[1] both refer to that rendering. +/// +/// \see ovrTextureSwapChain, ovr_SubmitFrame +/// +typedef struct OVR_ALIGNAS(OVR_PTR_SIZE) ovrLayerEyeMatrix_ { + /// Header.Type must be ovrLayerType_EyeMatrix. + ovrLayerHeader Header; + + /// ovrTextureSwapChains for the left and right eye respectively. + /// The second one of which can be NULL for cases described above. + ovrTextureSwapChain ColorTexture[ovrEye_Count]; + + /// Specifies the ColorTexture sub-rect UV coordinates. + /// Both Viewport[0] and Viewport[1] must be valid. + ovrRecti Viewport[ovrEye_Count]; + + /// Specifies the position and orientation of each eye view, with position specified in meters. + /// RenderPose will typically be the value returned from ovr_CalcEyePoses, + /// but can be different in special cases if a different head pose is used for rendering. + ovrPosef RenderPose[ovrEye_Count]; + + /// Specifies the mapping from a view-space vector + /// to a UV coordinate on the textures given above. + /// P = (x,y,z,1)*Matrix + /// TexU = P.x/P.z + /// TexV = P.y/P.z + ovrMatrix4f Matrix[ovrEye_Count]; + + /// Specifies the timestamp when the source ovrPosef (used in calculating RenderPose) + /// was sampled from the SDK. Typically retrieved by calling ovr_GetTimeInSeconds + /// around the instant the application calls ovr_GetTrackingState + /// The main purpose for this is to accurately track app tracking latency. + double SensorSampleTime; +} ovrLayerEyeMatrix; + +/// Describes a layer of Quad type, which is a single quad in world or viewer space. +/// It is used for ovrLayerType_Quad. This type of layer represents a single +/// object placed in the world and not a stereo view of the world itself. +/// +/// A typical use of ovrLayerType_Quad is to draw a television screen in a room +/// that for some reason is more convenient to draw as a layer than as part of the main +/// view in layer 0. For example, it could implement a 3D popup GUI that is drawn at a +/// higher resolution than layer 0 to improve fidelity of the GUI. +/// +/// Quad layers are visible from both sides; they are not back-face culled. +/// +/// \see ovrTextureSwapChain, ovr_SubmitFrame +/// +typedef struct OVR_ALIGNAS(OVR_PTR_SIZE) ovrLayerQuad_ { + /// Header.Type must be ovrLayerType_Quad. + ovrLayerHeader Header; + + /// Contains a single image, never with any stereo view. + ovrTextureSwapChain ColorTexture; + + /// Specifies the ColorTexture sub-rect UV coordinates. + ovrRecti Viewport; + + /// Specifies the orientation and position of the center point of a Quad layer type. + /// The supplied direction is the vector perpendicular to the quad. + /// The position is in real-world meters (not the application's virtual world, + /// the physical world the user is in) and is relative to the "zero" position + /// set by ovr_RecenterTrackingOrigin unless the ovrLayerFlag_HeadLocked flag is used. + ovrPosef QuadPoseCenter; + + /// Width and height (respectively) of the quad in meters. + ovrVector2f QuadSize; +} ovrLayerQuad; + +/// Describes a layer of type ovrLayerType_Cylinder which is a single cylinder +/// relative to the recentered origin. This type of layer represents a single +/// object placed in the world and not a stereo view of the world itself. +/// +/// -Z +Y +/// U=0 +--+--+ U=1 +/// +---+ | +---+ +-----------------+ - V=0 +/// +--+ \ | / +--+ | | | +/// +-+ \ / +-+ | | | +/// ++ \ A / ++ | | | +/// ++ \---/ ++ | | | +/// | \ / | | +X | | +/// +-------------C------R------+ +X +--------C--------+ | <--- Height +/// (+Y is out of screen) | | | +/// | | | +/// R = Radius | | | +/// A = Angle (0,2*Pi) | | | +/// C = CylinderPoseCenter | | | +/// U/V = UV Coordinates +-----------------+ - V=1 +/// +/// An identity CylinderPoseCenter places the center of the cylinder +/// at the recentered origin unless the headlocked flag is set. +/// +/// Does not utilize HmdSpaceToWorldScaleInMeters. If necessary, adjust +/// translation and radius. +/// +/// \note Only the interior surface of the cylinder is visible. Use cylinder +/// layers when the user cannot leave the extents of the cylinder. Artifacts may +/// appear when viewing the cylinder's exterior surface. Additionally, while the +/// interface supports an Angle that ranges from [0,2*Pi] the angle should +/// remain less than 1.9*PI to avoid artifacts where the cylinder edges +/// converge. +/// +/// \see ovrTextureSwapChain, ovr_SubmitFrame +/// +typedef struct OVR_ALIGNAS(OVR_PTR_SIZE) ovrLayerCylinder_ { + /// Header.Type must be ovrLayerType_Cylinder. + ovrLayerHeader Header; + + /// Contains a single image, never with any stereo view. + ovrTextureSwapChain ColorTexture; + + /// Specifies the ColorTexture sub-rect UV coordinates. + ovrRecti Viewport; + + /// Specifies the orientation and position of the center point of a cylinder layer type. + /// The position is in real-world meters not the application's virtual world, + /// but the physical world the user is in. It is relative to the "zero" position + /// set by ovr_RecenterTrackingOrigin unless the ovrLayerFlag_HeadLocked flag is used. + ovrPosef CylinderPoseCenter; + + /// Radius of the cylinder in meters. + float CylinderRadius; + + /// Angle in radians. Range is from 0 to 2*Pi exclusive covering the entire + /// cylinder (see diagram and note above). + float CylinderAngle; + + /// Custom aspect ratio presumably set based on 'Viewport'. Used to + /// calculate the height of the cylinder based on the arc-length (CylinderAngle) + /// and radius (CylinderRadius) given above. The height of the cylinder is + /// given by: height = (CylinderRadius * CylinderAngle) / CylinderAspectRatio. + /// Aspect ratio is width / height. + float CylinderAspectRatio; +} ovrLayerCylinder; + +/// Describes a layer of type ovrLayerType_Cube which is a single timewarped +/// cubemap at infinity. When looking down the recentered origin's -Z axis, +X +/// face is left and +Y face is up. Similarly, if headlocked the +X face is +/// left, +Y face is up and -Z face is forward. Note that the coordinate system +/// is left-handed. +/// +/// ovrLayerFlag_TextureOriginAtBottomLeft flag is not supported by ovrLayerCube. +/// +/// \see ovrTextureSwapChain, ovr_SubmitFrame +/// +typedef struct OVR_ALIGNAS(OVR_PTR_SIZE) ovrLayerCube_ { + /// Header.Type must be ovrLayerType_Cube. + ovrLayerHeader Header; + + /// Orientation of the cube. + ovrQuatf Orientation; + + /// Contains a single cubemap swapchain (not a stereo pair of swapchains). + ovrTextureSwapChain CubeMapTexture; +} ovrLayerCube; + + +/// Union that combines ovrLayer types in a way that allows them +/// to be used in a polymorphic way. +typedef union ovrLayer_Union_ { + ovrLayerHeader Header; + ovrLayerEyeFov EyeFov; + ovrLayerEyeFovDepth EyeFovDepth; + ovrLayerQuad Quad; + ovrLayerEyeMatrix EyeMatrix; + ovrLayerEyeFovMultires Multires; + ovrLayerCylinder Cylinder; + ovrLayerCube Cube; +} ovrLayer_Union; + +//@} + +#if !defined(OVR_EXPORTING_CAPI) + +/// @name SDK Distortion Rendering +/// +/// All of rendering functions including the configure and frame functions +/// are not thread safe. It is OK to use ConfigureRendering on one thread and handle +/// frames on another thread, but explicit synchronization must be done since +/// functions that depend on configured state are not reentrant. +/// +/// These functions support rendering of distortion by the SDK. +/// +//@{ + +/// TextureSwapChain creation is rendering API-specific. +/// ovr_CreateTextureSwapChainDX, ovr_CreateTextureSwapChainGL and ovr_CreateTextureSwapChainVk +/// can be found in the rendering API-specific headers, such as OVR_CAPI_D3D.h, OVR_CAPI_GL.h +/// and OVR_CAPI_Vk.h. +/// +/// Gets the number of buffers in an ovrTextureSwapChain. +/// +/// \param[in] session Specifies an ovrSession previously returned by ovr_Create. +/// \param[in] chain Specifies the ovrTextureSwapChain for which the length should be retrieved. +/// \param[out] out_Length Returns the number of buffers in the specified chain. +/// +/// \return Returns an ovrResult for which OVR_SUCCESS(result) is false upon error. +/// +/// \see ovr_CreateTextureSwapChainDX, ovr_CreateTextureSwapChainGL, ovr_CreateTextureSwapChainVk +/// +OVR_PUBLIC_FUNCTION(ovrResult) +ovr_GetTextureSwapChainLength(ovrSession session, ovrTextureSwapChain chain, int* out_Length); + +/// Gets the current index in an ovrTextureSwapChain. +/// +/// \param[in] session Specifies an ovrSession previously returned by ovr_Create. +/// \param[in] chain Specifies the ovrTextureSwapChain for which the index should be retrieved. +/// \param[out] out_Index Returns the current (free) index in specified chain. +/// +/// \return Returns an ovrResult for which OVR_SUCCESS(result) is false upon error. +/// +/// \see ovr_CreateTextureSwapChainDX, ovr_CreateTextureSwapChainGL, ovr_CreateTextureSwapChainVk +/// +OVR_PUBLIC_FUNCTION(ovrResult) +ovr_GetTextureSwapChainCurrentIndex(ovrSession session, ovrTextureSwapChain chain, int* out_Index); + +/// Gets the description of the buffers in an ovrTextureSwapChain +/// +/// \param[in] session Specifies an ovrSession previously returned by ovr_Create. +/// \param[in] chain Specifies the ovrTextureSwapChain for which the description +/// should be retrieved. +/// \param[out] out_Desc Returns the description of the specified chain. +/// +/// \return Returns an ovrResult for which OVR_SUCCESS(result) is false upon error. +/// +/// \see ovr_CreateTextureSwapChainDX, ovr_CreateTextureSwapChainGL, ovr_CreateTextureSwapChainVk +/// +OVR_PUBLIC_FUNCTION(ovrResult) +ovr_GetTextureSwapChainDesc( + ovrSession session, + ovrTextureSwapChain chain, + ovrTextureSwapChainDesc* out_Desc); + +/// Commits any pending changes to an ovrTextureSwapChain, and advances its current index +/// +/// \param[in] session Specifies an ovrSession previously returned by ovr_Create. +/// \param[in] chain Specifies the ovrTextureSwapChain to commit. +/// +/// \note When Commit is called, the texture at the current index is considered ready for use by the +/// runtime, and further writes to it should be avoided. The swap chain's current index is advanced, +/// providing there's room in the chain. The next time the SDK dereferences this texture swap chain, +/// it will synchronize with the app's graphics context and pick up the submitted index, opening up +/// room in the swap chain for further commits. +/// +/// \return Returns an ovrResult for which OVR_SUCCESS(result) is false upon error. +/// Failures include but aren't limited to: +/// - ovrError_TextureSwapChainFull: ovr_CommitTextureSwapChain was called too many times on a +/// texture swapchain without calling submit to use the chain. +/// +/// \see ovr_CreateTextureSwapChainDX, ovr_CreateTextureSwapChainGL, ovr_CreateTextureSwapChainVk +/// +OVR_PUBLIC_FUNCTION(ovrResult) +ovr_CommitTextureSwapChain(ovrSession session, ovrTextureSwapChain chain); + +/// Destroys an ovrTextureSwapChain and frees all the resources associated with it. +/// +/// \param[in] session Specifies an ovrSession previously returned by ovr_Create. +/// \param[in] chain Specifies the ovrTextureSwapChain to destroy. If it is NULL then +/// this function has no effect. +/// +/// \see ovr_CreateTextureSwapChainDX, ovr_CreateTextureSwapChainGL, ovr_CreateTextureSwapChainVk +/// +OVR_PUBLIC_FUNCTION(void) +ovr_DestroyTextureSwapChain(ovrSession session, ovrTextureSwapChain chain); + +/// MirrorTexture creation is rendering API-specific. +/// ovr_CreateMirrorTextureWithOptionsDX and ovr_CreateMirrorTextureWithOptionsGL can be found in +/// rendering API-specific headers, such as OVR_CAPI_D3D.h and OVR_CAPI_GL.h + +/// Destroys a mirror texture previously created by one of the mirror texture creation functions. +/// +/// \param[in] session Specifies an ovrSession previously returned by ovr_Create. +/// \param[in] mirrorTexture Specifies the ovrTexture to destroy. If it is NULL then +/// this function has no effect. +/// +/// \see ovr_CreateMirrorTextureWithOptionsDX, ovr_CreateMirrorTextureWithOptionsGL +/// +OVR_PUBLIC_FUNCTION(void) +ovr_DestroyMirrorTexture(ovrSession session, ovrMirrorTexture mirrorTexture); + +/// Calculates the recommended viewport size for rendering a given eye within the HMD +/// with a given FOV cone. +/// +/// Higher FOV will generally require larger textures to maintain quality. +/// Apps packing multiple eye views together on the same texture should ensure there are +/// at least 8 pixels of padding between them to prevent texture filtering and chromatic +/// aberration causing images to leak between the two eye views. +/// +/// \param[in] session Specifies an ovrSession previously returned by ovr_Create. +/// \param[in] eye Specifies which eye (left or right) to calculate for. +/// \param[in] fov Specifies the ovrFovPort to use. +/// \param[in] pixelsPerDisplayPixel Specifies the ratio of the number of render target pixels +/// to display pixels at the center of distortion. 1.0 is the default value. Lower +/// values can improve performance, higher values give improved quality. +/// +/// <b>Example code</b> +/// \code{.cpp} +/// ovrHmdDesc hmdDesc = ovr_GetHmdDesc(session); +/// ovrSizei eyeSizeLeft = ovr_GetFovTextureSize(session, ovrEye_Left, +/// hmdDesc.DefaultEyeFov[ovrEye_Left], 1.0f); +/// ovrSizei eyeSizeRight = ovr_GetFovTextureSize(session, ovrEye_Right, +/// hmdDesc.DefaultEyeFov[ovrEye_Right], 1.0f); +/// \endcode +/// +/// \return Returns the texture width and height size. +/// +OVR_PUBLIC_FUNCTION(ovrSizei) +ovr_GetFovTextureSize( + ovrSession session, + ovrEyeType eye, + ovrFovPort fov, + float pixelsPerDisplayPixel); + +/// Computes the distortion viewport, view adjust, and other rendering parameters for +/// the specified eye. +/// +/// \param[in] session Specifies an ovrSession previously returned by ovr_Create. +/// \param[in] eyeType Specifies which eye (left or right) for which to perform calculations. +/// \param[in] fov Specifies the ovrFovPort to use. +/// +/// \return Returns the computed ovrEyeRenderDesc for the given eyeType and field of view. +/// +/// \see ovrEyeRenderDesc +/// +OVR_PUBLIC_FUNCTION(ovrEyeRenderDesc) +ovr_GetRenderDesc(ovrSession session, ovrEyeType eyeType, ovrFovPort fov); + +/// Waits until surfaces are available and it is time to begin rendering the frame. Must be +/// called before ovr_BeginFrame, but not necessarily from the same thread. +/// +/// \param[in] session Specifies an ovrSession previously returned by ovr_Create. +/// +/// \param[in] frameIndex Specifies the targeted application frame index. +/// +/// \return Returns an ovrResult for which OVR_SUCCESS(result) is false upon error and true +/// upon success. Return values include but aren't limited to: +/// - ovrSuccess: command completed successfully. +/// - ovrSuccess_NotVisible: rendering of a previous frame completed successfully but was not +/// displayed on the HMD, usually because another application currently has ownership of the +/// HMD. Applications receiving this result should stop rendering new content and call +/// ovr_GetSessionStatus to detect visibility. +/// - ovrError_DisplayLost: The session has become invalid (such as due to a device removal) +/// and the shared resources need to be released (ovr_DestroyTextureSwapChain), the session +/// needs to destroyed (ovr_Destroy) and recreated (ovr_Create), and new resources need to be +/// created (ovr_CreateTextureSwapChainXXX). The application's existing private graphics +/// resources do not need to be recreated unless the new ovr_Create call returns a different +/// GraphicsLuid. +/// +/// \see ovr_BeginFrame, ovr_EndFrame, ovr_GetSessionStatus +/// +OVR_PUBLIC_FUNCTION(ovrResult) +ovr_WaitToBeginFrame(ovrSession session, long long frameIndex); + +/// Called from render thread before application begins rendering. Must be called after +/// ovr_WaitToBeginFrame and before ovr_EndFrame, but not necessarily from the same threads. +/// +/// \param[in] session Specifies an ovrSession previously returned by ovr_Create. +/// +/// \param[in] frameIndex Specifies the targeted application frame index. It must match what was +/// passed to ovr_WaitToBeginFrame. +/// +/// \return Returns an ovrResult for which OVR_SUCCESS(result) is false upon error and true +/// upon success. Return values include but aren't limited to: +/// - ovrSuccess: command completed successfully. +/// - ovrError_DisplayLost: The session has become invalid (such as due to a device removal) +/// and the shared resources need to be released (ovr_DestroyTextureSwapChain), the session +/// needs to destroyed (ovr_Destroy) and recreated (ovr_Create), and new resources need to be +/// created (ovr_CreateTextureSwapChainXXX). The application's existing private graphics +/// resources do not need to be recreated unless the new ovr_Create call returns a different +/// GraphicsLuid. +/// +/// \see ovr_WaitToBeginFrame, ovr_EndFrame +/// +OVR_PUBLIC_FUNCTION(ovrResult) +ovr_BeginFrame(ovrSession session, long long frameIndex); + +/// Called from render thread after application has finished rendering. Must be called after +/// ovr_BeginFrame, but not necessarily from the same thread. Submits layers for distortion and +/// display, which will happen asynchronously. +/// +/// \param[in] session Specifies an ovrSession previously returned by ovr_Create. +/// +/// \param[in] frameIndex Specifies the targeted application frame index. It must match what was +/// passed to ovr_BeginFrame. +/// +/// \param[in] viewScaleDesc Provides additional information needed only if layerPtrList contains +/// an ovrLayerType_Quad. If NULL, a default version is used based on the current +/// configuration and a 1.0 world scale. +/// +/// \param[in] layerPtrList Specifies a list of ovrLayer pointers, which can include NULL entries to +/// indicate that any previously shown layer at that index is to not be displayed. +/// Each layer header must be a part of a layer structure such as ovrLayerEyeFov or +/// ovrLayerQuad, with Header.Type identifying its type. A NULL layerPtrList entry in the +/// array indicates the absence of the given layer. +/// +/// \param[in] layerCount Indicates the number of valid elements in layerPtrList. The maximum +/// supported layerCount is not currently specified, but may be specified in a future +/// version. +/// +/// - Layers are drawn in the order they are specified in the array, regardless of the layer type. +/// +/// - Layers are not remembered between successive calls to ovr_EndFrame. A layer must be +/// specified in every call to ovr_EndFrame or it won't be displayed. +/// +/// - If a layerPtrList entry that was specified in a previous call to ovr_EndFrame is +/// passed as NULL or is of type ovrLayerType_Disabled, that layer is no longer displayed. +/// +/// - A layerPtrList entry can be of any layer type and multiple entries of the same layer type +/// are allowed. No layerPtrList entry may be duplicated (i.e. the same pointer as an earlier +/// entry). +/// +/// <b>Example code</b> +/// \code{.cpp} +/// ovrLayerEyeFov layer0; +/// ovrLayerQuad layer1; +/// ... +/// ovrLayerHeader* layers[2] = { &layer0.Header, &layer1.Header }; +/// ovrResult result = ovr_EndFrame(session, frameIndex, nullptr, layers, 2); +/// \endcode +/// +/// \return Returns an ovrResult for which OVR_SUCCESS(result) is false upon error and true +/// upon success. Return values include but aren't limited to: +/// - ovrSuccess: rendering completed successfully. +/// - ovrError_DisplayLost: The session has become invalid (such as due to a device removal) +/// and the shared resources need to be released (ovr_DestroyTextureSwapChain), the session +/// needs to destroyed (ovr_Destroy) and recreated (ovr_Create), and new resources need to be +/// created (ovr_CreateTextureSwapChainXXX). The application's existing private graphics +/// resources do not need to be recreated unless the new ovr_Create call returns a different +/// GraphicsLuid. +/// - ovrError_TextureSwapChainInvalid: The ovrTextureSwapChain is in an incomplete or +/// inconsistent state. Ensure ovr_CommitTextureSwapChain was called at least once first. +/// +/// \see ovr_WaitToBeginFrame, ovr_BeginFrame, ovrViewScaleDesc, ovrLayerHeader +/// +OVR_PUBLIC_FUNCTION(ovrResult) +ovr_EndFrame( + ovrSession session, + long long frameIndex, + const ovrViewScaleDesc* viewScaleDesc, + ovrLayerHeader const* const* layerPtrList, + unsigned int layerCount); + +/// Submits layers for distortion and display. +/// +/// \deprecated Use ovr_WaitToBeginFrame, ovr_BeginFrame, and ovr_EndFrame instead. +/// +/// ovr_SubmitFrame triggers distortion and processing which might happen asynchronously. +/// The function will return when there is room in the submission queue and surfaces +/// are available. Distortion might or might not have completed. +/// +/// \param[in] session Specifies an ovrSession previously returned by ovr_Create. +/// +/// \param[in] frameIndex Specifies the targeted application frame index, or 0 to refer to one frame +/// after the last time ovr_SubmitFrame was called. +/// +/// \param[in] viewScaleDesc Provides additional information needed only if layerPtrList contains +/// an ovrLayerType_Quad. If NULL, a default version is used based on the current +/// configuration and a 1.0 world scale. +/// +/// \param[in] layerPtrList Specifies a list of ovrLayer pointers, which can include NULL entries to +/// indicate that any previously shown layer at that index is to not be displayed. +/// Each layer header must be a part of a layer structure such as ovrLayerEyeFov or +/// ovrLayerQuad, with Header.Type identifying its type. A NULL layerPtrList entry in the +/// array indicates the absence of the given layer. +/// +/// \param[in] layerCount Indicates the number of valid elements in layerPtrList. The maximum +/// supported layerCount is not currently specified, but may be specified in a future +/// version. +/// +/// - Layers are drawn in the order they are specified in the array, regardless of the layer type. +/// +/// - Layers are not remembered between successive calls to ovr_SubmitFrame. A layer must be +/// specified in every call to ovr_SubmitFrame or it won't be displayed. +/// +/// - If a layerPtrList entry that was specified in a previous call to ovr_SubmitFrame is +/// passed as NULL or is of type ovrLayerType_Disabled, that layer is no longer displayed. +/// +/// - A layerPtrList entry can be of any layer type and multiple entries of the same layer type +/// are allowed. No layerPtrList entry may be duplicated (i.e. the same pointer as an earlier +/// entry). +/// +/// <b>Example code</b> +/// \code{.cpp} +/// ovrLayerEyeFov layer0; +/// ovrLayerQuad layer1; +/// ... +/// ovrLayerHeader* layers[2] = { &layer0.Header, &layer1.Header }; +/// ovrResult result = ovr_SubmitFrame(session, frameIndex, nullptr, layers, 2); +/// \endcode +/// +/// \return Returns an ovrResult for which OVR_SUCCESS(result) is false upon error and true +/// upon success. Return values include but aren't limited to: +/// - ovrSuccess: rendering completed successfully. +/// - ovrSuccess_NotVisible: rendering completed successfully but was not displayed on the HMD, +/// usually because another application currently has ownership of the HMD. Applications +/// receiving this result should stop rendering new content, call ovr_GetSessionStatus +/// to detect visibility. +/// - ovrError_DisplayLost: The session has become invalid (such as due to a device removal) +/// and the shared resources need to be released (ovr_DestroyTextureSwapChain), the session +/// needs to destroyed (ovr_Destroy) and recreated (ovr_Create), and new resources need to be +/// created (ovr_CreateTextureSwapChainXXX). The application's existing private graphics +/// resources do not need to be recreated unless the new ovr_Create call returns a different +/// GraphicsLuid. +/// - ovrError_TextureSwapChainInvalid: The ovrTextureSwapChain is in an incomplete or +/// inconsistent state. Ensure ovr_CommitTextureSwapChain was called at least once first. +/// +/// \see ovr_GetPredictedDisplayTime, ovrViewScaleDesc, ovrLayerHeader, ovr_GetSessionStatus +/// +OVR_PUBLIC_FUNCTION(ovrResult) +ovr_SubmitFrame( + ovrSession session, + long long frameIndex, + const ovrViewScaleDesc* viewScaleDesc, + ovrLayerHeader const* const* layerPtrList, + unsigned int layerCount); + +///@} + +#endif // !defined(OVR_EXPORTING_CAPI) + +//------------------------------------------------------------------------------------- +/// @name Frame Timing +/// +//@{ + +/// +/// Contains the performance stats for a given SDK compositor frame +/// +/// All of the 'int' typed fields can be reset via the ovr_ResetPerfStats call. +/// +typedef struct OVR_ALIGNAS(4) ovrPerfStatsPerCompositorFrame_ { + /// Vsync Frame Index - increments with each HMD vertical synchronization signal (i.e. vsync or + /// refresh rate) + /// If the compositor drops a frame, expect this value to increment more than 1 at a time. + int HmdVsyncIndex; + + /// + /// Application stats + /// + + /// Index that increments with each successive ovr_SubmitFrame call + int AppFrameIndex; + + /// If the app fails to call ovr_SubmitFrame on time, then expect this value to increment with + /// each missed frame + int AppDroppedFrameCount; + + /// Motion-to-photon latency for the application + /// This value is calculated by either using the SensorSampleTime provided for the ovrLayerEyeFov + /// or if that + /// is not available, then the call to ovr_GetTrackingState which has latencyMarker set to ovrTrue + float AppMotionToPhotonLatency; + + /// Amount of queue-ahead in seconds provided to the app based on performance and overlap of + /// CPU and GPU utilization. A value of 0.0 would mean the CPU & GPU workload is being completed + /// in 1 frame's worth of time, while 11 ms (on the CV1) of queue ahead would indicate that the + /// app's CPU workload for the next frame is overlapping the GPU workload for the current frame. + float AppQueueAheadTime; + + /// Amount of time in seconds spent on the CPU by the app's render-thread that calls + /// ovr_SubmitFram. Measured as elapsed time between from when app regains control from + /// ovr_SubmitFrame to the next time the app calls ovr_SubmitFrame. + float AppCpuElapsedTime; + + /// Amount of time in seconds spent on the GPU by the app. + /// Measured as elapsed time between each ovr_SubmitFrame call using GPU timing queries. + float AppGpuElapsedTime; + + /// + /// SDK Compositor stats + /// + + /// Index that increments each time the SDK compositor completes a distortion and timewarp pass + /// Since the compositor operates asynchronously, even if the app calls ovr_SubmitFrame too late, + /// the compositor will kick off for each vsync. + int CompositorFrameIndex; + + /// Increments each time the SDK compositor fails to complete in time + /// This is not tied to the app's performance, but failure to complete can be related to other + /// factors such as OS capabilities, overall available hardware cycles to execute the compositor + /// in time and other factors outside of the app's control. + int CompositorDroppedFrameCount; + + /// Motion-to-photon latency of the SDK compositor in seconds. + /// This is the latency of timewarp which corrects the higher app latency as well as dropped app + /// frames. + float CompositorLatency; + + /// The amount of time in seconds spent on the CPU by the SDK compositor. Unless the + /// VR app is utilizing all of the CPU cores at their peak performance, there is a good chance the + /// compositor CPU times will not affect the app's CPU performance in a major way. + float CompositorCpuElapsedTime; + + /// The amount of time in seconds spent on the GPU by the SDK compositor. Any time spent on the + /// compositor will eat away from the available GPU time for the app. + float CompositorGpuElapsedTime; + + /// The amount of time in seconds spent from the point the CPU kicks off the compositor to the + /// point in time the compositor completes the distortion & timewarp on the GPU. In the event the + /// GPU time is not available, expect this value to be -1.0f. + float CompositorCpuStartToGpuEndElapsedTime; + + /// The amount of time in seconds left after the compositor is done on the GPU to the associated + /// V-Sync time. In the event the GPU time is not available, expect this value to be -1.0f. + float CompositorGpuEndToVsyncElapsedTime; + + /// + /// Async Spacewarp stats (ASW) + /// + + /// Will be true if ASW is active for the given frame such that the application is being forced + /// into half the frame-rate while the compositor continues to run at full frame-rate. + ovrBool AswIsActive; + + /// Increments each time ASW it activated where the app was forced in and out of + /// half-rate rendering. + int AswActivatedToggleCount; + + /// Accumulates the number of frames presented by the compositor which had extrapolated + /// ASW frames presented. + int AswPresentedFrameCount; + + /// Accumulates the number of frames that the compositor tried to present when ASW is + /// active but failed. + int AswFailedFrameCount; + +} ovrPerfStatsPerCompositorFrame; + +/// +/// Maximum number of frames of performance stats provided back to the caller of ovr_GetPerfStats +/// +enum { ovrMaxProvidedFrameStats = 5 }; + +/// +/// This is a complete descriptor of the performance stats provided by the SDK +/// +/// \see ovr_GetPerfStats, ovrPerfStatsPerCompositorFrame +typedef struct OVR_ALIGNAS(4) ovrPerfStats_ { + /// FrameStatsCount will have a maximum value set by ovrMaxProvidedFrameStats + /// If the application calls ovr_GetPerfStats at the native refresh rate of the HMD + /// then FrameStatsCount will be 1. If the app's workload happens to force + /// ovr_GetPerfStats to be called at a lower rate, then FrameStatsCount will be 2 or more. + /// If the app does not want to miss any performance data for any frame, it needs to + /// ensure that it is calling ovr_SubmitFrame and ovr_GetPerfStats at a rate that is at least: + /// "HMD_refresh_rate / ovrMaxProvidedFrameStats". On the Oculus Rift CV1 HMD, this will + /// be equal to 18 times per second. + /// + /// The performance entries will be ordered in reverse chronological order such that the + /// first entry will be the most recent one. + ovrPerfStatsPerCompositorFrame FrameStats[ovrMaxProvidedFrameStats]; + int FrameStatsCount; + + /// If the app calls ovr_GetPerfStats at less than 18 fps for CV1, then AnyFrameStatsDropped + /// will be ovrTrue and FrameStatsCount will be equal to ovrMaxProvidedFrameStats. + ovrBool AnyFrameStatsDropped; + + /// AdaptiveGpuPerformanceScale is an edge-filtered value that a caller can use to adjust + /// the graphics quality of the application to keep the GPU utilization in check. The value + /// is calculated as: (desired_GPU_utilization / current_GPU_utilization) + /// As such, when this value is 1.0, the GPU is doing the right amount of work for the app. + /// Lower values mean the app needs to pull back on the GPU utilization. + /// If the app is going to directly drive render-target resolution using this value, then + /// be sure to take the square-root of the value before scaling the resolution with it. + /// Changing render target resolutions however is one of the many things an app can do + /// increase or decrease the amount of GPU utilization. + /// Since AdaptiveGpuPerformanceScale is edge-filtered and does not change rapidly + /// (i.e. reports non-1.0 values once every couple of seconds) the app can make the + /// necessary adjustments and then keep watching the value to see if it has been satisfied. + float AdaptiveGpuPerformanceScale; + + /// Will be true if Async Spacewarp (ASW) is available for this system which is dependent on + /// several factors such as choice of GPU, OS and debug overrides + ovrBool AswIsAvailable; + + /// Contains the Process ID of the VR application the stats are being polled for + /// If an app continues to grab perf stats even when it is not visible, then expect this + /// value to point to the other VR app that has grabbed focus (i.e. became visible) + ovrProcessId VisibleProcessId; +} ovrPerfStats; + +#if !defined(OVR_EXPORTING_CAPI) + +/// Retrieves performance stats for the VR app as well as the SDK compositor. +/// +/// This function will return stats for the VR app that is currently visible in the HMD +/// regardless of what VR app is actually calling this function. +/// +/// If the VR app is trying to make sure the stats returned belong to the same application, +/// the caller can compare the VisibleProcessId with their own process ID. Normally this will +/// be the case if the caller is only calling ovr_GetPerfStats when ovr_GetSessionStatus has +/// IsVisible flag set to be true. +/// +/// If the VR app calling ovr_GetPerfStats is actually the one visible in the HMD, +/// then new perf stats will only be populated after a new call to ovr_SubmitFrame. +/// That means subsequent calls to ovr_GetPerfStats after the first one without calling +/// ovr_SubmitFrame will receive a FrameStatsCount of zero. +/// +/// If the VR app is not visible, or was initially marked as ovrInit_Invisible, then each call +/// to ovr_GetPerfStats will immediately fetch new perf stats from the compositor without +/// a need for the ovr_SubmitFrame call. +/// +/// Even though invisible VR apps do not require ovr_SubmitFrame to be called to gather new +/// perf stats, since stats are generated at the native refresh rate of the HMD (i.e. 90 Hz +/// for CV1), calling it at a higher rate than that would be unnecessary. +/// +/// \param[in] session Specifies an ovrSession previously returned by ovr_Create. +/// \param[out] outStats Contains the performance stats for the application and SDK compositor +/// \return Returns an ovrResult for which OVR_SUCCESS(result) is false upon error and true +/// upon success. +/// +/// \see ovrPerfStats, ovrPerfStatsPerCompositorFrame, ovr_ResetPerfStats +/// +OVR_PUBLIC_FUNCTION(ovrResult) ovr_GetPerfStats(ovrSession session, ovrPerfStats* outStats); + +/// Resets the accumulated stats reported in each ovrPerfStatsPerCompositorFrame back to zero. +/// +/// Only the integer values such as HmdVsyncIndex, AppDroppedFrameCount etc. will be reset +/// as the other fields such as AppMotionToPhotonLatency are independent timing values updated +/// per-frame. +/// +/// \param[in] session Specifies an ovrSession previously returned by ovr_Create. +/// \return Returns an ovrResult for which OVR_SUCCESS(result) is false upon error and true +/// upon success. +/// +/// \see ovrPerfStats, ovrPerfStatsPerCompositorFrame, ovr_GetPerfStats +/// +OVR_PUBLIC_FUNCTION(ovrResult) ovr_ResetPerfStats(ovrSession session); + +/// Gets the time of the specified frame midpoint. +/// +/// Predicts the time at which the given frame will be displayed. The predicted time +/// is the middle of the time period during which the corresponding eye images will +/// be displayed. +/// +/// The application should increment frameIndex for each successively targeted frame, +/// and pass that index to any relevant OVR functions that need to apply to the frame +/// identified by that index. +/// +/// This function is thread-safe and allows for multiple application threads to target +/// their processing to the same displayed frame. +/// +/// In the even that prediction fails due to various reasons (e.g. the display being off +/// or app has yet to present any frames), the return value will be current CPU time. +/// +/// \param[in] session Specifies an ovrSession previously returned by ovr_Create. +/// \param[in] frameIndex Identifies the frame the caller wishes to target. +/// A value of zero returns the next frame index. +/// \return Returns the absolute frame midpoint time for the given frameIndex. +/// \see ovr_GetTimeInSeconds +/// +OVR_PUBLIC_FUNCTION(double) ovr_GetPredictedDisplayTime(ovrSession session, long long frameIndex); + +/// Returns global, absolute high-resolution time in seconds. +/// +/// The time frame of reference for this function is not specified and should not be +/// depended upon. +/// +/// \return Returns seconds as a floating point value. +/// \see ovrPoseStatef, ovrFrameTiming +/// +OVR_PUBLIC_FUNCTION(double) ovr_GetTimeInSeconds(); + +#endif // !defined(OVR_EXPORTING_CAPI) + +/// Performance HUD enables the HMD user to see information critical to +/// the real-time operation of the VR application such as latency timing, +/// and CPU & GPU performance metrics +/// +/// App can toggle performance HUD modes as such: +/// \code{.cpp} +/// ovrPerfHudMode PerfHudMode = ovrPerfHud_LatencyTiming; +/// ovr_SetInt(session, OVR_PERF_HUD_MODE, (int)PerfHudMode); +/// \endcode +/// +typedef enum ovrPerfHudMode_ { + ovrPerfHud_Off = 0, ///< Turns off the performance HUD + ovrPerfHud_PerfSummary = 1, ///< Shows performance summary and headroom + ovrPerfHud_LatencyTiming = 2, ///< Shows latency related timing info + ovrPerfHud_AppRenderTiming = 3, ///< Shows render timing info for application + ovrPerfHud_CompRenderTiming = 4, ///< Shows render timing info for OVR compositor + ovrPerfHud_AswStats = 6, ///< Shows Async Spacewarp-specific info + ovrPerfHud_VersionInfo = 5, ///< Shows SDK & HMD version Info + ovrPerfHud_LinkPerf = 7, ///< Shows Oculus Link performance. + ovrPerfHud_Count = 8, ///< \internal Count of enumerated elements. + ovrPerfHud_EnumSize = 0x7fffffff ///< \internal Force type int32_t. +} ovrPerfHudMode; + +/// Layer HUD enables the HMD user to see information about a layer +/// +/// App can toggle layer HUD modes as such: +/// \code{.cpp} +/// ovrLayerHudMode LayerHudMode = ovrLayerHud_Info; +/// ovr_SetInt(session, OVR_LAYER_HUD_MODE, (int)LayerHudMode); +/// \endcode +/// +typedef enum ovrLayerHudMode_ { + ovrLayerHud_Off = 0, ///< Turns off the layer HUD + ovrLayerHud_Info = 1, ///< Shows info about a specific layer + ovrLayerHud_EnumSize = 0x7fffffff +} ovrLayerHudMode; + +///@} + +/// Debug HUD is provided to help developers gauge and debug the fidelity of their app's +/// stereo rendering characteristics. Using the provided quad and crosshair guides, +/// the developer can verify various aspects such as VR tracking units (e.g. meters), +/// stereo camera-parallax properties (e.g. making sure objects at infinity are rendered +/// with the proper separation), measuring VR geometry sizes and distances and more. +/// +/// App can toggle the debug HUD modes as such: +/// \code{.cpp} +/// ovrDebugHudStereoMode DebugHudMode = ovrDebugHudStereo_QuadWithCrosshair; +/// ovr_SetInt(session, OVR_DEBUG_HUD_STEREO_MODE, (int)DebugHudMode); +/// \endcode +/// +/// The app can modify the visual properties of the stereo guide (i.e. quad, crosshair) +/// using the ovr_SetFloatArray function. For a list of tweakable properties, +/// see the OVR_DEBUG_HUD_STEREO_GUIDE_* keys in the OVR_CAPI_Keys.h header file. +typedef enum ovrDebugHudStereoMode_ { + /// Turns off the Stereo Debug HUD. + ovrDebugHudStereo_Off = 0, + + /// Renders Quad in world for Stereo Debugging. + ovrDebugHudStereo_Quad = 1, + + /// Renders Quad+crosshair in world for Stereo Debugging + ovrDebugHudStereo_QuadWithCrosshair = 2, + + /// Renders screen-space crosshair at infinity for Stereo Debugging + ovrDebugHudStereo_CrosshairAtInfinity = 3, + + /// \internal Count of enumerated elements + ovrDebugHudStereo_Count, + + ovrDebugHudStereo_EnumSize = 0x7fffffff ///< \internal Force type int32_t +} ovrDebugHudStereoMode; + +#if !defined(OVR_EXPORTING_CAPI) + +// ----------------------------------------------------------------------------------- +/// @name Property Access +/// +/// These functions read and write OVR properties. Supported properties +/// are defined in OVR_CAPI_Keys.h +/// +//@{ + +/// Reads a boolean property. +/// +/// \param[in] session Specifies an ovrSession previously returned by ovr_Create. +/// \param[in] propertyName The name of the property, which needs to be valid for only the call. +/// \param[in] defaultVal specifes the value to return if the property couldn't be read. +/// \return Returns the property interpreted as a boolean value. Returns defaultVal if +/// the property doesn't exist. +OVR_PUBLIC_FUNCTION(ovrBool) +ovr_GetBool(ovrSession session, const char* propertyName, ovrBool defaultVal); + +/// Writes or creates a boolean property. +/// If the property wasn't previously a boolean property, it is changed to a boolean property. +/// +/// \param[in] session Specifies an ovrSession previously returned by ovr_Create. +/// \param[in] propertyName The name of the property, which needs to be valid only for the call. +/// \param[in] value The value to write. +/// \return Returns true if successful, otherwise false. A false result should only occur if the +/// property +/// name is empty or if the property is read-only. +OVR_PUBLIC_FUNCTION(ovrBool) +ovr_SetBool(ovrSession session, const char* propertyName, ovrBool value); + +/// Reads an integer property. +/// +/// \param[in] session Specifies an ovrSession previously returned by ovr_Create. +/// \param[in] propertyName The name of the property, which needs to be valid only for the call. +/// \param[in] defaultVal Specifes the value to return if the property couldn't be read. +/// \return Returns the property interpreted as an integer value. Returns defaultVal if +/// the property doesn't exist. +OVR_PUBLIC_FUNCTION(int) ovr_GetInt(ovrSession session, const char* propertyName, int defaultVal); + +/// Writes or creates an integer property. +/// +/// If the property wasn't previously a boolean property, it is changed to an integer property. +/// +/// \param[in] session Specifies an ovrSession previously returned by ovr_Create. +/// \param[in] propertyName The name of the property, which needs to be valid only for the call. +/// \param[in] value The value to write. +/// \return Returns true if successful, otherwise false. A false result should only occur if the +/// property name is empty or if the property is read-only. +OVR_PUBLIC_FUNCTION(ovrBool) ovr_SetInt(ovrSession session, const char* propertyName, int value); + +/// Reads a float property. +/// +/// \param[in] session Specifies an ovrSession previously returned by ovr_Create. +/// \param[in] propertyName The name of the property, which needs to be valid only for the call. +/// \param[in] defaultVal specifes the value to return if the property couldn't be read. +/// \return Returns the property interpreted as an float value. Returns defaultVal if +/// the property doesn't exist. +OVR_PUBLIC_FUNCTION(float) +ovr_GetFloat(ovrSession session, const char* propertyName, float defaultVal); + +/// Writes or creates a float property. +/// If the property wasn't previously a float property, it's changed to a float property. +/// +/// \param[in] session Specifies an ovrSession previously returned by ovr_Create. +/// \param[in] propertyName The name of the property, which needs to be valid only for the call. +/// \param[in] value The value to write. +/// \return Returns true if successful, otherwise false. A false result should only occur if the +/// property name is empty or if the property is read-only. +OVR_PUBLIC_FUNCTION(ovrBool) +ovr_SetFloat(ovrSession session, const char* propertyName, float value); + +/// Reads a float array property. +/// +/// \param[in] session Specifies an ovrSession previously returned by ovr_Create. +/// \param[in] propertyName The name of the property, which needs to be valid only for the call. +/// \param[in] values An array of float to write to. +/// \param[in] valuesCapacity Specifies the maximum number of elements to write to the values array. +/// \return Returns the number of elements read, or 0 if property doesn't exist or is empty. +OVR_PUBLIC_FUNCTION(unsigned int) +ovr_GetFloatArray( + ovrSession session, + const char* propertyName, + float values[], + unsigned int valuesCapacity); + +/// Writes or creates a float array property. +/// +/// \param[in] session Specifies an ovrSession previously returned by ovr_Create. +/// \param[in] propertyName The name of the property, which needs to be valid only for the call. +/// \param[in] values An array of float to write from. +/// \param[in] valuesSize Specifies the number of elements to write. +/// \return Returns true if successful, otherwise false. A false result should only occur if the +/// property name is empty or if the property is read-only. +OVR_PUBLIC_FUNCTION(ovrBool) +ovr_SetFloatArray( + ovrSession session, + const char* propertyName, + const float values[], + unsigned int valuesSize); + +/// Reads a string property. +/// Strings are UTF8-encoded and null-terminated. +/// +/// \param[in] session Specifies an ovrSession previously returned by ovr_Create. +/// \param[in] propertyName The name of the property, which needs to be valid only for the call. +/// \param[in] defaultVal Specifes the value to return if the property couldn't be read. +/// \return Returns the string property if it exists. Otherwise returns defaultVal, which can be +/// specified as NULL. The return memory is guaranteed to be valid until next call to +/// ovr_GetString or until the session is destroyed, whichever occurs first. +OVR_PUBLIC_FUNCTION(const char*) +ovr_GetString(ovrSession session, const char* propertyName, const char* defaultVal); + +/// Writes or creates a string property. +/// Strings are UTF8-encoded and null-terminated. +/// +/// \param[in] session Specifies an ovrSession previously returned by ovr_Create. +/// \param[in] propertyName The name of the property, which needs to be valid only for the call. +/// \param[in] value The string property, which only needs to be valid for the duration of the call. +/// \return Returns true if successful, otherwise false. A false result should only occur if the +/// property name is empty or if the property is read-only. +OVR_PUBLIC_FUNCTION(ovrBool) +ovr_SetString(ovrSession session, const char* propertyName, const char* value); + +///@} + +#endif // !defined(OVR_EXPORTING_CAPI) + +#ifdef __cplusplus +} // extern "C" +#endif + +#if defined(_MSC_VER) +#pragma warning(pop) +#endif + +/// @cond DoxygenIgnore + + +OVR_STATIC_ASSERT( + sizeof(ovrTextureSwapChainDesc) == 10 * 4, + "ovrTextureSwapChainDesc size mismatch"); + +// ----------------------------------------------------------------------------------- +// ***** Backward compatibility #includes +// +// This is at the bottom of this file because the following is dependent on the +// declarations above. + +#if !defined(OVR_CAPI_NO_UTILS) +#include "Extras/OVR_CAPI_Util.h" +#endif + +/// @endcond + +#endif // OVR_CAPI_h |