truce_core/
export.rs

1use std::sync::Arc;
2
3use crate::plugin::PluginRuntime;
4use truce_params::{ParamInfo, Params};
5
6/// Unified export trait for all plugin formats.
7///
8/// Implement this once on your plugin type. All format wrappers
9/// (CLAP, VST3, AU, standalone) use this to construct your plugin
10/// and access its parameters.
11///
12/// ```ignore
13/// impl PluginExport for MyPlugin {
14///     type Params = MyParams;
15///     fn create() -> Self { Self::new() }
16///     fn params(&self) -> &MyParams { &self.params }
17///     fn params_arc(&self) -> Arc<MyParams> { self.params.clone() }
18/// }
19/// ```
20///
21/// All parameter mutation goes through the atomic-backed accessors on
22/// `&Params` - no `&mut Params` accessor is required, which keeps the
23/// trait usable while the editor holds an `Arc<Params>` reader.
24pub trait PluginExport: PluginRuntime + Sized {
25    type Params: Params;
26
27    /// Construct a new instance of the plugin.
28    fn create() -> Self;
29
30    /// Immutable access to the parameter struct.
31    fn params(&self) -> &Self::Params;
32
33    /// Get a shared `Arc` reference to the parameter struct.
34    ///
35    /// Used by format wrappers to pass params to GUI closures without
36    /// raw pointers. The Arc is cloned (cheap ref-count bump), not the
37    /// params themselves.
38    fn params_arc(&self) -> Arc<Self::Params>;
39
40    /// Shared meter storage handle, mirroring [`Self::params_arc`]:
41    /// the audio thread publishes meter values into this store from
42    /// inside `process()` (via the shells' meter callback), and GUI
43    /// `get_meter` closures read it - never the plugin instance,
44    /// whose `&mut` the audio thread holds for the whole block.
45    ///
46    /// The `truce::plugin!` shells own the store and return their
47    /// handle here; a hand-written `PluginExport` impl keeps one
48    /// alongside its params `Arc`.
49    fn meter_store(&self) -> Arc<crate::meters::MeterStore>;
50
51    /// Static parameter metadata for registration-time access.
52    ///
53    /// Format wrappers' `register_*` paths (`truce-vst2`, `truce-vst3`,
54    /// `truce-au`, `truce-aax`) call this instead of the historical
55    /// `Self::create().params().param_infos()` walk, which constructed
56    /// a full plugin instance - including any allocation the
57    /// constructor did (DSP buffers, FFT plans, image atlases) - just
58    /// to read static metadata. On platforms where registration runs
59    /// from C++ static initializers (notably AAX `Describe`) those
60    /// allocations sit in a fragile init-order regime; avoiding them
61    /// closes a class of platform-dependent registration bugs.
62    ///
63    /// Default impl prefers
64    /// [`Params::param_infos_static`]
65    /// when it returns a non-empty vec (the `#[derive(Params)]` path
66    /// emits an override built from compile-time metadata) and falls
67    /// back to the runtime construction otherwise - so plugins with
68    /// hand-written `Params` impls that don't override the static
69    /// path keep working unchanged.
70    #[must_use]
71    fn param_infos_static() -> Vec<ParamInfo> {
72        let from_params = <Self::Params as Params>::param_infos_static();
73        if from_params.is_empty() {
74            Self::create().params().param_infos()
75        } else {
76            from_params
77        }
78    }
79
80    /// Static "does this plugin have an editor" predicate. AAX's
81    /// `Describe` path needs to know this at registration time
82    /// (`has_editor` field on the static descriptor). Paired with
83    /// [`Self::param_infos_static`], this is the second reason every
84    /// format's registration walk constructed a plugin.
85    ///
86    /// Default impl falls back to that runtime path so unannotated
87    /// plugins keep working. Plugins that want to avoid the
88    /// static-init plugin construction (notably for AAX hosts that
89    /// run `Describe` very early) override with a `const`-style
90    /// answer:
91    ///
92    /// ```ignore
93    /// impl PluginExport for MyPlugin {
94    ///     // ...
95    ///     fn has_editor_static() -> bool { true }
96    /// }
97    /// ```
98    ///
99    /// VST2 / VST3 / AU never call this - they don't need the answer
100    /// at registration time.
101    #[must_use]
102    fn has_editor_static() -> bool {
103        Self::create().editor().is_some()
104    }
105}
truce_core/export.rs

truce_core/
export.rs
