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