Monado OpenXR Runtime
u_builders.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 @ref xrt_builder implementations.
6 * @author Jakob Bornecrantz <jakob@collabora.com>
7 * @ingroup aux_util
8 */
9
10#pragma once
11
12#include "xrt/xrt_space.h"
13#include "xrt/xrt_prober.h"
14
15
16#ifdef __cplusplus
17extern "C" {
18#endif
19
22
23
24/*!
25 * Max return of the number @ref xrt_prober_device.
26 *
27 * @ingroup aux_util
28 */
29#define U_BUILDER_SEARCH_MAX (16) // 16 Vive trackers
30
31/*!
32 * Argument to @ref u_builder_roles_helper_open_system and implemented by
33 * @ref u_builder::open_system_static_roles function.
34 *
35 * A builder implement this function is free to focus on only creating the
36 * devices and assigning them initial roles. With this implementation details
37 * of the @ref xrt_system_devices and @ref xrt_space_overseer is taken care of
38 * by the caller of this function.
39 *
40 * @ingroup aux_util
41 */
43 cJSON *config,
44 struct xrt_prober *xp,
45 struct xrt_tracking_origin *origin,
46 struct xrt_system_devices *xsysd,
47 struct xrt_frame_context *xfctx,
48 struct u_builder_roles_helper *ubrh);
49
50/*!
51 * A filter to match the against.
52 *
53 * @ingroup aux_util
54 */
56{
57 uint16_t vendor_id;
58 uint16_t product_id;
59 enum xrt_bus_type bus_type;
60};
61
62/*!
63 * Results of a search of devices.
64 *
65 * @ingroup aux_util
66 */
68{
69 //! Out field of found @ref xrt_prober_device.
71
72 //! Number of found devices.
74};
75
76/*!
77 * This small helper struct is for @ref u_builder_roles_helper_open_system,
78 * lets a builder focus on opening devices rather then dealing with Monado
79 * structs like @ref xrt_system_devices and the like.
80 *
81 * @ingroup aux_util
82 */
84{
85 struct xrt_device *head;
86 struct xrt_device *left;
87 struct xrt_device *right;
88 struct xrt_device *gamepad;
89
90 struct
91 {
92 struct xrt_device *left;
93 struct xrt_device *right;
94 } hand_tracking;
95};
96
97/*!
98 * This helper struct makes it easier to implement the builder interface, but it
99 * also comes with a set of integration that may not be what all builders want.
100 * See the below functions for more information.
101 *
102 * * @ref u_builder_open_system_static_roles
103 * * @ref u_builder_roles_helper_open_system
104 *
105 * @ingroup aux_util
106 */
108{
109 //! Base for this struct.
111
112 /*!
113 * @copydoc u_builder_open_system_fn
114 */
116};
117
118
119/*
120 *
121 * Functions.
122 *
123 */
124
125/*!
126 * Find the first @ref xrt_prober_device in the prober list.
127 *
128 * @ingroup aux_util
129 */
130struct xrt_prober_device *
132 size_t xpdev_count,
133 uint16_t vendor_id,
134 uint16_t product_id,
135 enum xrt_bus_type bus_type);
136
137/*!
138 * Find all of the @ref xrt_prober_device that matches any in the given list of
139 * @ref u_builder_search_filter filters.
140 *
141 * @ingroup aux_util
142 */
143void
145 struct xrt_prober_device *const *xpdevs,
146 size_t xpdev_count,
147 const struct u_builder_search_filter *filters,
148 size_t filter_count,
149 struct u_builder_search_results *results);
150
151/*!
152 * Helper function for setting up tracking origins. Applies 3dof offsets for devices with XRT_TRACKING_TYPE_NONE.
153 *
154 * @ingroup aux_util
155 */
156void
158 struct xrt_device *left,
159 struct xrt_device *right,
160 struct xrt_device *gamepad,
161 struct xrt_vec3 *global_tracking_origin_offset);
162
163/*!
164 * Create a legacy space overseer, most builders probably want to have a more
165 * advanced setup then this, especially stand alone ones. Uses
166 * @ref u_builder_setup_tracking_origins internally and
167 * @ref u_space_overseer_legacy_setup.
168 *
169 * @ingroup aux_util
170 */
171void
173 struct xrt_device *head,
174 struct xrt_device *left,
175 struct xrt_device *right,
176 struct xrt_device *gamepad,
177 struct xrt_device **xdevs,
178 uint32_t xdev_count,
179 bool root_is_unbounded,
180 bool per_app_local_spaces,
181 struct xrt_space_overseer **out_xso);
182
183/*!
184 * Helper to create a system devices that has static roles and a appropriate
185 * space overseer. Currently uses the functions below to create a full system
186 * with the help of @p fn argument. But this might change in the future.
187 *
188 * * @ref u_system_devices_static_allocate
189 * * @ref u_system_devices_static_finalize
190 * * @ref u_builder_create_space_overseer_legacy
191 *
192 * @ingroup aux_util
193 */
196 cJSON *config,
197 struct xrt_prober *xp,
198 struct xrt_session_event_sink *broadcast,
199 struct xrt_system_devices **out_xsysd,
200 struct xrt_space_overseer **out_xso,
202
203/*!
204 * Implementation for xrt_builder::open_system to be used with @ref u_builder.
205 * Uses @ref u_builder_roles_helper_open_system internally, a builder that uses
206 * the @ref u_builder should use this function for xrt_builder::open_system.
207 *
208 * When using this function the builder must have @ref u_builder and implement
209 * the @ref u_builder::open_system_static_roles function, see documentation for
210 * @ref u_builder_open_system_fn about requirements.
211 *
212 * @ingroup aux_util
213 */
216 cJSON *config,
217 struct xrt_prober *xp,
218 struct xrt_session_event_sink *broadcast,
219 struct xrt_system_devices **out_xsysd,
220 struct xrt_space_overseer **out_xso);
221
222
223#ifdef __cplusplus
224}
225#endif
xrt_result_t(* u_builder_open_system_fn)(struct xrt_builder *xb, cJSON *config, struct xrt_prober *xp, struct xrt_tracking_origin *origin, struct xrt_system_devices *xsysd, struct xrt_frame_context *xfctx, struct u_builder_roles_helper *ubrh)
Argument to u_builder_roles_helper_open_system and implemented by u_builder::open_system_static_roles...
Definition: u_builders.h:42
#define U_BUILDER_SEARCH_MAX
Max return of the number xrt_prober_device.
Definition: u_builders.h:29
void u_builder_create_space_overseer_legacy(struct xrt_session_event_sink *broadcast, struct xrt_device *head, struct xrt_device *left, struct xrt_device *right, struct xrt_device *gamepad, struct xrt_device **xdevs, uint32_t xdev_count, bool root_is_unbounded, bool per_app_local_spaces, struct xrt_space_overseer **out_xso)
Create a legacy space overseer, most builders probably want to have a more advanced setup then this,...
Definition: u_builders.c:159
xrt_result_t u_builder_roles_helper_open_system(struct xrt_builder *xb, cJSON *config, struct xrt_prober *xp, struct xrt_session_event_sink *broadcast, struct xrt_system_devices **out_xsysd, struct xrt_space_overseer **out_xso, u_builder_open_system_fn fn)
Helper to create a system devices that has static roles and a appropriate space overseer.
Definition: u_builders.c:211
void u_builder_search(struct xrt_prober *xp, struct xrt_prober_device *const *xpdevs, size_t xpdev_count, const struct u_builder_search_filter *filters, size_t filter_count, struct u_builder_search_results *results)
Find all of the xrt_prober_device that matches any in the given list of u_builder_search_filter filte...
Definition: u_builders.c:68
xrt_result_t u_builder_open_system_static_roles(struct xrt_builder *xb, cJSON *config, struct xrt_prober *xp, struct xrt_session_event_sink *broadcast, struct xrt_system_devices **out_xsysd, struct xrt_space_overseer **out_xso)
Implementation for xrt_builder::open_system to be used with u_builder.
Definition: u_builders.c:277
struct xrt_prober_device * u_builder_find_prober_device(struct xrt_prober_device *const *xpdevs, size_t xpdev_count, uint16_t vendor_id, uint16_t product_id, enum xrt_bus_type bus_type)
Find the first xrt_prober_device in the prober list.
Definition: u_builders.c:47
void u_builder_setup_tracking_origins(struct xrt_device *head, struct xrt_device *left, struct xrt_device *right, struct xrt_device *gamepad, struct xrt_vec3 *global_tracking_origin_offset)
Helper function for setting up tracking origins.
Definition: u_builders.c:106
enum xrt_result xrt_result_t
Result type used across Monado.
This small helper struct is for u_builder_roles_helper_open_system, lets a builder focus on opening d...
Definition: u_builders.h:84
A filter to match the against.
Definition: u_builders.h:56
Results of a search of devices.
Definition: u_builders.h:68
struct xrt_prober_device * xpdevs[(16)]
Out field of found xrt_prober_device.
Definition: u_builders.h:70
size_t xpdev_count
Number of found devices.
Definition: u_builders.h:73
This helper struct makes it easier to implement the builder interface, but it also comes with a set o...
Definition: u_builders.h:108
u_builder_open_system_fn open_system_static_roles
Argument to u_builder_roles_helper_open_system and implemented by u_builder::open_system_static_roles...
Definition: u_builders.h:115
struct xrt_builder base
Base for this struct.
Definition: u_builders.h:110
Sets up a collection of devices and builds a system, a setter upper.
Definition: xrt_prober.h:560
A single HMD or input device.
Definition: xrt_device.h:281
Object used to track all sinks and frame producers in a graph.
Definition: xrt_frame.h:108
A probed device, may or may not be opened.
Definition: xrt_prober.h:85
uint16_t product_id
USB/Bluetooth product ID (PID)
Definition: xrt_prober.h:94
uint16_t vendor_id
USB/Bluetooth vendor ID (VID)
Definition: xrt_prober.h:89
The main prober that probes and manages found but not opened HMD devices that are connected to the sy...
Definition: xrt_prober.h:132
Used internally from producers of events to push events into session, some sinks might multiplex even...
Definition: xrt_session.h:206
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:222
A tracking system or device origin.
Definition: xrt_tracking.h:71
A 3 element vector with single floats.
Definition: xrt_defines.h:273
Common interface to probe for devices.
xrt_bus_type
Bus type of a device.
Definition: xrt_prober.h:63
Header defining xrt space and space overseer.