//! Traits and structs describing plugins and editors. use raw_window_handle::{HasRawWindowHandle, RawWindowHandle}; use std::any::Any; use std::sync::Arc; use crate::buffer::Buffer; use crate::context::{GuiContext, ProcessContext}; use crate::param::internals::Params; /// Basic functionality that needs to be implemented by a plugin. The wrappers will use this to /// expose the plugin in a particular plugin format. /// /// The main thing you need to do is define a `[Params]` struct containing all of your parmaeters. /// See the trait's documentation for more information on how to do that, or check out the examples. /// /// This is super basic, and lots of things I didn't need or want to use yet haven't been /// implemented. Notable missing features include: /// /// - Sidechain inputs /// - Multiple output busses /// - Special handling for offline processing /// - MIDI CC handling /// - Outputting MIDI events from the process function (you can output parmaeter changes from an /// editor GUI) #[allow(unused_variables)] pub trait Plugin: Default + Send + Sync + 'static { const NAME: &'static str; const VENDOR: &'static str; const URL: &'static str; const EMAIL: &'static str; /// Semver compatible version string (e.g. `0.0.1`). Hosts likely won't do anything with this, /// but just in case they do this should only contain decimals values and dots. const VERSION: &'static str; /// The default number of inputs. Some hosts like, like Bitwig and Ardour, use the defaults /// instead of setting up the busses properly. const DEFAULT_NUM_INPUTS: u32 = 2; /// The default number of inputs. Some hosts like, like Bitwig and Ardour, use the defaults /// instead of setting up the busses properly. const DEFAULT_NUM_OUTPUTS: u32 = 2; /// Whether the plugin accepts note events, and which level of . If this is set to /// [`MidiConfig::None`], then the plugin won't receive any note events. const MIDI_INPUT: MidiConfig = MidiConfig::None; /// If enabled, the audio processing cycle may be split up into multiple smaller chunks if /// parameter values change occur in the middle of the buffer. Depending on the host these /// blocks may be as small as a single sample. Bitwig Studio sends at most one parameter change /// every 64 samples. const SAMPLE_ACCURATE_AUTOMATION: bool = false; /// The plugin's parameters. The host will update the parameter values before calling /// `process()`. These parameters are identified by strings that should never change when the /// plugin receives an update. fn params(&self) -> Arc; /// The plugin's editor, if it has one. The actual editor instance is created in /// [`Editor::spawn()`]. A plugin editor likely wants to interact with the plugin's parameters /// and other shared data, so you'll need to move [`Arc`] pointing to any data you want to /// access into the editor. You can later modify the parameters through the /// [`GuiContext`][crate::prelude::GuiContext] and [`ParamSetter`][crate::prelude::ParamSetter] after the editor /// GUI has been created. fn editor(&self) -> Option> { None } // // The following functions follow the lifetime of the plugin. // /// Whether the plugin supports a bus config. This only acts as a check, and the plugin /// shouldn't do anything beyond returning true or false. fn accepts_bus_config(&self, config: &BusConfig) -> bool { config.num_input_channels == 2 && config.num_output_channels == 2 } /// Initialize the plugin for the given bus and buffer configurations. If the plugin is being /// restored from an old state, then that state will have already been restored at this point. /// If based on those parameters (or for any reason whatsoever) the plugin needs to introduce /// latency, then you can do so here using the process context. Depending on how the host /// restores plugin state, this function may also be called twice in rapid succession. If the /// plugin fails to inialize for whatever reason, then this should return `false`. /// /// Before this point, the plugin should not have done any expensive initialization. Please /// don't be that plugin that takes twenty seconds to scan. /// /// After this function [`reset()`][Self::reset()] will always be called. If you need to clear /// state, such as filters or envelopes, then you should do so in that function inistead. fn initialize( &mut self, bus_config: &BusConfig, buffer_config: &BufferConfig, context: &mut impl ProcessContext, ) -> bool { true } /// Clear internal state such as filters and envelopes. This is always called after /// [`initialize()`][Self::initialize(0)], and it may also be called at any other time from the /// audio thread. You should thus not do any allocations in this function. fn reset(&mut self) {} /// Process audio. The host's input buffers have already been copied to the output buffers if /// they are not processing audio in place (most hosts do however). All channels are also /// guarenteed to contain the same number of samples. Lastly, denormals have already been taken /// case of by NIH-plug, and you can optionally enable the `assert_process_allocs` feature to /// abort the program when any allocation accurs in the process function while running in debug /// mode. /// /// The framework provides convenient iterators on the [`Buffer`] object to process audio either /// either per-sample per-channel, or per-block per-channel per-sample. The first approach is /// preferred for plugins that don't require block-based processing because of their use of /// per-sample SIMD or excessive branching. The parameter smoothers can also work in both modes: /// use [`Smoother::next()`][crate::prelude::Smoother::next()] for per-sample processing, and /// [`Smoother::next_block()`][crate::prelude::Smoother::next_block()] for block-based /// processing. In order to use block-based smoothing, you will need to call /// [`initialize_block_smoothers()`][Self::initialize_block_smoothers()] in your /// [`initialize()`][Self::initialize()] function first to reserve enough capacity in the /// smoothers. /// /// TODO: Provide a way to access auxiliary input channels if the IO configuration is /// assymetric /// TODO: Pass transport and other context information to the plugin /// TODO: Create an example plugin that uses block-based processing fn process(&mut self, buffer: &mut Buffer, context: &mut impl ProcessContext) -> ProcessStatus; /// Convenience function to allocate memory for block-based smoothing. Since this allocates /// memory, this should be called in [`initialize()`][Self::initialize()]. If you are going to /// use [`Buffer::iter_blocks()`] and want to use parameter smoothing in those blocks, then call /// this function with the same maximum block size first before calling /// [`Smoother::next_block()`][crate::prelude::Smoother::next_block()]. fn initialize_block_smoothers(&mut self, max_block_size: usize) { for (_, mut param, _) in self.params().param_map() { unsafe { param.initialize_block_smoother(max_block_size) }; } } } /// Provides auxiliary metadata needed for a CLAP plugin. pub trait ClapPlugin: Plugin { /// A unique ID that identifies this particular plugin. This is usually in reverse domain name /// notation, e.g. `com.manufacturer.plugin-name`. const CLAP_ID: &'static str; /// A short description for the plugin. const CLAP_DESCRIPTION: &'static str; /// Arbitrary keywords describing the plugin. See the CLAP specification for examples: /// . /// /// On windows `win32-dpi-aware` is automatically added. const CLAP_FEATURES: &'static [&'static str]; /// A URL to the plugin's manual, CLAP does not specify what to do when there is none. // // TODO: CLAP does not specify this, can these manual fields be null pointers? const CLAP_MANUAL_URL: &'static str; /// A URL to the plugin's support page, CLAP does not specify what to do when there is none. const CLAP_SUPPORT_URL: &'static str; } /// Provides auxiliary metadata needed for a VST3 plugin. pub trait Vst3Plugin: Plugin { /// The unique class ID that identifies this particular plugin. You can use the /// `*b"fooofooofooofooo"` syntax for this. /// /// This will be shuffled into a different byte order on Windows for project-compatibility. const VST3_CLASS_ID: [u8; 16]; /// One or more categories, separated by pipe characters (`|), up to 127 characters. Anything /// logner than that will be truncated. See the VST3 SDK for examples of common categories: /// const VST3_CATEGORIES: &'static str; /// [`VST3_CLASS_ID`][Self::VST3_CLASS_ID`] in the correct order for the current platform so /// projects and presets can be shared between platforms. This should not be overridden. const PLATFORM_VST3_CLASS_ID: [u8; 16] = swap_vst3_uid_byte_order(Self::VST3_CLASS_ID); } #[cfg(not(target_os = "windows"))] const fn swap_vst3_uid_byte_order(uid: [u8; 16]) -> [u8; 16] { uid } #[cfg(target_os = "windows")] const fn swap_vst3_uid_byte_order(mut uid: [u8; 16]) -> [u8; 16] { // No mutable references in const functions, so we can't use `uid.swap()` let original_uid = uid; uid[0] = original_uid[3]; uid[1] = original_uid[2]; uid[2] = original_uid[1]; uid[3] = original_uid[0]; uid[4] = original_uid[5]; uid[5] = original_uid[4]; uid[6] = original_uid[7]; uid[7] = original_uid[6]; uid } /// An editor for a [`Plugin`]. pub trait Editor: Send + Sync { /// Create an instance of the plugin's editor and embed it in the parent window. As explained in /// [`Plugin::editor()`], you can then read the parameter values directly from your [`Params`] /// object, and modifying the values can be done using the functions on the /// [`ParamSetter`][crate::prelude::ParamSetter]. When you change a parameter value that way it will be /// broadcasted to the host and also updated in your [`Params`] struct. /// /// This function should return a handle to the editor, which will be dropped when the editor /// gets closed. Implement the [`Drop`] trait on the returned handle if you need to explicitly /// handle the editor's closing behavior. /// /// If [`set_scale_factor()`][Self::set_scale_factor()] has been called, then any created /// windows should have their sizes multiplied by that factor. /// /// The wrapper guarantees that a previous handle has been dropped before this function is /// called again. // // TODO: Think of how this would work with the event loop. On Linux the wrapper must provide a // timer using VST3's `IRunLoop` interface, but on Window and macOS the window would // normally register its own timer. Right now we just ignore this because it would // otherwise be basically impossible to have this still be GUI-framework agnostic. Any // callback that deos involve actual GUI operations will still be spooled to the IRunLoop // instance. fn spawn( &self, parent: ParentWindowHandle, context: Arc, ) -> Box; /// Return the (currnent) size of the editor in pixels as a `(width, height)` pair. This size /// must be reported in _logical pixels_, i.e. the size before being multiplied by the DPI /// scaling factor to get the actual physical screen pixels. fn size(&self) -> (u32, u32); /// Set the DPI scaling factor, if supported. The plugin APIs don't make any guarantees on when /// this is called, but for now just assume it will be the first function that gets called /// before creating the editor. If this is set, then any windows created by this editor should /// have their sizes multiplied by this scaling factor on Windows and Linux. /// /// Right now this is never called on macOS since DPI scaling is built into the operating system /// there. fn set_scale_factor(&self, factor: f32) -> bool; /// A callback that will be called wheneer the parameter values changed while the editor is /// open. You don't need to do anything with this, but this can be used to force a redraw when /// the host sends a new value for a parameter or when a parameter change sent to the host gets /// processed. /// /// This function will be called from the **audio thread**. It must thus be lock-free and may /// not allocate. fn param_values_changed(&self); // TODO: Reconsider adding a tick function here for the Linux `IRunLoop`. To keep this platform // and API agnostic, add a way to ask the GuiContext if the wrapper already provides a // tick function. If it does not, then the Editor implementation must handle this by // itself. This would also need an associated `PREFERRED_FRAME_RATE` constant. // TODO: Host->Plugin resizing } /// A raw window handle for platform and GUI framework agnostic editors. pub struct ParentWindowHandle { pub handle: RawWindowHandle, } unsafe impl HasRawWindowHandle for ParentWindowHandle { fn raw_window_handle(&self) -> RawWindowHandle { self.handle } } /// We only support a single main input and output bus at the moment. #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub struct BusConfig { /// The number of input channels for the plugin. pub num_input_channels: u32, /// The number of output channels for the plugin. pub num_output_channels: u32, } /// Configuration for (the host's) audio buffers. #[derive(Debug, Clone, Copy, PartialEq)] pub struct BufferConfig { /// The current sample rate. pub sample_rate: f32, /// The maximum buffer size the host will use. The plugin should be able to accept variable /// sized buffers up to this size. pub max_buffer_size: u32, } /// Indicates the current situation after the plugin has processed audio. #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub enum ProcessStatus { /// Something went wrong while processing audio. Error(&'static str), /// The plugin has finished processing audio. When the input is silent, the most may suspend the /// plugin to save resources as it sees fit. Normal, /// The plugin has a (reverb) tail with a specific length in samples. Tail(u32), /// This plugin will continue to produce sound regardless of whether or not the input is silent, /// and should thus not be deactivated by the host. This is essentially the same as having an /// infite tail. KeepAlive, } /// Determines which note events a plugin receives. #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)] pub enum MidiConfig { /// The plugin will not have a note input port and will thus not receive any not events. None, /// The plugin receives note on/off events, pressure, and potentially a couple standardized /// expression types depending on the plugin standard and host. Basic, // // TODO: // /// The plugin receives full MIDI CCs as well as pitch bend information. For VST3 plugins this // /// involves adding 130*16 parameters to bind to the the 128 MIDI CCs, pitch bend, and channel // /// pressure. // MidiCCs, } /// Event for (incoming) notes. The set of supported note events depends on the value of /// [`Plugin::MIDI_INPUT`]. Also check out the [`util`][crate::util] module for convenient /// conversion functions. /// /// All of the timings are sample offsets withing the current buffer. /// /// TODO: Add more events as needed #[derive(Debug, Clone, Copy, PartialEq)] #[non_exhaustive] pub enum NoteEvent { /// A note on event, available on [`MidiConfig::Basic`] and up. NoteOn { timing: u32, /// The note's channel, from 0 to 16. channel: u8, /// The note's MIDI key number, from 0 to 127. note: u8, /// The note's velocity, from 0 to 1. Some plugin APIs may allow higher precision than the /// 127 levels available in MIDI. velocity: f32, }, /// A note off event, available on [`MidiConfig::Basic`] and up. NoteOff { timing: u32, /// The note's channel, from 0 to 16. channel: u8, /// The note's MIDI key number, from 0 to 127. note: u8, /// The note's velocity, from 0 to 1. Some plugin APIs may allow higher precision than the /// 127 levels available in MIDI. velocity: f32, }, /// A polyphonic note pressure/aftertouch event, available on [`MidiConfig::Basic`] and up. Not /// all hosts may support polyphonic aftertouch. PolyPressure { timing: u32, /// The note's channel, from 0 to 16. channel: u8, /// The note's MIDI key number, from 0 to 127. note: u8, /// The note's pressure, from 0 to 1. pressure: f32, }, /// A volume expression event, available on [`MidiConfig::Basic`] and up. Not all hosts may /// support these expressions. Volume { timing: u32, /// The note's channel, from 0 to 16. channel: u8, /// The note's MIDI key number, from 0 to 127. note: u8, /// The note's voltage gain ratio, where 1.0 is unity gain. gain: f32, }, /// A panning expression event, available on [`MidiConfig::Basic`] and up. Not all hosts may /// support these expressions. Pan { timing: u32, /// The note's channel, from 0 to 16. channel: u8, /// The note's MIDI key number, from 0 to 127. note: u8, /// The note's panning from, from -1 to 1, with -1 being panned hard left, and 1 being /// panned hard right. pan: f32, }, /// A tuning expression event, available on [`MidiConfig::Basic`] and up. Not all hosts may support /// these expressions. Tuning { timing: u32, /// The note's channel, from 0 to 16. channel: u8, /// The note's MIDI key number, from 0 to 127. note: u8, /// The note's tuning in semitones, from -120 to 120. tuning: f32, }, /// A vibrato expression event, available on [`MidiConfig::Basic`] and up. Not all hosts may support /// these expressions. Vibrato { timing: u32, /// The note's channel, from 0 to 16. channel: u8, /// The note's MIDI key number, from 0 to 127. note: u8, /// The note's vibrato amount, from 0 to 1. vibrato: f32, }, /// A expression expression (yes, expression expression) event, available on /// [`MidiConfig::Basic`] and up. Not all hosts may support these expressions. Expression { timing: u32, /// The note's channel, from 0 to 16. channel: u8, /// The note's MIDI key number, from 0 to 127. note: u8, /// The note's expression amount, from 0 to 1. expression: f32, }, /// A brightness expression event, available on [`MidiConfig::Basic`] and up. Not all hosts may support /// these expressions. Brightness { timing: u32, /// The note's channel, from 0 to 16. channel: u8, /// The note's MIDI key number, from 0 to 127. note: u8, /// The note's brightness amount, from 0 to 1. brightness: f32, }, // TODO: Add MIDI channel pressure, pitchbend, and CCs } impl NoteEvent { /// Return the sample within the current buffer this event belongs to. pub fn timing(&self) -> u32 { match &self { NoteEvent::NoteOn { timing, .. } => *timing, NoteEvent::NoteOff { timing, .. } => *timing, NoteEvent::PolyPressure { timing, .. } => *timing, NoteEvent::Volume { timing, .. } => *timing, NoteEvent::Pan { timing, .. } => *timing, NoteEvent::Tuning { timing, .. } => *timing, NoteEvent::Vibrato { timing, .. } => *timing, NoteEvent::Expression { timing, .. } => *timing, NoteEvent::Brightness { timing, .. } => *timing, } } }