matrixfurry.com
The open source OpenXR runtime
1// Copyright 2019, 2022, Collabora, Ltd.
2// SPDX-License-Identifier: BSL-1.0
3/*!
4 * @file
5 * @brief Low-pass IIR filter for integers - C wrapper
6 * @author Rylie Pavlik <rylie.pavlik@collabora.com>
7 * @author Malek Hodroj <pocmalek@gmail.com>
8 * @ingroup aux_math
9 */
10
11#pragma once
12
13#include <stdint.h>
14#include <stdbool.h>
15
16#ifdef __cplusplus
17extern "C" {
18#endif
19/*!
20 * An IIR (low pass) filter for integer values.
21 *
22 * Wraps xrt::auxiliary::math::IntegerLowPassIIRFilter - see that if you need a different scalar type.
23 *
24 */
25struct m_lowpass_integer;
26
27/*!
28 * Constructor
29 *
30 * @note Taking alpha, not a cutoff frequency, here, because it's easier with the rational math.
31 *
32 * Together, the two parameters specify the alpha value used to blend between new input and existing state. Larger
33 * values mean more influence from new input.
34 *
35 * @param alpha_numerator The numerator of the alpha value. Must be greater than 0 and less than @p alpha_denominator
36 * @param alpha_denominator The denominator of the alpha value. Must be greater than 0.
37 *
38 * @return null if a parameter is out of range
39 *
40 * @public @memberof m_lowpass_integer
41 */
42struct m_lowpass_integer *
43m_lowpass_integer_create(int64_t alpha_numerator, int64_t alpha_denominator);
44
45
46/*!
47 * Filter a sample
48 *
49 * @param mli self-pointer
50 * @param sample The value to filter
51 *
52 * @public @memberof m_lowpass_integer
53 */
54void
55m_lowpass_integer_add_sample(struct m_lowpass_integer *mli, int64_t sample);
56
57/*!
58 * Get the filtered value.
59 *
60 * Probably 0 or other meaningless value if it's not initialized: see @ref m_lowpass_integer_is_initialized
61 *
62 * @param mli self-pointer
63 *
64 * @public @memberof m_lowpass_integer
65 */
66int64_t
67m_lowpass_integer_get_state(const struct m_lowpass_integer *mli);
68
69/*!
70 * Get whether we have initialized state.
71 *
72 * @param mli self-pointer
73 *
74 * @public @memberof m_lowpass_integer
75 */
76bool
77m_lowpass_integer_is_initialized(const struct m_lowpass_integer *mli);
78
79/*!
80 * Destroy a lowpass integer filter.
81 *
82 * Does null checks.
83 *
84 * @param ptr_to_mli Address of your lowpass integer filter. Will be set to zero.
85 *
86 * @public @memberof m_lowpass_integer
87 */
88void
89m_lowpass_integer_destroy(struct m_lowpass_integer **ptr_to_mli);
90
91#ifdef __cplusplus
92}
93#endif