webrtc-constraints 0.1.0

A pure Rust implementation of WebRTC Media Constraints API
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
128
129
130
131
132
133
134

/// The function used to compute the "fitness distance" of a [setting][media_track_settings] value of a [`MediaStreamTrack`][media_stream_track] object.
///
/// # W3C Spec Compliance
///
/// The trait corresponds to the ["fitness distance"][fitness_distance] function in the W3C ["Media Capture and Streams"][media_capture_and_streams_spec] spec.
///
/// [media_stream_track]: https://www.w3.org/TR/mediacapture-streams/#dom-mediastreamtrack
/// [media_track_settings]: https://www.w3.org/TR/mediacapture-streams/#dom-mediatracksettings
/// [fitness_distance]: https://www.w3.org/TR/mediacapture-streams/#dfn-fitness-distance
/// [media_capture_and_streams_spec]: https://www.w3.org/TR/mediacapture-streams
pub trait FitnessDistance<Subject> {
    /// The type returned in the event of a computation error.
    type Error;

    /// Computes the fitness distance of the given `subject` in the range of `0.0..=1.0`.
    ///
    /// A distance of `0.0` denotes it maximally fit, one of `1.0` as maximally unfit.
    fn fitness_distance(&self, subject: Subject) -> Result<f64, Self::Error>;
}

mod empty_constraint;
mod setting;
mod settings;
mod value_constraint;
mod value_range_constraint;
mod value_sequence_constraint;

use std::cmp::Ordering;

pub use self::{
    setting::{SettingFitnessDistanceError, SettingFitnessDistanceErrorKind},
    settings::SettingsFitnessDistanceError,
};

fn nearly_cmp(lhs: f64, rhs: f64) -> Ordering {
    // Based on: https://stackoverflow.com/a/32334103/227536

    let epsilon: f64 = 128.0 * f64::EPSILON;
    let abs_th: f64 = f64::MIN;

    debug_assert!(epsilon < 1.0);

    if lhs == rhs {
        return Ordering::Equal;
    }

    let diff = (lhs - rhs).abs();
    let norm = (lhs.abs() + rhs.abs()).min(f64::MAX);

    if diff < (epsilon * norm).max(abs_th) {
        Ordering::Equal
    } else if lhs < rhs {
        Ordering::Less
    } else {
        Ordering::Greater
    }
}

fn is_nearly_greater_than_or_equal_to(actual: f64, min: f64) -> bool {
    nearly_cmp(actual, min) != Ordering::Less
}

fn is_nearly_less_than_or_equal_to(actual: f64, max: f64) -> bool {
    nearly_cmp(actual, max) != Ordering::Greater
}

fn is_nearly_equal_to(actual: f64, exact: f64) -> bool {
    nearly_cmp(actual, exact) == Ordering::Equal
}

fn relative_fitness_distance(actual: f64, ideal: f64) -> f64 {
    // As specified in step 7 of the `fitness distance` algorithm:
    // <https://www.w3.org/TR/mediacapture-streams/#dfn-fitness-distance>
    //
    // > For all positive numeric constraints […],
    // > the fitness distance is the result of the formula
    // >
    // > ```
    // > (actual == ideal) ? 0 : |actual - ideal| / max(|actual|, |ideal|)
    // > ```
    if (actual - ideal).abs() < f64::EPSILON {
        0.0
    } else {
        let numerator = (actual - ideal).abs();
        let denominator = actual.abs().max(ideal.abs());
        if denominator.abs() < f64::EPSILON {
            // Avoid division by zero crashes:
            0.0
        } else {
            numerator / denominator
        }
    }
}

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

    mod relative_fitness_distance {
        #[test]
        fn zero_distance() {
            // Make sure we're not dividing by zero:
            assert_eq!(super::relative_fitness_distance(0.0, 0.0), 0.0);

            assert_eq!(super::relative_fitness_distance(0.5, 0.5), 0.0);
            assert_eq!(super::relative_fitness_distance(1.0, 1.0), 0.0);
            assert_eq!(super::relative_fitness_distance(2.0, 2.0), 0.0);
        }

        #[test]
        fn fract_distance() {
            assert_eq!(super::relative_fitness_distance(1.0, 2.0), 0.5);
            assert_eq!(super::relative_fitness_distance(2.0, 1.0), 0.5);

            assert_eq!(super::relative_fitness_distance(0.5, 1.0), 0.5);
            assert_eq!(super::relative_fitness_distance(1.0, 0.5), 0.5);

            assert_eq!(super::relative_fitness_distance(0.25, 0.5), 0.5);
            assert_eq!(super::relative_fitness_distance(0.5, 0.25), 0.5);
        }

        #[test]
        fn one_distance() {
            assert_eq!(super::relative_fitness_distance(0.0, 0.5), 1.0);
            assert_eq!(super::relative_fitness_distance(0.5, 0.0), 1.0);

            assert_eq!(super::relative_fitness_distance(0.0, 1.0), 1.0);
            assert_eq!(super::relative_fitness_distance(1.0, 0.0), 1.0);

            assert_eq!(super::relative_fitness_distance(0.0, 2.0), 1.0);
            assert_eq!(super::relative_fitness_distance(2.0, 0.0), 1.0);
        }
    }
}