truce_core/
plugin.rs

1use crate::buffer::AudioBuffer;
2use crate::bus::BusLayout;
3use crate::editor::Editor;
4use crate::events::EventList;
5use crate::info::PluginInfo;
6use crate::process::{ProcessContext, ProcessStatus};
7use truce_params::sample::Sample;
8
9/// The format-facing plugin trait. **Plugin authors do NOT implement
10/// this directly.**
11///
12/// `Plugin` is the surface every format wrapper (CLAP, VST3, VST2,
13/// LV2, AU, AAX) consumes. The `truce::plugin!` macro generates an
14/// `impl Plugin for __HotShellWrapper` from the user's
15/// `truce_plugin::PluginLogic` impl, bridging the GUI-aware user
16/// trait into this GUI-free format-wrapper surface so `truce-core`
17/// doesn't pull in `truce-gui` types.
18///
19/// What plugin authors implement instead:
20///
21/// ```ignore
22/// impl truce::prelude::PluginLogic for MyPlugin {
23///     fn reset(&mut self, sr: f64, bs: usize) { /* ... */ }
24///     fn process(&mut self, /* ... */) -> ProcessStatus { /* ... */ }
25///     fn layout(&self) -> GridLayout { /* ... */ }
26/// }
27///
28/// truce::plugin! { logic: MyPlugin, params: MyPluginParams }
29/// ```
30///
31/// The macro-emitted `impl Plugin` routes each method directly to the
32/// user's impl, except `editor()` which the macro builds from the
33/// user's `custom_editor` (preferred) or `layout` (built-in fallback).
34pub trait Plugin: Send + 'static {
35    /// The plugin's chosen audio sample precision. Either `f32` (the
36    /// default - matches host wire format for nearly all formats) or
37    /// `f64` (for plugins whose DSP path runs in `f64` end-to-end:
38    /// high-order biquads, oscillator phase accumulators, long-running
39    /// cumulative state).
40    ///
41    /// The format wrapper bridges between host buffer precision and
42    /// `Self::Sample` at the block boundary - so the plugin's
43    /// `process()` always receives `AudioBuffer<Self::Sample>`
44    /// regardless of what the host sent. See
45    /// `truce_core::RawBufferScratch` for the conversion machinery.
46    ///
47    /// Drive this from the prelude: `truce::prelude` / `truce::prelude32`
48    /// implies `f32`, `truce::prelude64` implies `f64`. The
49    /// `truce::plugin!` macro emits `type Sample = …;` based on
50    /// which prelude is in scope at the macro call site.
51    type Sample: Sample;
52
53    /// Opt into zero-copy in-place I/O. When this returns `true`,
54    /// the format wrapper skips its safety memcpy on host-aliased
55    /// buffers and hands the plugin the raw shared memory through
56    /// `AudioBuffer::in_out_mut(ch)`. The plugin must check
57    /// `AudioBuffer::is_in_place(ch)` per channel before reading
58    /// `input(ch)` - for in-place channels `input(ch)` returns an
59    /// empty slice, and the data lives only in the shared buffer.
60    ///
61    /// Default `false`: the wrapper copies aliased inputs into scratch
62    /// so `input(ch)` and `output(ch)` are always disjoint. Costs one
63    /// memcpy per aliased channel per block (a few hundred KB/sec at
64    /// audio rates) and lets plugin code stay format-agnostic.
65    ///
66    /// `where Self: Sized` so a `dyn Plugin` trait object stays
67    /// dyn-compatible - the format wrappers consume `P: Plugin`
68    /// generically and call the method statically.
69    #[must_use]
70    fn supports_in_place() -> bool
71    where
72        Self: Sized,
73    {
74        false
75    }
76
77    /// Static metadata about the plugin.
78    ///
79    /// Use `plugin_info!()` for zero-boilerplate (reads from truce.toml
80    /// + Cargo.toml at compile time - no `build.rs` required).
81    fn info() -> PluginInfo
82    where
83        Self: Sized;
84
85    /// Supported bus layouts. The host picks one.
86    #[must_use]
87    fn bus_layouts() -> Vec<BusLayout>
88    where
89        Self: Sized,
90    {
91        vec![BusLayout::stereo()]
92    }
93
94    /// Called once after construction. Not real-time safe.
95    fn init(&mut self) {}
96
97    /// Called when sample rate or max block size changes.
98    /// Reset filters, delay lines, etc. Not real-time safe.
99    fn reset(&mut self, sample_rate: f64, max_block_size: usize);
100
101    /// Real-time audio processing.
102    fn process(
103        &mut self,
104        buffer: &mut AudioBuffer<Self::Sample>,
105        events: &EventList,
106        context: &mut ProcessContext,
107    ) -> ProcessStatus;
108
109    /// Save extra state beyond parameter values. Empty `Vec` means
110    /// "no extra state": matches the user-facing
111    /// `truce_plugin::PluginLogic::save_state` shape so the wrapper
112    /// bridge is a passthrough rather than an `Option<Vec<u8>>` to
113    /// `Vec<u8>` translation.
114    fn save_state(&self) -> Vec<u8> {
115        Vec::new()
116    }
117
118    /// Restore extra state. Matches the user-facing
119    /// `truce_plugin::PluginLogic::load_state` `Result` shape so the
120    /// wrapper bridge is a passthrough.
121    ///
122    /// # Errors
123    ///
124    /// Returns `Err` when the macro-generated impl forwards a
125    /// `PluginLogic::load_state` failure (malformed bytes, version
126    /// skew between session file and plugin build, etc).
127    fn load_state(&mut self, _data: &[u8]) -> Result<(), crate::state::StateLoadError> {
128        Ok(())
129    }
130
131    /// GUI editor. Return None for headless plugins.
132    fn editor(&mut self) -> Option<Box<dyn Editor>> {
133        None
134    }
135
136    /// Processing latency in samples. Host uses this for delay compensation.
137    /// Return 0 if the plugin adds no latency (default).
138    fn latency(&self) -> u32 {
139        0
140    }
141
142    /// Tail time in samples. Return `u32::MAX` for infinite tail.
143    /// Return 0 for no tail (default).
144    fn tail(&self) -> u32 {
145        0
146    }
147
148    /// Read a meter value by ID (0.0–1.0). Called by the GUI at ~60fps.
149    /// Override to expose level meters, gain reduction, etc.
150    fn get_meter(&self, _meter_id: u32) -> f32 {
151        0.0
152    }
153}
truce_core/plugin.rs

truce_core/
plugin.rs
