audio_processor_traits/
parameters.rs

1// Augmented Audio: Audio libraries and applications
2// Copyright (c) 2022 Pedro Tacla Yamada
3//
4// The MIT License (MIT)
5//
6// Permission is hereby granted, free of charge, to any person obtaining a copy
7// of this software and associated documentation files (the "Software"), to deal
8// in the Software without restriction, including without limitation the rights
9// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
10// copies of the Software, and to permit persons to whom the Software is
11// furnished to do so, subject to the following conditions:
12//
13// The above copyright notice and this permission notice shall be included in
14// all copies or substantial portions of the Software.
15//
16// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
22// THE SOFTWARE.
23//! Provides a basic mechanism for defining float parameters and modifying them
24//! through introspection at runtime.
25
26use std::convert::TryFrom;
27
28use audio_garbage_collector::{make_shared, Shared};
29
30/// A shared reference to a boxed generic handle
31pub type AudioProcessorHandleRef = Shared<Box<dyn AudioProcessorHandle>>;
32
33/// Build a shared reference to a boxed generic handle
34pub fn make_handle_ref<T: AudioProcessorHandle + 'static>(v: T) -> AudioProcessorHandleRef {
35    make_shared(Box::new(v))
36}
37
38/// A type which can create an `AudioProcessorHandleRef`
39pub trait AudioProcessorHandleProvider {
40    fn generic_handle(&self) -> AudioProcessorHandleRef;
41}
42
43/// An empty handle with no parameters
44pub struct AudioProcessorEmptyHandle;
45
46impl AudioProcessorHandle for AudioProcessorEmptyHandle {
47    fn parameter_count(&self) -> usize {
48        0
49    }
50
51    fn get_parameter_spec(&self, _index: usize) -> ParameterSpec {
52        panic!("There are no parameter specs")
53    }
54
55    fn get_parameter(&self, _index: usize) -> Option<ParameterValue> {
56        None
57    }
58
59    fn set_parameter(&self, _index: usize, _request: ParameterValue) {}
60}
61
62/// This trait can be implemented by AudioProcessor handles to provide runtime introspection on
63/// the parameters that a processor provides.
64pub trait AudioProcessorHandle: Send + Sync {
65    /// This method should return the name of the processor. This may displayed in a GUI application
66    /// as the effect/instrument name.
67    fn name(&self) -> String {
68        "AudioProcessorHandle::name can be set at the processor handle with a name for the handle"
69            .to_string()
70    }
71
72    /// Should return the number of parameters.
73    fn parameter_count(&self) -> usize;
74
75    /// After finding the number of parameters a callee will get `ParameterSpec` declarations
76    /// giving more metadata about this parameter.
77    fn get_parameter_spec(&self, index: usize) -> ParameterSpec;
78
79    /// Should return the value for the parameter at this index
80    fn get_parameter(&self, index: usize) -> Option<ParameterValue>;
81
82    /// Should set the value for the parameter at this index
83    fn set_parameter(&self, index: usize, request: ParameterValue);
84}
85
86/// A runtime typed parameter value
87#[derive(PartialEq, Clone, Debug)]
88pub enum ParameterValue {
89    Float { value: f32 },
90}
91
92impl From<f32> for ParameterValue {
93    fn from(value: f32) -> Self {
94        Self::Float { value }
95    }
96}
97
98impl TryFrom<ParameterValue> for f32 {
99    type Error = ();
100
101    fn try_from(value: ParameterValue) -> Result<Self, Self::Error> {
102        let ParameterValue::Float { value } = value;
103        Ok(value)
104    }
105}
106
107#[derive(Debug, Clone)]
108pub struct FloatType {
109    pub range: (f32, f32),
110    pub step: Option<f32>,
111}
112
113#[derive(Debug, Clone)]
114pub enum ParameterType {
115    Float(FloatType),
116}
117
118impl ParameterType {
119    pub fn float(&self) -> Option<&FloatType> {
120        let ParameterType::Float(inner) = self;
121        Some(inner)
122    }
123}
124
125/// Meta-data around a parameter. A GUI application may use this information to display
126/// the label around the parameter and decide what type of control to render to modify it.
127#[derive(Debug, Clone)]
128pub struct ParameterSpec {
129    name: String,
130    ty: ParameterType,
131}
132
133impl ParameterSpec {
134    pub fn new(name: String, ty: ParameterType) -> Self {
135        ParameterSpec { name, ty }
136    }
137
138    pub fn name(&self) -> &str {
139        &self.name
140    }
141
142    pub fn ty(&self) -> &ParameterType {
143        &self.ty
144    }
145}
146
147#[cfg(test)]
148mod test {
149    use std::convert::TryFrom;
150
151    use super::*;
152
153    #[test]
154    fn test_empty_handle_name() {
155        let handle = AudioProcessorEmptyHandle;
156        assert_eq!(handle.name(), "AudioProcessorHandle::name can be set at the processor handle with a name for the handle");
157    }
158
159    #[test]
160    fn test_empty_handle_parameter_count() {
161        let handle = AudioProcessorEmptyHandle;
162        assert_eq!(handle.parameter_count(), 0);
163    }
164
165    #[test]
166    fn test_empty_handle_get_parameter() {
167        let handle = AudioProcessorEmptyHandle;
168        assert_eq!(handle.get_parameter(0), None);
169    }
170
171    #[test]
172    fn test_parameter_value() {
173        let v = ParameterValue::Float { value: 0.5 };
174        assert_eq!(v, 0.5.into());
175        assert_eq!(f32::try_from(v).unwrap(), 0.5);
176    }
177
178    #[test]
179    fn test_parameter_type() {
180        let ty = ParameterType::Float(FloatType {
181            range: (0.0, 1.0),
182            step: None,
183        });
184        assert!(ty.float().is_some());
185    }
186
187    #[test]
188    fn test_parameter_spec() {
189        let spec = ParameterSpec::new(
190            "test".to_string(),
191            ParameterType::Float(FloatType {
192                range: (0.0, 1.0),
193                step: None,
194            }),
195        );
196        assert_eq!(spec.name(), "test");
197        assert!(spec.ty().float().is_some());
198    }
199
200    #[test]
201    fn test_parameter_value_from_f32() {
202        let v = ParameterValue::Float { value: 0.5 };
203        assert_eq!(v, 0.5.into());
204    }
205}
audio_processor_traits/parameters.rs

audio_processor_traits/
parameters.rs
