Monado OpenXR Runtime
wmr_hmd.h
Go to the documentation of this file.
1// Copyright 2018, Philipp Zabel.
2// Copyright 2020-2021, N Madsen.
3// Copyright 2020-2023, Collabora, Ltd.
4// SPDX-License-Identifier: BSL-1.0
5/*!
6 * @file
7 * @brief Interface to the WMR HMD driver code.
8 * @author Philipp Zabel <philipp.zabel@gmail.com>
9 * @author nima01 <nima_zero_one@protonmail.com>
10 * @author Jakob Bornecrantz <jakob@collabora.com>
11 * @author Nova King <technobaboo@proton.me>
12 * @ingroup drv_wmr
13 */
14
15#pragma once
16
17#include "tracking/t_tracking.h"
18#include "xrt/xrt_device.h"
19#include "xrt/xrt_frame.h"
20#include "xrt/xrt_prober.h"
21#include "os/os_threading.h"
22#include "math/m_imu_3dof.h"
23#include "util/u_logging.h"
25#include "util/u_var.h"
26
27#include "wmr_protocol.h"
28#include "wmr_config.h"
29#include "wmr_camera.h"
30#include "wmr_common.h"
31#include "wmr_hmd_controller.h"
32
33
34#ifdef __cplusplus
35extern "C" {
36#endif
37
38/* Support 2 controllers on HP Reverb G2 */
39#define WMR_MAX_CONTROLLERS 2
40
41struct wmr_hmd;
42
44{
45 enum wmr_headset_type hmd_type;
46
47 //! String by which we recognise the device
48 const char *dev_id_str;
49 //! Friendly ID string for debug
50 const char *debug_name;
51
52 int (*init_func)(struct wmr_hmd *wh);
53 void (*deinit_func)(struct wmr_hmd *wh);
54 void (*screen_enable_func)(struct wmr_hmd *wh, bool enable);
55};
56
57/*!
58 * @implements xrt_device
59 */
60struct wmr_hmd
61{
62 struct xrt_device base;
63
64 const struct wmr_headset_descriptor *hmd_desc;
65
66 //! firmware configuration block, with device names etc
68
69 //! Config data parsed from the firmware JSON
71
72 //! Packet reading thread.
74
75 enum u_logging_level log_level;
76
77 /*!
78 * This is the Hololens Sensors device, this is where we get all of the
79 * IMU data and read the config from.
80 *
81 * During start it is owned by the thread creating the device, after
82 * init it is owned by the reading thread. Read/write access is
83 * protected by the hid_lock
84 */
85
87 struct os_mutex hid_lock;
88
89 /*!
90 * This is the vendor specific companion device of the Hololens Sensors.
91 * When activated, it will report the physical IPD adjustment and proximity
92 * sensor status of the headset. It also allows enabling/disabling the HMD
93 * screen on Reverb G1/G2.
94 */
96
97 //! Current desired HMD screen state.
99 //! Latest raw IPD value read from the device.
100 uint16_t raw_ipd;
101 //! Latest proximity sensor value read from the device.
103
104 struct hololens_sensors_packet packet;
105
106 struct
107 {
108 //! Protects all members of the `fusion` substruct.
110
111 //! Main fusion calculator.
113
114 //! The last angular velocity from the IMU, for prediction.
116
117 //! When did we get the last IMU sample, in CPU time.
119 } fusion;
120
121 //! Fields related to camera-based tracking (SLAM and hand tracking)
122 struct
123 {
124 //! Source of video/IMU data for tracking
125 struct xrt_fs *source;
126
127 //! Context for @ref source
129
130 //! SLAM tracker.
131 //! @todo Right now, we are not consistent in how we interface with
132 //! trackers. In particular, we have a @ref xrt_tracked_slam field but not
133 //! an equivalent for hand tracking.
135
136 //! Calibration data for SLAM
138
139 //! Set at start. Whether the SLAM tracker was initialized.
141
142 //! Set at start. Whether the hand tracker was initialized.
144
145 //! SLAM systems track the IMU pose, enabling this corrects it to middle of the eyes
146 bool imu2me;
148
149 //! Whether to track the HMD with 6dof SLAM or fallback to the `fusion` 3dof tracker
151
152 //! Last tracked pose
154
155 //! Additional offset to apply to `pose`
157
158 //! Average 4 IMU samples before sending them to the trackers
160
161 /*!
162 * Offset for tracked pose offsets (applies to both fusion and SLAM).
163 * Applied when getting the tracked poses, so is effectively a offset
164 * to increase or decrease prediction.
165 */
167
168 struct
169 {
170 struct u_var_button hmd_screen_enable_btn;
171 struct u_var_button switch_tracker_btn;
172 char hand_status[128];
173 char slam_status[128];
174 } gui;
175
176 /* Tunnelled controller devices (Reverb G2, Odyssey+) handling */
177 struct os_mutex controller_status_lock;
178 struct os_cond controller_status_cond;
179 bool have_left_controller_status;
180 bool have_right_controller_status;
181
182 struct wmr_hmd_controller_connection *controller[WMR_MAX_CONTROLLERS];
183};
184
185static inline struct wmr_hmd *
186wmr_hmd(struct xrt_device *p)
187{
188 return (struct wmr_hmd *)p;
189}
190
191void
192wmr_hmd_create(enum wmr_headset_type hmd_type,
193 struct os_hid_device *hid_holo,
194 struct os_hid_device *hid_ctrl,
195 struct xrt_prober_device *dev_holo,
196 enum u_logging_level log_level,
197 struct xrt_device **out_hmd,
198 struct xrt_device **out_handtracker,
199 struct xrt_device **out_left_controller,
200 struct xrt_device **out_right_controller);
201
202bool
203wmr_hmd_send_controller_packet(struct wmr_hmd *hmd, const uint8_t *buffer, uint32_t buf_size);
204int
205wmr_hmd_read_sync_from_controller(struct wmr_hmd *hmd, uint8_t *buffer, uint32_t buf_size, int timeout_ms);
206#ifdef __cplusplus
207}
208#endif
u_logging_level
Logging level enum.
Definition: u_logging.h:44
wmr_headset_type
Headset type, used to select different control and init/shutdown procedures.
Definition: wmr_common.h:29
A IMU fusion specially made for 3dof devices.
Wrapper around OS threading native functions.
Definition: wmr_protocol.h:79
Definition: m_imu_3dof.h:35
A wrapper around a native conditional variable.
Definition: os_threading.h:189
Representing a single hid interface on a device.
Definition: os_hid.h:29
A wrapper around a native mutex.
Definition: os_threading.h:55
All in one helper that handles locking, waiting for change and starting a thread.
Definition: os_threading.h:465
Calibration information necessary for SLAM tracking.
Definition: t_tracking.h:649
Simple pushable button.
Definition: u_var.h:79
Draggable single precision float information.
Definition: u_var.h:120
Definition: wmr_protocol.h:90
Definition: wmr_hmd.h:44
const char * debug_name
Friendly ID string for debug.
Definition: wmr_hmd.h:50
const char * dev_id_str
String by which we recognise the device.
Definition: wmr_hmd.h:48
Definition: wmr_config.h:152
Definition: wmr_hmd_controller.h:24
Definition: wmr_hmd.h:61
struct wmr_config_header config_hdr
firmware configuration block, with device names etc
Definition: wmr_hmd.h:67
bool slam_enabled
Set at start. Whether the SLAM tracker was initialized.
Definition: wmr_hmd.h:140
struct m_imu_3dof i3dof
Main fusion calculator.
Definition: wmr_hmd.h:112
struct u_var_draggable_f32 tracked_offset_ms
Offset for tracked pose offsets (applies to both fusion and SLAM).
Definition: wmr_hmd.h:166
bool hand_enabled
Set at start. Whether the hand tracker was initialized.
Definition: wmr_hmd.h:143
struct wmr_hmd_config config
Config data parsed from the firmware JSON.
Definition: wmr_hmd.h:70
struct xrt_fs * source
Source of video/IMU data for tracking.
Definition: wmr_hmd.h:125
struct os_thread_helper oth
Packet reading thread.
Definition: wmr_hmd.h:73
struct os_hid_device * hid_hololens_sensors_dev
This is the Hololens Sensors device, this is where we get all of the IMU data and read the config fro...
Definition: wmr_hmd.h:86
bool average_imus
Average 4 IMU samples before sending them to the trackers.
Definition: wmr_hmd.h:159
uint64_t last_imu_timestamp_ns
When did we get the last IMU sample, in CPU time.
Definition: wmr_hmd.h:118
struct xrt_vec3 last_angular_velocity
The last angular velocity from the IMU, for prediction.
Definition: wmr_hmd.h:115
struct xrt_pose offset
Additional offset to apply to pose
Definition: wmr_hmd.h:156
struct xrt_pose pose
Last tracked pose.
Definition: wmr_hmd.h:153
uint16_t raw_ipd
Latest raw IPD value read from the device.
Definition: wmr_hmd.h:100
struct wmr_hmd::@218 tracking
Fields related to camera-based tracking (SLAM and hand tracking)
struct xrt_frame_context xfctx
Context for source.
Definition: wmr_hmd.h:128
bool hmd_screen_enable
Current desired HMD screen state.
Definition: wmr_hmd.h:98
struct t_slam_calibration slam_calib
Calibration data for SLAM.
Definition: wmr_hmd.h:137
bool slam_over_3dof
Whether to track the HMD with 6dof SLAM or fallback to the fusion 3dof tracker.
Definition: wmr_hmd.h:150
uint8_t proximity_sensor
Latest proximity sensor value read from the device.
Definition: wmr_hmd.h:102
struct xrt_tracked_slam * slam
SLAM tracker.
Definition: wmr_hmd.h:134
struct os_hid_device * hid_control_dev
This is the vendor specific companion device of the Hololens Sensors.
Definition: wmr_hmd.h:95
struct os_mutex mutex
Protects all members of the fusion substruct.
Definition: wmr_hmd.h:109
bool imu2me
SLAM systems track the IMU pose, enabling this corrects it to middle of the eyes.
Definition: wmr_hmd.h:146
A single HMD or input device.
Definition: xrt_device.h:282
struct xrt_hmd_parts * hmd
Null if this device does not interface with the users head.
Definition: xrt_device.h:294
Object used to track all sinks and frame producers in a graph.
Definition: xrt_frame.h:108
Frameserver that generates frames.
Definition: xrt_frameserver.h:70
A pose composed of a position and orientation.
Definition: xrt_defines.h:464
A probed device, may or may not be opened.
Definition: xrt_prober.h:85
An adapter that wraps an external SLAM tracker to provide SLAM tracking.
Definition: xrt_tracking.h:294
A 3 element vector with single floats.
Definition: xrt_defines.h:274
Tracking API interface.
Code to generate disortion meshes.
Basic logging functionality.
Variable tracking code.
Interface to read WMR cameras.
Defines and constants related to WMR driver code.
WMR and MS HoloLens configuration structures.
void wmr_hmd_create(enum wmr_headset_type hmd_type, struct os_hid_device *hid_holo, struct os_hid_device *hid_ctrl, struct xrt_prober_device *dev_holo, enum u_logging_level log_level, struct xrt_device **out_hmd, struct xrt_device **out_handtracker, struct xrt_device **out_left_controller, struct xrt_device **out_right_controller)
Definition: wmr_hmd.c:1794
Implementation of tunnelled controller connection, that translates messages passing via an HP G2 or S...
WMR and MS HoloLens protocol constants, structures and helpers header.
Header defining an xrt display or controller device.
Data frame header.
Common interface to probe for devices.