The open source OpenXR runtime
xrt: Add xrt_space interface
+279
+279
src/xrt/include/xrt/xrt_space.h
+279
src/xrt/include/xrt/xrt_space.h
···
1
+
// Copyright 2019-2023, Collabora, Ltd.
2
+
// SPDX-License-Identifier: BSL-1.0
3
+
/*!
4
+
* @file
5
+
* @brief Header defining xrt space and space overseer.
6
+
* @author Jakob Bornecrantz <jakob@collabora.com>
7
+
* @ingroup xrt_iface
8
+
*/
9
+
10
+
#pragma once
11
+
12
+
#include "xrt/xrt_defines.h"
13
+
14
+
#ifdef __cplusplus
15
+
extern "C" {
16
+
#endif
17
+
18
+
19
+
struct xrt_device;
20
+
21
+
/*!
22
+
* A space very similar to a OpenXR XrSpace but not a full one-to-one mapping,
23
+
* but used to power XrSpace.
24
+
*
25
+
* @see @ref xrt_space_overseer
26
+
* @see @ref design-spaces
27
+
* @ingroup xrt_iface
28
+
*/
29
+
struct xrt_space
30
+
{
31
+
/*!
32
+
* Reference helper.
33
+
*/
34
+
struct xrt_reference reference;
35
+
36
+
/*!
37
+
* Destroy function.
38
+
*/
39
+
void (*destroy)(struct xrt_space *xs);
40
+
};
41
+
42
+
/*!
43
+
* Update the reference counts on space(s).
44
+
*
45
+
* @param[in,out] dst Pointer to a object reference: if the object reference is
46
+
* non-null will decrement its counter. The reference that
47
+
* @p dst points to will be set to @p src.
48
+
* @param[in] src New object for @p dst to refer to (may be null).
49
+
* If non-null, will have its refcount increased.
50
+
* @ingroup xrt_iface
51
+
* @relates xrt_space
52
+
*/
53
+
static inline void
54
+
xrt_space_reference(struct xrt_space **dst, struct xrt_space *src)
55
+
{
56
+
struct xrt_space *old_dst = *dst;
57
+
58
+
if (old_dst == src) {
59
+
return;
60
+
}
61
+
62
+
if (src) {
63
+
xrt_reference_inc(&src->reference);
64
+
}
65
+
66
+
*dst = src;
67
+
68
+
if (old_dst) {
69
+
if (xrt_reference_dec(&old_dst->reference)) {
70
+
old_dst->destroy(old_dst);
71
+
}
72
+
}
73
+
}
74
+
75
+
/*!
76
+
* Object that oversees and manages spaces, one created for each XR system.
77
+
*
78
+
* The space overseer is used by the state tracker to query the poses of spaces
79
+
* and devices in that space system. While the default implementation
80
+
* @ref u_space_overseer implements the spaces as a graph of relatable spaces,
81
+
* that is a implementation detail (the interface also lends itself to that
82
+
* since bases have parents). As such the graph is not exposed in this interface
83
+
* and spaces are technically free floating.
84
+
*
85
+
* One advantage of the free floating nature is that an overseer implementation
86
+
* has much greater flexibility in configuring the graph to fit the current XR
87
+
* system the best, it also have freedom to reconfigure the graph at runtime
88
+
* should that be needed. Since any potential graph isn't exposed there is no
89
+
* need to synchronise it across the app process and the service process.
90
+
*
91
+
* @see @ref design-spaces
92
+
* @ingroup xrt_iface
93
+
*/
94
+
struct xrt_space_overseer
95
+
{
96
+
struct
97
+
{
98
+
struct xrt_space *root; //!< Root space, always available
99
+
struct xrt_space *view; //!< View space, may be null (in very rare cases).
100
+
struct xrt_space *local; //!< Local space, may be null (in very rare cases).
101
+
struct xrt_space *stage; //!< Stage space, may be null.
102
+
struct xrt_space *unbounded; //!< Unbounded space, only here for slam trackers.
103
+
104
+
/*!
105
+
* Semantic spaces to be mapped to OpenXR spaces.
106
+
*/
107
+
} semantic;
108
+
109
+
/*!
110
+
* Create a space with a fixed offset to the parent space.
111
+
*
112
+
* @param[in] xso Owning space overseer.
113
+
* @param[in] parent The parent space for the new space.
114
+
* @param[in] offset Offset to the space.
115
+
* @param[out] out_space The newly created space.
116
+
*/
117
+
xrt_result_t (*create_offset_space)(struct xrt_space_overseer *xso,
118
+
struct xrt_space *parent,
119
+
const struct xrt_pose *offset,
120
+
struct xrt_space **out_space);
121
+
122
+
/*!
123
+
* Create a space that wraps a device input pose, implicitly make the
124
+
* device's tracking space the returned space parent.
125
+
*
126
+
* @param[in] xso Owning space overseer.
127
+
* @param[in] xdev Device to get the pose from.
128
+
* @param[in] name Name of the pose input.
129
+
* @param[out] out_space The newly created space.
130
+
*/
131
+
xrt_result_t (*create_pose_space)(struct xrt_space_overseer *xso,
132
+
struct xrt_device *xdev,
133
+
enum xrt_input_name name,
134
+
struct xrt_space **out_space);
135
+
136
+
/*!
137
+
* Locate a space in the base space.
138
+
*
139
+
* @see xrt_device::get_tracked_pose.
140
+
*
141
+
* @param[in] xso Owning space overseer.
142
+
* @param[in] base_space The space that we want the pose in.
143
+
* @param[in] base_offset Offset if any to the base space.
144
+
* @param[in] at_timestamp_ns At which time.
145
+
* @param[in] space The space to be located.
146
+
* @param[in] offset Offset if any to the located space.
147
+
* @param[out] out_relation Resulting pose.
148
+
*/
149
+
xrt_result_t (*locate_space)(struct xrt_space_overseer *xso,
150
+
struct xrt_space *base_space,
151
+
const struct xrt_pose *base_offset,
152
+
uint64_t at_timestamp_ns,
153
+
struct xrt_space *space,
154
+
const struct xrt_pose *offset,
155
+
struct xrt_space_relation *out_relation);
156
+
157
+
/*!
158
+
* Locate a the origin of the tracking space of a device, this is not
159
+
* the same as the device position. In other words, what is the position
160
+
* of the space that the device is in, and which it returns its poses
161
+
* in. Needed to use @ref xrt_device::get_view_poses and
162
+
* @ref xrt_device::get_hand_tracking.
163
+
*
164
+
* @see xrt_device::get_tracked_pose.
165
+
*
166
+
* @param[in] xso Owning space overseer.
167
+
* @param[in] base_space The space that we want the pose in.
168
+
* @param[in] base_offset Offset if any to the base space.
169
+
* @param[in] at_timestamp_ns At which time.
170
+
* @param[in] xdev Device to get the pose from.
171
+
* @param[out] out_relation Resulting pose.
172
+
*/
173
+
xrt_result_t (*locate_device)(struct xrt_space_overseer *xso,
174
+
struct xrt_space *base_space,
175
+
const struct xrt_pose *base_offset,
176
+
uint64_t at_timestamp_ns,
177
+
struct xrt_device *xdev,
178
+
struct xrt_space_relation *out_relation);
179
+
180
+
/*!
181
+
* Destroy function.
182
+
*
183
+
* @param xso The space overseer.
184
+
*/
185
+
void (*destroy)(struct xrt_space_overseer *xs);
186
+
};
187
+
188
+
/*!
189
+
* @copydoc xrt_space_overseer::create_offset_space
190
+
*
191
+
* Helper for calling through the function pointer.
192
+
*
193
+
* @public @memberof xrt_space_overseer
194
+
*/
195
+
static inline xrt_result_t
196
+
xrt_space_overseer_create_offset_space(struct xrt_space_overseer *xso,
197
+
struct xrt_space *parent,
198
+
const struct xrt_pose *offset,
199
+
struct xrt_space **out_space)
200
+
{
201
+
return xso->create_offset_space(xso, parent, offset, out_space);
202
+
}
203
+
204
+
/*!
205
+
* @copydoc xrt_space_overseer::create_pose_space
206
+
*
207
+
* Helper for calling through the function pointer.
208
+
*
209
+
* @public @memberof xrt_space_overseer
210
+
*/
211
+
static inline xrt_result_t
212
+
xrt_space_overseer_create_pose_space(struct xrt_space_overseer *xso,
213
+
struct xrt_device *xdev,
214
+
enum xrt_input_name name,
215
+
struct xrt_space **out_space)
216
+
{
217
+
return xso->create_pose_space(xso, xdev, name, out_space);
218
+
}
219
+
220
+
/*!
221
+
* @copydoc xrt_space_overseer::locate_space
222
+
*
223
+
* Helper for calling through the function pointer.
224
+
*
225
+
* @public @memberof xrt_space_overseer
226
+
*/
227
+
static inline xrt_result_t
228
+
xrt_space_overseer_locate_space(struct xrt_space_overseer *xso,
229
+
struct xrt_space *base_space,
230
+
const struct xrt_pose *base_offset,
231
+
uint64_t at_timestamp_ns,
232
+
struct xrt_space *space,
233
+
const struct xrt_pose *offset,
234
+
struct xrt_space_relation *out_relation)
235
+
{
236
+
return xso->locate_space(xso, base_space, base_offset, at_timestamp_ns, space, offset, out_relation);
237
+
}
238
+
239
+
/*!
240
+
* @copydoc xrt_space_overseer::locate_device
241
+
*
242
+
* Helper for calling through the function pointer.
243
+
*
244
+
* @public @memberof xrt_space_overseer
245
+
*/
246
+
static inline xrt_result_t
247
+
xrt_space_overseer_locate_device(struct xrt_space_overseer *xso,
248
+
struct xrt_space *base_space,
249
+
const struct xrt_pose *base_offset,
250
+
uint64_t at_timestamp_ns,
251
+
struct xrt_device *xdev,
252
+
struct xrt_space_relation *out_relation)
253
+
{
254
+
return xso->locate_device(xso, base_space, base_offset, at_timestamp_ns, xdev, out_relation);
255
+
}
256
+
257
+
/*!
258
+
* Helper for calling through the function pointer: does a null check and sets
259
+
* xc_ptr to null if freed.
260
+
*
261
+
* @see xrt_space_overseer::destroy
262
+
* @public @memberof xrt_space_overseer
263
+
*/
264
+
static inline void
265
+
xrt_space_overseer_destroy(struct xrt_space_overseer **xso_ptr)
266
+
{
267
+
struct xrt_space_overseer *xso = *xso_ptr;
268
+
if (xso == NULL) {
269
+
return;
270
+
}
271
+
272
+
xso->destroy(xso);
273
+
*xso_ptr = NULL;
274
+
}
275
+
276
+
277
+
#ifdef __cplusplus
278
+
}
279
+
#endif