The open source OpenXR runtime
xrt: Better documentation for revised system devices/roles interface
authored by
Ryan Pavlik
and committed by
Jakob Bornecrantz
51fa07cf
26a2221e
+99
-14
+99
-14
src/xrt/include/xrt/xrt_system.h
+99
-14
src/xrt/include/xrt/xrt_system.h
···
16
16
struct xrt_system_devices;
17
17
struct xrt_instance;
18
18
19
-
19
+
/*!
20
+
* Maximum number of devices simultaneously usable by an implementation of
21
+
* @ref xrt_system_devices
22
+
*
23
+
* @ingroup xrt_iface
24
+
*/
20
25
#define XRT_SYSTEM_MAX_DEVICES (32)
21
26
22
27
/*!
23
-
* Roles of the devices, negative index means unpopulated. When the devices
24
-
* change the caller will do the needed actions to handle a device changes, for
25
-
* the OpenXR state tracker this may include switching bound interaction profile
26
-
* and generating the events for such a change.
28
+
* Data associating a device index (in @ref xrt_system_devices::xdevs) with a
29
+
* given "role" for dynamic role switching.
30
+
*
31
+
* For each of the named roles, a negative value means unpopulated/not available.
32
+
*
33
+
* Populated by a call from the @ref xrt_system_devices interface.
34
+
*
35
+
* When the caller of @ref xrt_system_devices_get_roles sees a change (based on
36
+
* comparing @ref generation_id) the caller must do the needed actions to handle
37
+
* device changes. For example, for the OpenXR state tracker this may include
38
+
* rebinding, queuing a change to the current interaction profile, and queuing
39
+
* the events associated with such a change.
27
40
*
28
41
* @see xrt_system_devices
29
42
* @ingroup xrt_iface
···
31
44
struct xrt_system_roles
32
45
{
33
46
/*!
34
-
* Monotonically increasing generation counter, is increased when ever
35
-
* the roles is changed. Will always be greater then zero, this is to
47
+
* Monotonically increasing generation counter for the association
48
+
* between role and index.
49
+
*
50
+
* Increment whenever the roles are changed.
51
+
*
52
+
* All valid values are greater then zero; this is to
36
53
* make init easier where any cache can start at zero and be guaranteed
37
54
* to be replaced with a new @ref xrt_system_roles.
38
55
*/
39
56
uint64_t generation_id;
40
57
58
+
/*!
59
+
* Index in @ref xrt_system_devices::xdevs for the user's left
60
+
* controller/hand, or negative if none available.
61
+
*/
41
62
int32_t left;
63
+
64
+
/*!
65
+
* Index in @ref xrt_system_devices::xdevs for the user's right
66
+
* controller/hand, or negative if none available.
67
+
*/
42
68
int32_t right;
69
+
70
+
/*!
71
+
* Index in @ref xrt_system_devices::xdevs for the user's gamepad
72
+
* device, or negative if none available.
73
+
*/
43
74
int32_t gamepad;
44
75
};
45
76
46
77
/*!
47
-
* Guaranteed invalid content, not using designated initializers due to C++.
78
+
* Guaranteed invalid constant for @ref xrt_system_roles, not using designated
79
+
* initializers due to C++.
48
80
*
49
81
* @ingroup xrt_iface
82
+
* @relates xrt_system_roles
50
83
*/
51
84
#define XRT_SYSTEM_ROLES_INIT \
52
85
{ \
···
55
88
56
89
57
90
/*!
58
-
* A collection of @ref xrt_device, and the roles they have been assigned.
91
+
* A collection of @ref xrt_device, and an interface for identifying the roles
92
+
* they have been assigned.
59
93
*
60
94
* @see xrt_device, xrt_instance.
61
95
*/
62
96
struct xrt_system_devices
63
97
{
98
+
/*!
99
+
* All devices known in the system.
100
+
*
101
+
* This is conventionally considered the "owning" reference to the devices.
102
+
* Valid entries are contiguous.
103
+
*/
64
104
struct xrt_device *xdevs[XRT_SYSTEM_MAX_DEVICES];
105
+
106
+
/*!
107
+
* The number of elements in @ref xdevs that are valid.
108
+
*/
65
109
size_t xdev_count;
66
110
111
+
/*!
112
+
* Observing pointers for devices in some static (unchangeable) roles.
113
+
*
114
+
* All pointers in this struct must also exist in @ref xdevs. The
115
+
* association between a member of this struct and a given device
116
+
* cannot change during runtime.
117
+
*/
67
118
struct
68
119
{
120
+
/*!
121
+
* An observing pointer to the device serving as the "head"
122
+
* (and HMD).
123
+
*
124
+
* Required.
125
+
*/
69
126
struct xrt_device *head;
127
+
128
+
/*!
129
+
* An observing pointer to the device providing eye tracking
130
+
* (optional).
131
+
*/
70
132
struct xrt_device *eyes;
133
+
134
+
/*!
135
+
* Devices providing optical (or otherwise more directly
136
+
* measured than from controller estimation) hand tracking.
137
+
*/
71
138
struct
72
139
{
140
+
141
+
/*!
142
+
* An observing pointer to the device providing hand
143
+
* tracking for the left hand (optional).
144
+
*
145
+
* Currently this is used for both optical and
146
+
* controller driven hand-tracking.
147
+
*/
73
148
struct xrt_device *left;
149
+
150
+
/*!
151
+
* An observing pointer to the device providing hand
152
+
* tracking for the right hand (optional).
153
+
*
154
+
* Currently this is used for both optical and
155
+
* controller driven hand-tracking.
156
+
*/
74
157
struct xrt_device *right;
75
158
} hand_tracking;
76
159
} static_roles;
···
80
163
* Function to get the dynamic input device roles from this system
81
164
* devices, see @ref xrt_system_roles for more information.
82
165
*
83
-
* @param[in] xsysd Pointer to self
84
-
* @param[out] roles Pointer to xrt_system_roles
166
+
* @param xsysd Pointer to self
167
+
* @param[out] out_roles Pointer to xrt_system_roles
85
168
*/
86
169
xrt_result_t (*get_roles)(struct xrt_system_devices *xsysd, struct xrt_system_roles *out_roles);
87
170
88
171
/*!
89
172
* Destroy all the devices that are owned by this system devices.
90
173
*
91
-
* Code consuming this interface should use xrt_system_devices_destroy.
174
+
* Code consuming this interface should use @ref xrt_system_devices_destroy.
175
+
*
176
+
* @param xsysd Pointer to self
92
177
*/
93
178
void (*destroy)(struct xrt_system_devices *xsysd);
94
179
};
···
111
196
*
112
197
* @param[in,out] xsysd_ptr A pointer to the xrt_system_devices struct pointer.
113
198
*
114
-
* Will destroy the system devices if *xsysd_ptr is not NULL. Will then set
115
-
* *xsysd_ptr to NULL.
199
+
* Will destroy the system devices if `*xsysd_ptr` is not NULL. Will then set
200
+
* `*xsysd_ptr` to NULL.
116
201
*
117
202
* @public @memberof xrt_system_devices
118
203
*/