plughost_core/event_routing.rs
1//! A plugin's event ports, and the routes that carry events from a chain's event inputs through
2//! its slots to its event outputs.
3
4use crate::{AudioDirection, InputError, Support};
5
6/// Maximum external event inputs of a chain, and event routes or collected outputs of one slot.
7pub const MAX_EVENT_PORTS: usize = 16;
8
9/// A native event port. IDs are scoped to a direction; `index` is the native position that
10/// directly hosted plugins use as a [`Event::port`](crate::Event::port).
11#[derive(Clone, Debug, PartialEq, Eq)]
12#[non_exhaustive]
13pub struct EventPortInfo {
14 /// Native event port ID, scoped to its direction.
15 pub id: u64,
16 /// Native port position used by directly hosted processing.
17 pub index: u32,
18 /// Native display name.
19 pub name: String,
20 /// Whether this port receives or produces events.
21 pub direction: AudioDirection,
22 /// MIDI 1.0 channel messages, natively or through the format's note events and parameter
23 /// mapping. Which messages a plugin uses remains its own choice.
24 pub midi: Support,
25 /// System exclusive messages.
26 pub sysex: Support,
27 /// Notes keep their IDs and the expressions of single notes arrive: CLAP ports that take the
28 /// CLAP dialect, and VST3 buses whose controller lists note expressions for them. Pressure
29 /// also reaches ports without it, as poly pressure.
30 pub note_expression: Support,
31 /// MPE: MIDI 1.0 with each note on its own channel, whose pitch bend, channel pressure and
32 /// controller 74 shape that note. plughost delivers it as MIDI either way.
33 pub mpe: Support,
34}
35
36impl EventPortInfo {
37 /// A port whose support for each kind of event is unknown.
38 #[must_use]
39 pub fn new(id: u64, index: u32, name: impl Into<String>, direction: AudioDirection) -> Self {
40 EventPortInfo {
41 id,
42 index,
43 name: name.into(),
44 direction,
45 midi: Support::Unknown,
46 sysex: Support::Unknown,
47 note_expression: Support::Unknown,
48 mpe: Support::Unknown,
49 }
50 }
51}
52
53/// Where a slot's event input port takes events from.
54#[derive(Clone, Copy, Debug, PartialEq, Eq)]
55#[non_exhaustive]
56pub enum EventSource {
57 /// One of the chain's external event inputs, by index.
58 External {
59 /// Zero-based index into the chain’s external event inputs.
60 port: usize,
61 },
62 /// An event output port of the previous slot, by native ID; it must be one of that slot's
63 /// collected outputs.
64 Previous {
65 /// Native output port ID of the immediately preceding slot.
66 port: u64,
67 },
68}
69
70/// One source delivered to a native event input port. Several routes to one port merge in offset
71/// order; at equal offsets, events keep the order of the routes, then their source order.
72#[derive(Clone, Copy, Debug, PartialEq, Eq)]
73#[non_exhaustive]
74pub struct EventInputRoute {
75 /// Native input port ID receiving this route.
76 pub port: u64,
77 /// External input or collected output of the preceding slot.
78 pub source: EventSource,
79}
80
81impl EventInputRoute {
82 /// Native event input `port` fed from `source`.
83 #[must_use]
84 pub const fn new(port: u64, source: EventSource) -> EventInputRoute {
85 EventInputRoute { port, source }
86 }
87}
88
89/// A slot's event routing. Native event ports not named here are left inactive where the format
90/// allows. The last slot's collected outputs, in this order, are the chain's event outputs.
91#[derive(Clone, Debug, Default, PartialEq, Eq)]
92#[non_exhaustive]
93pub struct SlotEventConfig {
94 /// Routes merged by offset; equal-offset events retain route and source order.
95 pub inputs: Vec<EventInputRoute>,
96 /// Native event output ports whose events are collected.
97 pub outputs: Vec<u64>,
98}
99
100/// The event ports a slot's native preparation activates.
101#[derive(Clone, Debug, Default, PartialEq, Eq)]
102#[non_exhaustive]
103pub struct EventConfig {
104 /// Native input port IDs to activate.
105 pub inputs: Vec<u64>,
106 /// Native output port IDs to activate and collect.
107 pub outputs: Vec<u64>,
108}
109
110impl EventConfig {
111 /// The native event inputs and outputs to activate.
112 #[must_use]
113 pub fn new(inputs: Vec<u64>, outputs: Vec<u64>) -> EventConfig {
114 EventConfig { inputs, outputs }
115 }
116}
117
118impl SlotEventConfig {
119 /// A slot's routed event inputs and its active event outputs.
120 #[must_use]
121 pub fn new(inputs: Vec<EventInputRoute>, outputs: Vec<u64>) -> SlotEventConfig {
122 SlotEventConfig { inputs, outputs }
123 }
124
125 /// The native input ports routes deliver to, each once, in route order. Internal to the
126 /// plughost crates; exempt from semver.
127 #[doc(hidden)]
128 pub fn native(&self) -> EventConfig {
129 let mut inputs: Vec<u64> = Vec::new();
130 for route in &self.inputs {
131 if !inputs.contains(&route.port) {
132 inputs.push(route.port);
133 }
134 }
135 EventConfig {
136 inputs,
137 outputs: self.outputs.clone(),
138 }
139 }
140
141 /// Checks the counts, duplicate outputs, and each route's source; `previous` is the previous
142 /// slot's routing, if any.
143 pub(crate) fn validate(
144 &self,
145 slot: usize,
146 event_inputs: usize,
147 previous: Option<&SlotEventConfig>,
148 ) -> Result<(), InputError> {
149 if self.inputs.len() > MAX_EVENT_PORTS || self.outputs.len() > MAX_EVENT_PORTS {
150 return Err(InputError::EventPortCount);
151 }
152 for (index, port) in self.outputs.iter().enumerate() {
153 if self.outputs[..index].contains(port) {
154 return Err(InputError::DuplicateEventPort { id: *port });
155 }
156 }
157 for (index, route) in self.inputs.iter().enumerate() {
158 let available = match route.source {
159 EventSource::External { port } => port < event_inputs,
160 EventSource::Previous { port } => {
161 previous.is_some_and(|previous| previous.outputs.contains(&port))
162 }
163 };
164 if !available || self.inputs[..index].contains(route) {
165 return Err(InputError::EventRoute {
166 slot,
167 port: route.port,
168 });
169 }
170 }
171 Ok(())
172 }
173}