remove sync requirement for nih_plug gui state, update nih_plug example

Author: BillyDM

examples/nih_plug_gain_egui/Cargo.toml

@@ -22,3 +22,9 @@ nih_plug = { workspace = true, default-features = true, features = [
 ] }
 nih_plug_egui = { path = "../../nih_plug_egui" }
 atomic_float = "1.1"
+# Optional, only include if you want to pass messages between the
+# GUI and the audio thread.
+rtrb = "0.3"
+# Optional, only include if you want to sync complex state between
+# the GUI and the audio thread.
+triple_buffer = "8.1"

examples/nih_plug_gain_egui/src/lib.rs

@@ -7,10 +7,17 @@ use nih_plug_egui::{
 };
 use std::sync::Arc;
 
+const MIN_WINDOW_WIDTH: u32 = 300;
+const MIN_WINDOW_HEIGHT: u32 = 220;
+
 /// The time it takes for the peak meter to decay by 12 dB after switching to complete silence.
 const PEAK_METER_DECAY_MS: f64 = 150.0;
 
-/// This is mostly identical to the gain example, minus some fluff, and with a GUI.
+/// If you are using message channels, then allocate enough capacity for the expected worse case
+/// scenario for your plugin.
+const GUI_TO_AUDIO_MSG_CHANNEL_CAPACITY: usize = 512;
+const AUDIO_TO_GUI_MSG_CHANNEL_CAPACITY: usize = 128;
+
 pub struct Gain {
     params: Arc<GainParams>,
 
@@ -22,6 +29,25 @@ pub struct Gain {
     ///
     /// This is stored as voltage gain.
     peak_meter: Arc<AtomicF32>,
+
+    /// A message channel to send events between the GUI and the audio thread.
+    ///
+    /// This is optional. If you don't need to pass events, you can omit this field.
+    msg_channel: AudioMsgChannel,
+    /// Used to demonstrate how to pass heap-allocated data from the GUI to the audio thread.
+    heap_data_example: Vec<f32>,
+
+    /// State that is synced between the GUI and the audio thread using a triple buffer.
+    /// This can be used as an alternative to the message channel approach. Note, the roles of which
+    /// thread has the input and which has the output can be reversed.
+    ///
+    /// The downside to this approach is that it takes 3x the memory.
+    ///
+    /// This is optional. If you don't need this, you can omit it.
+    triple_buffer_state: triple_buffer::Output<TripleBufferState>,
+
+    /// Temporarily hold on to the initial GUI state until the editor is first opened.
+    initial_gui_state: Option<GuiState>,
 }
 
 #[derive(Params)]
@@ -41,19 +67,43 @@ pub struct GainParams {
 
 impl Default for Gain {
     fn default() -> Self {
+        let (to_audio_tx, from_gui_rx) = rtrb::RingBuffer::new(GUI_TO_AUDIO_MSG_CHANNEL_CAPACITY);
+        let (to_gui_tx, from_audio_rx) = rtrb::RingBuffer::new(AUDIO_TO_GUI_MSG_CHANNEL_CAPACITY);
+
+        let (triple_buffer_input, triple_buffer_output) =
+            triple_buffer::triple_buffer(&TripleBufferState::default());
+
         Self {
             params: Arc::new(GainParams::default()),
 
             peak_meter_decay_weight: 1.0,
             peak_meter: Arc::new(AtomicF32::new(util::MINUS_INFINITY_DB)),
+
+            msg_channel: AudioMsgChannel {
+                to_gui_tx,
+                from_gui_rx,
+                msg_sent: false,
+            },
+            heap_data_example: Vec::new(),
+
+            triple_buffer_state: triple_buffer_output,
+
+            initial_gui_state: Some(GuiState {
+                msg_channel: GuiMsgChannel {
+                    to_audio_tx,
+                    from_audio_rx,
+                },
+                triple_buffer_state: triple_buffer_input,
+                next_value: 0,
+            }),
         }
     }
 }
 
 impl Default for GainParams {
     fn default() -> Self {
         Self {
-            editor_state: EguiState::from_size(300, 180),
+            editor_state: EguiState::from_size(MIN_WINDOW_WIDTH, MIN_WINDOW_HEIGHT),
 
             // See the main gain example for more details
             gain: FloatParam::new(
@@ -74,6 +124,71 @@ impl Default for GainParams {
     }
 }
 
+/// Here you can store any state you need for your GUI.
+///
+/// This state persists across editor openings.
+pub struct GuiState {
+    /// A message channel to send events between the GUI and the audio thread.
+    ///
+    /// This is optional. If you don't need to pass events, you can omit this field.
+    msg_channel: GuiMsgChannel,
+
+    /// State that is synced between the GUI and the audio thread using a triple buffer.
+    /// This can be used as an alternative the message channel approach. Note, the roles of which
+    /// thread has the input and which has the output can be reversed.
+    ///
+    /// The downside to this approach is that it takes 3x the memory.
+    ///
+    /// This is optional. If you don't need this, you can omit it.
+    triple_buffer_state: triple_buffer::Input<TripleBufferState>,
+    next_value: u64,
+}
+
+/// A message channel to send events between the GUI and the audio thread.
+///
+/// This is optional. If you don't need to pass events, you can omit this.
+pub struct GuiMsgChannel {
+    /// A message channel to send events from the GUI to the audio thread.
+    to_audio_tx: rtrb::Producer<GuiToAudioMsg>,
+    /// A message channel to receive events from the audio thread.
+    from_audio_rx: rtrb::Consumer<AudioToGuiMsg>,
+}
+/// A message channel to send events between the GUI and the audio thread.
+///
+/// This is optional. If you don't need to pass events, you can omit this.
+pub struct AudioMsgChannel {
+    /// A message channel to send events from the audio thread to the GUI thread.
+    to_gui_tx: rtrb::Producer<AudioToGuiMsg>,
+    /// A message channel to receive events from the GUI thread.
+    from_gui_rx: rtrb::Consumer<GuiToAudioMsg>,
+    msg_sent: bool,
+}
+
+#[derive(Debug)]
+pub enum GuiToAudioMsg {
+    MessageA,
+    MessageWithHeapData(Vec<f32>),
+}
+#[derive(Debug)]
+pub enum AudioToGuiMsg {
+    MessageA,
+    DropOldHeapData(Vec<f32>),
+}
+
+/// State that is synced between the GUI and the audio thread using a triple buffer.
+/// This can be used as an alternative the message channel approach. Note, the roles
+/// of which thread has the input and which has the output can be reversed.
+///
+/// The downside to this approach is that it takes 3x the memory.
+///
+/// This is optional. If you don't need this, you can omit it.
+#[derive(Debug, Default, Clone)]
+pub struct TripleBufferState {
+    value_a: bool,
+    value_b: u64,
+    some_data: Vec<u32>,
+}
+
 impl Plugin for Gain {
     const NAME: &'static str = "Gain (nih_plug_egui)";
     const VENDOR: &'static str = "Moist Plugins GmbH";
@@ -108,17 +223,16 @@ impl Plugin for Gain {
         let params = self.params.clone();
         let peak_meter = self.peak_meter.clone();
         let egui_state = params.editor_state.clone();
+
         create_egui_editor(
             self.params.editor_state.clone(),
-            (),
+            self.initial_gui_state.take().unwrap(),
             Default::default(),
-            |_, _, _| {},
-            move |egui_ctx, setter, _queue, _state| {
+            |_egui_ctx, _queue, _gui_state| {},
+            move |egui_ctx, setter, _queue, gui_state| {
                 ResizableWindow::new("res-wind")
-                    .min_size(Vec2::new(128.0, 128.0))
+                    .min_size(Vec2::new(MIN_WINDOW_WIDTH as f32, MIN_WINDOW_HEIGHT as f32))
                     .show(egui_ctx, egui_state.as_ref(), |ui| {
-                        // NOTE: See `plugins/diopser/src/editor.rs` for an example using the generic UI widget
-
                         // This is a fancy widget that can get all the information it needs to properly
                         // display and modify the parameter from the parametr itself
                         // It's not yet fully implemented, as the text is missing.
@@ -161,6 +275,25 @@ impl Plugin for Gain {
                             egui::widgets::ProgressBar::new(peak_meter_normalized)
                                 .text(peak_meter_text),
                         );
+
+                        // Demonstrate sending a message to the audio thread.
+                        if ui.button("send message").clicked() {
+                            if let Err(e) = gui_state.msg_channel.to_audio_tx.push(GuiToAudioMsg::MessageA) {
+                                nih_error!("Failed to send message to audio thread: {}", e);
+                            }
+                        }
+                        // Demonstrate receiving messages from the audio thread.
+                        while let Ok(msg) = gui_state.msg_channel.from_audio_rx.pop() {
+                            nih_log!("Got message from audio thread: {:?}", &msg);
+                        }
+
+                        // Demonstrate mutating synced triple buffer state.
+                        if ui.button("mutate synced state").clicked() {
+                            gui_state.next_value += 1;
+                            // Note, `triple_buffer_state.input_buffer_mut()` will not work for syncing state
+                            // this way. You must always completely overwrite the state with new data.
+                            gui_state.triple_buffer_state.write(TripleBufferState { value_a: false, value_b: gui_state.next_value, some_data: Vec::new() });
+                        }
                     });
             },
         )
@@ -187,6 +320,48 @@ impl Plugin for Gain {
         _aux: &mut AuxiliaryBuffers,
         _context: &mut impl ProcessContext<Self>,
     ) -> ProcessStatus {
+        // Demonstrate receiving messages from the GUI thread.
+        while let Ok(msg) = self.msg_channel.from_gui_rx.pop() {
+            match msg {
+                GuiToAudioMsg::MessageA => {
+                    nih_dbg!("Got MessageA from GUI");
+                }
+                GuiToAudioMsg::MessageWithHeapData(mut heap_data) => {
+                    nih_dbg!("Got MessageWithHeapData from GUI");
+
+                    // Replace the old heap data with the new data.
+                    std::mem::swap(&mut self.heap_data_example, &mut heap_data);
+
+                    // Note, you must be careful not to drop heap-allocated data on the audio
+                    // thread. Send the old data back to the GUI thread to be deallocated there.
+                    if let Err(e) = self
+                        .msg_channel
+                        .to_gui_tx
+                        .push(AudioToGuiMsg::DropOldHeapData(heap_data))
+                    {
+                        nih_error!("Failed to send message to GUI thread: {}", e);
+                    }
+                }
+            }
+        }
+
+        // Demonstrate sending messages to the GUI thread.
+        if self.params.editor_state.is_open() && !self.msg_channel.msg_sent {
+            if let Err(e) = self.msg_channel.to_gui_tx.push(AudioToGuiMsg::MessageA) {
+                nih_error!("Failed to send message to GUI thread: {}", e);
+            }
+
+            // Only send the example message once to avoid spamming the GUI.
+            self.msg_channel.msg_sent = true;
+        }
+
+        // Demonstrate triple buffer usage.
+        let state = self.triple_buffer_state.read();
+        // Use the state somehow...
+        let _ = &state.value_a;
+        let _ = &state.value_b;
+        let _ = &state.some_data;
+
         for channel_samples in buffer.iter_samples() {
             let mut amplitude = 0.0;
             let num_samples = channel_samples.len();

nih_plug_egui/src/editor.rs

@@ -11,7 +11,7 @@ use egui_baseview::egui::Context;
 use egui_baseview::EguiWindow;
 use egui_baseview::Queue;
 use nih_plug::prelude::{Editor, GuiContext, ParamSetter, ParentWindowHandle};
-use parking_lot::RwLock;
+use parking_lot::Mutex;
 use raw_window_handle::{HasRawWindowHandle, RawWindowHandle};
 use std::sync::atomic::Ordering;
 use std::sync::Arc;
@@ -20,7 +20,7 @@ use std::sync::Arc;
 pub(crate) struct EguiEditor<T> {
     pub(crate) egui_state: Arc<EguiState>,
     /// The plugin's state. This is kept in between editor openenings.
-    pub(crate) user_state: Arc<RwLock<T>>,
+    pub(crate) user_state: Arc<Mutex<T>>,
 
     pub(crate) settings: Arc<EguiSettings>,
 
@@ -63,7 +63,7 @@ unsafe impl HasRawWindowHandle for ParentWindowHandleAdapter {
 
 impl<T> Editor for EguiEditor<T>
 where
-    T: 'static + Send + Sync,
+    T: 'static + Send,
 {
     fn spawn(
         &self,
@@ -111,7 +111,7 @@ where
             },
             self.settings.graphics_config.clone(),
             state,
-            move |egui_ctx, queue, state| build(egui_ctx, queue, &mut state.write()),
+            move |egui_ctx, queue, state| build(egui_ctx, queue, &mut state.lock()),
             move |egui_ctx, queue, state| {
                 let setter = ParamSetter::new(context.as_ref());
 
@@ -141,7 +141,7 @@ where
                 // this we would also have a blank GUI when it gets first opened because most DAWs open
                 // their GUI while the window is still unmapped.
                 egui_ctx.request_repaint();
-                (update)(egui_ctx, &setter, queue, &mut state.write());
+                (update)(egui_ctx, &setter, queue, &mut state.lock());
             },
         );
 

nih_plug_egui/src/lib.rs

@@ -9,7 +9,7 @@ use crossbeam::atomic::AtomicCell;
 use egui::Context;
 use nih_plug::params::persist::PersistentField;
 use nih_plug::prelude::{Editor, ParamSetter};
-use parking_lot::RwLock;
+use parking_lot::Mutex;
 use serde::{Deserialize, Serialize};
 use std::sync::atomic::{AtomicBool, Ordering};
 use std::sync::Arc;
@@ -88,13 +88,13 @@ pub fn create_egui_editor<T, B, U>(
     update: U,
 ) -> Option<Box<dyn Editor>>
 where
-    T: 'static + Send + Sync,
+    T: 'static + Send,
     B: Fn(&Context, &mut Queue, &mut T) + 'static + Send + Sync,
     U: Fn(&Context, &ParamSetter, &mut Queue, &mut T) + 'static + Send + Sync,
 {
     Some(Box::new(editor::EguiEditor {
         egui_state,
-        user_state: Arc::new(RwLock::new(user_state)),
+        user_state: Arc::new(Mutex::new(user_state)),
         settings: Arc::new(settings),
         build: Arc::new(build),
         update: Arc::new(update),