Add a dasp_graph crate.

This adds a new crate for working with dynamic audio graphs.

From the new docs:

> `dasp_graph` is targeted towards users who require an efficient yet
> flexible and dynamically configurable audio graph. Use cases might
> include virtual mixers, digital audio workstations, game audio systems,
> virtual modular synthesizers and related usecases.

This work has been a long-time coming and is the result of many
discussions in the rust audio community and many lessons learned over
the last few years of working with rust and audio. In particular:

- the development of and reflection on [dsp-chain](https://crates.io/crates/dsp-chain) and its shortcomings.
- The (reasonable) limitations of [dasp_signal](https://crates.io/crates/dasp_signal) when dynamically configuring graphs.
- Discussion on the design of audio graphs with @raphlinus at RustAudio/dsp-chain#141.
- The development of the [spatial audio server](https://github.com/museumsvictoria/spatial_audio_server).
- A recent email discussion with Sami Perttu on DASP and audio graphs.

`dasp_graph` is of course not a one-size-fits-all solution. Instead, it
is designed specifically to work well alongside (and fill a gap within)
the rest of the `dasp` crate ecosystem. Please refer to the "Comparing
`dasp_signal`" section of the `dasp_graph` root documentation for a more
detailed overview of the design choices between the two, what
applications each are best suited toward and how the two best
interoperate together.

A small suite of node implementations are provided out of the box
including a `Delay`, `Sum`, `Pass`, `GraphNode` and `BoxedNode`, all of
which can be enabled/disabled via their associated features.

Following this, I have some ideas for adding an optional `sync` module
to the crate, aimed at controlling and monitoring a dasp graph and it's
nodes from a separate thread (i.e. for convenient use alongside a GUI)
in a non-dynamically-allocating, non-blocking manner. The work so far
has been performed with these plans in mind. The ideas are for the most
part based on the discussion at RustAudio/dsp-chain#141.

Also, `no_std` support for `dasp_graph` is currently blocked on petgraph
support for `no_std`. A PR is open for adding `no_std` support at
petgraph/petgraph#238. In the meantime, the `std` feature must be
enabled to use the new `dasp::graph` module. This is also noted in the
updated docs.

For more information about the crate and inner workings feel free to
read through the new `dasp_graph` docs. I'm yet to add examples, but
hopefully the added tests can give a good idea of how to use the crate
in the meantime.

Author: mitchmindtree

Cargo.toml

@@ -3,6 +3,7 @@ members = [
     "dasp",
     "dasp_envelope",
     "dasp_frame",
+    "dasp_graph",
     "dasp_interpolate",
     "dasp_peak",
     "dasp_ring_buffer",

dasp/Cargo.toml

@@ -13,6 +13,7 @@ edition = "2018"
 [dependencies]
 dasp_envelope = { version = "0.11", path = "../dasp_envelope", default-features = false, optional = true }
 dasp_frame = { version = "0.11", path = "../dasp_frame", default-features = false }
+dasp_graph = { version = "0.11", path = "../dasp_graph", default-features = false, optional = true }
 dasp_interpolate = { version = "0.11", path = "../dasp_interpolate", default-features = false, optional = true }
 dasp_peak = { version = "0.11", path = "../dasp_peak", default-features = false, optional = true }
 dasp_ring_buffer = { version = "0.11", path = "../dasp_ring_buffer", default-features = false, optional = true }
@@ -24,7 +25,13 @@ dasp_window = { version = "0.11", path = "../dasp_window", default-features = fa
 
 [features]
 default = ["std"]
-all = ["std", "all-no-std"]
+all = [
+    "std",
+    "all-no-std",
+    # TODO: Move these into `all-no-std` once `dasp_graph` gains `no_std` support.
+    "graph",
+    "graph-all-nodes",
+]
 all-no-std = [
     "envelope",
     "envelope-peak",
@@ -65,6 +72,13 @@ std = [
 envelope = ["dasp_envelope"]
 envelope-peak = ["dasp_envelope/peak"]
 envelope-rms = ["dasp_envelope/rms"]
+graph = ["dasp_graph"]
+graph-all-nodes = ["dasp_graph/all-nodes"]
+graph-node-boxed = ["dasp_graph/node-boxed"]
+graph-node-delay = ["dasp_graph/node-delay"]
+graph-node-graph = ["dasp_graph/node-graph"]
+graph-node-pass = ["dasp_graph/node-pass"]
+graph-node-sum = ["dasp_graph/node-sum"]
 interpolate = ["dasp_interpolate"]
 interpolate-floor = ["dasp_interpolate/floor"]
 interpolate-linear = ["dasp_interpolate/linear"]

dasp/src/lib.rs

@@ -23,6 +23,7 @@
 //! - See the [**Converter** type](./signal/interpolate/struct.Converter.html) for sample rate
 //!   conversion and scaling.
 //! - See the [**ring_buffer** module](./ring_buffer/index.html) for fast FIFO queue options.
+//! - See the [**graph** module](./graph/index.html) for working with dynamic audio graphs.
 //!
 //! ## Optional Features
 //!
@@ -40,6 +41,16 @@
 //!   [envelope](./envelope/index.html) module.
 //!     - The **envelope-peak** feature enables peak envelope detection.
 //!     - The **envelope-rms** feature enables RMS envelope detection.
+//! - The **graph** feature enables the `dasp_graph` crate via the [graph](./graph/index.html)
+//!   module.
+//!     - The **node-boxed** feature provides a `Node` implementation for `Box<dyn Node>`.
+//!     - The **node-delay** feature provides a simple multi-channel `Delay` node.
+//!     - The **node-graph** feature provides an implementation of `Node` for a type that encapsulates
+//!       another `dasp` graph type.
+//!     - The **node-pass** feature provides a `Pass` node that simply passes audio from its
+//!       inputs to its outputs.
+//!     - The **node-signal** feature provides an implementation of `Node` for `dyn Signal`.
+//!     - The **node-sum** feature provides `Sum` and `SumBuffers` `Node` implementations.
 //! - The **interpolate** feature enables the `dasp_interpolate` crate via the
 //!   [interpolate](./interpolate/index.html) module.
 //!     - The **interpolate-floor** feature enables a floor interpolation implementation.
@@ -83,6 +94,10 @@
 //! `--no-default-features`.
 //!
 //! To enable all of the above features in a `no_std` context, enable the **all-no-std** feature.
+//!
+//! *Note: The **graph** module is currently only available with the **std** feature enabled.
+//! Adding support for `no_std` is pending the addition of support for `no_std` in petgraph. See
+//! [this PR](https://github.com/petgraph/petgraph/pull/238).
 
 #![cfg_attr(not(feature = "std"), no_std)]
 
@@ -91,6 +106,10 @@
 pub use dasp_envelope as envelope;
 #[doc(inline)]
 pub use dasp_frame::{self as frame, Frame};
+// TODO: Remove `std` requirement once `dasp_graph` gains `no_std` support.
+#[cfg(all(feature = "graph", feature = "std"))]
+#[doc(inline)]
+pub use dasp_graph as graph;
 #[cfg(feature = "interpolate")]
 #[doc(inline)]
 pub use dasp_interpolate as interpolate;

dasp_graph/Cargo.toml

@@ -0,0 +1,31 @@
+[package]
+name = "dasp_graph"
+description = "A digital audio signal processing graph."
+version = "0.11.0"
+authors = ["mitchmindtree <[email protected]>"]
+readme = "../README.md"
+keywords = ["dsp", "audio", "graph", "pcm", "audio"]
+license = "MIT OR Apache-2.0"
+repository = "https://github.com/rustaudio/dasp.git"
+homepage = "https://github.com/rustaudio/dasp"
+edition = "2018"
+
+[features]
+default = ["all-nodes"]
+all-nodes = ["node-boxed", "node-delay", "node-graph", "node-pass", "node-signal", "node-sum"]
+node-boxed = []
+node-delay = ["dasp_ring_buffer"]
+node-graph = []
+node-pass = []
+node-signal = ["dasp_frame", "dasp_signal"]
+node-sum = ["dasp_slice"]
+
+[dependencies]
+dasp_frame = { version = "0.11", default-features = false, features = ["std"], optional = true }
+dasp_ring_buffer = { version = "0.11", default-features = false, features = ["std"], optional = true }
+dasp_signal = { version = "0.11", default-features = false, features = ["std"], optional = true }
+dasp_slice = { version = "0.11", default-features = false, features = ["std"], optional = true }
+petgraph = { version = "0.5", default-features = false }
+
+[dev-dependencies]
+petgraph = { version = "0.5", features = ["stable_graph"] }

dasp_graph/src/buffer.rs

@@ -0,0 +1,59 @@
+use core::fmt;
+use core::ops::{Deref, DerefMut};
+
+/// The fixed-size buffer used for processing the graph.
+#[derive(Clone)]
+pub struct Buffer {
+    data: [f32; Self::LEN],
+}
+
+impl Buffer {
+    /// The fixed length of the **Buffer** type.
+    pub const LEN: usize = 64;
+    /// A silent **Buffer**.
+    pub const SILENT: Self = Buffer {
+        data: [0.0; Self::LEN],
+    };
+
+    /// Short-hand for writing silence to the whole buffer.
+    pub fn silence(&mut self) {
+        self.data.copy_from_slice(&Self::SILENT)
+    }
+}
+
+impl Default for Buffer {
+    fn default() -> Self {
+        Self::SILENT
+    }
+}
+
+impl From<[f32; Self::LEN]> for Buffer {
+    fn from(data: [f32; Self::LEN]) -> Self {
+        Buffer { data }
+    }
+}
+
+impl fmt::Debug for Buffer {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        fmt::Debug::fmt(&self.data[..], f)
+    }
+}
+
+impl PartialEq for Buffer {
+    fn eq(&self, other: &Self) -> bool {
+        &self[..] == &other[..]
+    }
+}
+
+impl Deref for Buffer {
+    type Target = [f32];
+    fn deref(&self) -> &Self::Target {
+        &self.data[..]
+    }
+}
+
+impl DerefMut for Buffer {
+    fn deref_mut(&mut self) -> &mut Self::Target {
+        &mut self.data[..]
+    }
+}