Trait PluginLogic64

Source

pub trait PluginLogic64: 'static {
    type Params: Params;
    type DspState: Default + Send + 'static;

    const PRESERVE_DSP_STATE: bool = true;
Show 13 methods
    // Required methods
    fn process(
        state: &mut Self::DspState,
        params: &Self::Params,
        buffer: &mut AudioBuffer<'_, f64>,
        events: &EventList,
        context: &mut ProcessContext<'_>,
    ) -> ProcessStatus;
    fn editor(params: Arc<Self::Params>) -> Box<dyn Editor>;

    // Provided methods
    fn supports_in_place() -> bool { ... }
    fn bus_layouts() -> Vec<BusLayout> { ... }
    fn init(params: &Self::Params, cx: &InitContext) -> Self::DspState { ... }
    fn reset(
        state: &mut Self::DspState,
        params: &Self::Params,
        config: &AudioConfig,
    ) { ... }
    fn save_state(state: &Self::DspState) -> Vec<u8> ⓘ { ... }
    fn snapshot_into(state: &Self::DspState, buf: &mut Vec<u8>) -> bool { ... }
    fn load_state(
        state: &mut Self::DspState,
        data: &[u8],
    ) -> Result<(), StateLoadError> { ... }
    fn state_changed(state: &mut Self::DspState, params: &Self::Params) { ... }
    fn migrate_state(foreign: &ForeignState<'_>) -> Option<MigratedState> { ... }
    fn latency(state: &Self::DspState) -> u32 { ... }
    fn tail(state: &Self::DspState) -> u32 { ... }
}

Expand description

The f64-buffer user-facing plugin trait. Same surface as PluginLogic but with the audio buffer pinned to f64.

Plugin authors don’t usually name this directly - truce::prelude64 re-exports it as PluginLogic, so the impl header reads the same regardless of which precision the prelude chose. Pick truce::prelude64 (and thus this leaf) when the DSP path runs in f64 end-to-end and the wrapper-boundary widen/narrow memcpy is worth the cleaner DSP code.

Provided Associated Constants§

Source

const PRESERVE_DSP_STATE: bool = true

Whether the hot-reload shell may preserve live DSP state across a code-only reload. Default true: the shell keeps the state when a best-effort layout probe (type_name + size_of + align_of) matches, so a reverb tail survives an edit-and-reload, and re-inits when it differs. Set to false on a state that must always re-init on reload.

Required Associated Types§

Source

type Params: Params

