future-proof list of node processing buffers

Author: BillyDM

crates/firewheel-core/src/node.rs

@@ -186,8 +186,19 @@ pub struct EmptyConfig;
 
 /// A dyn-compatible [`AudioNode`].
 pub trait DynAudioNode {
+    /// Get information about this node.
+    ///
+    /// This method is only called once after the node is added to the audio graph.
     fn info(&self) -> AudioNodeInfo;
+
+    /// Construct a processor for this node.
     fn processor(&self, stream_info: &StreamInfo) -> Box<dyn AudioNodeProcessor>;
+
+    /// If [`AudioNodeInfo::call_update_method`] was set to `true`, then the Firewheel
+    /// context will call this method on every update cycle.
+    ///
+    /// * `id` - The ID of this node.
+    /// * `configuration` - The custom configuration of this node.
     fn update(&mut self, cx: UpdateContext) {
         let _ = cx;
     }
@@ -236,22 +247,14 @@ pub trait AudioNodeProcessor: 'static + Send {
     /// If any output buffers contain all zeros up to `samples` (silent),
     /// then mark that buffer as silent in [`ProcInfo::out_silence_mask`].
     ///
-    /// * `inputs` - The input buffers.
-    /// * `outputs` - The output buffers,
-    /// * `events` - A list of events for this node to process.
+    /// * `buffers` - The buffers of data to process.
     /// * `proc_info` - Additional information about the process.
-    /// * `scratch_buffers` - A list of extra scratch buffers that can be
-    /// used for processing. This removes the need for nodes to allocate
-    /// their own scratch buffers. Each buffer has a length of
-    /// [`StreamInfo::max_block_frames`]. These buffers are shared across
-    /// all nodes, so assume that they contain junk data.
+    /// * `events` - A list of events for this node to process.
     fn process(
         &mut self,
-        inputs: &[&[f32]],
-        outputs: &mut [&mut [f32]],
-        events: NodeEventList,
+        buffers: ProcBuffers,
         proc_info: &ProcInfo,
-        scratch_buffers: ScratchBuffers,
+        events: NodeEventList,
     ) -> ProcessStatus;
 
     /// Called when the audio stream has been stopped.
@@ -269,12 +272,33 @@ pub trait AudioNodeProcessor: 'static + Send {
 
 pub const NUM_SCRATCH_BUFFERS: usize = 8;
 
-/// A list of extra scratch buffers that can be
-/// used for processing. This removes the need for nodes to allocate
-/// their own scratch buffers. Each buffer has a length of
-/// [`StreamInfo::max_block_frames`]. These buffers are shared across
-/// all nodes, so assume that they contain junk data.
-pub type ScratchBuffers<'a, 'b> = &'a mut [&'b mut [f32]; NUM_SCRATCH_BUFFERS];
+/// The buffers used in [`AudioNodeProcessor::process`].
+pub struct ProcBuffers<'a, 'b, 'c, 'd> {
+    /// The audio input buffers.
+    ///
+    /// The number of channels will always equal the [`ChannelConfig::num_inputs`]
+    /// value that was returned in [`AudioNode::info`].
+    ///
+    /// Each channel slice will have a length of [`ProcInfo::frames`].
+    pub inputs: &'a [&'b [f32]],
+
+    /// The audio input buffers.
+    ///
+    /// The number of channels will always equal the [`ChannelConfig::num_outputs`]
+    /// value that was returned in [`AudioNode::info`].
+    ///
+    /// Each channel slice will have a length of [`ProcInfo::frames`].
+    ///
+    /// These buffers may contain junk data.
+    pub outputs: &'a mut [&'b mut [f32]],
+
+    /// A list of extra scratch buffers that can be used for processing.
+    /// This removes the need for nodes to allocate their own scratch buffers.
+    /// Each buffer has a length of [`StreamInfo::max_block_frames`]. These
+    /// buffers are shared across all nodes, so assume that they contain junk
+    /// data.
+    pub scratch_buffers: &'c mut [&'d mut [f32]; NUM_SCRATCH_BUFFERS],
+}
 
 /// Additional information for processing audio
 pub struct ProcInfo<'a> {

crates/firewheel-core/src/node/dummy.rs

