1/**************************************************************************/
2/* xr_interface.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_INTERFACE_H
32#define XR_INTERFACE_H
33
34#include "core/math/projection.h"
35#include "core/os/thread_safe.h"
36#include "servers/xr_server.h"
37
38// forward declaration
39struct BlitToScreen;
40
41/**
42 The XR interface is a template class on top of which we build interface to different AR, VR and tracking SDKs.
43 The idea is that we subclass this class, implement the logic, and then instantiate a singleton of each interface
44 when Godot starts. These instances do not initialize themselves but register themselves with the AR/VR server.
45
46 If the user wants to enable AR/VR the choose the interface they want to use and initialize it.
47
48 Note that we may make this into a fully instantiable class for GDExtension support.
49*/
50
51class XRInterface : public RefCounted {
52 GDCLASS(XRInterface, RefCounted);
53
54public:
55 enum Capabilities { /* purely metadata, provides some info about what this interface supports */
56 XR_NONE = 0, /* no capabilities */
57 XR_MONO = 1, /* can be used with mono output */
58 XR_STEREO = 2, /* can be used with stereo output */
59 XR_QUAD = 4, /* can be used with quad output (not currently supported) */
60 XR_VR = 8, /* offers VR support */
61 XR_AR = 16, /* offers AR support */
62 XR_EXTERNAL = 32 /* renders to external device */
63 };
64
65 enum TrackingStatus { /* tracking status currently based on AR but we can start doing more with this for VR as well */
66 XR_NORMAL_TRACKING,
67 XR_EXCESSIVE_MOTION,
68 XR_INSUFFICIENT_FEATURES,
69 XR_UNKNOWN_TRACKING,
70 XR_NOT_TRACKING
71 };
72
73 enum PlayAreaMode { /* defines the mode used by the XR interface for tracking */
74 XR_PLAY_AREA_UNKNOWN, /* Area mode not set or not available */
75 XR_PLAY_AREA_3DOF, /* Only support orientation tracking, no positional tracking, area will center around player */
76 XR_PLAY_AREA_SITTING, /* Player is in seated position, limited positional tracking, fixed guardian around player */
77 XR_PLAY_AREA_ROOMSCALE, /* Player is free to move around, full positional tracking */
78 XR_PLAY_AREA_STAGE, /* Same as roomscale but origin point is fixed to the center of the physical space, XRServer.center_on_hmd disabled */
79 };
80
81 enum EnvironmentBlendMode {
82 XR_ENV_BLEND_MODE_OPAQUE, /* You cannot see the real world, VR like */
83 XR_ENV_BLEND_MODE_ADDITIVE, /* You can see the real world, AR like */
84 XR_ENV_BLEND_MODE_ALPHA_BLEND, /* Real world is passed through where alpha channel is 0.0 and gradually blends to opaque for value 1.0. */
85 };
86
87protected:
88 _THREAD_SAFE_CLASS_
89
90 static void _bind_methods();
91
92public:
93 /** general interface information **/
94 virtual StringName get_name() const = 0;
95 virtual uint32_t get_capabilities() const = 0;
96
97 bool is_primary();
98 void set_primary(bool p_is_primary);
99
100 virtual bool is_initialized() const = 0; /* returns true if we've initialized this interface */
101 virtual bool initialize() = 0; /* initialize this interface, if this has an HMD it becomes the primary interface */
102 virtual void uninitialize() = 0; /* deinitialize this interface */
103 virtual Dictionary get_system_info() = 0; /* return a dictionary with info about our system */
104
105 /** input and output **/
106
107 virtual PackedStringArray get_suggested_tracker_names() const; /* return a list of likely/suggested tracker names */
108 virtual PackedStringArray get_suggested_pose_names(const StringName &p_tracker_name) const; /* return a list of likely/suggested action names for this tracker */
109 virtual TrackingStatus get_tracking_status() const; /* get the status of our current tracking */
110 virtual void trigger_haptic_pulse(const String &p_action_name, const StringName &p_tracker_name, double p_frequency, double p_amplitude, double p_duration_sec, double p_delay_sec = 0); /* trigger a haptic pulse */
111
112 /** specific to VR **/
113 virtual bool supports_play_area_mode(XRInterface::PlayAreaMode p_mode); /* query if this interface supports this play area mode */
114 virtual XRInterface::PlayAreaMode get_play_area_mode() const; /* get the current play area mode */
115 virtual bool set_play_area_mode(XRInterface::PlayAreaMode p_mode); /* change the play area mode, note that this should return false if the mode is not available */
116 virtual PackedVector3Array get_play_area() const; /* if available, returns an array of vectors denoting the play area the player can move around in */
117
118 /** specific to AR **/
119 virtual bool get_anchor_detection_is_enabled() const;
120 virtual void set_anchor_detection_is_enabled(bool p_enable);
121 virtual int get_camera_feed_id();
122
123 /** rendering and internal **/
124
125 virtual Size2 get_render_target_size() = 0; /* returns the recommended render target size per eye for this device */
126 virtual uint32_t get_view_count() = 0; /* returns the view count we need (1 is monoscopic, 2 is stereoscopic but can be more) */
127 virtual Transform3D get_camera_transform() = 0; /* returns the position of our camera for updating our camera node. For monoscopic this is equal to the views transform, for stereoscopic this should be an average */
128 virtual Transform3D get_transform_for_view(uint32_t p_view, const Transform3D &p_cam_transform) = 0; /* get each views transform */
129 virtual Projection get_projection_for_view(uint32_t p_view, double p_aspect, double p_z_near, double p_z_far) = 0; /* get each view projection matrix */
130 virtual RID get_vrs_texture(); /* obtain VRS texture */
131 virtual RID get_color_texture(); /* obtain color output texture (if applicable) */
132 virtual RID get_depth_texture(); /* obtain depth output texture (if applicable, used for reprojection) */
133 virtual RID get_velocity_texture(); /* obtain velocity output texture (if applicable, used for spacewarp) */
134
135 virtual void process() = 0;
136 virtual void pre_render(){};
137 virtual bool pre_draw_viewport(RID p_render_target) { return true; }; /* inform XR interface we are about to start our viewport draw process */
138 virtual Vector<BlitToScreen> post_draw_viewport(RID p_render_target, const Rect2 &p_screen_rect) = 0; /* inform XR interface we finished our viewport draw process */
139 virtual void end_frame(){};
140
141 /** passthrough **/
142
143 virtual bool is_passthrough_supported() { return false; }
144 virtual bool is_passthrough_enabled() { return false; }
145 virtual bool start_passthrough() { return false; }
146 virtual void stop_passthrough() {}
147
148 /** environment blend mode. */
149 virtual Array get_supported_environment_blend_modes();
150 virtual XRInterface::EnvironmentBlendMode get_environment_blend_mode() const { return XR_ENV_BLEND_MODE_OPAQUE; }
151 virtual bool set_environment_blend_mode(EnvironmentBlendMode mode) { return false; }
152
153 XRInterface();
154 ~XRInterface();
155
156private:
157 struct VRSData {
158 RID vrs_texture;
159 Size2i size;
160 } vrs;
161};
162
163VARIANT_ENUM_CAST(XRInterface::Capabilities);
164VARIANT_ENUM_CAST(XRInterface::TrackingStatus);
165VARIANT_ENUM_CAST(XRInterface::PlayAreaMode);
166VARIANT_ENUM_CAST(XRInterface::EnvironmentBlendMode);
167
168#endif // XR_INTERFACE_H
169