-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathOVR_CAPI.h
2103 lines (1766 loc) · 89 KB
/
OVR_CAPI.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
/********************************************************************************//**
\file OVR_CAPI.h
\brief C Interface to the Oculus PC SDK tracking and rendering library.
\copyright Copyright 2014-2016 Oculus VR, LLC All Rights reserved.
************************************************************************************/
#ifndef OVR_CAPI_h // We don't use version numbers within this name, as all versioned variations of this file are currently mutually exclusive.
#define OVR_CAPI_h ///< Header include guard
#include "OVR_CAPI_Keys.h"
#include "OVR_Version.h"
#include "OVR_ErrorCode.h"
#include <stdint.h>
#if defined(_MSC_VER)
#pragma warning(push)
#pragma warning(disable: 4324) // structure was padded due to __declspec(align())
#pragma warning(disable: 4359) // The alignment specified for a type is less than the alignment of the type of one of its data members
#endif
//-----------------------------------------------------------------------------------
// ***** OVR_OS
//
#if !defined(OVR_OS_WIN32) && defined(_WIN32)
#define OVR_OS_WIN32
#endif
#if !defined(OVR_OS_MAC) && defined(__APPLE__)
#define OVR_OS_MAC
#endif
#if !defined(OVR_OS_LINUX) && defined(__linux__)
#define OVR_OS_LINUX
#endif
//-----------------------------------------------------------------------------------
// ***** OVR_CPP
//
#if !defined(OVR_CPP)
#if defined(__cplusplus)
#define OVR_CPP(x) x
#else
#define OVR_CPP(x) /* Not C++ */
#endif
#endif
//-----------------------------------------------------------------------------------
// ***** OVR_CDECL
//
/// LibOVR calling convention for 32-bit Windows builds.
//
#if !defined(OVR_CDECL)
#if defined(_WIN32)
#define OVR_CDECL __cdecl
#else
#define OVR_CDECL
#endif
#endif
//-----------------------------------------------------------------------------------
// ***** OVR_EXTERN_C
//
/// Defined as extern "C" when built from C++ code.
//
#if !defined(OVR_EXTERN_C)
#ifdef __cplusplus
#define OVR_EXTERN_C extern "C"
#else
#define OVR_EXTERN_C
#endif
#endif
//-----------------------------------------------------------------------------------
// ***** OVR_PUBLIC_FUNCTION / OVR_PRIVATE_FUNCTION
//
// OVR_PUBLIC_FUNCTION - Functions that externally visible from a shared library. Corresponds to Microsoft __dllexport.
// OVR_PUBLIC_CLASS - C++ structs and classes that are externally visible from a shared library. Corresponds to Microsoft __dllexport.
// OVR_PRIVATE_FUNCTION - Functions that are not visible outside of a shared library. They are private to the shared library.
// OVR_PRIVATE_CLASS - C++ structs and classes that are not visible outside of a shared library. They are private to the shared library.
//
// OVR_DLL_BUILD - Used to indicate that the current compilation unit is of a shared library.
// OVR_DLL_IMPORT - Used to indicate that the current compilation unit is a user of the corresponding shared library.
// OVR_STATIC_BUILD - used to indicate that the current compilation unit is not a shared library but rather statically linked code.
//
#if !defined(OVR_PUBLIC_FUNCTION)
#if defined(OVR_DLL_BUILD)
#if defined(_WIN32)
#define OVR_PUBLIC_FUNCTION(rval) OVR_EXTERN_C __declspec(dllexport) rval OVR_CDECL
#define OVR_PUBLIC_CLASS __declspec(dllexport)
#define OVR_PRIVATE_FUNCTION(rval) rval OVR_CDECL
#define OVR_PRIVATE_CLASS
#else
#define OVR_PUBLIC_FUNCTION(rval) OVR_EXTERN_C __attribute__((visibility("default"))) rval OVR_CDECL /* Requires GCC 4.0+ */
#define OVR_PUBLIC_CLASS __attribute__((visibility("default"))) /* Requires GCC 4.0+ */
#define OVR_PRIVATE_FUNCTION(rval) __attribute__((visibility("hidden"))) rval OVR_CDECL
#define OVR_PRIVATE_CLASS __attribute__((visibility("hidden")))
#endif
#elif defined(OVR_DLL_IMPORT)
#if defined(_WIN32)
#define OVR_PUBLIC_FUNCTION(rval) OVR_EXTERN_C __declspec(dllimport) rval OVR_CDECL
#define OVR_PUBLIC_CLASS __declspec(dllimport)
#else
#define OVR_PUBLIC_FUNCTION(rval) OVR_EXTERN_C rval OVR_CDECL
#define OVR_PUBLIC_CLASS
#endif
#define OVR_PRIVATE_FUNCTION(rval) rval OVR_CDECL
#define OVR_PRIVATE_CLASS
#else // OVR_STATIC_BUILD
#define OVR_PUBLIC_FUNCTION(rval) OVR_EXTERN_C rval OVR_CDECL
#define OVR_PUBLIC_CLASS
#define OVR_PRIVATE_FUNCTION(rval) rval OVR_CDECL
#define OVR_PRIVATE_CLASS
#endif
#endif
//-----------------------------------------------------------------------------------
// ***** OVR_EXPORT
//
/// Provided for backward compatibility with older versions of this library.
//
#if !defined(OVR_EXPORT)
#ifdef OVR_OS_WIN32
#define OVR_EXPORT __declspec(dllexport)
#else
#define OVR_EXPORT
#endif
#endif
//-----------------------------------------------------------------------------------
// ***** OVR_ALIGNAS
//
#if !defined(OVR_ALIGNAS)
#if defined(__GNUC__) || defined(__clang__)
#define OVR_ALIGNAS(n) __attribute__((aligned(n)))
#elif defined(_MSC_VER) || defined(__INTEL_COMPILER)
#define OVR_ALIGNAS(n) __declspec(align(n))
#elif defined(__CC_ARM)
#define OVR_ALIGNAS(n) __align(n)
#else
#error Need to define OVR_ALIGNAS
#endif
#endif
//-----------------------------------------------------------------------------------
// ***** OVR_CC_HAS_FEATURE
//
// This is a portable way to use compile-time feature identification available
// with some compilers in a clean way. Direct usage of __has_feature in preprocessing
// statements of non-supporting compilers results in a preprocessing error.
//
// Example usage:
// #if OVR_CC_HAS_FEATURE(is_pod)
// if(__is_pod(T)) // If the type is plain data then we can safely memcpy it.
// memcpy(&destObject, &srcObject, sizeof(object));
// #endif
//
#if !defined(OVR_CC_HAS_FEATURE)
#if defined(__clang__) // http://clang.llvm.org/docs/LanguageExtensions.html#id2
#define OVR_CC_HAS_FEATURE(x) __has_feature(x)
#else
#define OVR_CC_HAS_FEATURE(x) 0
#endif
#endif
// ------------------------------------------------------------------------
// ***** OVR_STATIC_ASSERT
//
// Portable support for C++11 static_assert().
// Acts as if the following were declared:
// void OVR_STATIC_ASSERT(bool const_expression, const char* msg);
//
// Example usage:
// OVR_STATIC_ASSERT(sizeof(int32_t) == 4, "int32_t expected to be 4 bytes.");
#if !defined(OVR_STATIC_ASSERT)
#if !(defined(__cplusplus) && (__cplusplus >= 201103L)) /* Other */ && \
!(defined(__GXX_EXPERIMENTAL_CXX0X__)) /* GCC */ && \
!(defined(__clang__) && defined(__cplusplus) && OVR_CC_HAS_FEATURE(cxx_static_assert)) /* clang */ && \
!(defined(_MSC_VER) && (_MSC_VER >= 1600) && defined(__cplusplus)) /* VS2010+ */
#if !defined(OVR_SA_UNUSED)
#if defined(OVR_CC_GNU) || defined(OVR_CC_CLANG)
#define OVR_SA_UNUSED __attribute__((unused))
#else
#define OVR_SA_UNUSED
#endif
#define OVR_SA_PASTE(a,b) a##b
#define OVR_SA_HELP(a,b) OVR_SA_PASTE(a,b)
#endif
#if defined(__COUNTER__)
#define OVR_STATIC_ASSERT(expression, msg) typedef char OVR_SA_HELP(compileTimeAssert, __COUNTER__) [((expression) != 0) ? 1 : -1] OVR_SA_UNUSED
#else
#define OVR_STATIC_ASSERT(expression, msg) typedef char OVR_SA_HELP(compileTimeAssert, __LINE__) [((expression) != 0) ? 1 : -1] OVR_SA_UNUSED
#endif
#else
#define OVR_STATIC_ASSERT(expression, msg) static_assert(expression, msg)
#endif
#endif
//-----------------------------------------------------------------------------------
// ***** 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.
//-----------------------------------------------------------------------------------
// ***** Simple Math Structures
/// 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 4x4 matrix with float elements.
typedef struct OVR_ALIGNAS(4) ovrMatrix4f_
{
float M[4][4];
} ovrMatrix4f;
/// Position and orientation together.
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; ///< The tangent of the angle between the viewing vector and the top edge of the field of view.
float DownTan; ///< The tangent of the angle between the viewing vector and the bottom edge of the field of view.
float LeftTan; ///< The tangent of the angle between the viewing vector and the left edge of the field of view.
float RightTan; ///< The tangent of the angle between the viewing vector and the right edge of the field of view.
} 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_EnumSize = 0x7fffffff ///< \internal Force type int32_t.
} ovrHmdType;
/// HMD capability bits reported by device.
///
typedef enum ovrHmdCaps_
{
// Read-only flags
ovrHmdCap_DebugDevice = 0x0010, ///< <B>(read only)</B> Specifies that the HMD is a virtual debug device.
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 via a magnetometer or other means.
ovrTrackingCap_Position = 0x0040, ///< Supports positional tracking.
ovrTrackingCap_EnumSize = 0x7fffffff ///< \internal Force type int32_t.
} ovrTrackingCaps;
/// 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;
/// 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 paddding.
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; ///< Capability bits described by ovrHmdCaps which the HMD currently supports.
unsigned int DefaultHmdCaps; ///< Capability bits described by ovrHmdCaps which are default for the current Hmd.
unsigned int AvailableTrackingCaps; ///< Capability bits described by ovrTrackingCaps which the system currently supports.
unsigned int DefaultTrackingCaps; ///< Capability bits described by ovrTrackingCaps which are default for the current system.
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; ///< Nominal refresh rate of the display in cycles per second at the time of HMD creation.
OVR_ON64(OVR_UNUSED_STRUCT_PAD(pad1, 4)) ///< \internal struct paddding.
} ovrHmdDesc;
/// Used as an opaque pointer to an OVR session.
typedef struct ovrHmdStruct* ovrSession;
/// Bit flags describing the current status of sensor tracking.
/// The values must be the same as in enum StatusBits
///
/// \see ovrTrackingState
///
typedef enum ovrStatusBits_
{
ovrStatus_OrientationTracked = 0x0001, ///< Orientation is currently tracked (connected and in use).
ovrStatus_PositionTracked = 0x0002, ///< Position is currently tracked (false if out of range).
ovrStatus_EnumSize = 0x7fffffff ///< \internal Force type int32_t.
} ovrStatusBits;
/// Specifies the description of a single sensor.
///
/// \see ovrGetTrackerDesc
///
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_
{
ovrTracker_Connected = 0x0020, ///< The sensor is present, else the sensor is absent or offline.
ovrTracker_PoseTracked = 0x0004 ///< The sensor has a valid pose, else the pose is unavailable. This will only be set if ovrTracker_Connected is set.
} ovrTrackerFlags;
/// Specifies the pose for a single sensor.
///
typedef struct OVR_ALIGNAS(8) _ovrTrackerPose
{
unsigned int TrackerFlags; ///< ovrTrackerFlags.
ovrPosef Pose; ///< The sensor's pose. This pose includes sensor tilt (roll and pitch). For a leveled coordinate system use LeveledPose.
ovrPosef LeveledPose; ///< The sensor's leveled pose, aligned with gravity. This value includes position 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.
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 hand.
/// These values can be combined with ovrInputState for complete hand controller information.
ovrPoseStatef HandPoses[2];
/// HandPoses status flags described by ovrStatusBits.
/// Only ovrStatus_OrientationTracked and ovrStatus_PositionTracked are reported.
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,
/// and so will change every time that is 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, 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.
ovrVector3f HmdToEyeOffset; ///< Translation of each eye, 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.
/// - HmdToEyeOffset is the same value pair provided in ovrEyeRenderDesc.
/// - 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_
{
ovrVector3f HmdToEyeOffset[ovrEye_Count]; ///< Translation of each eye.
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, ///< 2D textures.
ovrTexture_2D_External, ///< External 2D texture. Not used on PC
ovrTexture_Cube, ///< Cube maps. Not currently supported on PC.
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,
ovrTextureBind_DX_RenderTarget = 0x0001, ///< The application can write into the chain with pixel shader
ovrTextureBind_DX_UnorderedAccess = 0x0002, ///< The application can write to the chain with compute shader
ovrTextureBind_DX_DepthStencil = 0x0004, ///< The chain buffers can be bound as depth and/or stencil buffers
ovrTextureBind_EnumSize = 0x7fffffff ///< \internal Force type int32_t.
} ovrTextureBindFlags;
/// The format of a texture.
///
/// \see ovrTextureSwapChainDesc
///
typedef enum ovrTextureFormat_
{
OVR_FORMAT_UNKNOWN,
OVR_FORMAT_B5G6R5_UNORM, ///< Not currently supported on PC. Would require a DirectX 11.1 device.
OVR_FORMAT_B5G5R5A1_UNORM, ///< Not currently supported on PC. Would require a DirectX 11.1 device.
OVR_FORMAT_B4G4R4A4_UNORM, ///< Not currently supported on PC. Would require a DirectX 11.1 device.
OVR_FORMAT_R8G8B8A8_UNORM,
OVR_FORMAT_R8G8B8A8_UNORM_SRGB,
OVR_FORMAT_B8G8R8A8_UNORM,
OVR_FORMAT_B8G8R8A8_UNORM_SRGB, ///< Not supported for OpenGL applications
OVR_FORMAT_B8G8R8X8_UNORM, ///< Not supported for OpenGL applications
OVR_FORMAT_B8G8R8X8_UNORM_SRGB, ///< Not supported for OpenGL applications
OVR_FORMAT_R16G16B16A16_FLOAT,
OVR_FORMAT_D16_UNORM,
OVR_FORMAT_D24_UNORM_S8_UINT,
OVR_FORMAT_D32_FLOAT,
OVR_FORMAT_D32_FLOAT_S8X24_UINT,
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,
/// 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,
ovrTextureMisc_EnumSize = 0x7fffffff ///< \internal Force type int32_t.
} ovrTextureFlags;
/// Description used to create a texture swap chain.
///
/// \see ovr_CreateTextureSwapChainDX
/// \see ovr_CreateTextureSwapChainGL
///
typedef struct
{
ovrTextureType Type;
ovrTextureFormat Format;
int ArraySize; ///< Only supported with ovrTexture_2D. Not supported on PC at this time.
int Width;
int Height;
int MipLevels;
int SampleCount; ///< Current only supported on depth textures
ovrBool StaticImage; ///< Not buffered in a chain. For images that don't change
unsigned int MiscFlags; ///< ovrTextureMiscFlags
unsigned int BindFlags; ///< ovrTextureBindFlags. Not used for GL.
} ovrTextureSwapChainDesc;
/// Description used to create a mirror texture.
///
/// \see ovr_CreateMirrorTextureDX
/// \see ovr_CreateMirrorTextureGL
///
typedef struct
{
ovrTextureFormat Format;
int Width;
int Height;
unsigned int MiscFlags; ///< ovrTextureMiscFlags
} ovrMirrorTextureDesc;
typedef struct ovrTextureSwapChainData* ovrTextureSwapChain;
typedef struct ovrMirrorTextureData* ovrMirrorTexture;
//-----------------------------------------------------------------------------------
/// 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_
{
ovrButton_A = 0x00000001,
ovrButton_B = 0x00000002,
ovrButton_RThumb = 0x00000004,
ovrButton_RShoulder = 0x00000008,
// Bit mask of all buttons on the right Touch controller
ovrButton_RMask = ovrButton_A | ovrButton_B | ovrButton_RThumb | ovrButton_RShoulder,
ovrButton_X = 0x00000100,
ovrButton_Y = 0x00000200,
ovrButton_LThumb = 0x00000400,
ovrButton_LShoulder = 0x00000800,
// Bit mask of all buttons on the left Touch controller
ovrButton_LMask = ovrButton_X | ovrButton_Y | ovrButton_LThumb | ovrButton_LShoulder,
// Navigation through DPad.
ovrButton_Up = 0x00010000,
ovrButton_Down = 0x00020000,
ovrButton_Left = 0x00040000,
ovrButton_Right = 0x00080000,
ovrButton_Enter = 0x00100000, // Start on XBox controller.
ovrButton_Back = 0x00200000, // Back on Xbox controller.
ovrButton_VolUp = 0x00400000, // only supported by Remote.
ovrButton_VolDown = 0x00800000, // only supported by Remote.
ovrButton_Home = 0x01000000,
ovrButton_Private = ovrButton_VolUp | ovrButton_VolDown | ovrButton_Home,
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_RIndexTrigger = 0x00000010,
// Bit mask of all the button touches on the right controller
ovrTouch_RButtonMask = ovrTouch_A | ovrTouch_B | ovrTouch_RThumb | ovrTouch_RIndexTrigger,
ovrTouch_X = ovrButton_X,
ovrTouch_Y = ovrButton_Y,
ovrTouch_LThumb = ovrButton_LThumb,
ovrTouch_LIndexTrigger = 0x00001000,
// Bit mask of all the button touches on the left controller
ovrTouch_LButtonMask = ovrTouch_X | ovrTouch_Y | ovrTouch_LThumb | ovrTouch_LIndexTrigger,
// Finger pose state
// Derived internally based on distance, proximity to sensors and filtering.
ovrTouch_RIndexPointing = 0x00000020,
ovrTouch_RThumbUp = 0x00000040,
// Bit mask of all right controller poses
ovrTouch_RPoseMask = ovrTouch_RIndexPointing | ovrTouch_RThumbUp,
ovrTouch_LIndexPointing = 0x00002000,
ovrTouch_LThumbUp = 0x00004000,
// Bit mask of all left controller poses
ovrTouch_LPoseMask = ovrTouch_LIndexPointing | ovrTouch_LThumbUp,
ovrTouch_EnumSize = 0x7fffffff ///< \internal Force type int32_t.
} ovrTouch;
/// Specifies which controller is connected; multiple can be connected at once.
typedef enum ovrControllerType_
{
ovrControllerType_None = 0x00,
ovrControllerType_LTouch = 0x01,
ovrControllerType_RTouch = 0x02,
ovrControllerType_Touch = 0x03,
ovrControllerType_Remote = 0x04,
ovrControllerType_XBox = 0x10,
ovrControllerType_Active = 0xff, ///< Operate on or query whichever controller is active.
ovrControllerType_EnumSize = 0x7fffffff ///< \internal Force type int32_t.
} ovrControllerType;
/// 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 the range 0.0 to 1.0f.
float IndexTrigger[ovrHand_Count];
// Left and right hand trigger values (ovrHand_Left and ovrHand_Right), in the range 0.0 to 1.0f.
float HandTrigger[ovrHand_Count];
// Horizontal and vertical thumbstick axis values (ovrHand_Left and ovrHand_Right), in the range -1.0f to 1.0f.
ovrVector2f Thumbstick[ovrHand_Count];
// The type of the controller this state is for.
ovrControllerType ControllerType;
} ovrInputState;
//-----------------------------------------------------------------------------------
// ***** 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.
ovrInit_RequestVersion = 0x00000004,
// 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 minimum minor version of the LibOVR runtime.
/// Flags must include ovrInit_RequestVersion or this will be ignored
/// and OVR_MINOR_VERSION will be used.
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
// -----------------------------------------------------------------------------------
// ***** API Interfaces
// Overview of the API
//
// Setup:
// - ovr_Initialize().
// - ovr_Create(&hmd, &graphicsId).
// - Use hmd members and ovr_GetFovTextureSize() to determine graphics configuration
// and ovr_GetRenderDesc() to get per-eye rendering parameters.
// - Allocate texture swap chains with ovr_CreateTextureSwapChainDX() or
// ovr_CreateTextureSwapChainGL(). Create any associated render target views or
// frame buffer objects.
//
// Application Loop:
// - Call ovr_GetPredictedDisplayTime() to get the current frame timing information.
// - Call ovr_GetTrackingState() and ovr_CalcEyePoses() to obtain the predicted
// rendering pose for each eye based on timing.
// - Render the scene content into the current buffer of the texture swapchains
// for each eye and layer you plan to update this frame. If you render into a
// texture swap chain, you must call ovr_CommitTextureSwapChain() on it to commit
// the changes before you reference the chain this frame (otherwise, your latest
// changes won't be picked up).
// - Call ovr_SubmitFrame() to render the distorted layers to and present them on the HMD.
// If ovr_SubmitFrame returns ovrSuccess_NotVisible, there is no need to render the scene
// for the next loop iteration. Instead, just call ovr_SubmitFrame again until it returns
// ovrSuccess.
//
// Shutdown:
// - ovr_Destroy().
// - ovr_Shutdown().
/// Initializes LibOVR
///
/// Initialize LibOVR for application usage. This includes finding and loading the LibOVRRT
/// shared library. No LibOVR API functions, other than ovr_GetLastErrorInfo, 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