Skip to main content

plughost_core/
config.rs

1use crate::errors::InputError;
2/// Channel layout of an audio bus. Each layout has one channel order, listed on its variant.
3/// Formats whose native order differs are mapped explicitly; a layout a format cannot express
4/// is refused rather than approximated.
5///
6/// Ls and Rs are the surrounds of layouts without side channels. Layouts that also have side
7/// surrounds (Lss, Rss) list Ls and Rs as the rear surrounds before them. Height channels are
8/// top front (Ltf, Rtf), top middle (Ltm, Rtm) and top rear (Ltr, Rtr); Lw and Rw are the wides.
9/// A new variant also belongs in [`Layout::ALL`], which formats search to recognize layouts.
10#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
11#[non_exhaustive]
12pub enum Layout {
13    /// No bus, for example the input of an instrument.
14    None,
15    /// One center channel.
16    Mono,
17    /// Left, right.
18    Stereo,
19    /// L R C LFE Ls Rs
20    Surround51,
21    /// L R C LFE Ls Rs Lss Rss (7.1 surround with side channels)
22    Surround71,
23    /// L R C
24    Lcr,
25    /// L R Ls Rs
26    Quad,
27    /// L R C Ls Rs
28    Surround50,
29    /// L R C Ls Rs Lss Rss
30    Surround70,
31    /// L R C LFE Ls Rs Ltm Rtm
32    Surround512,
33    /// L R C LFE Ls Rs Ltf Rtf Ltr Rtr
34    Surround514,
35    /// L R C LFE Ls Rs Lss Rss Ltm Rtm
36    Surround712,
37    /// L R C LFE Ls Rs Lss Rss Ltf Rtf Ltr Rtr
38    Surround714,
39    /// L R C LFE Ls Rs Lss Rss Ltf Rtf Ltr Rtr Ltm Rtm Lw Rw
40    Surround916,
41    /// First-order ambisonics: ACN channel order, SN3D normalization.
42    Ambisonics1,
43    /// Second-order ambisonics: ACN channel order, SN3D normalization.
44    Ambisonics2,
45    /// Third-order ambisonics: ACN channel order, SN3D normalization.
46    Ambisonics3,
47    /// Fourth-order ambisonics: ACN channel order, SN3D normalization.
48    Ambisonics4,
49}
50
51impl Layout {
52    /// Every layout, in declaration order.
53    pub const ALL: [Layout; 18] = [
54        Layout::None,
55        Layout::Mono,
56        Layout::Stereo,
57        Layout::Surround51,
58        Layout::Surround71,
59        Layout::Lcr,
60        Layout::Quad,
61        Layout::Surround50,
62        Layout::Surround70,
63        Layout::Surround512,
64        Layout::Surround514,
65        Layout::Surround712,
66        Layout::Surround714,
67        Layout::Surround916,
68        Layout::Ambisonics1,
69        Layout::Ambisonics2,
70        Layout::Ambisonics3,
71        Layout::Ambisonics4,
72    ];
73
74    /// Number of planar channels in this layout.
75    pub fn channels(self) -> usize {
76        match self {
77            Layout::None => 0,
78            Layout::Mono => 1,
79            Layout::Stereo => 2,
80            Layout::Lcr => 3,
81            Layout::Quad | Layout::Ambisonics1 => 4,
82            Layout::Surround50 => 5,
83            Layout::Surround51 => 6,
84            Layout::Surround70 => 7,
85            Layout::Surround71 | Layout::Surround512 => 8,
86            Layout::Ambisonics2 => 9,
87            Layout::Surround514 | Layout::Surround712 => 10,
88            Layout::Surround714 => 12,
89            Layout::Surround916 | Layout::Ambisonics3 => 16,
90            Layout::Ambisonics4 => 25,
91        }
92    }
93}
94
95/// Floating-point precision of the prepared audio buffers.
96#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
97#[non_exhaustive]
98pub enum SampleFormat {
99    /// IEEE 754 single-precision samples.
100    F32,
101    /// IEEE 754 double-precision samples.
102    F64,
103}
104
105/// The processing mode reported to the plugin. Offline rendering is not paced to wall-clock time;
106/// `Realtime` only changes what the plugin is told, for plugins that misbehave in offline mode.
107#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)]
108#[non_exhaustive]
109pub enum ProcessMode {
110    /// Tell the plugin it may use its offline rendering mode. This is the default.
111    #[default]
112    Offline,
113    /// Tell the plugin it is processing in real time; this does not provide real-time scheduling.
114    Realtime,
115}
116
117/// Processing configuration for a plugin’s main input and output buses.
118#[derive(Clone, Copy, Debug, PartialEq)]
119#[non_exhaustive]
120pub struct ProcessConfig {
121    /// Samples per second; must be finite and greater than zero.
122    pub sample_rate: f64,
123    /// Maximum frames per processing call, from 1 through `i32::MAX`.
124    pub max_block_size: usize,
125    /// Sample precision used by every channel.
126    pub sample_format: SampleFormat,
127    /// Requested main input bus layout; `None` for an instrument without input.
128    pub input: Layout,
129    /// Requested main output bus layout.
130    pub output: Layout,
131    /// Processing mode reported to the plugin.
132    pub mode: ProcessMode,
133}
134
135impl ProcessConfig {
136    /// Offline processing of `input` to `output`; see [`Self::with_mode`].
137    #[must_use]
138    pub const fn new(
139        sample_rate: f64,
140        max_block_size: usize,
141        sample_format: SampleFormat,
142        input: Layout,
143        output: Layout,
144    ) -> ProcessConfig {
145        ProcessConfig {
146            sample_rate,
147            max_block_size,
148            sample_format,
149            input,
150            output,
151            mode: ProcessMode::Offline,
152        }
153    }
154
155    /// Reports `mode` to the plugin.
156    #[must_use]
157    pub const fn with_mode(mut self, mode: ProcessMode) -> ProcessConfig {
158        self.mode = mode;
159        self
160    }
161
162    /// Validates scalar values before a format changes the current processing setup.
163    /// Layout and sample-format support are negotiated with the plugin afterwards.
164    pub fn validate(&self) -> Result<(), InputError> {
165        validate_processing(self.sample_rate, self.max_block_size)
166    }
167}
168
169pub(crate) fn validate_processing(
170    sample_rate: f64,
171    max_block_size: usize,
172) -> Result<(), InputError> {
173    if !sample_rate.is_finite() || sample_rate <= 0.0 {
174        return Err(InputError::SampleRate);
175    }
176    // VST3 uses signed 32-bit block lengths; CLAP and AU use unsigned 32-bit lengths.
177    if max_block_size == 0 || max_block_size > i32::MAX as usize {
178        return Err(InputError::BlockSize);
179    }
180    Ok(())
181}