The open source OpenXR runtime
xrt: Add system builders and update xrt_prober interface
Aka setter uppers.
+241
-3
+240
-3
src/xrt/include/xrt/xrt_prober.h
+240
-3
src/xrt/include/xrt/xrt_prober.h
···
33
33
struct xrt_prober_entry_lists;
34
34
struct xrt_auto_prober;
35
35
struct xrt_tracking_factory;
36
+
struct xrt_builder;
37
+
struct xrt_system_devices;
36
38
struct os_hid_device;
37
39
38
40
/*!
···
121
123
122
124
/*!
123
125
* Enumerate all connected devices, whether or not we have an associated
124
-
* driver.
126
+
* driver. Can not be called with the device list is locked
127
+
* @ref xrt_prober::lock_list and @ref xrt_prober::unlock_list.
128
+
*
129
+
* This function along with lock/unlock allows a @ref xrt_builder to
130
+
* re-probe the devices after having opened another device. A bit more
131
+
* detailed: It can get a list of devices, search it, open the enabling
132
+
* one, release the list, do a probe, get the list again and re-scan
133
+
* to detect any additional devices that may show up once the first
134
+
* device has been been started.
125
135
*
126
-
* @note Code consuming this interface should use
127
-
* xrt_prober_probe()
136
+
* @note Code consuming this interface should use xrt_prober_probe()
137
+
* @see xrt_prober::lock_list, xrt_prober::unlock_list
128
138
*/
129
139
int (*probe)(struct xrt_prober *xp);
130
140
131
141
/*!
142
+
* Locks the prober list of probed devices and returns it, while locked
143
+
* calling @ref xrt_prober::probe is forbidden. Not thread safe.
144
+
* See @ref xrt_prober::probe for more detailed expected usage.
145
+
*
146
+
* @note Code consuming this interface should use xrt_prober_lock_list()
147
+
* @see xrt_prober::probe, xrt_prober::unlock_list
148
+
*/
149
+
xrt_result_t (*lock_list)(struct xrt_prober *xp,
150
+
struct xrt_prober_device ***out_devices,
151
+
size_t *out_device_count);
152
+
153
+
/*!
154
+
* Unlocks the list, allowing for @ref xrt_prober::probe to be called.
155
+
* Takes a pointer to the list pointer and clears it. Not thread safe.
156
+
* See @ref xrt_prober::probe for more detailed expected usage.
157
+
*
158
+
* @note Code consuming this interface should use xrt_prober_unlock_list()
159
+
* @see xrt_prober::probe, xrt_prober::lock_list
160
+
*/
161
+
xrt_result_t (*unlock_list)(struct xrt_prober *xp, struct xrt_prober_device ***devices);
162
+
163
+
/*!
132
164
* Dump a listing of all devices found on the system to platform
133
165
* dependent output (stdout).
134
166
*
135
167
* @note Code consuming this interface should use xrt_prober_dump()
136
168
*/
137
169
int (*dump)(struct xrt_prober *xp);
170
+
171
+
/*!
172
+
* Create system devices.
173
+
*
174
+
* @param[in] xp Prober self parameter.
175
+
* @param[out] out_xsysd Return of system devices, the pointed pointer must be NULL.
176
+
*
177
+
* @note Code consuming this interface should use xrt_prober_create_system()
178
+
*/
179
+
xrt_result_t (*create_system)(struct xrt_prober *xp, struct xrt_system_devices **out_xsysd);
138
180
139
181
/*!
140
182
* Iterate through drivers (by ID and auto-probers) checking to see if
···
230
272
}
231
273
232
274
/*!
275
+
* @copydoc xrt_prober::lock_list
276
+
*
277
+
* Helper function for @ref xrt_prober::lock_list.
278
+
*
279
+
* @public @memberof xrt_prober
280
+
*/
281
+
static inline xrt_result_t
282
+
xrt_prober_lock_list(struct xrt_prober *xp, struct xrt_prober_device ***out_devices, size_t *out_device_count)
283
+
{
284
+
return xp->lock_list(xp, out_devices, out_device_count);
285
+
}
286
+
287
+
/*!
288
+
* @copydoc xrt_prober::unlock_list
289
+
*
290
+
* Helper function for @ref xrt_prober::unlock_list.
291
+
*
292
+
* @public @memberof xrt_prober
293
+
*/
294
+
static inline xrt_result_t
295
+
xrt_prober_unlock_list(struct xrt_prober *xp, struct xrt_prober_device ***devices)
296
+
{
297
+
return xp->unlock_list(xp, devices);
298
+
}
299
+
300
+
/*!
233
301
* @copydoc xrt_prober::dump
234
302
*
235
303
* Helper function for @ref xrt_prober::dump.
···
240
308
xrt_prober_dump(struct xrt_prober *xp)
241
309
{
242
310
return xp->dump(xp);
311
+
}
312
+
313
+
/*!
314
+
* @copydoc xrt_prober::create_system
315
+
*
316
+
* Helper function for @ref xrt_prober::create_system.
317
+
*
318
+
* @public @memberof xrt_prober
319
+
*/
320
+
static inline xrt_result_t
321
+
xrt_prober_create_system(struct xrt_prober *xp, struct xrt_system_devices **out_xsysd)
322
+
{
323
+
return xp->create_system(xp, out_xsysd);
243
324
}
244
325
245
326
/*!
···
370
451
371
452
/*
372
453
*
454
+
* Builder interface.
455
+
*
456
+
*/
457
+
458
+
/*!
459
+
* A estimate from a setter upper about how many devices they can open.
460
+
*
461
+
* @ingroup xrt_iface
462
+
*/
463
+
struct xrt_builder_estimate
464
+
{
465
+
struct
466
+
{
467
+
bool head;
468
+
bool left;
469
+
bool right;
470
+
bool dof6;
471
+
uint32_t extra_device_count;
472
+
} certain, maybe;
473
+
474
+
/*!
475
+
* A setter upper defined priority, mostly for vive vs survive.
476
+
*
477
+
* 0 normal priority, positive value higher, negative lower.
478
+
*/
479
+
int32_t priority;
480
+
};
481
+
482
+
/*!
483
+
* Function pointer type for creating a @ref xrt_builder.
484
+
*
485
+
* @ingroup xrt_iface
486
+
*/
487
+
typedef struct xrt_builder *(*xrt_builder_create_func_t)(void);
488
+
489
+
/*!
490
+
* Sets up a collection of devices and builds a system, a setter upper.
491
+
*
492
+
* @ingroup xrt_iface
493
+
*/
494
+
struct xrt_builder
495
+
{
496
+
//! Short identifier, like "vive", "north_star", "rgb_tracking".
497
+
const char *identifier;
498
+
499
+
//! "Localized" pretty name.
500
+
const char *name;
501
+
502
+
//! List of identifiers for drivers this setter-upper uses/supports.
503
+
const char **driver_identifiers;
504
+
505
+
//! Number of driver identifiers.
506
+
size_t driver_identifier_count;
507
+
508
+
//! Should this builder be excluded from automatic discovery.
509
+
bool exclude_from_automatic_discovery;
510
+
511
+
/*!
512
+
* From the devices found, estimate without opening the devices how
513
+
* good the system will be.
514
+
*
515
+
* @param[in] xb Builder self parameter.
516
+
* @param[in] xp Prober
517
+
* @param[in] config JSON config object if found for this setter upper.
518
+
* @param[out] out_estimate Estimate to be filled out.
519
+
*
520
+
* @note Code consuming this interface should use xrt_builder_estimate_system()
521
+
*/
522
+
xrt_result_t (*estimate_system)(struct xrt_builder *xb,
523
+
cJSON *config,
524
+
struct xrt_prober *xp,
525
+
struct xrt_builder_estimate *out_estimate);
526
+
527
+
/*!
528
+
* We are now committed to opening these devices.
529
+
*
530
+
* @param[in] xb Builder self parameter.
531
+
* @param[in] xp Prober
532
+
* @param[in] config JSON config object if found for this setter upper.
533
+
* @param[out] out_xsysd Return of system devices, the pointed pointer must be NULL.
534
+
*
535
+
* @note Code consuming this interface should use xrt_builder_open_system()
536
+
*/
537
+
xrt_result_t (*open_system)(struct xrt_builder *xb,
538
+
cJSON *config,
539
+
struct xrt_prober *xp,
540
+
struct xrt_system_devices **out_xsysd);
541
+
542
+
/*!
543
+
* Destroy this setter upper.
544
+
*
545
+
* @note Code consuming this interface should use xrt_builder_destroy()
546
+
*/
547
+
void (*destroy)(struct xrt_builder *xb);
548
+
};
549
+
550
+
/*!
551
+
* @copydoc xrt_builder::estimate_system
552
+
*
553
+
* Helper function for @ref xrt_builder::estimate_system.
554
+
*
555
+
* @public @memberof xrt_builder
556
+
*/
557
+
static inline xrt_result_t
558
+
xrt_builder_estimate_system(struct xrt_builder *xb,
559
+
cJSON *config,
560
+
struct xrt_prober *xp,
561
+
struct xrt_builder_estimate *estimate)
562
+
{
563
+
return xb->estimate_system(xb, config, xp, estimate);
564
+
}
565
+
566
+
/*!
567
+
* @copydoc xrt_builder::open_system
568
+
*
569
+
* Helper function for @ref xrt_builder::open_system.
570
+
*
571
+
* @public @memberof xrt_builder
572
+
*/
573
+
static inline xrt_result_t
574
+
xrt_builder_open_system(struct xrt_builder *xb,
575
+
cJSON *config,
576
+
struct xrt_prober *xp,
577
+
struct xrt_system_devices **out_xsysd)
578
+
{
579
+
return xb->open_system(xb, config, xp, out_xsysd);
580
+
}
581
+
582
+
/*!
583
+
* @copydoc xrt_builder::destroy
584
+
*
585
+
* Helper for calling through the function pointer: does a null check and sets
586
+
* xb_ptr to null if freed.
587
+
*
588
+
* @public @memberof xrt_builder
589
+
*/
590
+
static inline void
591
+
xrt_builder_destroy(struct xrt_builder **xb_ptr)
592
+
{
593
+
struct xrt_builder *xb = *xb_ptr;
594
+
if (xb == NULL) {
595
+
return;
596
+
}
597
+
598
+
xb->destroy(xb);
599
+
*xb_ptr = NULL;
600
+
}
601
+
602
+
603
+
/*
604
+
*
373
605
* Found device interface.
374
606
*
375
607
*/
···
504
736
*/
505
737
struct xrt_prober_entry_lists
506
738
{
739
+
/*!
740
+
* A null terminated list of @ref xrt_builder creation functions.
741
+
*/
742
+
xrt_builder_create_func_t *builders;
743
+
507
744
/*!
508
745
* A null terminated list of null terminated lists of
509
746
* @ref xrt_prober_entry.