Monado OpenXR Runtime
u_system_helpers.h
Go to the documentation of this file.
1// Copyright 2022-2023, Collabora, Ltd.
2// SPDX-License-Identifier: BSL-1.0
3/*!
4 * @file
5 * @brief Helpers for system objects like @ref xrt_system_devices.
6 * @author Jakob Bornecrantz <jakob@collabora.com>
7 * @ingroup aux_util
8 */
9
10#pragma once
11
12#include "xrt/xrt_results.h"
13#include "xrt/xrt_frame.h"
14#include "xrt/xrt_system.h"
15#include "xrt/xrt_instance.h"
16#include "xrt/xrt_tracking.h"
17
18
19#ifdef __cplusplus
20extern "C" {
21#endif
22
24
25
26/*!
27 * Helper struct to manage devices by implementing the @ref xrt_system_devices.
28 *
29 * The default destroy function that is set by @ref u_system_devices_allocate
30 * will first destroy all of the @ref xrt_device and then destroy all nodes
31 * in the @ref xrt_frame_context.
32 *
33 * @ingroup aux_util
34 */
36{
37 struct xrt_system_devices base;
38
39 //! Optional frame context for visual tracking.
41
42 //! Optional shared tracking origin.
44};
45
46/*!
47 * Small inline helper to cast from @ref xrt_system_devices.
48 *
49 * @ingroup aux_util
50 */
51static inline struct u_system_devices *
53{
54 return (struct u_system_devices *)xsysd;
55}
56
57/*!
58 * Allocates a empty @ref u_system_devices to be filled in by the caller, only
59 * the destroy function is filled in.
60 *
61 * @ingroup aux_util
62 */
63struct u_system_devices *
65
66/*!
67 * Destroys all devices and clears out the frame context, doesn't free the
68 * struct itself, useful for code embedding the system devices struct into
69 * other objects where it's not the first member or C++ classes.
70 *
71 * @ingroup aux_util
72 */
73void
75
76/*!
77 * Destroy an u_system_devices_allocate and owned devices - helper function.
78 *
79 * @param[in,out] usysd_ptr A pointer to the u_system_devices_allocate struct pointer.
80 *
81 * Will destroy the system devices if *usysd_ptr is not NULL. Will then set *usysd_ptr to NULL.
82 *
83 * @public @memberof u_system_devices_allocate
84 */
85static inline void
86u_system_devices_destroy(struct u_system_devices **usysd_ptr)
87{
88 struct u_system_devices *usysd = *usysd_ptr;
89 if (usysd == NULL) {
90 return;
91 }
92
93 *usysd_ptr = NULL;
94 usysd->base.destroy(&usysd->base);
95}
96
97
98/*
99 *
100 * Static helper.
101 *
102 */
103
104/*!
105 * Helper struct to manage devices by implementing the @ref xrt_system_devices,
106 * this has only static device roles.
107 *
108 * @ingroup aux_util
109 */
111{
112 struct u_system_devices base;
113
114 //! Is automatically returned.
116
117 //! Tracks usage of device features.
118 struct xrt_reference feature_use[XRT_DEVICE_FEATURE_MAX_ENUM];
119};
120
121/*!
122 * Small inline helper to cast from @ref xrt_system_devices.
123 *
124 * @ingroup aux_util
125 */
126static inline struct u_system_devices_static *
128{
129 return (struct u_system_devices_static *)xsysd;
130}
131
132/*!
133 * Allocates a empty @ref u_system_devices to be filled in by the caller, only
134 * the destroy function is filled in.
135 *
136 * @ingroup aux_util
137 */
140
141/*!
142 * Finalizes the static struct with the given input devices, the system devices
143 * will always return these devices for the left and right role. This function
144 * must be called before @ref xrt_system_devices_get_roles is called.
145 *
146 * @ingroup aux_util
147 */
148void
150 struct xrt_device *left,
151 struct xrt_device *right,
152 struct xrt_device *gamepad);
153
154
155/*
156 *
157 * Generic system devices helper.
158 *
159 */
160
161/*!
162 * Takes a @ref xrt_instance, gets the prober from it and then uses the prober
163 * to allocate a filled in @ref u_system_devices.
164 *
165 * @ingroup aux_util
166 */
169 struct xrt_session_event_sink *broadcast,
170 struct xrt_system_devices **out_xsysd,
171 struct xrt_space_overseer **out_xso);
172
173/*!
174 * Helper function.
175 *
176 * Looks through @ref xrt_system_devices's devices and returns the first device
177 * that supports hand tracking and the supplied input name.
178 *
179 * Used by target_builder_lighthouse to find Knuckles controllers in the list of
180 * devices returned, the legacy builder to find hand tracking devices, etc.
181 *
182 * @ingroup aux_util
183 */
184struct xrt_device *
186
187/*!
188 * Helper to get the first left hand-tracking device,
189 * uses @ref u_system_devices_get_ht_device.
190 *
191 * @ingroup aux_util
192 */
193static inline struct xrt_device *
195{
196 return u_system_devices_get_ht_device(xsysd, XRT_INPUT_GENERIC_HAND_TRACKING_LEFT);
197}
198
199/*!
200 * Helper to get the first right hand-tracking device,
201 * uses @ref u_system_devices_get_ht_device.
202 *
203 * @ingroup aux_util
204 */
205static inline struct xrt_device *
207{
208 return u_system_devices_get_ht_device(xsysd, XRT_INPUT_GENERIC_HAND_TRACKING_RIGHT);
209}
210
211
212#ifdef __cplusplus
213}
214#endif
struct xrt_device * u_system_devices_get_ht_device(struct xrt_system_devices *xsysd, enum xrt_input_name name)
Helper function.
Definition: u_system_helpers.c:267
static struct xrt_device * u_system_devices_get_ht_device_right(struct xrt_system_devices *xsysd)
Helper to get the first right hand-tracking device, uses u_system_devices_get_ht_device.
Definition: u_system_helpers.h:206
void u_system_devices_static_finalize(struct u_system_devices_static *usysds, struct xrt_device *left, struct xrt_device *right, struct xrt_device *gamepad)
Finalizes the static struct with the given input devices, the system devices will always return these...
Definition: u_system_helpers.c:193
struct u_system_devices_static * u_system_devices_static_allocate(void)
Allocates a empty u_system_devices to be filled in by the caller, only the destroy function is filled...
Definition: u_system_helpers.c:181
static struct xrt_device * u_system_devices_get_ht_device_left(struct xrt_system_devices *xsysd)
Helper to get the first left hand-tracking device, uses u_system_devices_get_ht_device.
Definition: u_system_helpers.h:194
void u_system_devices_close(struct xrt_system_devices *xsysd)
Destroys all devices and clears out the frame context, doesn't free the struct itself,...
Definition: u_system_helpers.c:167
struct u_system_devices * u_system_devices_allocate(void)
Allocates a empty u_system_devices to be filled in by the caller, only the destroy function is filled...
Definition: u_system_helpers.c:158
xrt_result_t u_system_devices_create_from_prober(struct xrt_instance *xinst, struct xrt_session_event_sink *broadcast, struct xrt_system_devices **out_xsysd, struct xrt_space_overseer **out_xso)
Takes a xrt_instance, gets the prober from it and then uses the prober to allocate a filled in u_syst...
Definition: u_system_helpers.c:237
static struct u_system_devices * u_system_devices(struct xrt_system_devices *xsysd)
Small inline helper to cast from xrt_system_devices.
Definition: u_system_helpers.h:52
static struct u_system_devices_static * u_system_devices_static(struct xrt_system_devices *xsysd)
Small inline helper to cast from xrt_system_devices.
Definition: u_system_helpers.h:127
xrt_input_name
Every internal input source known to monado with a baked in type.
Definition: xrt_defines.h:1311
enum xrt_result xrt_result_t
Result type used across Monado.
Helper struct to manage devices by implementing the xrt_system_devices, this has only static device r...
Definition: u_system_helpers.h:111
struct xrt_system_roles cached
Is automatically returned.
Definition: u_system_helpers.h:115
struct xrt_reference feature_use[XRT_DEVICE_FEATURE_MAX_ENUM]
Tracks usage of device features.
Definition: u_system_helpers.h:118
Helper struct to manage devices by implementing the xrt_system_devices.
Definition: u_system_helpers.h:36
struct xrt_tracking_origin origin
Optional shared tracking origin.
Definition: u_system_helpers.h:43
struct xrt_frame_context xfctx
Optional frame context for visual tracking.
Definition: u_system_helpers.h:40
A single HMD or input device.
Definition: xrt_device.h:280
enum xrt_device_name name
Enum identifier of the device.
Definition: xrt_device.h:282
Object used to track all sinks and frame producers in a graph.
Definition: xrt_frame.h:108
This interface acts as a root object for Monado.
Definition: xrt_instance.h:115
A base class for reference counted objects.
Definition: xrt_defines.h:97
Used internally from producers of events to push events into session, some sinks might multiplex even...
Definition: xrt_session.h:219
Object that oversees and manages spaces, one created for each XR system.
Definition: xrt_space.h:96
A collection of xrt_device, and an interface for identifying the roles they have been assigned.
Definition: xrt_system.h:221
void(* destroy)(struct xrt_system_devices *xsysd)
Destroy all the devices that are owned by this system devices.
Definition: xrt_system.h:332
Data associating a device index (in xrt_system_devices::xdevs) with a given "role" for dynamic role s...
Definition: xrt_system.h:161
A tracking system or device origin.
Definition: xrt_tracking.h:71
Data frame header.
Header for xrt_instance object.
Internal result type for XRT.
Header for system objects.
Header defining the tracking system integration in Monado.