pot-head 0.2.1

A no_std Rust library for processing raw potmeter inputs in embedded systems
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127

//! Response curve implementations.
//!
//! Transforms normalized input (0.0..1.0) through different response curves.

/// Response curve types for potentiometer output.
#[derive(Debug, Clone, Copy, PartialEq)]
pub enum ResponseCurve {
    /// Linear response (1:1 mapping).
    Linear,

    /// Logarithmic response (audio taper).
    ///
    /// Requires `std-math` feature and `libm` dependency.
    #[cfg(feature = "std-math")]
    Logarithmic,
}

impl ResponseCurve {
    /// Apply the response curve to a normalized value (0.0..1.0).
    ///
    /// Returns the transformed value, also in the range 0.0..1.0.
    #[inline]
    pub fn apply(&self, normalized: f32) -> f32 {
        match self {
            ResponseCurve::Linear => normalized,

            #[cfg(feature = "std-math")]
            ResponseCurve::Logarithmic => apply_logarithmic(normalized),
        }
    }
}

/// Apply logarithmic (audio taper) curve.
///
/// Uses exponential function to create logarithmic response:
/// output = (e^(3x) - 1) / (e^3 - 1)
///
/// This gives perceptually linear volume control where:
/// - Lower values spread out (fine control at low volumes)
/// - Higher values compress (coarse control at high volumes)
#[cfg(feature = "std-math")]
#[inline]
fn apply_logarithmic(normalized: f32) -> f32 {
    const E3_MINUS_1: f32 = 19.085_537; // e^3 - 1 precomputed

    // Clamp to valid range to prevent edge cases
    let x = normalized.clamp(0.0, 1.0);

    // Compute e^(3x) using libm
    let exp_3x = libm::expf(3.0 * x);

    // Apply formula: (e^(3x) - 1) / (e^3 - 1)
    (exp_3x - 1.0) / E3_MINUS_1
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_linear_curve() {
        let curve = ResponseCurve::Linear;

        assert_eq!(curve.apply(0.0), 0.0);
        assert_eq!(curve.apply(0.25), 0.25);
        assert_eq!(curve.apply(0.5), 0.5);
        assert_eq!(curve.apply(0.75), 0.75);
        assert_eq!(curve.apply(1.0), 1.0);
    }

    #[cfg(feature = "std-math")]
    #[test]
    fn test_logarithmic_curve() {
        let curve = ResponseCurve::Logarithmic;

        // Boundary conditions
        let result_0 = curve.apply(0.0);
        let result_1 = curve.apply(1.0);

        assert!(
            (result_0 - 0.0).abs() < 0.001,
            "Expected ~0.0, got {}",
            result_0
        );
        assert!(
            (result_1 - 1.0).abs() < 0.001,
            "Expected ~1.0, got {}",
            result_1
        );

        // Logarithmic curve should have more resolution at lower values
        // i.e., output at 0.25 should be significantly less than 0.25
        let result_quarter = curve.apply(0.25);
        assert!(
            result_quarter < 0.15,
            "Expected <0.15, got {}",
            result_quarter
        );

        // Output at 0.5 should be less than 0.5 (shifted down)
        let result_half = curve.apply(0.5);
        assert!(result_half < 0.5, "Expected <0.5, got {}", result_half);

        // Monotonically increasing
        assert!(result_0 < result_quarter);
        assert!(result_quarter < result_half);
        assert!(result_half < result_1);
    }

    #[cfg(feature = "std-math")]
    #[test]
    fn test_logarithmic_curve_clamping() {
        let curve = ResponseCurve::Logarithmic;

        // Values outside range should be clamped
        assert!((curve.apply(-0.1) - 0.0).abs() < 0.001);
        assert!((curve.apply(1.1) - 1.0).abs() < 0.001);
    }

    #[test]
    fn test_response_curve_copy() {
        let curve1 = ResponseCurve::Linear;
        let curve2 = curve1;

        assert_eq!(curve1, curve2);
    }
}