1/**************************************************************************/
2/* xr_server.h */
3/**************************************************************************/
4/* This file is part of: */
5/* GODOT ENGINE */
6/* https://godotengine.org */
7/**************************************************************************/
8/* Copyright (c) 2014-present Godot Engine contributors (see AUTHORS.md). */
9/* Copyright (c) 2007-2014 Juan Linietsky, Ariel Manzur. */
10/* */
11/* Permission is hereby granted, free of charge, to any person obtaining */
12/* a copy of this software and associated documentation files (the */
13/* "Software"), to deal in the Software without restriction, including */
14/* without limitation the rights to use, copy, modify, merge, publish, */
15/* distribute, sublicense, and/or sell copies of the Software, and to */
16/* permit persons to whom the Software is furnished to do so, subject to */
17/* the following conditions: */
18/* */
19/* The above copyright notice and this permission notice shall be */
20/* included in all copies or substantial portions of the Software. */
21/* */
22/* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, */
23/* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF */
24/* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. */
25/* IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY */
26/* CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, */
27/* TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE */
28/* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. */
29/**************************************************************************/
30
31#ifndef XR_SERVER_H
32#define XR_SERVER_H
33
34#include "core/object/ref_counted.h"
35#include "core/os/os.h"
36#include "core/os/thread_safe.h"
37#include "core/templates/rid.h"
38#include "core/variant/variant.h"
39
40class XRInterface;
41class XRPositionalTracker;
42
43/**
44 The XR server is a singleton object that gives access to the various
45 objects and SDKs that are available on the system.
46 Because there can be multiple SDKs active this is exposed as an array
47 and our XR server object acts as a pass through
48 Also each positioning tracker is accessible from here.
49
50 I've added some additional info into this header file that should move
51 into the documentation, I will do so when we're close to accepting this PR
52 or as a separate PR once this has been merged into the master branch.
53**/
54
55class XRServer : public Object {
56 GDCLASS(XRServer, Object);
57 _THREAD_SAFE_CLASS_
58
59public:
60 enum XRMode {
61 XRMODE_DEFAULT, /* Default behavior, means we check project settings */
62 XRMODE_OFF, /* Ignore project settings, disable OpenXR, disable shaders */
63 XRMODE_ON, /* Ignore project settings, enable OpenXR, enable shaders, run editor in VR (if applicable) */
64 };
65
66 enum TrackerType {
67 TRACKER_HEAD = 0x01, /* tracks the position of the players head (or in case of handheld AR, location of the phone) */
68 TRACKER_CONTROLLER = 0x02, /* tracks a controller */
69 TRACKER_BASESTATION = 0x04, /* tracks location of a base station */
70 TRACKER_ANCHOR = 0x08, /* tracks an anchor point, used in AR to track a real live location */
71 TRACKER_UNKNOWN = 0x80, /* unknown tracker */
72
73 TRACKER_ANY_KNOWN = 0x7f, /* all except unknown */
74 TRACKER_ANY = 0xff /* used by get_connected_trackers to return all types */
75 };
76
77 enum RotationMode {
78 RESET_FULL_ROTATION = 0, /* we reset the full rotation, regardless of how the HMD is oriented, we're looking dead ahead */
79 RESET_BUT_KEEP_TILT = 1, /* reset rotation but keep tilt. */
80 DONT_RESET_ROTATION = 2, /* don't reset the rotation, we will only center on position */
81 };
82
83private:
84 static XRMode xr_mode;
85
86 Vector<Ref<XRInterface>> interfaces;
87 Dictionary trackers;
88
89 Ref<XRInterface> primary_interface; /* we'll identify one interface as primary, this will be used by our viewports */
90
91 double world_scale; /* scale by which we multiply our tracker positions */
92 Transform3D world_origin; /* our world origin point, maps a location in our virtual world to the origin point in our real world tracking volume */
93 Transform3D reference_frame; /* our reference frame */
94
95protected:
96 static XRServer *singleton;
97
98 static void _bind_methods();
99
100public:
101 static XRMode get_xr_mode();
102 static void set_xr_mode(XRMode p_mode);
103
104 static XRServer *get_singleton();
105
106 /*
107 World scale allows you to specify a scale factor that is applied to all positioning vectors in our VR world in essence scaling up, or scaling down the world.
108 For stereoscopic rendering specifically this is very important to give an accurate sense of scale.
109 Add controllers into the mix and an accurate mapping of real world movement to perceived virtual movement becomes very important.
110
111 Most VR platforms, and our assumption, is that 1 unit in our virtual world equates to 1 meter in the real mode.
112 This scale basically effects the unit size relationship to real world size.
113
114 I may remove access to this property in GDScript in favor of exposing it on the XROrigin3D node
115 */
116 double get_world_scale() const;
117 void set_world_scale(double p_world_scale);
118
119 /*
120 The world maps the 0,0,0 coordinate of our real world coordinate system for our tracking volume to a location in our
121 virtual world. It is this origin point that should be moved when the player is moved through the world by controller
122 actions be it straffing, teleporting, etc. Movement of the player by moving through the physical space is always tracked
123 in relation to this point.
124
125 Note that the XROrigin3D spatial node in your scene automatically updates this property and it should be used instead of
126 direct access to this property and it therefore is not available in GDScript
127
128 Note: this should not be used in AR and should be ignored by an AR based interface as it would throw what you're looking at in the real world
129 and in the virtual world out of sync
130 */
131 Transform3D get_world_origin() const;
132 void set_world_origin(const Transform3D &p_world_origin);
133
134 /*
135 center_on_hmd calculates a new reference frame. This ensures the HMD is positioned to 0,0,0 facing 0,0,-1 (need to verify this direction)
136 in the virtual world.
137
138 You can ignore the tilt of the device ensuring you're looking straight forward even if the player is looking down or sideways.
139 You can chose to keep the height the tracking provides which is important for room scale capable tracking.
140
141 Note: this should not be used in AR and should be ignored by an AR based interface as it would throw what you're looking at in the real world
142 and in the virtual world out of sync
143 */
144 Transform3D get_reference_frame() const;
145 void center_on_hmd(RotationMode p_rotation_mode, bool p_keep_height);
146
147 /*
148 get_hmd_transform gets our hmd transform (centered between eyes) with most up to date tracking, relative to the origin
149 */
150 Transform3D get_hmd_transform();
151
152 /*
153 Interfaces are objects that 'glue' Godot to an AR or VR SDK such as the Oculus SDK, OpenVR, OpenHMD, etc.
154 */
155 void add_interface(const Ref<XRInterface> &p_interface);
156 void remove_interface(const Ref<XRInterface> &p_interface);
157 int get_interface_count() const;
158 Ref<XRInterface> get_interface(int p_index) const;
159 Ref<XRInterface> find_interface(const String &p_name) const;
160 TypedArray<Dictionary> get_interfaces() const;
161
162 /*
163 note, more then one interface can technically be active, especially on mobile, but only one interface is used for
164 rendering. This interface identifies itself by calling set_primary_interface when it is initialized
165 */
166 Ref<XRInterface> get_primary_interface() const;
167 void set_primary_interface(const Ref<XRInterface> &p_primary_interface);
168
169 /*
170 Our trackers are objects that expose the orientation and position of physical devices such as controller, anchor points, etc.
171 They are created and managed by our active AR/VR interfaces.
172 */
173 void add_tracker(Ref<XRPositionalTracker> p_tracker);
174 void remove_tracker(Ref<XRPositionalTracker> p_tracker);
175 Dictionary get_trackers(int p_tracker_types);
176 Ref<XRPositionalTracker> get_tracker(const StringName &p_name) const;
177
178 /*
179 We don't know which trackers and actions will existing during runtime but we can request suggested names from our interfaces to help our IDE UI.
180 */
181 PackedStringArray get_suggested_tracker_names() const;
182 PackedStringArray get_suggested_pose_names(const StringName &p_tracker_name) const;
183 // Q: Should we add get_suggested_input_names and get_suggested_haptic_names even though we don't use them for the IDE?
184
185 // Process is called before we handle our physics process and game process. This is where our interfaces will update controller data and such.
186 void _process();
187
188 // Pre-render is called right before we're rendering our viewports.
189 // This is where interfaces such as OpenVR and OpenXR will update positioning data.
190 // Many of these interfaces will also do a predictive sync which ensures we run at a steady framerate.
191 void pre_render();
192
193 // End-frame is called right after Godot has finished its rendering bits.
194 void end_frame();
195
196 XRServer();
197 ~XRServer();
198};
199
200#define XR XRServer
201
202VARIANT_ENUM_CAST(XRServer::TrackerType);
203VARIANT_ENUM_CAST(XRServer::RotationMode);
204
205#endif // XR_SERVER_H
206