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}