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};
83
84/*!
85 * Information provided by the application at instance create time.
86 *
87 * Some information may be process-specific.
88 */
90{
91 //! Generic data from application.
93
94 //! Process-specific, platform-specific data.
96};
97
98/*!
99 * @interface xrt_instance
100 *
101 * This interface acts as a root object for Monado.
102 * It typically either wraps an @ref xrt_prober or forms a connection to an
103 * out-of-process XR service.
104 *
105 * This is as close to a singleton object as there is in Monado: you should not
106 * create more than one xrt_instance implementation per process.
107 *
108 * Each "target" will provide its own (private) implementation of this
109 * interface, which is exposed by implementing xrt_instance_create().
110 *
111 * Additional information can be found in @ref understanding-targets.
112 *
113 * @sa ipc_instance_create
114 */
116{
117 /*!
118 * @name Interface Methods
119 *
120 * All implementations of the xrt_instance interface must
121 * populate all these function pointers with their implementation
122 * methods. To use this interface, see the helper functions.
123 * @{
124 */
125
126 /*!
127 * Creates all of the system resources like the devices and system
128 * compositor. The system compositor is optional.
129 *
130 * Should only be called once.
131 *
132 * @note Code consuming this interface should use xrt_instance_create_system()
133 *
134 * @param xinst Pointer to self
135 * @param[out] out_xsys Return of system, required.
136 * @param[out] out_xsysd Return of devices, required.
137 * @param[out] out_xsysc Return of system compositor, optional.
138 *
139 * @see xrt_prober::probe, xrt_prober::select, xrt_gfx_provider_create_native
140 */
142 struct xrt_system **out_xsys,
143 struct xrt_system_devices **out_xsysd,
144 struct xrt_space_overseer **out_xso,
145 struct xrt_system_compositor **out_xsysc);
146
147 /*!
148 * Get the instance @ref xrt_prober, if any.
149 *
150 * If the instance is not using an @ref xrt_prober, it may return null.
151 *
152 * The instance retains ownership of the prober and is responsible for
153 * destroying it.
154 *
155 * Can be called multiple times. (The prober is usually created at
156 * instance construction time.)
157 *
158 * @note Code consuming this interface should use
159 * xrt_instance_get_prober().
160 *
161 * @param xinst Pointer to self
162 * @param[out] out_xp Pointer to xrt_prober pointer, will be populated
163 * or set to NULL.
164 *
165 * @return XRT_SUCCESS on success, other error code on error.
166 */
167 xrt_result_t (*get_prober)(struct xrt_instance *xinst, struct xrt_prober **out_xp);
168
169 /*!
170 * Destroy the instance and its owned objects, including the prober (if
171 * any).
172 *
173 * Code consuming this interface should use xrt_instance_destroy().
174 *
175 * @param xinst Pointer to self
176 */
177 void (*destroy)(struct xrt_instance *xinst);
178 /*!
179 * @}
180 */
181
182 /*!
183 * Instance information structure, including both platform and application info.
184 */
186
187 /*!
188 * CLOCK_MONOTONIC timestamp of the instance startup.
189 */
191
192 /*!
193 * An "aspect" of the xrt_instance interface, used only on Android.
194 *
195 * @see xrt_instance_android
196 */
197 struct xrt_instance_android *android_instance;
198};
199
200/*!
201 * @copydoc xrt_instance::create_system
202 *
203 * Helper for calling through the function pointer.
204 *
205 * @public @memberof xrt_instance
206 */
207static inline xrt_result_t
209 struct xrt_system **out_xsys,
210 struct xrt_system_devices **out_xsysd,
211 struct xrt_space_overseer **out_xso,
212 struct xrt_system_compositor **out_xsysc)
213{
214 return xinst->create_system(xinst, out_xsys, out_xsysd, out_xso, out_xsysc);
215}
216
217/*!
218 * @copydoc xrt_instance::get_prober
219 *
220 * Helper for calling through the function pointer.
221 *
222 * @public @memberof xrt_instance
223 */
224static inline xrt_result_t
225xrt_instance_get_prober(struct xrt_instance *xinst, struct xrt_prober **out_xp)
226{
227 return xinst->get_prober(xinst, out_xp);
228}
229
230/*!
231 * Destroy an xrt_instance - helper function.
232 *
233 * @param[in,out] xinst_ptr A pointer to your instance implementation pointer.
234 *
235 * Will destroy the instance if *xinst_ptr is not NULL. Will then set *xinst_ptr
236 * to NULL.
237 *
238 * @public @memberof xrt_instance
239 */
240static inline void
242{
243 struct xrt_instance *xinst = *xinst_ptr;
244 if (xinst == NULL) {
245 return;
246 }
247
248 xinst->destroy(xinst);
249 *xinst_ptr = NULL;
250}
251
252/*!
253 * @name Factory
254 * Implemented in each target.
255 * @{
256 */
257/*!
258 * Create an implementation of the xrt_instance interface.
259 *
260 * Creating more then one @ref xrt_instance is probably never the right thing
261 * to do, so avoid it.
262 *
263 * Each target must implement this function.
264 *
265 * @param[in] ii A pointer to a info struct containing information about the
266 * application.
267 * @param[out] out_xinst A pointer to an xrt_instance pointer. Will be
268 * populated.
269 *
270 * @return 0 on success
271 *
272 * @relates xrt_instance
273 */
275xrt_instance_create(struct xrt_instance_info *ii, struct xrt_instance **out_xinst);
276
277/*!
278 * @}
279 */
280
281/*!
282 * @}
283 */
284
285
286#ifdef __cplusplus
287}
288#endif
static void xrt_instance_destroy(struct xrt_instance **xinst_ptr)
Destroy an xrt_instance - helper function.
Definition: xrt_instance.h:241
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:208
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:225
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:281
Information provided by the application at instance create time.
Definition: xrt_instance.h:90
struct xrt_platform_info platform_info
Process-specific, platform-specific data.
Definition: xrt_instance.h:95
struct xrt_application_info app_info
Generic data from application.
Definition: xrt_instance.h:92
This interface acts as a root object for Monado.
Definition: xrt_instance.h:116
struct xrt_instance_android * android_instance
An "aspect" of the xrt_instance interface, used only on Android.
Definition: xrt_instance.h:197
struct xrt_instance_info instance_info
Instance information structure, including both platform and application info.
Definition: xrt_instance.h:185
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:167
void(* destroy)(struct xrt_instance *xinst)
Destroy the instance and its owned objects, including the prober (if any).
Definition: xrt_instance.h:177
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:141
int64_t startup_timestamp
CLOCK_MONOTONIC timestamp of the instance startup.
Definition: xrt_instance.h:190
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:2423
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.