From ff202ea8910b23ed6c3e79d8ab73a3e081995dd4 Mon Sep 17 00:00:00 2001
From: Weird Constructor <weirdconstructor@gmail.com>
Date: Sun, 24 Jul 2022 07:34:45 +0200
Subject: [PATCH] Improved top level documentation

---
 CHANGELOG.md |  2 ++
 README.md    | 29 +++++++++++++++++++++++++++--
 src/lib.rs   | 29 +++++++++++++++++++++++++++--
 3 files changed, 56 insertions(+), 4 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6e9b0c2..085e13b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,3 +10,5 @@ similar bugs in the delay line (and all-pass & comb filters). Refactored
 the cubic interpolation and tested it seperately now.
 * Feature: Matrix::get\_connections() returns information about the connections
 to the adjacent cells.
+* Feature: Added the MatrixCellChain abstraction for easy creation of DSP
+chains on the hexagonal Matrix.
diff --git a/README.md b/README.md
index 076aaf5..832e0ef 100644
--- a/README.md
+++ b/README.md
@@ -111,13 +111,16 @@ use hexodsp::*;
 let (node_conf, mut node_exec) = new_node_engine();
 let mut matrix = Matrix::new(node_conf, 3, 3);
 
-
 let sin = NodeId::Sin(0);
 let amp = NodeId::Amp(0);
+let out = NodeId::Out(0);
 matrix.place(0, 0, Cell::empty(sin)
                    .out(None, None, sin.out("sig")));
 matrix.place(0, 1, Cell::empty(amp)
-                   .input(amp.inp("inp"), None, None));
+                   .input(amp.inp("inp"), None, None)
+                   .out(None, None, amp.out("sig")));
+matrix.place(0, 2, Cell::empty(out)
+                   .input(out.inp("inp"), None, None));
 matrix.sync().unwrap();
 
 let gain_p = amp.inp_param("gain").unwrap();
@@ -128,6 +131,28 @@ let (out_l, out_r) = node_exec.test_run(0.11, true);
 // samples now.
 ```
 
+There is also a simplified version for easier setup of DSP chains
+on the hexagonal grid, using the [crate::MatrixCellChain] abstraction:
+
+```rust
+use hexodsp::*;
+
+let (node_conf, mut node_exec) = new_node_engine();
+let mut matrix = Matrix::new(node_conf, 3, 3);
+let mut chain = MatrixCellChain::new(CellDir::B);
+
+chain.node_out("sin", "sig")
+    .node_io("amp", "inp", "sig")
+    .set_atom("gain", SAtom::param(0.25))
+    .node_inp("out", "ch1")
+    .place(&mut matrix, 0, 0);
+matrix.sync().unwrap();
+
+let (out_l, out_r) = node_exec.test_run(0.11, true);
+// out_l and out_r contain two channels of audio
+// samples now.
+```
+
 ### State of Development
 
 As of 2021-05-18: The architecture and it's functionality have been mostly
diff --git a/src/lib.rs b/src/lib.rs
index 7704886..f68aa3a 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -113,13 +113,16 @@ use hexodsp::*;
 let (node_conf, mut node_exec) = new_node_engine();
 let mut matrix = Matrix::new(node_conf, 3, 3);
 
-
 let sin = NodeId::Sin(0);
 let amp = NodeId::Amp(0);
+let out = NodeId::Out(0);
 matrix.place(0, 0, Cell::empty(sin)
                    .out(None, None, sin.out("sig")));
 matrix.place(0, 1, Cell::empty(amp)
-                   .input(amp.inp("inp"), None, None));
+                   .input(amp.inp("inp"), None, None)
+                   .out(None, None, amp.out("sig")));
+matrix.place(0, 2, Cell::empty(out)
+                   .input(out.inp("inp"), None, None));
 matrix.sync().unwrap();
 
 let gain_p = amp.inp_param("gain").unwrap();
@@ -130,6 +133,28 @@ let (out_l, out_r) = node_exec.test_run(0.11, true);
 // samples now.
 ```
 
+There is also a simplified version for easier setup of DSP chains
+on the hexagonal grid, using the [crate::MatrixCellChain] abstraction:
+
+```rust
+use hexodsp::*;
+
+let (node_conf, mut node_exec) = new_node_engine();
+let mut matrix = Matrix::new(node_conf, 3, 3);
+let mut chain = MatrixCellChain::new(CellDir::B);
+
+chain.node_out("sin", "sig")
+    .node_io("amp", "inp", "sig")
+    .set_atom("gain", SAtom::param(0.25))
+    .node_inp("out", "ch1")
+    .place(&mut matrix, 0, 0);
+matrix.sync().unwrap();
+
+let (out_l, out_r) = node_exec.test_run(0.11, true);
+// out_l and out_r contain two channels of audio
+// samples now.
+```
+
 ## State of Development
 
 As of 2021-05-18: The architecture and it's functionality have been mostly