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_U16,
236 U_VAR_KIND_RO_U32,
237 U_VAR_KIND_RO_F32,
238 U_VAR_KIND_RO_I64,
239 U_VAR_KIND_RO_U64,
240 U_VAR_KIND_RO_F64,
241 U_VAR_KIND_RO_I64_NS,
242 U_VAR_KIND_RO_VEC3_I32,
243 U_VAR_KIND_RO_VEC3_F32,
244 U_VAR_KIND_RO_QUAT_F32,
245 U_VAR_KIND_RO_FF_F64,
246 U_VAR_KIND_RO_FF_VEC3_F32,
247 U_VAR_KIND_GUI_HEADER,
248 U_VAR_KIND_GUI_HEADER_BEGIN,
249 U_VAR_KIND_GUI_HEADER_END,
250 U_VAR_KIND_BUTTON,
251 U_VAR_KIND_COMBO,
252 U_VAR_KIND_HISTOGRAM_F32,
253 U_VAR_KIND_DRAGGABLE_U16,
254 U_VAR_KIND_CURVE,
255 U_VAR_KIND_CURVES,
256};
257
258/*!
259 * Maximum string length for a tracked variable.
260 *
261 * @ingroup aux_util
262 */
263#define U_VAR_NAME_STRING_SIZE 256
264
265/*!
266 * Struct that keeps all of the information about the variable, some of the UI
267 * state is kept on it.
268 *
269 * @ingroup aux_util
270 */
272{
273 char name[U_VAR_NAME_STRING_SIZE];
274 void *ptr;
275
276 enum u_var_kind kind;
277
278 struct
279 {
280 bool graphed;
281 } gui;
282};
283
284/*!
285 * Struct containing the information about a root object.
286 *
287 * @ingroup aux_util
288 */
290{
291 //! The displayed name.
292 const char *name;
293
294 //! Raw name without any suffix.
295 const char *raw_name;
296
297 //! The number of the window, or zero (name and raw_name are the same).
298 uint32_t number;
299};
300
301/*!
302 * Callback for entering and leaving root nodes.
303 *
304 * @ingroup aux_util
305 */
306typedef void (*u_var_root_cb)(struct u_var_root_info *info, void *);
307
308/*!
309 * Callback on each variable a root node has.
310 *
311 * @ingroup aux_util
312 */
313typedef void (*u_var_elm_cb)(struct u_var_info *info, void *);
314
315/*!
316 * Add a named root object, the u_var subsystem is completely none-invasive
317 * to the object it's tracking. The root pointer is used as a entry into a
318 * hashmap of hidden objects. When not active all calls are stubs and have no
319 * side-effects.
320 *
321 * This is intended only for debugging and is turned off by default, as this all
322 * very very unsafe. It is only pointers straight into objects, completely
323 * ignores ownership or any safe practices.
324 *
325 * The parameter @p suffix_with_number makes the variable tracking code suffix
326 * the name of the object with with a number. This allows multiple objects of
327 * the same name name.
328 *
329 * ```c
330 * // On create
331 * u_var_add_root((void*)psmv, "PS Move Controller", true);
332 * u_var_add_rgb_u8((void*)psmv, &psmv->led_color, "LED");
333 * u_var_add_log_level(psmv, &psmv->log_level, "Log level");
334 *
335 * // On destroy, only need to destroy the root object.
336 * u_var_remove_root((void*)psmv);
337 * ```
338 *
339 * @param root Object to be tracked.
340 * @param c_name Name of object, null terminated "C" string.
341 * @param suffix_with_number Should name be suffixed with a number.
342 *
343 * @ingroup aux_util
344 */
345void
346u_var_add_root(void *root, const char *c_name, bool suffix_with_number);
347
348/*!
349 * Remove the root node.
350 *
351 * @ingroup aux_util
352 */
353void
355
356/*!
357 * Visit all root nodes and their variables.
358 *
359 * @ingroup aux_util
360 */
361void
362u_var_visit(u_var_root_cb enter_cb, u_var_root_cb exit_cb, u_var_elm_cb elem_cb, void *priv);
363
364/*!
365 * This forces the variable tracking code to on, it is disabled by default.
366 *
367 * @ingroup aux_util
368 */
369void
371
372#define U_VAR_ADD_FUNCS() \
373 ADD_FUNC(bool, bool, BOOL) \
374 ADD_FUNC(rgb_u8, struct xrt_colour_rgb_u8, RGB_U8) \
375 ADD_FUNC(rgb_f32, struct xrt_colour_rgb_f32, RGB_F32) \
376 ADD_FUNC(u8, uint8_t, U8) \
377 ADD_FUNC(u16, uint16_t, U16) \
378 ADD_FUNC(u64, uint64_t, U64) \
379 ADD_FUNC(i32, int32_t, I32) \
380 ADD_FUNC(i64, int64_t, I64) \
381 ADD_FUNC(f32, float, F32) \
382 ADD_FUNC(f64, double, F64) \
383 ADD_FUNC(f32_arr, struct u_var_f32_arr, F32_ARR) \
384 ADD_FUNC(f32_timing, struct u_var_timing, TIMING) \
385 ADD_FUNC(vec3_i32, struct xrt_vec3_i32, VEC3_I32) \
386 ADD_FUNC(vec3_f32, struct xrt_vec3, VEC3_F32) \
387 ADD_FUNC(pose, struct xrt_pose, POSE) \
388 ADD_FUNC(sink_debug, struct u_sink_debug, SINK_DEBUG) \
389 ADD_FUNC(native_images_debug, struct u_native_images_debug, NATIVE_IMAGES_DEBUG) \
390 ADD_FUNC(log_level, enum u_logging_level, LOG_LEVEL) \
391 ADD_FUNC(ro_text, const char, RO_TEXT) \
392 ADD_FUNC(ro_ftext, const char, RO_FTEXT) \
393 ADD_FUNC(ro_i16, int16_t, RO_I16) \
394 ADD_FUNC(ro_i32, int32_t, RO_I32) \
395 ADD_FUNC(ro_u16, uint16_t, RO_U16) \
396 ADD_FUNC(ro_u32, uint32_t, RO_U32) \
397 ADD_FUNC(ro_f32, float, RO_F32) \
398 ADD_FUNC(ro_i64, int64_t, RO_I64) \
399 ADD_FUNC(ro_u64, uint64_t, RO_U64) \
400 ADD_FUNC(ro_f64, double, RO_F64) \
401 ADD_FUNC(ro_i64_ns, int64_t, RO_I64_NS) \
402 ADD_FUNC(ro_vec3_i32, struct xrt_vec3_i32, RO_VEC3_I32) \
403 ADD_FUNC(ro_vec3_f32, struct xrt_vec3, RO_VEC3_F32) \
404 ADD_FUNC(ro_quat_f32, struct xrt_quat, RO_QUAT_F32) \
405 ADD_FUNC(ro_ff_f64, struct m_ff_f64, RO_FF_F64) \
406 ADD_FUNC(ro_ff_vec3_f32, struct m_ff_vec3_f32, RO_FF_VEC3_F32) \
407 ADD_FUNC(gui_header, bool, GUI_HEADER) \
408 ADD_FUNC(gui_header_begin, bool, GUI_HEADER_BEGIN) \
409 ADD_FUNC(gui_header_end, bool, GUI_HEADER_END) \
410 ADD_FUNC(button, struct u_var_button, BUTTON) \
411 ADD_FUNC(combo, struct u_var_combo, COMBO) \
412 ADD_FUNC(draggable_f32, struct u_var_draggable_f32, DRAGGABLE_F32) \
413 ADD_FUNC(draggable_u16, struct u_var_draggable_u16, DRAGGABLE_U16) \
414 ADD_FUNC(histogram_f32, struct u_var_histogram_f32, HISTOGRAM_F32) \
415 ADD_FUNC(curve, struct u_var_curve, CURVE) \
416 ADD_FUNC(curves, struct u_var_curves, CURVES)
417
418#define ADD_FUNC(SUFFIX, TYPE, ENUM) void u_var_add_##SUFFIX(void *, TYPE *, const char *);
419
420U_VAR_ADD_FUNCS()
421
422#undef ADD_FUNC
423
424
425#ifdef __cplusplus
426}
427#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:306
#define U_VAR_NAME_STRING_SIZE
Maximum string length for a tracked variable.
Definition: u_var.h:263
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:313
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:211
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:272
Struct containing the information about a root object.
Definition: u_var.h:290
uint32_t number
The number of the window, or zero (name and raw_name are the same).
Definition: u_var.h:298
const char * name
The displayed name.
Definition: u_var.h:292
const char * raw_name
Raw name without any suffix.
Definition: u_var.h:295
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.