The plugin’s parameter struct (#[derive(Params)]). Shared, immutable during a block - it arrives by reference every call from the shell, which owns the Arc. Never stored in Self::DspState.

Source

type DspState: Default + Send + 'static

The mutable per-block audio state - filter memory, voice buffers, phase accumulators. A plain struct, distinct from the descriptor Self (except for the small-effect type DspState = Self shape). A plugin with no audio state implements the stateless leaf trait instead of this one and never names a DspState. Owned by the shell, so it can outlive a code swap. Default is how the state is born: the default Self::init returns Self::DspState::default(), so most plugins never write init - they #[derive(Default)] (or hand-write Default when a fresh state has non-zero fields) and override init only when construction needs params. No layout trait is required - the hot-reload shell fingerprints the type at load time from its type_name / size_of / align_of.

Required Methods§

Source

fn process( state: &mut Self::DspState, params: &Self::Params, buffer: &mut AudioBuffer<'_, f64>, events: &EventList, context: &mut ProcessContext<'_>, ) -> ProcessStatus

Process one block of audio. Real-time - no allocations, locks, or I/O. state is exclusively owned this block; params is shared and immutable.

Source

fn editor(params: Arc<Self::Params>) -> Box<dyn Editor>

Construct the editor for this plugin. Required.

There is no auto-fallback - every plugin explicitly names which renderer it wants. For the built-in widget layout, call truce_gui::default_editor(params, layout); for custom renderers, construct an EguiEditor / IcedEditor / SlintEditor / hand-rolled Editor here. The choice of renderer crate the plugin’s Cargo.toml pulls IS the choice of editor.

An associated function, not a method: it receives the lock-free Arc<Self::Params> store the wrapper already holds, so the host can open the editor while audio is running without ever taking the plugin lock. Editors bind only to the param store (plus meters / transport, all lock-free); custom DSP state is read at runtime through the editor bridge, not at construction.

Provided Methods§

Source

fn supports_in_place() -> bool

Opt into zero-copy in-place I/O. When this returns true, the format wrapper skips its safety memcpy on host-aliased buffers and hands the plugin the raw shared memory through AudioBuffer::in_out_mut(ch). The plugin must check AudioBuffer::is_in_place(ch) per channel before reading input(ch).

Default false: the wrapper copies aliased inputs into scratch so input(ch) and output(ch) are always disjoint. Costs one memcpy per aliased channel per block.

Source

fn bus_layouts() -> Vec<BusLayout>

Supported audio bus configurations. The host picks one; the others are rejected at bus-config time before process is ever called. Default: the standard audio effect - stereo and mono - so it shows on both track widths.

Source

fn init(params: &Self::Params, cx: &InitContext) -> Self::DspState

Build the initial audio state from params. Replaces the old new constructor: the descriptor is stateless, so state is born here and owned by the shell. Not real-time safe - allocate freely.

Default: Self::DspState::default(). Override only when construction genuinely needs to read params; a fixed initial state belongs in the state type’s Default impl instead.

Source

fn reset( state: &mut Self::DspState, params: &Self::Params, config: &AudioConfig, )

Reset for a new sample rate / block size / processing mode. Clear state’s filters / delay lines; read config.process_mode to size buffers for an offline render (allocation belongs here, off the audio thread) - see AudioConfig.

Params plumbing is NOT your job: the shell calls params.set_sample_rate(config.sample_rate) and params.snap_smoothers() before invoking this, so the body only handles state the plugin itself owns. Default: no-op, right for a stateless plugin (DspState = ()).

Source

fn save_state(state: &Self::DspState) -> Vec<u8> ⓘ

Serialize plugin-specific state (DSP state, not params - those are saved automatically). Default: delegates to Self::snapshot_into (empty when neither is overridden).

Runs on a host or GUI thread while the audio thread is paused at a block boundary (the wrapper’s plugin lock), so reading any field is safe - but an audio block that arrives mid-save waits for this to return. Keep it cheap: copy bytes out, don’t compute or compress here. To take this off the plugin lock entirely, override Self::snapshot_into instead.

Source

fn snapshot_into(state: &Self::DspState, buf: &mut Vec<u8>) -> bool

Opt into lock-free state save. buf arrives cleared, with its capacity retained across calls so a steady state is allocation-free; fill it with the same bytes Self::save_state would produce (append freely - it is never carried over from the previous block).

The return value is a static capability, not a per-block flag: true means “this plugin publishes snapshots”, false means “it never does” (the default). Once you return true you must return true for the plugin’s whole lifetime - if the custom state empties out, return true with buf left empty (an empty blob), don’t return false. The shell latches the opt-in on the first published block; a later false is a contract violation that would otherwise leave the host reading a stale snapshot forever.

Called on the audio thread after each process block, under the same real-time rules as process - bounded, no unbounded allocation. The wrapper publishes the result into a lock-free slot the host reads without ever taking the plugin lock, so saving state while audio runs never stalls the audio thread. Overriding this is the preferred way to serialize custom state; the default Self::save_state delegates here.

Source

fn load_state( state: &mut Self::DspState, data: &[u8], ) -> Result<(), StateLoadError>

Restore plugin-specific state into state.

Runs on the audio thread between blocks, with the same exclusive access process() has - writing any field is safe.

§Errors

Return Err(StateLoadError) when the blob is malformed or otherwise can’t be interpreted - the format wrapper logs the failure (and on hosts that support it, surfaces it to the DAW).

Source

fn state_changed(state: &mut Self::DspState, params: &Self::Params)

Called on the audio thread immediately after Self::load_state returns. Invalidate or recompute any caches in state that the next process() reads. Default: no-op.

Source

fn migrate_state(foreign: &ForeignState<'_>) -> Option<MigratedState>

Translate foreign state - a previous framework’s blob, or a truce envelope saved under a different plugin id - into truce params + extra, so a plugin ported to truce keeps its users’ old sessions and presets. Runs on the host thread; receiverless so it can’t touch (or alias) the live instance. Return None for bytes you don’t recognize - the wrapper then reports load failure to the host, exactly as if this hook didn’t exist.

One-shot by construction: the next save writes a normal truce envelope, so this never becomes a permanent dual-format reader. Keyed formats (AU / LV2 / AAX) only see foreign bytes when truce.toml declares the legacy keys to probe ([plugin.legacy_state]).

Source

fn latency(state: &Self::DspState) -> u32

Report latency in samples for plugin delay compensation. May change at runtime - return a new value and the host is notified (see the wrapper latency-change path).

Source