Monado OpenXR Runtime
xrt_instance.h
Go to the documentation of this file.
1// Copyright 2020-2024, Collabora, Ltd.
2// SPDX-License-Identifier: BSL-1.0
3/*!
4 * @file
5 * @brief Header for @ref xrt_instance object.
6 * @author Jakob Bornecrantz <jakob@collabora.com>
7 * @author Korcan Hussein <korcan.hussein@collabora.com>
8 * @ingroup xrt_iface
9 */
10
11#pragma once
12
13#include "xrt/xrt_compiler.h"
14#include "xrt/xrt_defines.h"
15#include "xrt/xrt_config_os.h"
16
17
18#ifdef __cplusplus
19extern "C" {
20#endif
21
22
23struct xrt_prober;
24struct xrt_device;
25struct xrt_instance_android;
27struct xrt_system;
30
31struct _JavaVM;
32
33/*!
34 * Platform-specific information for an instance.
35 *
36 * Does not get transported between processes.
37 *
38 * @addtogroup xrt_iface
39 */
41{
42#if defined(XRT_OS_ANDROID) || defined(XRT_DOXYGEN)
43 /*!
44 * @name Android members
45 * @{
46 */
47 struct _JavaVM *vm;
48 void *context;
49 /*! @} */
50#else
51 //! To avoid empty structs.
52 uint32_t _padding;
53#endif
54};
55
56
57/*!
58 * @addtogroup xrt_iface
59 * @{
60 */
61
62#define XRT_MAX_APPLICATION_NAME_SIZE 128
63
64/*!
65 * Non-process-specific information provided by the application at instance create time.
66 *
67 * This is transported between client and server over IPC.
68 *
69 * @see xrt_instance_info
70 */
72{
73 char application_name[XRT_MAX_APPLICATION_NAME_SIZE];
74 bool ext_hand_tracking_enabled;
75 bool ext_hand_tracking_data_source_enabled;
76 bool ext_eye_gaze_interaction_enabled;
77 bool ext_hand_interaction_enabled;
78 bool htc_facial_tracking_enabled;
79 bool fb_body_tracking_enabled;
80 bool fb_face_tracking2_enabled;
81 bool meta_body_tracking_full_body_enabled;
82 bool meta_body_tracking_calibration_enabled;
83};
84
85/*!
86 * Information provided by the application at instance create time.
87 *
88 * Some information may be process-specific.
89 */
91{
92 //! Generic data from application.
94
95 //! Process-specific, platform-specific data.
97};
98
99/*!
100 * @interface xrt_instance
101 *
102 * This interface acts as a root object for Monado.
103 * It typically either wraps an @ref xrt_prober or forms a connection to an
104 * out-of-process XR service.
105 *
106 * This is as close to a singleton object as there is in Monado: you should not
107 * create more than one xrt_instance implementation per process.
108 *
109 * Each "target" will provide its own (private) implementation of this
110 * interface, which is exposed by implementing xrt_instance_create().
111 *
112 * Additional information can be found in @ref understanding-targets.
113 *
114 * @sa ipc_instance_create
115 */
117{
118 /*!
119 * @name Interface Methods
120 *
121 * All implementations of the xrt_instance interface must
122 * populate all these function pointers with their implementation
123 * methods. To use this interface, see the helper functions.
124 * @{
125 */
126
127 /*!
128 * Creates all of the system resources like the devices and system
129 * compositor. The system compositor is optional.
130 *
131 * Should only be called once.
132 *
133 * @note Code consuming this interface should use xrt_instance_create_system()
134 *
135 * @param xinst Pointer to self
136 * @param[out] out_xsys Return of system, required.
137 * @param[out] out_xsysd Return of devices, required.
138 * @param[out] out_xsysc Return of system compositor, optional.
139 *
140 * @see xrt_prober::probe, xrt_prober::select, xrt_gfx_provider_create_native
141 */
143 struct xrt_system **out_xsys,
144 struct xrt_system_devices **out_xsysd,
145 struct xrt_space_overseer **out_xso,
146 struct xrt_system_compositor **out_xsysc);
147
148 /*!
149 * Get the instance @ref xrt_prober, if any.
150 *
151 * If the instance is not using an @ref xrt_prober, it may return null.
152 *
153 * The instance retains ownership of the prober and is responsible for
154 * destroying it.
155 *
156 * Can be called multiple times. (The prober is usually created at
157 * instance construction time.)
158 *
159 * @note Code consuming this interface should use
160 * xrt_instance_get_prober().
161 *
162 * @param xinst Pointer to self
163 * @param[out] out_xp Pointer to xrt_prober pointer, will be populated
164 * or set to NULL.
165 *
166 * @return XRT_SUCCESS on success, other error code on error.
167 */
168 xrt_result_t (*get_prober)(struct xrt_instance *xinst, struct xrt_prober **out_xp);
169
170 /*!
171 * Destroy the instance and its owned objects, including the prober (if
172 * any).
173 *
174 * Code consuming this interface should use xrt_instance_destroy().
175 *
176 * @param xinst Pointer to self
177 */
178 void (*destroy)(struct xrt_instance *xinst);
179 /*!
180 * @}
181 */
182
183 /*!
184 * Instance information structure, including both platform and application info.
185 */
187
188 /*!
189 * CLOCK_MONOTONIC timestamp of the instance startup.
190 */
192
193 /*!
194 * An "aspect" of the xrt_instance interface, used only on Android.
195 *
196 * @see xrt_instance_android
197 */
198 struct xrt_instance_android *android_instance;
199};
200
201/*!
202 * @copydoc xrt_instance::create_system
203 *
204 * Helper for calling through the function pointer.
205 *
206 * @public @memberof xrt_instance
207 */
208static inline xrt_result_t
210 struct xrt_system **out_xsys,
211 struct xrt_system_devices **out_xsysd,
212 struct xrt_space_overseer **out_xso,
213 struct xrt_system_compositor **out_xsysc)
214{
215 return xinst->create_system(xinst, out_xsys, out_xsysd, out_xso, out_xsysc);
216}
217
218/*!
219 * @copydoc xrt_instance::get_prober
220 *
221 * Helper for calling through the function pointer.
222 *
223 * @public @memberof xrt_instance
224 */
225static inline xrt_result_t
226xrt_instance_get_prober(struct xrt_instance *xinst, struct xrt_prober **out_xp)
227{
228 return xinst->get_prober(xinst, out_xp);
229}
230
231/*!
232 * Destroy an xrt_instance - helper function.
233 *
234 * @param[in,out] xinst_ptr A pointer to your instance implementation pointer.
235 *
236 * Will destroy the instance if *xinst_ptr is not NULL. Will then set *xinst_ptr
237 * to NULL.
238 *
239 * @public @memberof xrt_instance
240 */
241static inline void
243{
244 struct xrt_instance *xinst = *xinst_ptr;
245 if (xinst == NULL) {
246 return;
247 }
248
249 xinst->destroy(xinst);
250 *xinst_ptr = NULL;
251}
252
253/*!
254 * @name Factory
255 * Implemented in each target.
256 * @{
257 */
258/*!
259 * Create an implementation of the xrt_instance interface.
260 *
261 * Creating more then one @ref xrt_instance is probably never the right thing
262 * to do, so avoid it.
263 *
264 * Each target must implement this function.
265 *
266 * @param[in] ii A pointer to a info struct containing information about the
267 * application.
268 * @param[out] out_xinst A pointer to an xrt_instance pointer. Will be
269 * populated.
270 *
271 * @return 0 on success
272 *
273 * @relates xrt_instance
274 */
276xrt_instance_create(struct xrt_instance_info *ii, struct xrt_instance **out_xinst);
277
278/*!
279 * @}
280 */
281
282/*!
283 * @}
284 */
285
286
287#ifdef __cplusplus
288}
289#endif
static void xrt_instance_destroy(struct xrt_instance **xinst_ptr)
Destroy an xrt_instance - helper function.
Definition: xrt_instance.h:242
xrt_result_t xrt_instance_create(struct xrt_instance_info *ii, struct xrt_instance **out_xinst)
Create an implementation of the xrt_instance interface.
Definition: target_instance.c:157
static xrt_result_t xrt_instance_create_system(struct xrt_instance *xinst, struct xrt_system **out_xsys, struct xrt_system_devices **out_xsysd, struct xrt_space_overseer **out_xso, struct xrt_system_compositor **out_xsysc)
Creates all of the system resources like the devices and system compositor.
Definition: xrt_instance.h:209
enum xrt_result xrt_result_t
Result type used across Monado.
static xrt_result_t xrt_instance_get_prober(struct xrt_instance *xinst, struct xrt_prober **out_xp)
Get the instance xrt_prober, if any.
Definition: xrt_instance.h:226
Non-process-specific information provided by the application at instance create time.
Definition: xrt_instance.h:72
A single HMD or input device.
Definition: xrt_device.h:282
Information provided by the application at instance create time.
Definition: xrt_instance.h:91
struct xrt_platform_info platform_info
Process-specific, platform-specific data.
Definition: xrt_instance.h:96
struct xrt_application_info app_info
Generic data from application.
Definition: xrt_instance.h:93
This interface acts as a root object for Monado.
Definition: xrt_instance.h:117
struct xrt_instance_android * android_instance
An "aspect" of the xrt_instance interface, used only on Android.
Definition: xrt_instance.h:198
struct xrt_instance_info instance_info
Instance information structure, including both platform and application info.
Definition: xrt_instance.h:186
xrt_result_t(* get_prober)(struct xrt_instance *xinst, struct xrt_prober **out_xp)
Get the instance xrt_prober, if any.
Definition: xrt_instance.h:168
void(* destroy)(struct xrt_instance *xinst)
Destroy the instance and its owned objects, including the prober (if any).
Definition: xrt_instance.h:178
xrt_result_t(* create_system)(struct xrt_instance *xinst, struct xrt_system **out_xsys, struct xrt_system_devices **out_xsysd, struct xrt_space_overseer **out_xso, struct xrt_system_compositor **out_xsysc)
Creates all of the system resources like the devices and system compositor.
Definition: xrt_instance.h:142
int64_t startup_timestamp
CLOCK_MONOTONIC timestamp of the instance startup.
Definition: xrt_instance.h:191
Definition: xrt_instance.h:41
The main prober that probes and manages found but not opened HMD devices that are connected to the sy...
Definition: xrt_prober.h:132
Object that oversees and manages spaces, one created for each XR system.
Definition: xrt_space.h:96
The system compositor handles composition for a system.
Definition: xrt_compositor.h:2427
A collection of xrt_device, and an interface for identifying the roles they have been assigned.
Definition: xrt_system.h:221
A system is a collection of devices, policies and optionally a compositor that is organised into a ch...
Definition: xrt_system.h:62
Header holding common defines.
Auto detect OS and certain features.
Common defines and enums for XRT.