matrixfurry.com
The open source OpenXR runtime
1// Copyright 2019-2025, Collabora, Ltd.
2// SPDX-License-Identifier: BSL-1.0
3/*!
4 * @file
5 * @brief Misc helpers for device drivers.
6 * @author Jakob Bornecrantz <jakob@collabora.com>
7 * @author Rylie Pavlik <rylie.pavlik@collabora.com>
8 * @author Moshi Turner <moshiturner@protonmail.com>
9 * @author Simon Zeni <simon.zeni@collabora.com>
10 * @ingroup aux_util
11 */
12
13#pragma once
14
15#include "xrt/xrt_compiler.h"
16#include "xrt/xrt_device.h"
17#include "xrt/xrt_tracking.h"
18
19#ifdef __cplusplus
20extern "C" {
21#endif
22
23
24extern const struct xrt_matrix_2x2 u_device_rotation_right;
25extern const struct xrt_matrix_2x2 u_device_rotation_left;
26extern const struct xrt_matrix_2x2 u_device_rotation_ident;
27extern const struct xrt_matrix_2x2 u_device_rotation_180;
28
29enum u_device_alloc_flags
30{
31 // clang-format off
32 U_DEVICE_ALLOC_NO_FLAGS = 0,
33 U_DEVICE_ALLOC_HMD = 1u << 0u,
34 U_DEVICE_ALLOC_TRACKING_NONE = 1u << 1u,
35 // clang-format on
36};
37
38/*!
39 *
40 * Info to describe 2D extents of a device's screen
41 *
42 */
43struct u_extents_2d
44{
45 uint32_t w_pixels; // Width of entire screen in pixels
46 uint32_t h_pixels; // Height of entire screen
47};
48
49/*!
50 *
51 * Info to describe a very simple headset with diffractive lens optics.
52 *
53 */
54struct u_device_simple_info
55{
56 struct
57 {
58 uint32_t w_pixels;
59 uint32_t h_pixels;
60 float w_meters;
61 float h_meters;
62 } display;
63
64 float lens_horizontal_separation_meters;
65 float lens_vertical_position_meters;
66
67 float fov[XRT_MAX_VIEWS];
68};
69
70/*!
71 * Setup the device information given a very simple info struct.
72 *
73 * @return true on success.
74 * @ingroup aux_util
75 */
76bool
77u_device_setup_one_eye(struct xrt_device *xdev, const struct u_device_simple_info *info);
78
79/*!
80 * Setup the device information given a very simple info struct.
81 *
82 * @return true on success.
83 * @ingroup aux_util
84 */
85bool
86u_device_setup_split_side_by_side(struct xrt_device *xdev, const struct u_device_simple_info *info);
87
88/*!
89 * Setup the device's display's 2D extents.
90 * Good for headsets without traditional VR optics.
91 *
92 * @return true on success.
93 * @ingroup aux_util
94 */
95bool
96u_extents_2d_split_side_by_side(struct xrt_device *xdev, const struct u_extents_2d *extents);
97
98
99/*!
100 * Dump the device config to stderr.
101 *
102 * @ingroup aux_util
103 */
104void
105u_device_dump_config(struct xrt_device *xdev, const char *prefix, const char *prod);
106
107#define U_DEVICE_ALLOCATE(type, flags, input_count, output_count) \
108 ((type *)u_device_allocate(flags, sizeof(type), input_count, output_count))
109
110
111/*!
112 * Helper function to allocate a device plus inputs in the same allocation
113 * placed after the device in memory.
114 *
115 * Will setup any pointers and num values.
116 *
117 * @ingroup aux_util
118 */
119void *
120u_device_allocate(enum u_device_alloc_flags flags, size_t size, size_t input_count, size_t output_count);
121
122/*!
123 * Helper function to free a device and any data hanging of it.
124 *
125 * @ingroup aux_util
126 */
127void
128u_device_free(struct xrt_device *xdev);
129
130
131#define XRT_DEVICE_ROLE_UNASSIGNED (-1)
132
133/*!
134 * Helper function to assign head, left hand, right hand, and gamepad roles.
135 *
136 * @ingroup aux_util
137 */
138void
139u_device_assign_xdev_roles(
140 struct xrt_device **xdevs, size_t xdev_count, int *head, int *left, int *right, int *gamepad);
141
142/*!
143 * Helper function for `get_view_pose` in an HMD driver.
144 *
145 * Takes in a translation from the left to right eye, and returns a center to left or right eye transform that assumes
146 * the eye relation is symmetrical around the tracked point ("center eye"). Knowing IPD is a subset of this: If you know
147 * IPD better than the overall Monado system, copy @p eye_relation and put your known IPD in @p real_eye_relation->x
148 *
149 * If you have rotation, apply it after calling this function.
150 *
151 * @param eye_relation 3D translation from left eye to right eye.
152 * @param view_index 0 for left, 1 for right.
153 * @param out_pose The output pose to populate. Will receive translation, with an identity rotation.
154 */
155void
156u_device_get_view_pose(const struct xrt_vec3 *eye_relation, uint32_t view_index, struct xrt_pose *out_pose);
157
158
159/*
160 *
161 * Default implementation of functions.
162 *
163 */
164
165/*!
166 * Helper function to implement @ref xrt_device::get_view_poses in a HMD driver.
167 *
168 * The field @ref xrt_device::hmd needs to be set and valid.
169 */
170xrt_result_t
171u_device_get_view_poses(struct xrt_device *xdev,
172 const struct xrt_vec3 *default_eye_relation,
173 int64_t at_timestamp_ns,
174 enum xrt_view_type view_type,
175 uint32_t view_count,
176 struct xrt_space_relation *out_head_relation,
177 struct xrt_fov *out_fovs,
178 struct xrt_pose *out_poses);
179
180/*!
181 * Helper function to implement @ref xrt_device::get_visibility_mask in a HMD driver.
182 *
183 * The field @ref xrt_device::hmd needs to be set and valid.
184 */
185xrt_result_t
186u_device_get_visibility_mask(struct xrt_device *xdev,
187 enum xrt_visibility_mask_type type,
188 uint32_t view_index,
189 struct xrt_visibility_mask **out_mask);
190
191/*
192 *
193 * No-op implementation of functions.
194 *
195 */
196
197/*!
198 * Noop function for @ref xrt_device::update_inputs,
199 * should only be used from a device with any inputs.
200 *
201 * @ingroup aux_util
202 */
203xrt_result_t
204u_device_noop_update_inputs(struct xrt_device *xdev);
205
206
207/*
208 *
209 * Helper function to fill in defaults.
210 *
211 */
212
213/*!
214 * Function pointer type for the device's get_tracked_pose function.
215 *
216 * @ingroup aux_util
217 */
218typedef xrt_result_t (*u_device_get_tracked_pose_function_t)(struct xrt_device *xdev,
219 const enum xrt_input_name name,
220 const int64_t at_timestamp_ns,
221 struct xrt_space_relation *const out_relation);
222
223/*!
224 * Function pointer type for the device's destroy function.
225 *
226 * @ingroup aux_util
227 */
228typedef void (*u_device_destroy_function_t)(struct xrt_device *xdev);
229
230/*!
231 * Populate the device's function pointers with default implementations.
232 *
233 * This function fills in all device function pointers with either noop or
234 * not-implemented versions, allowing drivers to override only the functions
235 * they actually implement. The exceptions are get_tracked_pose and destroy,
236 * which must be implemented by the driver and are passed in as function
237 * pointers, these must not be NULL.
238 *
239 * @param[in,out] xdev The device to populate with default function pointers.
240 * @param[in] get_tracked_pose_fn The function pointer to the device's get_tracked_pose function.
241 * @param[in] destroy_fn The function pointer to the device's destroy function.
242 * @ingroup aux_util
243 */
244void
245u_device_populate_function_pointers(struct xrt_device *xdev,
246 u_device_get_tracked_pose_function_t get_tracked_pose_fn,
247 u_device_destroy_function_t destroy_fn);
248
249#ifdef __cplusplus
250}
251#endif