Monado OpenXR Runtime
u_var.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 Variable tracking code.
6 * @author Jakob Bornecrantz <jakob@collabora.com>
7 * @ingroup aux_util
8 */
9
10#pragma once
11
12#include "xrt/xrt_defines.h" // IWYU pragma: keep
13
14#include "util/u_logging.h"
15
16
17#ifdef __cplusplus
18extern "C" {
19#endif
20
21
22struct xrt_frame_sink;
23struct u_sink_debug;
25struct m_ff_f64;
26struct m_ff_vec3_f32;
27
28/*!
29 * Used to plot an array for values.
30 *
31 * @ingroup aux_util
32 */
34{
35 void *data;
36 int *index_ptr;
37 int length;
38};
39
40/*!
41 * Used to plot a graph of timing information.
42 *
43 * @ingroup aux_util
44 */
46{
47 //! Values to be plotted.
49
50 //! A reference line drawn on the plot.
52
53 //! If false, reference_timing will be the bottom of the graph.
55
56 //! How many units the graph expands by default.
57 float range;
58
59 //! Rescale graph's value range when value exceeds range.
61
62 //! A string describing the unit used, not freed.
63 const char *unit;
64};
65
66/*!
67 * Callback for a button action
68 *
69 * @ingroup aux_util
70 */
71typedef void (*u_var_button_cb)(void *);
72
73/*!
74 * Simple pushable button.
75 *
76 * @ingroup aux_util
77 */
79{
80 //! Callback function to execute on button press
82
83 //! Pointer that will be passed to the function as its only argument
84 void *ptr;
85
86 //! Button text, use var `name` if zeroed
87 char label[64];
88
89 //! Button dimensions, zero for auto size
90 float width;
91 float height;
92
93 //! Whether this button is disabled
95};
96
97/*!
98 * Combo box information.
99 *
100 * @ingroup aux_util
101 */
103{
104 //! Number of options.
105 int count;
106
107 //! List of `count` option names separated by \0.
108 const char *options;
109
110 //! Pointer to the option value.
111 int *value;
112};
113
114/*!
115 * Draggable single precision float information.
116 *
117 * @ingroup aux_util
118 */
120{
121 float val;
122 float step;
123 float min;
124 float max;
125};
126
127/*!
128 * Draggable usingned 16-bit integer information.
129 *
130 * @ingroup aux_util
131 */
133{
134 //! @note Using a float instead of storing the value like @ref
135 //! u_var_draggable_f32. It seemed better to decouple the UI from the value
136 //! itself.
137 //! @todo Unify "draggable" widgets interface.
138 uint16_t *val;
139 uint16_t step;
140 uint16_t min;
141 uint16_t max;
142};
143
144/*!
145 * Histogram based on single precision bars.
146 *
147 * @ingroup aux_util
148 */
150{
151 float *values; //!< Bin heights
152 int count; //!< Number of bins
153 float width; //!< Widget width or 0 for auto
154 float height; //!< Widget height or 0 for auto
155};
156
157/*!
158 * A point on the curve, uses doubles like ImPlotPoint.
159 *
160 * @ingroup aux_util
161 */
163{
164 double x;
165 double y;
166};
167
168/*!
169 * Callback for getting points on a curve.
170 *
171 * @ingroup aux_util
172 */
173typedef struct u_var_curve_point (*u_var_curve_getter)(void *data, int i);
174
175/*!
176 * A single curve on a plot.
177 *
178 * @ingroup aux_util
179 */
181{
182 u_var_curve_getter getter; //!< Getter of 2D points for the curve
183 void *data; //!< User data for `getter`
184 int count; //!< Number of points to draw; param i < count
185 const char *label; //!< Curve name
186 const char *xlabel; //!< Label of the X axis
187 const char *ylabel; //!< Label of the Y axis
188};
189
190/*!
191 * A collection of curves to be plotted.
192 *
193 * @ingroup aux_util
194 */
196{
197 struct u_var_curve curves[16];
198 int curve_count;
199
200 // These override individual curve axis labels
201 const char *xlabel; //!< Label of the X axis
202 const char *ylabel; //!< Label of the Y axis
203};
204
205/*!
206 * What kind of variable is this tracking.
207 *
208 * @ingroup aux_util
209 */
211{
212 U_VAR_KIND_BOOL,
213 U_VAR_KIND_RGB_U8,
214 U_VAR_KIND_RGB_F32,
215 U_VAR_KIND_U8,
216 U_VAR_KIND_U16,
217 U_VAR_KIND_U64,
218 U_VAR_KIND_I32,
219 U_VAR_KIND_I64,
220 U_VAR_KIND_F32,
221 U_VAR_KIND_DRAGGABLE_F32,
222 U_VAR_KIND_F64,
223 U_VAR_KIND_F32_ARR,
224 U_VAR_KIND_TIMING,
225 U_VAR_KIND_VEC3_I32,
226 U_VAR_KIND_VEC3_F32,
227 U_VAR_KIND_POSE,
228 U_VAR_KIND_SINK_DEBUG,
229 U_VAR_KIND_NATIVE_IMAGES_DEBUG,
230 U_VAR_KIND_LOG_LEVEL,
231 U_VAR_KIND_RO_TEXT,
232 U_VAR_KIND_RO_FTEXT,
233 U_VAR_KIND_RO_I16,
234 U_VAR_KIND_RO_I32,
235 U_VAR_KIND_RO_U32,
236 U_VAR_KIND_RO_F32,
237 U_VAR_KIND_RO_I64,
238 U_VAR_KIND_RO_U64,
239 U_VAR_KIND_RO_F64,
240 U_VAR_KIND_RO_VEC3_I32,
241 U_VAR_KIND_RO_VEC3_F32,
242 U_VAR_KIND_RO_QUAT_F32,
243 U_VAR_KIND_RO_FF_F64,
244 U_VAR_KIND_RO_FF_VEC3_F32,
245 U_VAR_KIND_GUI_HEADER,
246 U_VAR_KIND_GUI_HEADER_BEGIN,
247 U_VAR_KIND_GUI_HEADER_END,
248 U_VAR_KIND_BUTTON,
249 U_VAR_KIND_COMBO,
250 U_VAR_KIND_HISTOGRAM_F32,
251 U_VAR_KIND_DRAGGABLE_U16,
252 U_VAR_KIND_CURVE,
253 U_VAR_KIND_CURVES,
254};
255
256/*!
257 * Maximum string length for a tracked variable.
258 *
259 * @ingroup aux_util
260 */
261#define U_VAR_NAME_STRING_SIZE 256
262
263/*!
264 * Struct that keeps all of the information about the variable, some of the UI
265 * state is kept on it.
266 *
267 * @ingroup aux_util
268 */
270{
271 char name[U_VAR_NAME_STRING_SIZE];
272 void *ptr;
273
274 enum u_var_kind kind;
275
276 struct
277 {
278 bool graphed;
279 } gui;
280};
281
282/*!
283 * Struct containing the information about a root object.
284 *
285 * @ingroup aux_util
286 */
288{
289 //! The displayed name.
290 const char *name;
291
292 //! Raw name without any suffix.
293 const char *raw_name;
294
295 //! The number of the window, or zero (name and raw_name are the same).
296 uint32_t number;
297};
298
299/*!
300 * Callback for entering and leaving root nodes.
301 *
302 * @ingroup aux_util
303 */
304typedef void (*u_var_root_cb)(struct u_var_root_info *info, void *);
305
306/*!
307 * Callback on each variable a root node has.
308 *
309 * @ingroup aux_util
310 */
311typedef void (*u_var_elm_cb)(struct u_var_info *info, void *);
312
313/*!
314 * Add a named root object, the u_var subsystem is completely none-invasive
315 * to the object it's tracking. The root pointer is used as a entry into a
316 * hashmap of hidden objects. When not active all calls are stubs and have no
317 * side-effects.
318 *
319 * This is intended only for debugging and is turned off by default, as this all
320 * very very unsafe. It is only pointers straight into objects, completely
321 * ignores ownership or any safe practices.
322 *
323 * The parameter @p suffix_with_number makes the variable tracking code suffix
324 * the name of the object with with a number. This allows multiple objects of
325 * the same name name.
326 *
327 * ```c
328 * // On create
329 * u_var_add_root((void*)psmv, "PS Move Controller", true);
330 * u_var_add_rgb_u8((void*)psmv, &psmv->led_color, "LED");
331 * u_var_add_log_level(psmv, &psmv->log_level, "Log level");
332 *
333 * // On destroy, only need to destroy the root object.
334 * u_var_remove_root((void*)psmv);
335 * ```
336 *
337 * @param root Object to be tracked.
338 * @param c_name Name of object, null terminated "C" string.
339 * @param suffix_with_number Should name be suffixed with a number.
340 *
341 * @ingroup aux_util
342 */
343void
344u_var_add_root(void *root, const char *c_name, bool suffix_with_number);
345
346/*!
347 * Remove the root node.
348 *
349 * @ingroup aux_util
350 */
351void
353
354/*!
355 * Visit all root nodes and their variables.
356 *
357 * @ingroup aux_util
358 */
359void
360u_var_visit(u_var_root_cb enter_cb, u_var_root_cb exit_cb, u_var_elm_cb elem_cb, void *priv);
361
362/*!
363 * This forces the variable tracking code to on, it is disabled by default.
364 *
365 * @ingroup aux_util
366 */
367void
369
370#define U_VAR_ADD_FUNCS() \
371 ADD_FUNC(bool, bool, BOOL) \
372 ADD_FUNC(rgb_u8, struct xrt_colour_rgb_u8, RGB_U8) \
373 ADD_FUNC(rgb_f32, struct xrt_colour_rgb_f32, RGB_F32) \
374 ADD_FUNC(u8, uint8_t, U8) \
375 ADD_FUNC(u16, uint16_t, U16) \
376 ADD_FUNC(u64, uint64_t, U64) \
377 ADD_FUNC(i32, int32_t, I32) \
378 ADD_FUNC(i64, int64_t, I64) \
379 ADD_FUNC(f32, float, F32) \
380 ADD_FUNC(f64, double, F64) \
381 ADD_FUNC(f32_arr, struct u_var_f32_arr, F32_ARR) \
382 ADD_FUNC(f32_timing, struct u_var_timing, TIMING) \
383 ADD_FUNC(vec3_i32, struct xrt_vec3_i32, VEC3_I32) \
384 ADD_FUNC(vec3_f32, struct xrt_vec3, VEC3_F32) \
385 ADD_FUNC(pose, struct xrt_pose, POSE) \
386 ADD_FUNC(sink_debug, struct u_sink_debug, SINK_DEBUG) \
387 ADD_FUNC(native_images_debug, struct u_native_images_debug, NATIVE_IMAGES_DEBUG) \
388 ADD_FUNC(log_level, enum u_logging_level, LOG_LEVEL) \
389 ADD_FUNC(ro_text, const char, RO_TEXT) \
390 ADD_FUNC(ro_ftext, const char, RO_FTEXT) \
391 ADD_FUNC(ro_i16, int16_t, RO_I16) \
392 ADD_FUNC(ro_i32, int32_t, RO_I32) \
393 ADD_FUNC(ro_u32, uint32_t, RO_I32) \
394 ADD_FUNC(ro_f32, float, RO_F32) \
395 ADD_FUNC(ro_i64, int64_t, RO_I64) \
396 ADD_FUNC(ro_u64, uint64_t, RO_U64) \
397 ADD_FUNC(ro_f64, double, RO_F64) \
398 ADD_FUNC(ro_vec3_i32, struct xrt_vec3_i32, RO_VEC3_I32) \
399 ADD_FUNC(ro_vec3_f32, struct xrt_vec3, RO_VEC3_F32) \
400 ADD_FUNC(ro_quat_f32, struct xrt_quat, RO_QUAT_F32) \
401 ADD_FUNC(ro_ff_f64, struct m_ff_f64, RO_FF_F64) \
402 ADD_FUNC(ro_ff_vec3_f32, struct m_ff_vec3_f32, RO_FF_VEC3_F32) \
403 ADD_FUNC(gui_header, bool, GUI_HEADER) \
404 ADD_FUNC(gui_header_begin, bool, GUI_HEADER_BEGIN) \
405 ADD_FUNC(gui_header_end, bool, GUI_HEADER_END) \
406 ADD_FUNC(button, struct u_var_button, BUTTON) \
407 ADD_FUNC(combo, struct u_var_combo, COMBO) \
408 ADD_FUNC(draggable_f32, struct u_var_draggable_f32, DRAGGABLE_F32) \
409 ADD_FUNC(draggable_u16, struct u_var_draggable_u16, DRAGGABLE_U16) \
410 ADD_FUNC(histogram_f32, struct u_var_histogram_f32, HISTOGRAM_F32) \
411 ADD_FUNC(curve, struct u_var_curve, CURVE) \
412 ADD_FUNC(curves, struct u_var_curves, CURVES)
413
414#define ADD_FUNC(SUFFIX, TYPE, ENUM) void u_var_add_##SUFFIX(void *, TYPE *, const char *);
415
416U_VAR_ADD_FUNCS()
417
418#undef ADD_FUNC
419
420
421#ifdef __cplusplus
422}
423#endif
void u_var_add_root(void *root, const char *c_name, bool suffix_with_number)
Add a named root object, the u_var subsystem is completely none-invasive to the object it's tracking.
void(* u_var_button_cb)(void *)
Callback for a button action.
Definition: u_var.h:71
void(* u_var_root_cb)(struct u_var_root_info *info, void *)
Callback for entering and leaving root nodes.
Definition: u_var.h:304
#define U_VAR_NAME_STRING_SIZE
Maximum string length for a tracked variable.
Definition: u_var.h:261
void u_var_visit(u_var_root_cb enter_cb, u_var_root_cb exit_cb, u_var_elm_cb elem_cb, void *priv)
Visit all root nodes and their variables.
void u_var_force_on(void)
This forces the variable tracking code to on, it is disabled by default.
void u_var_remove_root(void *root)
Remove the root node.
struct u_var_curve_point(* u_var_curve_getter)(void *data, int i)
Callback for getting points on a curve.
Definition: u_var.h:173
u_var_kind
What kind of variable is this tracking.
Definition: u_var.h:211
void(* u_var_elm_cb)(struct u_var_info *info, void *)
Callback on each variable a root node has.
Definition: u_var.h:311
Definition: m_filter_fifo.c:183
Definition: m_filter_fifo.c:23
A struct for debugging one or more native images.
Definition: u_native_images_debug.h:27
Allows more safely to debug sink inputs and outputs.
Definition: u_sink.h:190
Simple pushable button.
Definition: u_var.h:79
bool disabled
Whether this button is disabled.
Definition: u_var.h:94
char label[64]
Button text, use var name if zeroed.
Definition: u_var.h:87
u_var_button_cb cb
Callback function to execute on button press.
Definition: u_var.h:81
void * ptr
Pointer that will be passed to the function as its only argument.
Definition: u_var.h:84
float width
Button dimensions, zero for auto size.
Definition: u_var.h:90
Combo box information.
Definition: u_var.h:103
int count
Number of options.
Definition: u_var.h:105
int * value
Pointer to the option value.
Definition: u_var.h:111
const char * options
List of count option names separated by \0.
Definition: u_var.h:108
A point on the curve, uses doubles like ImPlotPoint.
Definition: u_var.h:163
A single curve on a plot.
Definition: u_var.h:181
const char * ylabel
Label of the Y axis.
Definition: u_var.h:187
int count
Number of points to draw; param i < count.
Definition: u_var.h:184
const char * xlabel
Label of the X axis.
Definition: u_var.h:186
void * data
User data for getter
Definition: u_var.h:183
const char * label
Curve name.
Definition: u_var.h:185
u_var_curve_getter getter
Getter of 2D points for the curve.
Definition: u_var.h:182
A collection of curves to be plotted.
Definition: u_var.h:196
const char * ylabel
Label of the Y axis.
Definition: u_var.h:202
const char * xlabel
Label of the X axis.
Definition: u_var.h:201
Draggable single precision float information.
Definition: u_var.h:120
Draggable usingned 16-bit integer information.
Definition: u_var.h:133
uint16_t * val
Definition: u_var.h:138
Used to plot an array for values.
Definition: u_var.h:34
Histogram based on single precision bars.
Definition: u_var.h:150
float height
Widget height or 0 for auto.
Definition: u_var.h:154
float width
Widget width or 0 for auto.
Definition: u_var.h:153
int count
Number of bins.
Definition: u_var.h:152
float * values
Bin heights.
Definition: u_var.h:151
Struct that keeps all of the information about the variable, some of the UI state is kept on it.
Definition: u_var.h:270
Struct containing the information about a root object.
Definition: u_var.h:288
uint32_t number
The number of the window, or zero (name and raw_name are the same).
Definition: u_var.h:296
const char * name
The displayed name.
Definition: u_var.h:290
const char * raw_name
Raw name without any suffix.
Definition: u_var.h:293
Used to plot a graph of timing information.
Definition: u_var.h:46
float range
How many units the graph expands by default.
Definition: u_var.h:57
bool center_reference_timing
If false, reference_timing will be the bottom of the graph.
Definition: u_var.h:54
bool dynamic_rescale
Rescale graph's value range when value exceeds range.
Definition: u_var.h:60
float reference_timing
A reference line drawn on the plot.
Definition: u_var.h:51
struct u_var_f32_arr values
Values to be plotted.
Definition: u_var.h:48
const char * unit
A string describing the unit used, not freed.
Definition: u_var.h:63
A object that is sent frames.
Definition: xrt_frame.h:58
Basic logging functionality.
Common defines and enums for XRT.