Skip to main content

plughost_core/
parameter.rs

1/// Native parameter properties. All flags default to false.
2#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)]
3#[non_exhaustive]
4pub struct ParameterFlags {
5    /// The parameter has discrete values; `step_count` describes the intervals.
6    pub discrete: bool,
7    /// The plugin permits sample-timed automation for this parameter.
8    pub automatable: bool,
9    /// The value is observable but host edits are prohibited.
10    pub read_only: bool,
11    /// The native parameter is marked hidden from ordinary host interfaces.
12    pub hidden: bool,
13    /// This parameter controls native bypass.
14    pub bypass: bool,
15    /// The native parameter represents a labeled list of choices.
16    pub list: bool,
17    /// This parameter selects a native program.
18    pub program_change: bool,
19}
20
21/// Native parameter identity, labels, normalized default, and edit capabilities.
22#[derive(Clone, Debug, PartialEq)]
23#[non_exhaustive]
24pub struct ParameterInfo {
25    /// VST3 or CLAP parameter ID, or Audio Unit parameter address.
26    pub id: u64,
27    /// Full native display name.
28    pub title: String,
29    /// Abbreviated native display name, or empty when unavailable.
30    pub short_title: String,
31    /// Native unit label, or empty when unavailable.
32    pub units: String,
33    /// Number of intervals; flags.discrete distinguishes a constant discrete value from continuous.
34    pub step_count: u32,
35    /// Native default, normalized to 0..=1. None when the format does not expose it.
36    pub default_value: Option<f64>,
37    /// Native capabilities and presentation flags.
38    pub flags: ParameterFlags,
39}
40
41impl ParameterInfo {
42    /// A continuous parameter without a default, short title, units or flags.
43    #[must_use]
44    pub fn new(id: u64, title: impl Into<String>) -> ParameterInfo {
45        ParameterInfo {
46            id,
47            title: title.into(),
48            short_title: String::new(),
49            units: String::new(),
50            step_count: 0,
51            default_value: None,
52            flags: ParameterFlags::default(),
53        }
54    }
55
56    /// Validates a writable, automatable normalized value and rounds discrete steps.
57    /// Rejects non-finite values and values outside `0..=1` before quantization.
58    pub fn automation_value(&self, value: f64) -> Result<f64, crate::InputError> {
59        self.validate_edit(value)?;
60        if !self.flags.automatable {
61            return Err(crate::InputError::NotAutomatable { id: self.id });
62        }
63        Ok(if self.step_count == 0 {
64            value
65        } else {
66            (value * f64::from(self.step_count)).round() / f64::from(self.step_count)
67        })
68    }
69
70    /// Rejects a host edit before a controller or processing queue is changed. Internal to the
71    /// plughost crates; exempt from semver.
72    #[doc(hidden)]
73    pub fn validate_edit(&self, value: f64) -> Result<(), crate::InputError> {
74        if !value.is_finite() || !(0.0..=1.0).contains(&value) {
75            return Err(crate::InputError::ParameterValue);
76        }
77        if self.flags.read_only {
78            return Err(crate::InputError::ReadOnlyParameter { id: self.id });
79        }
80        Ok(())
81    }
82}
83
84/// A normalized parameter value that takes effect at a sample offset within a block.
85#[derive(Clone, Copy, Debug, PartialEq)]
86#[non_exhaustive]
87pub struct ParameterChange {
88    /// Native parameter ID or Audio Unit address.
89    pub id: u64,
90    /// Zero-based sample offset relative to the supplied processing block.
91    pub offset: usize,
92    /// Finite normalized value in `0..=1`.
93    pub value: f64,
94}
95
96impl ParameterChange {
97    /// Native parameter `id` taking normalized `value` from sample `offset`.
98    #[must_use]
99    pub const fn new(id: u64, offset: usize, value: f64) -> ParameterChange {
100        ParameterChange { id, offset, value }
101    }
102}
103
104/// A point on one slot's automation lane. Offsets are relative to the supplied block/render.
105/// Points hold their value until the next point; simultaneous points preserve input order.
106#[derive(Clone, Copy, Debug, PartialEq)]
107#[non_exhaustive]
108pub struct AutomationEvent {
109    /// Zero-based index of the plugin slot receiving the change.
110    pub slot: usize,
111    /// Parameter ID, sample offset, and normalized value.
112    pub change: ParameterChange,
113}
114
115impl AutomationEvent {
116    /// `change` for the plugin in `slot`.
117    #[must_use]
118    pub const fn new(slot: usize, change: ParameterChange) -> AutomationEvent {
119        AutomationEvent { slot, change }
120    }
121}
122
123/// Checks nondecreasing offsets strictly below `frames` and finite normalized values.
124/// Does not query parameter metadata or enforce the per-block event budget.
125pub fn changes_fit(changes: &[ParameterChange], frames: usize) -> bool {
126    changes
127        .iter()
128        .all(|c| c.offset < frames && c.value.is_finite() && (0.0..=1.0).contains(&c.value))
129        && changes
130            .windows(2)
131            .all(|pair| pair[0].offset <= pair[1].offset)
132}
133
134/// Bound for caller text and native UTF-8 displays (VST3 has its own String128 output bound).
135pub const PARAMETER_TEXT_BYTES: usize = 4096;
136
137/// Rejects text containing NUL or exceeding `PARAMETER_TEXT_BYTES` UTF-8 bytes.
138pub fn validate_parameter_text(text: &str) -> Result<(), crate::InputError> {
139    if text.len() > PARAMETER_TEXT_BYTES || text.contains('\0') {
140        Err(crate::InputError::ParameterText)
141    } else {
142        Ok(())
143    }
144}
145
146/// Rejects non-finite values and values outside the inclusive normalized range `0..=1`.
147pub fn validate_normalized(value: f64) -> Result<(), crate::InputError> {
148    if value.is_finite() && (0.0..=1.0).contains(&value) {
149        Ok(())
150    } else {
151        Err(crate::InputError::ParameterValue)
152    }
153}
154
155/// One native unit or group in a parameter’s root-to-leaf hierarchy.
156#[derive(Clone, Debug, PartialEq, Eq)]
157#[non_exhaustive]
158pub struct ParameterGroup {
159    /// VST3 unit ID, CLAP module path, or AU group key path.
160    pub id: String,
161    /// Native group display name.
162    pub name: String,
163    /// Native VST3 program-list association, when supplied by the unit.
164    pub program_list_id: Option<i32>,
165}
166
167impl ParameterGroup {
168    /// Each field as given. Internal to the plughost crates; exempt from semver.
169    #[doc(hidden)]
170    #[must_use]
171    pub fn new(id: String, name: String, program_list_id: Option<i32>) -> ParameterGroup {
172        ParameterGroup {
173            id,
174            name,
175            program_list_id,
176        }
177    }
178}
179
180/// A fresh query. Endpoints describe the normalized mapping, not a linear scale.
181#[derive(Clone, Debug, PartialEq)]
182#[non_exhaustive]
183pub struct ParameterDetails {
184    /// Current parameter metadata, including flags.
185    pub info: ParameterInfo,
186    /// AU AudioUnitParameterUnit code. Other formats do not expose this unit enumeration.
187    pub native_unit: Option<u32>,
188    /// Native value corresponding to normalized zero.
189    pub plain_at_zero: f64,
190    /// Native value corresponding to normalized one.
191    pub plain_at_one: f64,
192    /// Root to leaf. None means unavailable; Some(empty) is ungrouped.
193    pub groups: Option<Vec<ParameterGroup>>,
194}
195
196impl ParameterDetails {
197    /// Details without a native unit or group information.
198    #[must_use]
199    pub fn new(info: ParameterInfo, plain_at_zero: f64, plain_at_one: f64) -> ParameterDetails {
200        ParameterDetails {
201            info,
202            native_unit: None,
203            plain_at_zero,
204            plain_at_one,
205            groups: None,
206        }
207    }
208}
209
210/// Maximum number of discrete choices returned by a single page request.
211pub const PARAMETER_CHOICE_PAGE_SIZE: u32 = 256;
212
213/// One discrete parameter choice and its native display conversion.
214#[derive(Clone, Debug, PartialEq)]
215#[non_exhaustive]
216pub struct ParameterChoice {
217    /// Zero-based discrete choice index.
218    pub index: u64,
219    /// Choice value in the inclusive normalized range `0..=1`.
220    pub normalized: f64,
221    /// Value expressed in the plugin’s native units.
222    pub plain: f64,
223    /// Native display text for this choice.
224    pub text: String,
225}
226
227impl ParameterChoice {
228    /// Each field as given. Internal to the plughost crates; exempt from semver.
229    #[doc(hidden)]
230    #[must_use]
231    pub fn new(index: u64, normalized: f64, plain: f64, text: String) -> ParameterChoice {
232        ParameterChoice {
233            index,
234            normalized,
235            plain,
236            text,
237        }
238    }
239}
240
241/// A bounded slice of a discrete parameter’s native choices.
242#[derive(Clone, Debug, PartialEq)]
243#[non_exhaustive]
244pub struct ParameterChoicePage {
245    /// Total number of discrete choices, including both endpoints.
246    pub total: u64,
247    /// Index of the first returned choice.
248    pub start: u64,
249    /// Choices in ascending index order; the final page may be shorter than requested.
250    pub choices: Vec<ParameterChoice>,
251}
252
253impl ParameterChoicePage {
254    /// Each field as given. Internal to the plughost crates; exempt from semver.
255    #[doc(hidden)]
256    #[must_use]
257    pub fn new(total: u64, start: u64, choices: Vec<ParameterChoice>) -> ParameterChoicePage {
258        ParameterChoicePage {
259            total,
260            start,
261            choices,
262        }
263    }
264}
265
266/// Checks the page-size limit and the representable discrete-choice index range.
267pub fn validate_choice_page(start: u64, count: u32) -> Result<(), crate::InputError> {
268    if count == 0 || count > PARAMETER_CHOICE_PAGE_SIZE || start > u64::from(u32::MAX) + 1 {
269        Err(crate::InputError::ParameterChoicePage)
270    } else {
271        Ok(())
272    }
273}