Skip to main content

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}