lotussim-shared 0.6.3

Shared types for LOTUS-Simulator scripts. Depend on `lotussim-script` instead of using this crate directly.
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

//! Logische Controller-Achsen und Force Feedback, getrennt von Tastenaktionen.
//!
//! Logical controller axes and force feedback, separate from button actions.

use serde::{Deserialize, Serialize};

/// Achsenwert ohne Belegung und Ruhelage eines zentrierten Gebers.
///
/// Axis value without a binding, and the rest position of a centered control.
pub const AXIS_CENTER: f32 = 0.5;

/// Beschreibt eine Achse, die bei der Engine registriert werden kann.
///
/// Describes an axis that can be registered with the engine.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct RegisterAxis {
    /// Eindeutige Achsen-ID für Scripts und die Belegung.
    ///
    /// Unique axis identifier used by scripts and bindings.
    pub id: String,
}

impl RegisterAxis {
    /// Erstellt einen neuen Registrierungseintrag für eine Achse.
    ///
    /// Creates a new axis registration entry.
    pub fn new(id: impl Into<String>) -> Self {
        Self { id: id.into() }
    }
}

/// Rückstellkraft einer Achse.
///
/// Restoring force of an axis.
///
/// `coefficient` und `saturation` sind unbeschränkte endliche Stärken.
/// Der Nennbereich ist `0..=1`. Die Engine multipliziert mit der Geräte-Intensität
/// und klemmt erst danach auf `0..=1`.
/// `offset` verschiebt die Federmitte und wird danach auf `-1..=1` geklemmt, ohne Skalierung.
/// `0` lässt die Federmitte unverändert.
///
/// `coefficient` and `saturation` are unrestricted finite strengths.
/// The nominal range is `0..=1`. The engine multiplies by the device intensity
/// and only then clamps to `0..=1`.
/// `offset` shifts the spring center and is then clamped to `-1..=1`, without scaling.
/// `0` leaves the spring center unchanged.
#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
pub struct SpringForce {
    /// Steifigkeit der Feder.
    ///
    /// Spring stiffness.
    pub coefficient: f32,
    /// Obere Grenze der Kraft.
    ///
    /// Upper bound of the force.
    pub saturation: f32,
    /// Verschiebung der Federmitte.
    ///
    /// Shift of the spring center.
    pub offset: f32,
}

/// Schwingung entlang einer Achse.
///
/// Oscillation along an axis.
#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
pub struct AxisVibration {
    /// Stärke als unbeschränkter endlicher Wert. `0` schaltet die Schwingung aus.
    /// Die Engine multipliziert mit der Geräte-Intensität und klemmt erst danach auf `0..=1`.
    ///
    /// Strength as an unrestricted finite value. `0` turns the oscillation off.
    /// The engine multiplies by the device intensity and only then clamps to `0..=1`.
    pub magnitude: f32,
    /// Frequenz in Hertz.
    ///
    /// Frequency in hertz.
    pub frequency_hz: f32,
}

/// Zuletzt gewünschtes Force Feedback einer logischen Achse.
///
/// Latest requested force feedback for one logical axis.
#[derive(Debug, Clone, Copy, PartialEq, Default, Serialize, Deserialize)]
pub struct AxisForceFeedback {
    /// Feder. `None`, solange das Script noch keine gesetzt hat.
    ///
    /// Spring. `None` until the script sets one.
    pub spring: Option<SpringForce>,
    /// Reibung, `0` heißt aus.
    ///
    /// Friction; `0` means off.
    pub friction: f32,
    /// Schwingung. `None` heißt aus.
    ///
    /// Oscillation. `None` means off.
    pub vibration: Option<AxisVibration>,
}

/// Begrenzt einen endlichen Wert auf `0..=1`. Nicht endliche Werte werden 0.
///
/// Clamps a finite value to `0..=1`. Non-finite values become 0.
pub fn clamp_unit(value: f32) -> f32 {
    if value.is_finite() {
        value.clamp(0.0, 1.0)
    } else {
        0.0
    }
}

/// Begrenzt einen endlichen Wert auf `-1..=1`. Nicht endliche Werte werden 0.
///
/// Clamps a finite value to `-1..=1`. Non-finite values become 0.
pub fn clamp_signed_unit(value: f32) -> f32 {
    if value.is_finite() {
        value.clamp(-1.0, 1.0)
    } else {
        0.0
    }
}

/// Begrenzt eine Frequenz auf `>= 0`. Nicht endliche Werte werden 0.
///
/// Clamps a frequency to `>= 0`. Non-finite values become 0.
pub fn clamp_frequency_hz(value: f32) -> f32 {
    if value.is_finite() {
        value.max(0.0)
    } else {
        0.0
    }
}