Monado OpenXR Runtime
xrt_system.h
Go to the documentation of this file.
1// Copyright 2020-2024, Collabora, Ltd.
2// Copyright 2023-2025, NVIDIA CORPORATION.
3// SPDX-License-Identifier: BSL-1.0
4/*!
5 * @file
6 * @brief Header for system objects.
7 * @author Jakob Bornecrantz <jakob@collabora.com>
8 * @author Korcan Hussein <korcan.hussein@collabora.com>
9 * @ingroup xrt_iface
10 */
11
12#pragma once
13
14#include "xrt/xrt_compiler.h"
15#include "xrt/xrt_defines.h"
16#include "xrt/xrt_device.h"
17
18#ifdef __cplusplus
19extern "C" {
20#endif
21
22struct xrt_instance;
24struct xrt_session;
26struct xrt_session_info;
27
28
29/*
30 *
31 * System.
32 *
33 */
34
35#define XRT_SYSTEM_ID 1
36
37#define XRT_MAX_SYSTEM_NAME_SIZE 256
38
39/*!
40 * Properties provided by the system.
41 */
43{
44 uint32_t vendor_id;
45 char name[XRT_MAX_SYSTEM_NAME_SIZE];
46 enum xrt_form_factor form_factor;
47};
48
49/*!
50 * A system is a collection of devices, policies and optionally a compositor
51 * that is organised into a chosive group that is usable by one user, most of
52 * the functionality of a system is exposed through other objects, this is the
53 * main object. It is from this you create sessions that is used to by apps to
54 * interact with the "system".
55 *
56 * Sibling objects: @ref xrt_system_devices, @ref xrt_system_compositor and
57 * @ref xrt_space_overseer.
58 *
59 * @ingroup xrt_iface
60 */
62{
63 /*!
64 * Create a @ref xrt_session and optionally a @ref xrt_compositor_native
65 * for this system.
66 *
67 * param[in] xsys Pointer to self.
68 * param[in] xsi Session info.
69 * param[out] out_xs Created session.
70 * param[out] out_xcn Native compositor for this session, optional.
71 */
73 const struct xrt_session_info *xsi,
74 struct xrt_session **out_xs,
75 struct xrt_compositor_native **out_xcn);
76
77 /*!
78 * Destroy the system, must be destroyed after system devices and system
79 * compositor has been destroyed.
80 *
81 * Code consuming this interface should use @ref xrt_system_destroy.
82 *
83 * @param xsys Pointer to self
84 */
85 void (*destroy)(struct xrt_system *xsys);
86
87 struct xrt_system_properties properties;
88};
89
90/*!
91 * @copydoc xrt_system::create_session
92 *
93 * Helper for calling through the function pointer.
94 *
95 * @public @memberof xrt_system
96 */
97static inline xrt_result_t
99 const struct xrt_session_info *xsi,
100 struct xrt_session **out_xs,
101 struct xrt_compositor_native **out_xcn)
102{
103 return xsys->create_session(xsys, xsi, out_xs, out_xcn);
104}
105
106/*!
107 * Destroy an xrt_system - helper function.
108 *
109 * @param[in,out] xsys_ptr A pointer to the xrt_system struct pointer.
110 *
111 * Will destroy the system if `*xsys_ptr` is not NULL. Will then set
112 * `*xsys_ptr` to NULL.
113 *
114 * @public @memberof xrt_system
115 */
116static inline void
118{
119 struct xrt_system *xsys = *xsys_ptr;
120 if (xsys == NULL) {
121 return;
122 }
123
124 *xsys_ptr = NULL;
125 xsys->destroy(xsys);
126}
127
128
129/*
130 *
131 * System devices.
132 *
133 */
134
135/*!
136 * Maximum number of devices simultaneously usable by an implementation of
137 * @ref xrt_system_devices
138 *
139 * @ingroup xrt_iface
140 */
141#define XRT_SYSTEM_MAX_DEVICES (32)
142
143/*!
144 * Data associating a device index (in @ref xrt_system_devices::xdevs) with a
145 * given "role" for dynamic role switching.
146 *
147 * For each of the named roles, a negative value means unpopulated/not available.
148 *
149 * Populated by a call from the @ref xrt_system_devices interface.
150 *
151 * When the caller of @ref xrt_system_devices_get_roles sees a change (based on
152 * comparing @ref generation_id) the caller must do the needed actions to handle
153 * device changes. For example, for the OpenXR state tracker this may include
154 * rebinding, queuing a change to the current interaction profile, and queuing
155 * the events associated with such a change.
156 *
157 * @see xrt_system_devices
158 * @ingroup xrt_iface
159 */
161{
162 /*!
163 * Monotonically increasing generation counter for the association
164 * between role and index.
165 *
166 * Increment whenever the roles are changed.
167 *
168 * All valid values are greater then zero; this is to
169 * make init easier where any cache can start at zero and be guaranteed
170 * to be replaced with a new @ref xrt_system_roles.
171 *
172 * alignas for 32 bit client support, see @ref ipc-design
173 */
174 XRT_ALIGNAS(8) uint64_t generation_id;
175
176 /*!
177 * Index in @ref xrt_system_devices::xdevs for the user's left
178 * controller/hand, or negative if none available.
179 */
180 int32_t left;
181
182 /*!
183 * Index in @ref xrt_system_devices::xdevs for the user's right
184 * controller/hand, or negative if none available.
185 */
186 int32_t right;
187
188 /*!
189 * Index in @ref xrt_system_devices::xdevs for the user's gamepad
190 * device, or negative if none available.
191 */
192 int32_t gamepad;
193
194 enum xrt_device_name left_profile;
195
196 enum xrt_device_name right_profile;
197
198 enum xrt_device_name gamepad_profile;
199};
200
201/*!
202 * Guaranteed invalid constant for @ref xrt_system_roles, not using designated
203 * initializers due to C++.
204 *
205 * @ingroup xrt_iface
206 * @relates xrt_system_roles
207 */
208#define XRT_SYSTEM_ROLES_INIT \
209 { \
210 0, -1, -1, -1, XRT_DEVICE_INVALID, XRT_DEVICE_INVALID, XRT_DEVICE_INVALID, \
211 }
212
213
214/*!
215 * A collection of @ref xrt_device, and an interface for identifying the roles
216 * they have been assigned.
217 *
218 * @see xrt_device, xrt_instance.
219 */
221{
222 /*!
223 * All devices known in the system.
224 *
225 * This is conventionally considered the "owning" reference to the devices.
226 * Valid entries are contiguous.
227 */
229
230 /*!
231 * The number of elements in @ref xdevs that are valid.
232 */
234
235 /*!
236 * Observing pointers for devices in some static (unchangeable) roles.
237 *
238 * All pointers in this struct must also exist in @ref xdevs. The
239 * association between a member of this struct and a given device
240 * cannot change during runtime.
241 */
242 struct
243 {
244 /*!
245 * An observing pointer to the device serving as the "head"
246 * (and HMD).
247 *
248 * Required.
249 */
251
252 /*!
253 * An observing pointer to the device providing eye tracking
254 * (optional).
255 */
257
258 /*!
259 * An observing pointer to the device providing face tracking
260 * (optional).
261 */
263
264 /*!
265 * An observing pointer to the device providing body tracking
266 * (optional).
267 */
269
270 /*!
271 * Devices providing optical (or otherwise more directly
272 * measured than from controller estimation) hand tracking.
273 */
274 struct
275 {
276 struct
277 {
278 /*!
279 * An observing pointer to the device providing
280 * unobstructed hand-tracking for the left hand (optional).
281 *
282 * can reference the same xrt_device instance as
283 * @ref hand_tracking::conforming::left, if provides both input types.
284 */
286
287 /*!
288 * An observing pointer to the device providing
289 * unobstructed hand-tracking for the right hand (optional).
290 *
291 * can reference the same xrt_device instance as
292 * @ref hand_tracking::conforming::right, if provides both input types.
293 */
295 } unobstructed;
296
297 struct
298 {
299 /*!
300 * An observing pointer to the device providing
301 * conforming (controller) hand-tracking for the left hand (optional).
302 *
303 * can reference the same xrt_device instance as
304 * @ref hand_tracking::unobstructed::left, if provides both input types.
305 */
306 struct xrt_device *left;
307
308 /*!
309 * An observing pointer to the device providing
310 * conforming (controller) hand-tracking for the right hand (optional).
311 *
312 * can reference the same xrt_device instance as
313 * @ref hand_tracking::unobstructed::right, if provides both input types.
314 */
315 struct xrt_device *right;
316 } conforming;
317 } hand_tracking;
318 } static_roles;
319
320
321 /*!
322 * Function to get the dynamic input device roles from this system
323 * devices, see @ref xrt_system_roles for more information.
324 *
325 * @param xsysd Pointer to self
326 * @param[out] out_roles Pointer to xrt_system_roles
327 */
328 xrt_result_t (*get_roles)(struct xrt_system_devices *xsysd, struct xrt_system_roles *out_roles);
329
330 /*!
331 * Increment the usage count of a feature.
332 * When the feature is used for the first time, then the feature will be begun.
333 *
334 * @param xsysd Pointer to self
335 * @param type Which feature is being counted.
336 */
337 xrt_result_t (*feature_inc)(struct xrt_system_devices *xsysd, enum xrt_device_feature_type type);
338
339 /*!
340 * Decrement the usage count of a feature.
341 * When the feature is not used by the current application any more, then the feature will be ended.
342 *
343 * @param xsysd Pointer to self
344 * @param type Which feature is being counted.
345 */
347
348 /*!
349 * Destroy all the devices that are owned by this system devices.
350 *
351 * Code consuming this interface should use @ref xrt_system_devices_destroy.
352 *
353 * @param xsysd Pointer to self
354 */
355 void (*destroy)(struct xrt_system_devices *xsysd);
356};
357
358/*!
359 * @copydoc xrt_system_devices::get_roles
360 *
361 * Helper for calling through the function pointer.
362 *
363 * @public @memberof xrt_system_devices
364 */
365static inline xrt_result_t
367{
368 return xsysd->get_roles(xsysd, out_roles);
369}
370
371/*!
372 * @copydoc xrt_system_devices::feature_inc
373 *
374 * Helper for calling through the function pointer.
375 *
376 * @public @memberof xrt_system_devices
377 */
378static inline xrt_result_t
380{
381 return xsysd->feature_inc(xsysd, type);
382}
383
384/*!
385 * @copydoc xrt_system_devices::feature_dec
386 *
387 * Helper for calling through the function pointer.
388 *
389 * @public @memberof xrt_system_devices
390 */
391static inline xrt_result_t
393{
394 return xsysd->feature_dec(xsysd, type);
395}
396
397/*!
398 * Destroy an xrt_system_devices and owned devices - helper function.
399 *
400 * @param[in,out] xsysd_ptr A pointer to the xrt_system_devices struct pointer.
401 *
402 * Will destroy the system devices if `*xsysd_ptr` is not NULL. Will then set
403 * `*xsysd_ptr` to NULL.
404 *
405 * @public @memberof xrt_system_devices
406 */
407static inline void
409{
410 struct xrt_system_devices *xsysd = *xsysd_ptr;
411 if (xsysd == NULL) {
412 return;
413 }
414
415 *xsysd_ptr = NULL;
416 xsysd->destroy(xsysd);
417}
418
419
420#ifdef __cplusplus
421}
422#endif
#define XRT_SYSTEM_MAX_DEVICES
Maximum number of devices simultaneously usable by an implementation of xrt_system_devices.
Definition: xrt_system.h:141
xrt_form_factor
What form factor is this device, mostly maps onto OpenXR's XrFormFactor.
Definition: xrt_defines.h:2065
enum xrt_result xrt_result_t
Result type used across Monado.
Main compositor server interface.
Definition: xrt_compositor.h:2233
A single HMD or input device.
Definition: xrt_device.h:280
This interface acts as a root object for Monado.
Definition: xrt_instance.h:116
Session information, mostly overlay extension data.
Definition: xrt_compositor.h:933
The XRT representation of XrSession, this object does not have all of the functionality of a session,...
Definition: xrt_session.h:259
A collection of xrt_device, and an interface for identifying the roles they have been assigned.
Definition: xrt_system.h:221
static xrt_result_t xrt_system_devices_feature_inc(struct xrt_system_devices *xsysd, enum xrt_device_feature_type type)
Increment the usage count of a feature.
Definition: xrt_system.h:379
xrt_result_t(* feature_inc)(struct xrt_system_devices *xsysd, enum xrt_device_feature_type type)
Increment the usage count of a feature.
Definition: xrt_system.h:337
size_t xdev_count
The number of elements in xdevs that are valid.
Definition: xrt_system.h:233
static xrt_result_t xrt_system_devices_get_roles(struct xrt_system_devices *xsysd, struct xrt_system_roles *out_roles)
Function to get the dynamic input device roles from this system devices, see xrt_system_roles for mor...
Definition: xrt_system.h:366
xrt_result_t(* get_roles)(struct xrt_system_devices *xsysd, struct xrt_system_roles *out_roles)
Function to get the dynamic input device roles from this system devices, see xrt_system_roles for mor...
Definition: xrt_system.h:328
static xrt_result_t xrt_system_devices_feature_dec(struct xrt_system_devices *xsysd, enum xrt_device_feature_type type)
Decrement the usage count of a feature.
Definition: xrt_system.h:392
void(* destroy)(struct xrt_system_devices *xsysd)
Destroy all the devices that are owned by this system devices.
Definition: xrt_system.h:355
struct xrt_device * head
An observing pointer to the device serving as the "head" (and HMD).
Definition: xrt_system.h:250
struct xrt_device * face
An observing pointer to the device providing face tracking (optional).
Definition: xrt_system.h:262
struct xrt_device * eyes
An observing pointer to the device providing eye tracking (optional).
Definition: xrt_system.h:256
xrt_result_t(* feature_dec)(struct xrt_system_devices *xsysd, enum xrt_device_feature_type type)
Decrement the usage count of a feature.
Definition: xrt_system.h:346
struct xrt_device * left
An observing pointer to the device providing unobstructed hand-tracking for the left hand (optional).
Definition: xrt_system.h:285
struct xrt_device * right
An observing pointer to the device providing unobstructed hand-tracking for the right hand (optional)...
Definition: xrt_system.h:294
struct xrt_device * body
An observing pointer to the device providing body tracking (optional).
Definition: xrt_system.h:268
static void xrt_system_devices_destroy(struct xrt_system_devices **xsysd_ptr)
Destroy an xrt_system_devices and owned devices - helper function.
Definition: xrt_system.h:408
Properties provided by the system.
Definition: xrt_system.h:43
Data associating a device index (in xrt_system_devices::xdevs) with a given "role" for dynamic role s...
Definition: xrt_system.h:161
int32_t right
Index in xrt_system_devices::xdevs for the user's right controller/hand, or negative if none availabl...
Definition: xrt_system.h:186
XRT_ALIGNAS(8) uint64_t generation_id
Monotonically increasing generation counter for the association between role and index.
int32_t gamepad
Index in xrt_system_devices::xdevs for the user's gamepad device, or negative if none available.
Definition: xrt_system.h:192
int32_t left
Index in xrt_system_devices::xdevs for the user's left controller/hand, or negative if none available...
Definition: xrt_system.h:180
A system is a collection of devices, policies and optionally a compositor that is organised into a ch...
Definition: xrt_system.h:62
xrt_result_t(* create_session)(struct xrt_system *xsys, const struct xrt_session_info *xsi, struct xrt_session **out_xs, struct xrt_compositor_native **out_xcn)
Create a xrt_session and optionally a xrt_compositor_native for this system.
Definition: xrt_system.h:72
static xrt_result_t xrt_system_create_session(struct xrt_system *xsys, const struct xrt_session_info *xsi, struct xrt_session **out_xs, struct xrt_compositor_native **out_xcn)
Create a xrt_session and optionally a xrt_compositor_native for this system.
Definition: xrt_system.h:98
static void xrt_system_destroy(struct xrt_system **xsys_ptr)
Destroy an xrt_system - helper function.
Definition: xrt_system.h:117
void(* destroy)(struct xrt_system *xsys)
Destroy the system, must be destroyed after system devices and system compositor has been destroyed.
Definition: xrt_system.h:85
Header holding common defines.
Common defines and enums for XRT.
xrt_device_name
A enum that is used to name devices so that the state trackers can reason about the devices easier.
Definition: xrt_defines.h:708
Header defining an xrt display or controller device.
xrt_device_feature_type
Higher level features for devices.
Definition: xrt_device.h:229