/************************************************************************************ \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 #endif #include #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 /// (read only) 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 : #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. /// /// Example code /// \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: ('true' or 'false')\n /// /// Example code /// \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. /// /// Example code /// \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. /// /// Example code /// \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). /// /// Example code /// \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). /// /// Example code /// \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