Trait nih_plug::context::process::ProcessContext

pub trait ProcessContext<P: Plugin> {
    // Required methods
    fn plugin_api(&self) -> PluginApi;
    fn execute_background(&self, task: P::BackgroundTask);
    fn execute_gui(&self, task: P::BackgroundTask);
    fn transport(&self) -> &Transport;
    fn next_event(&mut self) -> Option<PluginNoteEvent<P>>;
    fn send_event(&mut self, event: PluginNoteEvent<P>);
    fn set_latency_samples(&self, samples: u32);
    fn set_current_voice_capacity(&self, capacity: u32);
}

Contains both context data and callbacks the plugin can use during processing. Most notably this is how a plugin sends and receives note events, gets transport information, and accesses sidechain inputs and auxiliary outputs. This is passed to the plugin during as part of Plugin::process().

Required Methods

fn plugin_api(&self) -> PluginApi

Get the current plugin API.

fn execute_background(&self, task: P::BackgroundTask)

Execute a task on a background thread using [Plugin::task_executor]. This allows you to defer expensive tasks for later without blocking either the process function or the GUI thread. As long as creating the task is realtime-safe, this operation is too.

Note

Scheduling the same task multiple times will cause those duplicate tasks to pile up. Try to either prevent this from happening, or check whether the task still needs to be completed in your task executor.

fn execute_gui(&self, task: P::BackgroundTask)

Execute a task on a background thread using [Plugin::task_executor]. As long as creating the task is realtime-safe, this operation is too.

Note

Scheduling the same task multiple times will cause those duplicate tasks to pile up. Try to either prevent this from happening, or check whether the task still needs to be completed in your task executor.

fn transport(&self) -> &Transport

Get information about the current transport position and status.

fn next_event(&mut self) -> Option<PluginNoteEvent<P>>

Returns the next note event, if there is one. Use NoteEvent::timing() to get the event’s timing within the buffer. Only available when Plugin::MIDI_INPUT is set.

Usage

You will likely want to use this with a loop, since there may be zero, one, or more events for a sample:

let mut next_event = context.next_event();
for (sample_id, channel_samples) in buffer.iter_samples().enumerate() {
    while let Some(event) = next_event {
        if event.timing() != sample_id as u32 {
            break;
        }

        match event {
            NoteEvent::NoteOn { note, velocity, .. } => { ... },
            NoteEvent::NoteOff { note, .. } if note == 69 => { ... },
            NoteEvent::PolyPressure { note, pressure, .. } { ... },
            _ => (),
        }

        next_event = context.next_event();
    }

    // Do something with `channel_samples`...
}

ProcessStatus::Normal

fn send_event(&mut self, event: PluginNoteEvent<P>)

Send an event to the host. Only available when Plugin::MIDI_OUTPUT is set. Will not do anything otherwise.

fn set_latency_samples(&self, samples: u32)

Update the current latency of the plugin. If the plugin is currently processing audio, then this may cause audio playback to be restarted.

fn set_current_voice_capacity(&self, capacity: u32)

Set the current voice capacity for this plugin (so not the number of currently active voices). This may only be called if ClapPlugin::CLAP_POLY_MODULATION_CONFIG is set. capacity must be between 1 and the configured maximum capacity. Changing this at runtime allows the host to better optimize polyphonic modulation, or to switch to strictly monophonic modulation when dropping the capacity down to 1.

Implementors