Monado OpenXR Runtime
xrt_device.h
Go to the documentation of this file.
1// Copyright 2019-2024, Collabora, Ltd.
2// SPDX-License-Identifier: BSL-1.0
3/*!
4 * @file
5 * @brief Header defining an xrt display or controller device.
6 * @author Jakob Bornecrantz <jakob@collabora.com>
7 * @author Moshi Turner <moshiturner@protonmail.com>
8 * @author Korcan Hussein <korcan.hussein@collabora.com>
9 * @ingroup xrt_iface
10 */
11
12#pragma once
13
14#include "xrt/xrt_defines.h"
17#include "xrt/xrt_limits.h"
18
19#include <stdalign.h>
20
21#ifdef __cplusplus
22extern "C" {
23#endif
24
25struct xrt_tracking;
26
27#define XRT_DEVICE_NAME_LEN 256
28
29
30/*!
31 * A per-lens/display view information.
32 *
33 * @ingroup xrt_iface
34 */
36{
37 /*!
38 * @brief Viewport position on the screen.
39 *
40 * In absolute screen coordinates on an unrotated display, like the
41 * HMD presents it to the OS.
42 *
43 * This field is only used by @ref comp to setup the device rendering.
44 *
45 * If the view is being rotated by xrt_view.rot 90° right in the
46 * distortion shader then `display.w_pixels == viewport.h_pixels` and
47 * `display.h_pixels == viewport.w_pixels`.
48 */
49 struct
50 {
51 uint32_t x_pixels;
52 uint32_t y_pixels;
53 uint32_t w_pixels;
54 uint32_t h_pixels;
56
57 /*!
58 * @brief Physical properties of this display (or the part of a display
59 * that covers this view).
60 *
61 * Not in absolute screen coordinates but like the clients see them i.e.
62 * after rotation is applied by xrt_view::rot.
63 * This field is only used for the clients' swapchain setup.
64 *
65 * The xrt_view::display::w_pixels and xrt_view::display::h_pixels
66 * become the recommended image size for this view, after being scaled
67 * by the debug environment variable `XRT_COMPOSITOR_SCALE_PERCENTAGE`.
68 */
69 struct
70 {
71 uint32_t w_pixels;
72 uint32_t h_pixels;
74
75 /*!
76 * @brief Rotation 2d matrix used to rotate the position of the output
77 * of the distortion shaders onto the screen.
78 *
79 * If the distortion shader is based on a mesh, then this matrix rotates
80 * the vertex positions.
81 */
83};
84
85/*!
86 * All of the device components that deals with interfacing to a users head.
87 *
88 * HMD is probably a bad name for the future but for now will have to do.
89 *
90 * @ingroup xrt_iface
91 */
93{
94 /*!
95 * @brief The hmd screen as an unrotated display, like the HMD presents
96 * it to the OS.
97 *
98 * This field is used by @ref comp to setup the extended mode window.
99 */
100 struct
101 {
102 int w_pixels;
103 int h_pixels;
104 //! Nominal frame interval
107
108 /*!
109 * Display information.
110 *
111 * For now hardcoded display to two.
112 */
113 struct xrt_view views[XRT_MAX_VIEWS];
114
115 size_t view_count;
116 /*!
117 * Array of supported blend modes.
118 */
119 enum xrt_blend_mode blend_modes[XRT_MAX_DEVICE_BLEND_MODES];
120 size_t blend_mode_count;
121
122 /*!
123 * Distortion information.
124 */
125 struct
126 {
127 //! Supported distortion models, a bitfield.
129 //! Preferred disortion model, single value.
131
132 struct
133 {
134 //! Data.
135 float *vertices;
136 //! Number of vertices.
137 uint32_t vertex_count;
138 //! Stride of vertices
139 uint32_t stride;
140 //! 1 or 3 for (chromatic aberration).
142
143 //! Indices, for triangle strip.
145 //! Number of indices for the triangle strips (one per view).
146 uint32_t index_counts[XRT_MAX_VIEWS];
147 //! Offsets for the indices (one offset per view).
148 uint32_t index_offsets[XRT_MAX_VIEWS];
149 //! Total number of elements in mesh::indices array.
151 } mesh;
152
153 //! distortion is subject to the field of view
154 struct xrt_fov fov[XRT_MAX_VIEWS];
156};
157
158/*!
159 * A single named input, that sits on a @ref xrt_device.
160 *
161 * @ingroup xrt_iface
162 */
164{
165 //! Is this input active.
166 bool active;
167
168 //! alignas for 32 bit client support, see @ref ipc-design
169 alignas(8) int64_t timestamp;
170
171 enum xrt_input_name name;
172
173 union xrt_input_value value;
174};
175
176/*!
177 * A single named output, that sits on a @ref xrt_device.
178 *
179 * @ingroup xrt_iface
180 */
182{
183 enum xrt_output_name name;
184};
185
186
187/*!
188 * A binding pair, going @p from a binding point to a @p device input.
189 *
190 * @ingroup xrt_iface
191 */
193{
194 enum xrt_input_name from; //!< From which name.
195 enum xrt_input_name device; //!< To input on the device.
196};
197
198/*!
199 * A binding pair, going @p from a binding point to a @p device output.
200 *
201 * @ingroup xrt_iface
202 */
204{
205 enum xrt_output_name from; //!< From which name.
206 enum xrt_output_name device; //!< To output on the device.
207};
208
209/*!
210 * A binding profile, has lists of binding pairs to goes from device in @p name
211 * to the device it hangs off on.
212 *
213 * @ingroup xrt_iface
214 */
216{
217 //! Device this binding emulates.
219
220 struct xrt_binding_input_pair *inputs;
221 size_t input_count;
222 struct xrt_binding_output_pair *outputs;
223 size_t output_count;
224};
225
226/*!
227 * Higher level features for devices.
228 */
230{
231 XRT_DEVICE_FEATURE_HAND_TRACKING_LEFT = 0,
232 XRT_DEVICE_FEATURE_HAND_TRACKING_RIGHT,
233 XRT_DEVICE_FEATURE_EYE_TRACKING,
234 XRT_DEVICE_FEATURE_MAX_ENUM,
235};
236
237/*!
238 * Output limits of a particular device
239 */
241{
242 //! The sample rate of the device's haptic PCM support, 0 if haptic PCM is not supported.
244};
245
246/*!
247 * @interface xrt_device
248 *
249 * A single HMD or input device.
250 *
251 * @ingroup xrt_iface
252 */
254{
255 //! Enum identifier of the device.
257 enum xrt_device_type device_type;
258
259 //! A string describing the device.
260 char str[XRT_DEVICE_NAME_LEN];
261
262 //! A unique identifier. Persistent across configurations, if possible.
263 char serial[XRT_DEVICE_NAME_LEN];
264
265 //! Null if this device does not interface with the users head.
267
268 //! Always set, pointing to the tracking system for this device.
270
271 //! Number of bindings in xrt_device::binding_profiles
273 // Array of alternative binding profiles.
274 struct xrt_binding_profile *binding_profiles;
275
276 //! Number of inputs.
278 //! Array of input structs.
280
281 //! Number of outputs.
283 //! Array of output structs.
285
286 bool orientation_tracking_supported;
287 bool position_tracking_supported;
288 bool hand_tracking_supported;
289 bool eye_gaze_supported;
290 bool force_feedback_supported;
291 bool ref_space_usage_supported;
292 bool form_factor_check_supported;
293 bool stage_supported;
294 bool face_tracking_supported;
295 bool body_tracking_supported;
296 bool battery_status_supported;
297 bool planes_supported;
298 enum xrt_plane_detection_capability_flags_ext plane_capability_flags;
299
300 /*
301 *
302 * Functions.
303 *
304 */
305
306 /*!
307 * Update any attached inputs.
308 *
309 * @param[in] xdev The device.
310 */
312
313 /*!
314 * @brief Get relationship of a tracked device to the tracking origin
315 * space as the base space.
316 *
317 * It is the responsibility of the device driver to do any prediction,
318 * there are helper functions available for this.
319 *
320 * The timestamps are system monotonic timestamps, such as returned by
321 * os_monotonic_get_ns().
322 *
323 * @param[in] xdev The device.
324 * @param[in] name Some devices may have multiple poses on
325 * them, select the one using this field. For
326 * HMDs use @p XRT_INPUT_GENERIC_HEAD_POSE.
327 * For Unbounded Reference Space you can use
328 * @p XRT_INPUT_GENERIC_UNBOUNDED_SPACE_POSE
329 * to get the origin of that space.
330 * @param[in] at_timestamp_ns If the device can predict or has a history
331 * of positions, this is when the caller
332 * wants the pose to be from.
333 * @param[out] out_relation The relation read from the device.
334 *
335 * @see xrt_input_name
336 */
338 enum xrt_input_name name,
339 int64_t at_timestamp_ns,
340 struct xrt_space_relation *out_relation);
341
342 /*!
343 * @brief Get relationship of hand joints to the tracking origin space as
344 * the base space.
345 *
346 * It is the responsibility of the device driver to either do prediction
347 * or return joints from a previous time and write that time out to
348 * @p out_timestamp_ns.
349 *
350 * The timestamps are system monotonic timestamps, such as returned by
351 * os_monotonic_get_ns().
352 *
353 * @param[in] xdev The device.
354 * @param[in] name Some devices may have multiple poses on
355 * them, select the one using this field. For
356 * hand tracking use @p XRT_INPUT_GENERIC_HAND_TRACKING_DEFAULT_SET.
357 * @param[in] desired_timestamp_ns If the device can predict or has a history
358 * of positions, this is when the caller
359 * wants the pose to be from.
360 * @param[out] out_value The hand joint data read from the device.
361 * @param[out] out_timestamp_ns The timestamp of the data being returned.
362 *
363 * @see xrt_input_name
364 */
365 void (*get_hand_tracking)(struct xrt_device *xdev,
366 enum xrt_input_name name,
367 int64_t desired_timestamp_ns,
368 struct xrt_hand_joint_set *out_value,
369 int64_t *out_timestamp_ns);
370
371 /*!
372 * @brief Get the requested blend shape properties & weights for a face tracker
373 *
374 * @param[in] xdev The device.
375 * @param[in] facial_expression_type The facial expression data type (XR_FB_face_tracking,
376 * XR_HTC_facial_tracking, etc).
377 * @param[in] at_timestamp_ns Timestamp to be optionally used for prediction/history. For OXR extensions
378 * that do not pass a timestamp, the current timestamp is used.
379 * @param[in] out_value Set of requested expression weights & blend shape properties.
380 *
381 * @see xrt_input_name
382 */
384 enum xrt_input_name facial_expression_type,
385 int64_t at_timestamp_ns,
386 struct xrt_facial_expression_set *out_value);
387
388 /*!
389 * @brief Get the body skeleton in T-pose, used to query the skeleton hierarchy, scale, proportions etc
390 *
391 * @param[in] xdev The device.
392 * @param[in] body_tracking_type The body joint set type (XR_FB_body_tracking,
393 * XR_META_body_tracking_full_body, etc).
394 * @param[in] out_value The body skeleton hierarchy/properties.
395 *
396 * @see xrt_input_name
397 */
399 enum xrt_input_name body_tracking_type,
400 struct xrt_body_skeleton *out_value);
401
402 /*!
403 * @brief Get the joint locations for a body tracker
404 *
405 * @param[in] xdev The device.
406 * @param[in] body_tracking_type The body joint set type (XR_FB_body_tracking,
407 * XR_META_body_tracking_full_body, etc).
408 * @param[in] desired_timestamp_ns If the device can predict or has a history
409 * of locations, this is when the caller
410 * @param[in] out_value Set of body joint locations & properties.
411 *
412 * @see xrt_input_name
413 */
415 enum xrt_input_name body_tracking_type,
416 int64_t desired_timestamp_ns,
417 struct xrt_body_joint_set *out_value);
418
419 /*!
420 * Set a output value.
421 *
422 * @param[in] xdev The device.
423 * @param[in] name The output component name to set.
424 * @param[in] value The value to set the output to.
425 * @see xrt_output_name
426 */
427 void (*set_output)(struct xrt_device *xdev, enum xrt_output_name name, const struct xrt_output_value *value);
428
429 /*!
430 * Gets limits of this devices outputs.
431 *
432 * @param[in] xdev The device.
433 * @param[out] limits The returned limits.
434 */
436
437 /*!
438 * Begin a plane detection request
439 *
440 * @param[in] xdev The device.
441 * @param[in] begin_info The query specifying what type of planes are requested.
442 * @param[in] plane_detection_id The id for a previous plane detection request to be replaced or 0.
443 * @param[out] out_plane_detection_id The id of the new plane detection request generated by the xdev.
444 * @return generally XRT_SUCCESS, except for internal runtime failures.
445 */
447 const struct xrt_plane_detector_begin_info_ext *begin_info,
448 uint64_t plane_detection_id,
449 uint64_t *out_plane_detection_id);
450
451 /*!
452 * Destroy internal resources associated with plane_detector_id.
453 *
454 * @param[in] xdev The device.
455 * @param[in] plane_detection_id An id generated by the xdev.
456 * @return generally XRT_SUCCESS, except for internal runtime failures.
457 */
458 enum xrt_result (*destroy_plane_detection_ext)(struct xrt_device *xdev, uint64_t plane_detection_id);
459
460 /*!
461 * Get the state of a plane detection request.
462 *
463 * @param[in] xdev The device.
464 * @param[in] plane_detector_id An id generated by the xdev.
465 * @param[out] out_state The state of the plane detection.
466 * @return generally XRT_SUCCESS, except for internal runtime failures.
467 */
469 uint64_t plane_detection_id,
470 enum xrt_plane_detector_state_ext *out_state);
471
472 /*!
473 * Get results of a plane detection request.
474 *
475 * @param[in] xdev The device.
476 * @param[in] plane_detector_id An id generated by the xdev.
477 * @param[out] detections The detected planes, if any.
478 * @return generally XRT_SUCCESS, except for internal runtime failures.
479 */
481 uint64_t plane_detection_id,
482 struct xrt_plane_detections_ext *out_detections);
483
484 /*!
485 * @brief Get the per-view pose in relation to the view space.
486 *
487 * On most devices with coplanar displays and no built-in eye tracking
488 * or IPD sensing, this just calls a helper to process the provided
489 * eye relation, but this may also handle canted displays as well as
490 * eye tracking.
491 *
492 * Incorporates a call to xrt_device::get_tracked_pose or a wrapper for it
493 *
494 * @param[in] xdev The device.
495 * @param[in] default_eye_relation
496 * The interpupillary relation as a 3D position.
497 * Most simple stereo devices would just want to
498 * set `out_pose->position.[x|y|z] = ipd.[x|y|z]
499 * / 2.0f` and adjust for left vs right view.
500 * Not to be confused with IPD that is absolute
501 * distance, this is a full 3D translation
502 * If a device has a more accurate/dynamic way of
503 * knowing the eye relation, it may ignore this
504 * input.
505 * @param[in] at_timestamp_ns This is when the caller wants the poses and FOVs to be from.
506 * @param[in] view_count Number of views.
507 * @param[out] out_head_relation
508 * The head pose in the device tracking space.
509 * Combine with @p out_poses to get the views in
510 * device tracking space.
511 * @param[out] out_fovs An array (of size @p view_count ) to populate
512 * with the device-suggested fields of view.
513 * @param[out] out_poses An array (of size @p view_count ) to populate
514 * with view output poses in head space. When
515 * implementing, be sure to also set orientation:
516 * most likely identity orientation unless you
517 * have canted screens.
518 * (Caution: Even if you have eye tracking, you
519 * won't use eye orientation here!)
520 */
521 void (*get_view_poses)(struct xrt_device *xdev,
522 const struct xrt_vec3 *default_eye_relation,
523 int64_t at_timestamp_ns,
524 uint32_t view_count,
525 struct xrt_space_relation *out_head_relation,
526 struct xrt_fov *out_fovs,
527 struct xrt_pose *out_poses);
528
529 /**
530 * Compute the distortion at a single point.
531 *
532 * The input is @p u @p v in screen/output space (that is, predistorted), you are to compute and return the u,v
533 * coordinates to sample the render texture. The compositor will step through a range of u,v parameters to build
534 * the lookup (vertex attribute or distortion texture) used to pre-distort the image as required by the device's
535 * optics.
536 *
537 * @param xdev the device
538 * @param view the view index
539 * @param u horizontal texture coordinate
540 * @param v vertical texture coordinate
541 * @param[out] out_result corresponding u,v pairs for all three color channels.
542 */
544 struct xrt_device *xdev, uint32_t view, float u, float v, struct xrt_uv_triplet *out_result);
545
546 /*!
547 * Get the visibility mask for this device.
548 *
549 * @param[in] xdev The device.
550 * @param[in] type The type of visibility mask.
551 * @param[in] view_index The index of the view to get the mask for.
552 * @param[out] out_mask Output mask, caller must free.
553 */
555 enum xrt_visibility_mask_type type,
556 uint32_t view_index,
557 struct xrt_visibility_mask **out_mask);
558
559 /*!
560 * Called by the @ref xrt_space_overseer when a reference space that is
561 * implemented by this device is first used, or when the last usage of
562 * the reference space stops.
563 *
564 * What is provided is both the @ref xrt_reference_space_type that
565 * triggered the usage change and the @ref xrt_input_name (if any) that
566 * is used to drive the space.
567 *
568 * @see xrt_space_overseer_ref_space_inc
569 * @see xrt_space_overseer_ref_space_dec
570 * @see xrt_input_name
571 * @see xrt_reference_space_type
572 */
574 enum xrt_reference_space_type type,
575 enum xrt_input_name name,
576 bool used);
577
578 /*!
579 * @brief Check if given form factor is available or not.
580 *
581 * This should only be used in HMD device, if the device driver supports form factor check.
582 *
583 * @param[in] xdev The device.
584 * @param[in] form_factor Form factor to check.
585 *
586 * @return true if given form factor is available; otherwise false.
587 */
588 bool (*is_form_factor_available)(struct xrt_device *xdev, enum xrt_form_factor form_factor);
589
590 /*!
591 * @brief Get battery status information.
592 *
593 * @param[in] xdev The device.
594 * @param[out] out_present Whether battery status information exist for this device.
595 * @param[out] out_charging Whether the device's battery is being charged.
596 * @param[out] out_charge Battery charge as a value between 0 and 1.
597 */
599 bool *out_present,
600 bool *out_charging,
601 float *out_charge);
602
603 /*!
604 * Enable the feature for this device.
605 *
606 * @param[in] xdev The device.
607 * @param[in] type The type of device feature.
608 */
610
611 /*!
612 * Disable the feature for this device.
613 *
614 * @param[in] xdev The device.
615 * @param[in] type The type of device feature.
616 */
618
619 /*!
620 * Destroy device.
621 */
622 void (*destroy)(struct xrt_device *xdev);
623
624 // Add new functions above destroy.
625};
626
627/*!
628 * Helper function for @ref xrt_device::update_inputs.
629 *
630 * @copydoc xrt_device::update_inputs
631 *
632 * @public @memberof xrt_device
633 */
634static inline xrt_result_t
636{
637 return xdev->update_inputs(xdev);
638}
639
640/*!
641 * Helper function for @ref xrt_device::get_tracked_pose.
642 *
643 * @copydoc xrt_device::get_tracked_pose
644 *
645 * @public @memberof xrt_device
646 */
647static inline xrt_result_t
649 enum xrt_input_name name,
650 int64_t at_timestamp_ns,
651 struct xrt_space_relation *out_relation)
652{
653 return xdev->get_tracked_pose(xdev, name, at_timestamp_ns, out_relation);
654}
655
656/*!
657 * Helper function for @ref xrt_device::get_hand_tracking.
658 *
659 * @copydoc xrt_device::get_hand_tracking
660 *
661 * @public @memberof xrt_device
662 */
663static inline void
665 enum xrt_input_name name,
666 int64_t desired_timestamp_ns,
667 struct xrt_hand_joint_set *out_value,
668 int64_t *out_timestamp_ns)
669{
670 xdev->get_hand_tracking(xdev, name, desired_timestamp_ns, out_value, out_timestamp_ns);
671}
672
673/*!
674 * Helper function for @ref xrt_device::get_face_tracking.
675 *
676 * @copydoc xrt_device::get_face_tracking
677 *
678 * @public @memberof xrt_device
679 */
680static inline xrt_result_t
682 enum xrt_input_name facial_expression_type,
683 int64_t at_timestamp_ns,
684 struct xrt_facial_expression_set *out_value)
685{
686 return xdev->get_face_tracking(xdev, facial_expression_type, at_timestamp_ns, out_value);
687}
688
689/*!
690 * Helper function for @ref xrt_device::get_body_skeleton.
691 *
692 * @copydoc xrt_device::get_body_skeleton
693 *
694 * @public @memberof xrt_device
695 */
696static inline xrt_result_t
698 enum xrt_input_name body_tracking_type,
699 struct xrt_body_skeleton *out_value)
700{
701 return xdev->get_body_skeleton(xdev, body_tracking_type, out_value);
702}
703
704/*!
705 * Helper function for @ref xrt_device::get_body_joints.
706 *
707 * @copydoc xrt_device::get_body_joints
708 *
709 * @public @memberof xrt_device
710 */
711static inline xrt_result_t
713 enum xrt_input_name body_tracking_type,
714 int64_t desired_timestamp_ns,
715 struct xrt_body_joint_set *out_value)
716{
717 return xdev->get_body_joints(xdev, body_tracking_type, desired_timestamp_ns, out_value);
718}
719
720/*!
721 * Helper function for @ref xrt_device::set_output.
722 *
723 * @copydoc xrt_device::set_output
724 *
725 * @public @memberof xrt_device
726 */
727static inline void
729{
730 xdev->set_output(xdev, name, value);
731}
732
733static inline xrt_result_t
734xrt_device_get_output_limits(struct xrt_device *xdev, struct xrt_output_limits *limits)
735{
736 if (xdev->get_output_limits) {
737 return xdev->get_output_limits(xdev, limits);
738 } else {
740 }
741}
742
743/*!
744 * Helper function for @ref xrt_device::begin_plane_detection.
745 *
746 * @public @memberof xrt_device
747 */
748static inline enum xrt_result
750 const struct xrt_plane_detector_begin_info_ext *begin_info,
751 uint64_t plane_detection_id,
752 uint64_t *out_plane_detection_id)
753{
754 return xdev->begin_plane_detection_ext(xdev, begin_info, plane_detection_id, out_plane_detection_id);
755}
756
757/*!
758 * Helper function for @ref xrt_device::destroy_plane_detection.
759 *
760 * @public @memberof xrt_device
761 */
762static inline enum xrt_result
763xrt_device_destroy_plane_detection_ext(struct xrt_device *xdev, uint64_t plane_detection_id)
764{
765 return xdev->destroy_plane_detection_ext(xdev, plane_detection_id);
766}
767
768/*!
769 * Helper function for @ref xrt_device::get_plane_detections.
770 *
771 * @public @memberof xrt_device
772 */
773static inline enum xrt_result
775 uint64_t plane_detection_id,
776 enum xrt_plane_detector_state_ext *out_state)
777{
778 return xdev->get_plane_detection_state_ext(xdev, plane_detection_id, out_state);
779}
780
781/*!
782 * Helper function for @ref xrt_device::get_plane_detections.
783 *
784 * @public @memberof xrt_device
785 */
786static inline enum xrt_result
788 uint64_t plane_detection_id,
789 struct xrt_plane_detections_ext *out_detections)
790{
791 return xdev->get_plane_detections_ext(xdev, plane_detection_id, out_detections);
792}
793
794/*!
795 * Helper function for @ref xrt_device::get_view_poses.
796 *
797 * @copydoc xrt_device::get_view_poses
798 * @public @memberof xrt_device
799 */
800static inline void
802 const struct xrt_vec3 *default_eye_relation,
803 int64_t at_timestamp_ns,
804 uint32_t view_count,
805 struct xrt_space_relation *out_head_relation,
806 struct xrt_fov *out_fovs,
807 struct xrt_pose *out_poses)
808{
809 xdev->get_view_poses(xdev, default_eye_relation, at_timestamp_ns, view_count, out_head_relation, out_fovs,
810 out_poses);
811}
812
813/*!
814 * Helper function for @ref xrt_device::compute_distortion.
815 *
816 * @copydoc xrt_device::compute_distortion
817 *
818 * @public @memberof xrt_device
819 */
820static inline bool
822 struct xrt_device *xdev, uint32_t view, float u, float v, struct xrt_uv_triplet *out_result)
823{
824 return xdev->compute_distortion(xdev, view, u, v, out_result);
825}
826
827/*!
828 * Helper function for @ref xrt_device::get_visibility_mask.
829 *
830 * @copydoc xrt_device::get_visibility_mask
831 *
832 * @public @memberof xrt_device
833 */
834static inline xrt_result_t
836 enum xrt_visibility_mask_type type,
837 uint32_t view_index,
838 struct xrt_visibility_mask **out_mask)
839{
840 return xdev->get_visibility_mask(xdev, type, view_index, out_mask);
841}
842
843/*!
844 * Helper function for @ref xrt_device::ref_space_usage.
845 *
846 * @copydoc xrt_device::ref_space_usage
847 *
848 * @public @memberof xrt_device
849 */
850static inline xrt_result_t
852 enum xrt_reference_space_type type,
853 enum xrt_input_name name,
854 bool used)
855{
856 return xdev->ref_space_usage(xdev, type, name, used);
857}
858
859/*!
860 * Helper function for @ref xrt_device::is_form_factor_available.
861 *
862 * @copydoc xrt_device::is_form_factor_available
863 *
864 * @public @memberof xrt_device
865 */
866static inline bool
868{
869 return xdev->is_form_factor_available(xdev, form_factor);
870}
871
872/*!
873 * Helper function for @ref xrt_device::get_battery_status.
874 *
875 * @copydoc xrt_device::get_battery_status
876 *
877 * @public @memberof xrt_device
878 */
879static inline xrt_result_t
880xrt_device_get_battery_status(struct xrt_device *xdev, bool *out_present, bool *out_charging, float *out_charge)
881{
882 return xdev->get_battery_status(xdev, out_present, out_charging, out_charge);
883}
884
885/*!
886 * Helper function for @ref xrt_device::begin_feature.
887 *
888 * @copydoc xrt_device::begin_feature
889 *
890 * @public @memberof xrt_device
891 */
892static inline xrt_result_t
894{
895 return xdev->begin_feature(xdev, type);
896}
897
898/*!
899 * Helper function for @ref xrt_device::end_feature.
900 *
901 * @copydoc xrt_device::end_feature
902 *
903 * @public @memberof xrt_device
904 */
905static inline xrt_result_t
907{
908 return xdev->end_feature(xdev, type);
909}
910
911/*!
912 * Helper function for @ref xrt_device::destroy.
913 *
914 * Handles nulls, sets your pointer to null.
915 *
916 * @public @memberof xrt_device
917 */
918static inline void
920{
921 struct xrt_device *xdev = *xdev_ptr;
922 if (xdev == NULL) {
923 return;
924 }
925
926 xdev->destroy(xdev);
927 *xdev_ptr = NULL;
928}
929
930
931#ifdef __cplusplus
932} // extern "C"
933#endif
xrt_plane_detection_capability_flags_ext
Caps for a plane detector, see xrt_device.
Definition: xrt_plane_detector.h:30
xrt_visibility_mask_type
Visibility mask, mirror of XrVisibilityMaskKHR.
Definition: xrt_defines.h:1996
xrt_blend_mode
Blend mode that the device supports, exact mirror of XrEnvironmentBlendMode.
Definition: xrt_defines.h:109
xrt_form_factor
What form factor is this device, mostly maps onto OpenXR's XrFormFactor.
Definition: xrt_defines.h:1946
xrt_input_name
Every internal input source known to monado with a baked in type.
Definition: xrt_defines.h:1304
enum xrt_result xrt_result_t
Result type used across Monado.
xrt_reference_space_type
Type of a OpenXR mapped reference space, maps to the semantic spaces on the xrt_space_overseer struct...
Definition: xrt_defines.h:601
xrt_output_name
Name of a output with a baked in type.
Definition: xrt_defines.h:1807
xrt_result
Result type used across Monado.
Definition: xrt_results.h:22
xrt_plane_detector_state_ext
State of a plane detector, see xrt_device.
Definition: xrt_plane_detector.h:83
xrt_device_type
How an xrt_device can be used.
Definition: xrt_defines.h:788
@ XRT_ERROR_NOT_IMPLEMENTED
The interface function called is not implemented by its interface.
Definition: xrt_results.h:186
A binding pair, going from a binding point to a device input.
Definition: xrt_device.h:193
enum xrt_input_name device
To input on the device.
Definition: xrt_device.h:195
enum xrt_input_name from
From which name.
Definition: xrt_device.h:194
A binding pair, going from a binding point to a device output.
Definition: xrt_device.h:204
enum xrt_output_name device
To output on the device.
Definition: xrt_device.h:206
enum xrt_output_name from
From which name.
Definition: xrt_device.h:205
A binding profile, has lists of binding pairs to goes from device in name to the device it hangs off ...
Definition: xrt_device.h:216
enum xrt_device_name name
Device this binding emulates.
Definition: xrt_device.h:218
Definition: xrt_defines.h:1791
Definition: xrt_defines.h:1763
A single HMD or input device.
Definition: xrt_device.h:254
static void xrt_device_set_output(struct xrt_device *xdev, enum xrt_output_name name, const struct xrt_output_value *value)
Helper function for xrt_device::set_output.
Definition: xrt_device.h:728
static xrt_result_t xrt_device_get_tracked_pose(struct xrt_device *xdev, enum xrt_input_name name, int64_t at_timestamp_ns, struct xrt_space_relation *out_relation)
Helper function for xrt_device::get_tracked_pose.
Definition: xrt_device.h:648
enum xrt_result(* destroy_plane_detection_ext)(struct xrt_device *xdev, uint64_t plane_detection_id)
Destroy internal resources associated with plane_detector_id.
Definition: xrt_device.h:458
static enum xrt_result xrt_device_get_plane_detections_ext(struct xrt_device *xdev, uint64_t plane_detection_id, struct xrt_plane_detections_ext *out_detections)
Helper function for xrt_device::get_plane_detections.
Definition: xrt_device.h:787
xrt_result_t(* get_body_skeleton)(struct xrt_device *xdev, enum xrt_input_name body_tracking_type, struct xrt_body_skeleton *out_value)
Get the body skeleton in T-pose, used to query the skeleton hierarchy, scale, proportions etc.
Definition: xrt_device.h:398
static xrt_result_t xrt_device_begin_feature(struct xrt_device *xdev, enum xrt_device_feature_type type)
Helper function for xrt_device::begin_feature.
Definition: xrt_device.h:893
xrt_result_t(* get_body_joints)(struct xrt_device *xdev, enum xrt_input_name body_tracking_type, int64_t desired_timestamp_ns, struct xrt_body_joint_set *out_value)
Get the joint locations for a body tracker.
Definition: xrt_device.h:414
xrt_result_t(* ref_space_usage)(struct xrt_device *xdev, enum xrt_reference_space_type type, enum xrt_input_name name, bool used)
Called by the xrt_space_overseer when a reference space that is implemented by this device is first u...
Definition: xrt_device.h:573
static xrt_result_t xrt_device_update_inputs(struct xrt_device *xdev)
Helper function for xrt_device::update_inputs.
Definition: xrt_device.h:635
void(* get_hand_tracking)(struct xrt_device *xdev, enum xrt_input_name name, int64_t desired_timestamp_ns, struct xrt_hand_joint_set *out_value, int64_t *out_timestamp_ns)
Get relationship of hand joints to the tracking origin space as the base space.
Definition: xrt_device.h:365
static enum xrt_result xrt_device_destroy_plane_detection_ext(struct xrt_device *xdev, uint64_t plane_detection_id)
Helper function for xrt_device::destroy_plane_detection.
Definition: xrt_device.h:763
xrt_result_t(* get_output_limits)(struct xrt_device *xdev, struct xrt_output_limits *limits)
Gets limits of this devices outputs.
Definition: xrt_device.h:435
static xrt_result_t xrt_device_ref_space_usage(struct xrt_device *xdev, enum xrt_reference_space_type type, enum xrt_input_name name, bool used)
Helper function for xrt_device::ref_space_usage.
Definition: xrt_device.h:851
char str[256]
A string describing the device.
Definition: xrt_device.h:260
static void xrt_device_get_view_poses(struct xrt_device *xdev, const struct xrt_vec3 *default_eye_relation, int64_t at_timestamp_ns, uint32_t view_count, struct xrt_space_relation *out_head_relation, struct xrt_fov *out_fovs, struct xrt_pose *out_poses)
Helper function for xrt_device::get_view_poses.
Definition: xrt_device.h:801
static xrt_result_t xrt_device_get_face_tracking(struct xrt_device *xdev, enum xrt_input_name facial_expression_type, int64_t at_timestamp_ns, struct xrt_facial_expression_set *out_value)
Helper function for xrt_device::get_face_tracking.
Definition: xrt_device.h:681
void(* get_view_poses)(struct xrt_device *xdev, const struct xrt_vec3 *default_eye_relation, int64_t at_timestamp_ns, uint32_t view_count, struct xrt_space_relation *out_head_relation, struct xrt_fov *out_fovs, struct xrt_pose *out_poses)
Get the per-view pose in relation to the view space.
Definition: xrt_device.h:521
xrt_result_t(* get_visibility_mask)(struct xrt_device *xdev, enum xrt_visibility_mask_type type, uint32_t view_index, struct xrt_visibility_mask **out_mask)
Get the visibility mask for this device.
Definition: xrt_device.h:554
struct xrt_hmd_parts * hmd
Null if this device does not interface with the users head.
Definition: xrt_device.h:266
xrt_result_t(* get_face_tracking)(struct xrt_device *xdev, enum xrt_input_name facial_expression_type, int64_t at_timestamp_ns, struct xrt_facial_expression_set *out_value)
Get the requested blend shape properties & weights for a face tracker.
Definition: xrt_device.h:383
char serial[256]
A unique identifier. Persistent across configurations, if possible.
Definition: xrt_device.h:263
struct xrt_output * outputs
Array of output structs.
Definition: xrt_device.h:284
xrt_result_t(* begin_feature)(struct xrt_device *xdev, enum xrt_device_feature_type type)
Enable the feature for this device.
Definition: xrt_device.h:609
size_t output_count
Number of outputs.
Definition: xrt_device.h:282
bool(* is_form_factor_available)(struct xrt_device *xdev, enum xrt_form_factor form_factor)
Check if given form factor is available or not.
Definition: xrt_device.h:588
void(* set_output)(struct xrt_device *xdev, enum xrt_output_name name, const struct xrt_output_value *value)
Set a output value.
Definition: xrt_device.h:427
struct xrt_input * inputs
Array of input structs.
Definition: xrt_device.h:279
static xrt_result_t xrt_device_get_body_skeleton(struct xrt_device *xdev, enum xrt_input_name body_tracking_type, struct xrt_body_skeleton *out_value)
Helper function for xrt_device::get_body_skeleton.
Definition: xrt_device.h:697
size_t input_count
Number of inputs.
Definition: xrt_device.h:277
xrt_result_t(* get_battery_status)(struct xrt_device *xdev, bool *out_present, bool *out_charging, float *out_charge)
Get battery status information.
Definition: xrt_device.h:598
enum xrt_result(* get_plane_detections_ext)(struct xrt_device *xdev, uint64_t plane_detection_id, struct xrt_plane_detections_ext *out_detections)
Get results of a plane detection request.
Definition: xrt_device.h:480
void(* destroy)(struct xrt_device *xdev)
Destroy device.
Definition: xrt_device.h:622
static xrt_result_t xrt_device_end_feature(struct xrt_device *xdev, enum xrt_device_feature_type type)
Helper function for xrt_device::end_feature.
Definition: xrt_device.h:906
xrt_result_t(* update_inputs)(struct xrt_device *xdev)
Update any attached inputs.
Definition: xrt_device.h:311
static xrt_result_t xrt_device_get_body_joints(struct xrt_device *xdev, enum xrt_input_name body_tracking_type, int64_t desired_timestamp_ns, struct xrt_body_joint_set *out_value)
Helper function for xrt_device::get_body_joints.
Definition: xrt_device.h:712
enum xrt_result(* get_plane_detection_state_ext)(struct xrt_device *xdev, uint64_t plane_detection_id, enum xrt_plane_detector_state_ext *out_state)
Get the state of a plane detection request.
Definition: xrt_device.h:468
static enum xrt_result xrt_device_begin_plane_detection_ext(struct xrt_device *xdev, const struct xrt_plane_detector_begin_info_ext *begin_info, uint64_t plane_detection_id, uint64_t *out_plane_detection_id)
Helper function for xrt_device::begin_plane_detection.
Definition: xrt_device.h:749
struct xrt_tracking_origin * tracking_origin
Always set, pointing to the tracking system for this device.
Definition: xrt_device.h:269
xrt_result_t(* end_feature)(struct xrt_device *xdev, enum xrt_device_feature_type type)
Disable the feature for this device.
Definition: xrt_device.h:617
size_t binding_profile_count
Number of bindings in xrt_device::binding_profiles.
Definition: xrt_device.h:272
enum xrt_result(* begin_plane_detection_ext)(struct xrt_device *xdev, const struct xrt_plane_detector_begin_info_ext *begin_info, uint64_t plane_detection_id, uint64_t *out_plane_detection_id)
Begin a plane detection request.
Definition: xrt_device.h:446
static enum xrt_result xrt_device_get_plane_detection_state_ext(struct xrt_device *xdev, uint64_t plane_detection_id, enum xrt_plane_detector_state_ext *out_state)
Helper function for xrt_device::get_plane_detections.
Definition: xrt_device.h:774
enum xrt_device_name name
Enum identifier of the device.
Definition: xrt_device.h:256
static xrt_result_t xrt_device_get_visibility_mask(struct xrt_device *xdev, enum xrt_visibility_mask_type type, uint32_t view_index, struct xrt_visibility_mask **out_mask)
Helper function for xrt_device::get_visibility_mask.
Definition: xrt_device.h:835
static bool xrt_device_is_form_factor_available(struct xrt_device *xdev, enum xrt_form_factor form_factor)
Helper function for xrt_device::is_form_factor_available.
Definition: xrt_device.h:867
static void xrt_device_destroy(struct xrt_device **xdev_ptr)
Helper function for xrt_device::destroy.
Definition: xrt_device.h:919
xrt_result_t(* get_tracked_pose)(struct xrt_device *xdev, enum xrt_input_name name, int64_t at_timestamp_ns, struct xrt_space_relation *out_relation)
Get relationship of a tracked device to the tracking origin space as the base space.
Definition: xrt_device.h:337
bool(* compute_distortion)(struct xrt_device *xdev, uint32_t view, float u, float v, struct xrt_uv_triplet *out_result)
Compute the distortion at a single point.
Definition: xrt_device.h:543
static bool xrt_device_compute_distortion(struct xrt_device *xdev, uint32_t view, float u, float v, struct xrt_uv_triplet *out_result)
Helper function for xrt_device::compute_distortion.
Definition: xrt_device.h:821
static xrt_result_t xrt_device_get_battery_status(struct xrt_device *xdev, bool *out_present, bool *out_charging, float *out_charge)
Helper function for xrt_device::get_battery_status.
Definition: xrt_device.h:880
static void xrt_device_get_hand_tracking(struct xrt_device *xdev, enum xrt_input_name name, int64_t desired_timestamp_ns, struct xrt_hand_joint_set *out_value, int64_t *out_timestamp_ns)
Helper function for xrt_device::get_hand_tracking.
Definition: xrt_device.h:664
Definition: xrt_defines.h:1652
Describes a projection matrix fov.
Definition: xrt_defines.h:488
Joint set type used for hand tracking.
Definition: xrt_defines.h:1403
All of the device components that deals with interfacing to a users head.
Definition: xrt_device.h:93
float * vertices
Data.
Definition: xrt_device.h:135
struct xrt_fov fov[XRT_MAX_VIEWS]
distortion is subject to the field of view
Definition: xrt_device.h:154
uint32_t vertex_count
Number of vertices.
Definition: xrt_device.h:137
struct xrt_view views[XRT_MAX_VIEWS]
Display information.
Definition: xrt_device.h:113
uint64_t nominal_frame_interval_ns
Nominal frame interval.
Definition: xrt_device.h:105
uint32_t stride
Stride of vertices.
Definition: xrt_device.h:139
enum xrt_blend_mode blend_modes[XRT_MAX_DEVICE_BLEND_MODES]
Array of supported blend modes.
Definition: xrt_device.h:119
int * indices
Indices, for triangle strip.
Definition: xrt_device.h:144
enum xrt_distortion_model models
Supported distortion models, a bitfield.
Definition: xrt_device.h:128
uint32_t index_count_total
Total number of elements in mesh::indices array.
Definition: xrt_device.h:150
struct xrt_hmd_parts::@235 distortion
Distortion information.
uint32_t index_offsets[XRT_MAX_VIEWS]
Offsets for the indices (one offset per view).
Definition: xrt_device.h:148
uint32_t uv_channels_count
1 or 3 for (chromatic aberration).
Definition: xrt_device.h:141
struct xrt_hmd_parts::@234 screens[1]
The hmd screen as an unrotated display, like the HMD presents it to the OS.
enum xrt_distortion_model preferred
Preferred disortion model, single value.
Definition: xrt_device.h:130
uint32_t index_counts[XRT_MAX_VIEWS]
Number of indices for the triangle strips (one per view).
Definition: xrt_device.h:146
A single named input, that sits on a xrt_device.
Definition: xrt_device.h:164
int64_t timestamp
alignas for 32 bit client support, see IPC Design and Implementation
Definition: xrt_device.h:169
bool active
Is this input active.
Definition: xrt_device.h:166
A tightly packed 2x2 matrix of floats.
Definition: xrt_defines.h:515
Output limits of a particular device.
Definition: xrt_device.h:241
float haptic_pcm_sample_rate
The sample rate of the device's haptic PCM support, 0 if haptic PCM is not supported.
Definition: xrt_device.h:243
A union of all output types.
Definition: xrt_defines.h:1923
A single named output, that sits on a xrt_device.
Definition: xrt_device.h:182
Each plane has n polygons; ultimately plane metadata from locations and vetices is reconstructed.
Definition: xrt_plane_detector.h:171
A query for a plane.
Definition: xrt_plane_detector.h:97
A pose composed of a position and orientation.
Definition: xrt_defines.h:467
A relation with two spaces, includes velocity and acceleration.
Definition: xrt_defines.h:659
A tracking system or device origin.
Definition: xrt_tracking.h:71
Represents a uv triplet for distortion, basically just three xrt_vec2.
Definition: xrt_defines.h:263
A 3 element vector with single floats.
Definition: xrt_defines.h:273
A per-lens/display view information.
Definition: xrt_device.h:36
struct xrt_matrix_2x2 rot
Rotation 2d matrix used to rotate the position of the output of the distortion shaders onto the scree...
Definition: xrt_device.h:82
struct xrt_view::@232 viewport
Viewport position on the screen.
struct xrt_view::@233 display
Physical properties of this display (or the part of a display that covers this view).
Visibility mask helper, the indices and vertices are tightly packed after this struct.
Definition: xrt_visibility_mask.h:25
A union of all input types.
Definition: xrt_defines.h:1419
Common defines and enums for XRT.
xrt_distortion_model
Which distortion model does the device expose, used both as a bitfield and value.
Definition: xrt_defines.h:164
xrt_device_name
A enum that is used to name devices so that the state trackers can reason about the devices easier.
Definition: xrt_defines.h:714
xrt_device_feature_type
Higher level features for devices.
Definition: xrt_device.h:230
Header for limits of the XRT interfaces.
Header defining planes detector enum and structs.
Header defining visibility mask helper struct.