@@ -1,8 +1,6 @@
 use crate::{channel_config::ChannelConfig, event::NodeEventList, StreamInfo};
 
-use super::{
-    AudioNode, AudioNodeInfo, AudioNodeProcessor, ProcInfo, ProcessStatus, ScratchBuffers,
-};
+use super::{AudioNode, AudioNodeInfo, AudioNodeProcessor, ProcBuffers, ProcInfo, ProcessStatus};
 
 /// A "dummy" [`AudioNode`], a node which does nothing.
 #[derive(Default, Debug, Clone, Copy, PartialEq, Eq)]
@@ -38,11 +36,9 @@ struct DummyProcessor;
 impl AudioNodeProcessor for DummyProcessor {
     fn process(
         &mut self,
-        _inputs: &[&[f32]],
-        _outputs: &mut [&mut [f32]],
-        _events: NodeEventList,
+        _buffers: ProcBuffers,
         _proc_info: &ProcInfo,
-        _scratch_buffers: ScratchBuffers,
+        _events: NodeEventList,
     ) -> ProcessStatus {
         ProcessStatus::Bypass
     }

crates/firewheel-graph/src/graph/compiler/schedule.rs

@@ -3,7 +3,7 @@ use smallvec::SmallVec;
 use std::fmt::Debug;
 
 use firewheel_core::{
-    node::{AudioNodeProcessor, ProcessStatus},
+    node::{AudioNodeProcessor, ProcBuffers, ProcessStatus, NUM_SCRATCH_BUFFERS},
     SilenceMask,
 };
 
@@ -339,16 +339,11 @@ impl CompiledSchedule {
         (read_outputs)(outputs.as_slice(), silence_mask);
     }
 
-    pub fn process(
+    pub fn process<'a, 'b>(
         &mut self,
         frames: usize,
-        mut process: impl FnMut(
-            NodeID,
-            SilenceMask,
-            SilenceMask,
-            &[&[f32]],
-            &mut [&mut [f32]],
-        ) -> ProcessStatus,
+        scratch_buffers: &'a mut [&'b mut [f32]; NUM_SCRATCH_BUFFERS],
+        mut process: impl FnMut(NodeID, SilenceMask, SilenceMask, ProcBuffers) -> ProcessStatus,
     ) {
         let frames = frames.min(self.max_block_frames);
 
@@ -409,8 +404,11 @@ impl CompiledSchedule {
                 scheduled_node.id,
                 in_silence_mask,
                 out_silence_mask,
-                inputs.as_slice(),
-                outputs.as_mut_slice(),
+                ProcBuffers {
+                    inputs: inputs.as_slice(),
+                    outputs: outputs.as_mut_slice(),
+                    scratch_buffers,
+                },
             );
 
             let clear_buffer = |buffer_index: usize, silence_flag: &mut bool| {

crates/firewheel-graph/src/processor.rs

@@ -16,8 +16,8 @@ use firewheel_core::{
     dsp::{buffer::ChannelBuffer, declick::DeclickValues},
     event::{NodeEvent, NodeEventList},
     node::{
-        AudioNodeProcessor, NodeID, ProcInfo, ProcessStatus, StreamStatus, TransportInfo,
-        NUM_SCRATCH_BUFFERS,
+        AudioNodeProcessor, NodeID, ProcBuffers, ProcInfo, ProcessStatus, StreamStatus,
+        TransportInfo, NUM_SCRATCH_BUFFERS,
     },
     SilenceMask, StreamInfo,
 };
@@ -531,11 +531,11 @@ impl FirewheelProcessorInner {
 
         schedule_data.schedule.process(
             block_frames,
+            &mut scratch_buffers,
             |node_id: NodeID,
              in_silence_mask: SilenceMask,
              out_silence_mask: SilenceMask,
-             inputs: &[&[f32]],
-             outputs: &mut [&mut [f32]]|
+             proc_buffers: ProcBuffers|
              -> ProcessStatus {
                 let Some(node_entry) = self.nodes.get_mut(node_id.0) else {
                     return ProcessStatus::Bypass;
@@ -546,13 +546,9 @@ impl FirewheelProcessorInner {
                 proc_info.in_silence_mask = in_silence_mask;
                 proc_info.out_silence_mask = out_silence_mask;
 
-                let status = node_entry.processor.process(
-                    inputs,
-                    outputs,
-                    events,
-                    &proc_info,
-                    &mut scratch_buffers,
-                );
+                let status = node_entry
+                    .processor
+                    .process(proc_buffers, &proc_info, events);
 
                 node_entry.event_indices.clear();
 

crates/firewheel-nodes/src/beep_test.rs

@@ -4,8 +4,8 @@ use firewheel_core::{
     dsp::volume::{Volume, DEFAULT_AMP_EPSILON},
     event::NodeEventList,
     node::{
-        AudioNode, AudioNodeInfo, AudioNodeProcessor, EmptyConfig, ProcInfo, ProcessStatus,
-        ScratchBuffers,
+        AudioNode, AudioNodeInfo, AudioNodeProcessor, EmptyConfig, ProcBuffers, ProcInfo,
+        ProcessStatus,
     },
 };
 
@@ -80,13 +80,11 @@ struct Processor {
 impl AudioNodeProcessor for Processor {
     fn process(
         &mut self,
-        _inputs: &[&[f32]],
-        outputs: &mut [&mut [f32]],
-        events: NodeEventList,
+        buffers: ProcBuffers,
         _proc_info: &ProcInfo,
-        _scratch_buffers: ScratchBuffers,
+        events: NodeEventList,
     ) -> ProcessStatus {
-        let Some(out) = outputs.first_mut() else {
+        let Some(out) = buffers.outputs.first_mut() else {
             return ProcessStatus::ClearAllOutputs;
         };
 

crates/firewheel-nodes/src/peak_meter.rs

@@ -7,8 +7,8 @@ use firewheel_core::{
     dsp::volume::{amp_to_db, DbMeterNormalizer},
     event::NodeEventList,
     node::{
-        AudioNode, AudioNodeInfo, AudioNodeProcessor, EmptyConfig, ProcInfo, ProcessStatus,
-        NUM_SCRATCH_BUFFERS,
+        AudioNode, AudioNodeInfo, AudioNodeProcessor, EmptyConfig, ProcBuffers, ProcInfo,
+        ProcessStatus,
     },
     StreamInfo,
 };
@@ -245,11 +245,9 @@ struct Processor<const NUM_CHANNELS: usize> {
 impl<const NUM_CHANNELS: usize> AudioNodeProcessor for Processor<NUM_CHANNELS> {
     fn process(
         &mut self,
-        inputs: &[&[f32]],
-        _outputs: &mut [&mut [f32]],
-        _events: NodeEventList,
+        buffers: ProcBuffers,
         proc_info: &ProcInfo,
-        _scratch_buffers: &mut [&mut [f32]; NUM_SCRATCH_BUFFERS],
+        _events: NodeEventList,
     ) -> ProcessStatus {
         let enabled = self.shared_state.enabled.load(Ordering::Relaxed);
 
@@ -264,7 +262,8 @@ impl<const NUM_CHANNELS: usize> AudioNodeProcessor for Processor<NUM_CHANNELS> {
             return ProcessStatus::Bypass;
         }
 
-        for (i, (in_ch, peak_shared)) in inputs
+        for (i, (in_ch, peak_shared)) in buffers
+            .inputs
             .iter()
             .zip(self.shared_state.peak_gains.iter())
             .enumerate()

crates/firewheel-nodes/src/sampler.rs

@@ -19,7 +19,7 @@ use firewheel_core::{
         volume::{Volume, DEFAULT_AMP_EPSILON},
     },
     event::{NodeEventList, NodeEventType, SequenceCommand},
-    node::{AudioNode, AudioNodeInfo, AudioNodeProcessor, ProcInfo, ProcessStatus, ScratchBuffers},
+    node::{AudioNode, AudioNodeInfo, AudioNodeProcessor, ProcBuffers, ProcInfo, ProcessStatus},
     sample_resource::SampleResource,
     SilenceMask, StreamInfo,
 };
@@ -737,11 +737,9 @@ impl SamplerProcessor {
 impl AudioNodeProcessor for SamplerProcessor {
     fn process(
         &mut self,
-        _inputs: &[&[f32]],
-        outputs: &mut [&mut [f32]],
-        mut events: NodeEventList,
+        buffers: ProcBuffers,
         proc_info: &ProcInfo,
-        _scratch_buffers: ScratchBuffers,
+        mut events: NodeEventList,
     ) -> ProcessStatus {
         events.for_each(|event| match event {
             NodeEventType::SequenceCommand(command) => {
@@ -752,7 +750,7 @@ impl AudioNodeProcessor for SamplerProcessor {
 
                 match command {
                     SequenceCommand::StartOrRestart { delay } => {
-                        self.stop(proc_info.declick_values, outputs.len());
+                        self.stop(proc_info.declick_values, buffers.outputs.len());
 
                         self.playback_state = PlaybackState::Playing;
 
@@ -808,7 +806,7 @@ impl AudioNodeProcessor for SamplerProcessor {
                         }
                     }
                     SequenceCommand::Stop => {
-                        self.stop(proc_info.declick_values, outputs.len());
+                        self.stop(proc_info.declick_values, buffers.outputs.len());
 
                         self.playback_state = PlaybackState::Stopped;
                     }
@@ -824,9 +822,9 @@ impl AudioNodeProcessor for SamplerProcessor {
                         params,
                         start_immediately,
                     } => {
-                        self.stop(proc_info.declick_values, outputs.len());
+                        self.stop(proc_info.declick_values, buffers.outputs.len());
 
-                        self.set_sequence(&mut params.sequence, outputs.len());
+                        self.set_sequence(&mut params.sequence, buffers.outputs.len());
 
                         if self.params.sequence.is_none() {
                             return;
@@ -855,13 +853,17 @@ impl AudioNodeProcessor for SamplerProcessor {
                                 + (seconds.fract() * self.sample_rate).round() as u64
                         };
 
-                        self.set_playhead(playhead_frames, proc_info.declick_values, outputs.len());
+                        self.set_playhead(
+                            playhead_frames,
+                            proc_info.declick_values,
+                            buffers.outputs.len(),
+                        );
                     }
                     SamplerEvent::SetPlayheadSamples(playhead_frames) => {
                         self.set_playhead(
                             *playhead_frames,
                             proc_info.declick_values,
-                            outputs.len(),
+                            buffers.outputs.len(),
                         );
                     }
                 }
@@ -907,7 +909,7 @@ impl AudioNodeProcessor for SamplerProcessor {
                         .do_loop(sample_state.num_times_looped_back);
 
                     let (finished, n_channels) = self.process_internal(
-                        outputs,
+                        buffers.outputs,
                         proc_info.frames,
                         looping,
                         proc_info.declick_values,
@@ -938,7 +940,12 @@ impl AudioNodeProcessor for SamplerProcessor {
             }
         }
 
-        for (i, out_buf) in outputs.iter_mut().enumerate().skip(num_filled_channels) {
+        for (i, out_buf) in buffers
+            .outputs
+            .iter_mut()
+            .enumerate()
+            .skip(num_filled_channels)
+        {
             if !proc_info.out_silence_mask.is_channel_silent(i) {
                 out_buf[..proc_info.frames].fill(0.0);
             }
@@ -960,7 +967,7 @@ impl AudioNodeProcessor for SamplerProcessor {
                 let copy_frames = proc_info.frames.min(declicker.frames_left);
                 let start_frame = fade_out_frames - declicker.frames_left;
 
-                for (out_buf, tmp_buf) in outputs.iter_mut().zip(tmp_buffers.iter()) {
+                for (out_buf, tmp_buf) in buffers.outputs.iter_mut().zip(tmp_buffers.iter()) {
                     for (os, &ts) in out_buf[..copy_frames]
                         .iter_mut()
                         .zip(tmp_buf[start_frame..start_frame + copy_frames].iter())
@@ -978,10 +985,10 @@ impl AudioNodeProcessor for SamplerProcessor {
             }
         }
 
-        let out_silence_mask = if num_filled_channels >= outputs.len() {
+        let out_silence_mask = if num_filled_channels >= buffers.outputs.len() {
             SilenceMask::NONE_SILENT
         } else {
-            let mut mask = SilenceMask::new_all_silent(outputs.len());
+            let mut mask = SilenceMask::new_all_silent(buffers.outputs.len());
             for i in 0..num_filled_channels {
                 mask.set_channel(i, false);
             }