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}