// Copyright (c) 2021-2022 Weird Constructor // This file is a part of HexoDSP. Released under GPL-3.0-or-later. // See README.md and COPYING for details. /*! # HexoDSP DSP nodes and DSP code ## How to Add a New DSP Node When adding a new node to HexoDSP, I recommend working through the following checklist: - [ ] Implement boilerplate in node_yourname.rs - [ ] Add input parameter and output signal definition to dsp/mod.rs - [ ] Document boilerplate in node_yourname.rs - [ ] DSP implementation - [ ] Parameter fine tuning - [ ] DSP tests for all (relevant) params - [ ] Ensure Documentation is properly formatted for the GUI - [ ] Format the source using `cargo fmt` - [ ] Add CHANGELOG.md entry in HexoSynth - [ ] Add CHANGELOG.md entry in HexoDSP - [ ] Add table entry in README.md in HexoSynth - [ ] Add table entry in README.md in HexoDSP The boilerplate can be a bit daunting. But it pays off, because HexoSynth will give you a GUI for your DSP code for free at the end. Generally I recommend starting out small. Define your new node with minimal parameters until you get the hang of all the things involved to make it compile in the first place. **Be aware that new DSP nodes need to meet these quality guidelines to be included:** - Clean Rust code that I can understand and maintain. You can use `cargo fmt` (rustfmt) to format the code. - Does not drag in huge dependency trees. One rationale here is, that I don't want the sound of a HexoSynth patch to change (significantly) because some upstream crate decided to change their DSP code. To have optimal control over this, I would love to have all the DSP code contained in HexoDSP. Make sure to link the repository the code comes from though. If you add dependencies for your DSP node, make sure that it's characteristics are properly covered by the automated tests. So that problems become visible in case upstream breaks or changes it's DSP code. If DSP code changes just slightly, the test cases of course need to be changed accordingly. - Come with automated smoke tests like all the other nodes, most test signal min/max/rms over time, as well as the frequency spectrum where applicable. - It's parameters have proper denormalized mappings, like `0.5 => 4000 Hz` or `0.3 => 200ms`. - Provide short descriptions for the node and it's parameters. - Provide a comprehensive longer help text with (more details further down in this guide): - What this node is about - How to use it - How the parameters work in combination - Suggestions which combinations with other nodes might be interesting - If applicable: provide a graph function for visualizing what it does. ### Boilerplate - I recommend copying an existing node code, like `node_ad.rs` for instance. - In this file `mod.rs` copy it's entry in the `node_list` macro definition. - Copy the `tests/node_ad.rs` file to have a starting point for the automated testing. Also keep in mind looking in other tests, about how they test things. Commonly used macros are found in the ´tests/common/´ module. A `node_list` macro entry looks like this: ```ignore // node_id => node_label UIType UICategory // | | / | // / /------/ / | // / | / | xxx => Xxx UIType::Generic UICategory::Signal // node_param_idx // name denorm round format steps norm norm denorm // norm_fun fun fun fun def min max default (0 inp n_id d_id r_id f_def stp_d -1.0, 1.0, 0.0) (1 gain n_gain d_gain r_id f_def stp_d 0.0, 1.0, 1.0) (2 att n_att d_att r_id f_def stp_d 0.0, 1.0, 1.0) // node_param_idx UI widget type (mode, knob, sample) // | atom_idx | format fun // | | name constructor| | min max // | | | | def|ult_v|lue | / // | | | | | | | | | {3 0 mono setting(0) mode fa_out_mono 0 1}, [0 sig], ``` The first entries, encapsulated in ´( )´ are the input ports or also called input parameters. Input parameters can be connected to outputs of other DSP nodes. In contrast to the ´{ }´ encapsulated so called _Atom parameters_. The data type for these is the [SAtom] datatype. And these parameters can not be automated. You can freely choose parameter names like eg. `inp` or `gain` and pick names that suit the parameter semantics best. But I would like you to keep the naming consistent with the rest of HexoDSP nodes if that is suitable to the DSP node. There are some implicit conventions in HexoDSP for naming though: - `inp` for single channel signal input - `ch1`, `ch2`, ... for multiple channels - `sig` for signal output - `trig` for receiving a single trigger signal - `t_*` if multiple trigger signals are expected - If you have `freq` inputs, consider also adding `det` for detuning that frequency input. But only if you think this makes sense in the context of the DSP node. The macros in the node list definition like `n_gain`, `d_pit`, `r_fq` and so on are all macros that are defined in the HexoDSP crate. You can create your own normalization/denormalization, rounding, step and formatting function macros if the existing ones don't suit the DSP node's needs. ### Signal Ranges in HexoDSP The HexoDSP graph, or rather the nodes, operate with the raw normalized (audio) signal range [-1, 1]. There is a second range that is also common in HexoDSP, which is the control signal range [0, 1]. Following this convention will help combinding HexoDSP nodes with each other. The existing normalization/denormalization functions for the node list declaration already encode most of the conventions in HexoDSP, but here is a short incomplete overview of common value mappings to the normalized signal ranges: - Frequencies are usually using the `n_pit` and `d_pit` mappings. Where 0.0 is 440Hz and the next octave is at 0.1 with 880Hz and the octave before that is at -0.1 with 220Hz. This means one octave per 0.1 signal value. - Triggers have to rise above the "high" threshold of 0.5 to be recognized, and the signal has to fall below 0.25 to be detected as "low" again. Same works for gates. ### Node Documentation **Attention: Defining the documentation for your DSP node is not optional. It's required to make it compile in the first place!** Every DSP node must come with online documentation. The online documentation is what makes the node usable in the first place. It's the only hint for the user to learn how to use this node. Keep in mind that the user is not an engineer, but usually a musician. They want to make music and know how to use a parameter. Every input parameter and atom parameter requires you to define a documenation entry in the corresponding ´node_*.rs´ module/file. And also a _DESC_ and _HELP_ entry. Here an example from ´node_ad.rs´: ```ignore pub const inp: &'static str = "Ad inp\nSignal input. If you don't connect this, and set this to 1.0 \ this will act as envelope signal generator. But you can also just \ route a signal directly through this of course.\nRange: (-1..1)\n"; ``` The general format of the parameter documentation should be: ```ignore " \n A short description what this paramter means/does and relates to others.\n Range: \n" ``` Keep the description of the paramter short and concise. Look at the space available in HexoSynth where this is displayed. If you want to write more elaborate documentation for a paramter, write it in the `HELP` entry. The _range_ relates to the DSP signal range this paramter is supposed to receive. This should either be the unipolar range (0..1) or the bipolar range (-1..1). Other ranges should be avoided, because everything in HexoDSP is supposed to be fine with receiving values in those ranges. Next you need to document the node itself, how it works what it does and so on... For this there are two entries: ```ignore pub const DESC: &'static str = r#"Attack-Decay Envelope This is a simple envelope offering an attack time and decay time with a shape parameter. You can use it as envelope generator to modulate other inputs or process a signal with it directly. "#; pub const HELP: &'static str = r#"Ad - Attack-Decay Envelope This simple two stage envelope with attack and decay offers shape parameters ... "#; ``` _DESC_ should only contain a short description of the node. It's space is as limited as the space for the parameter description. It will be autowrapped. _HELP_ can be a multiple pages long detailed description of the node. Keep the width of the lines below a certain limit (below 80 usually). Or else it will be truncated in the help text window in HexoSynth. As inspiration what should be in the help documentation: - What the node does (even if it repeats mostly what _DESC_ already says) - How the input paramters relate to each other. - What the different atom settings (if any) mean. - Which other DSP nodes this node is commonly combined with. - Interesting or even uncommon uses of this DSP node. - Try to inspire the user to experiment. ### Node Code Structure For non trivial DSP nodes, the DSP code itself should be separate from it's `dsp/node_*.rs` file. That file should only care about interfacing the DSP code with HexoDSP, but not implement all the complicated DSP code. It's good practice to factor out the DSP code into a separate module or file. Look at `node_tslfo.rs` for instance. It wires up the `TriSawLFO` from `dsp/helpers.rs` to the HexoDSP node interface. ```ignore // node_tslfo.rs use super::helpers::{TriSawLFO, Trigger}; #[derive(Debug, Clone)] pub struct TsLFO { lfo: Box>, trig: Trigger, } // ... impl DspNode for TsLFO { // ... #[inline] fn process(&mut self, /* ... */) { // ... let lfo = &mut *self.lfo; for frame in 0..ctx.nframes() { // ... out.write(frame, lfo.next_unipolar() as f32); } // ... } } ``` The code for `TriSawLFO` in `dsp/helpers.rs` is then independent and reusable else where. ### Node Parameter/Inputs When implementing your node, you want to access the parameters or inputs of your DSP node. This is done using the buffer access modules in `dsp/mod.rs` that are defined using the `node_list` macro. Let me give you a short overview using `node_sin.rs` as an example: ```ignore #[inline] fn process( &mut self, ctx: &mut T, // DSP execution context holding the DSP graph input and output buffers. _ectx: &mut NodeExecContext, // Contains special stuff, like the FeedbackBuffers _nctx: &NodeContext, // Holds context info about the node, for instance which ports // are connected. _atoms: &[SAtom], // An array holding the Atom parameters inputs: &[ProcBuf], // An array holding the input parameter buffers, containing // either outputs from other DSP nodes or smoothed parameter // settings from the GUI/frontend. outputs: &mut [ProcBuf], // An array holding the output buffers. ctx_vals: LedPhaseVals, // Values for visual aids in the GUI (the hextile LED) ) { use crate::dsp::{denorm_offs, inp, out}; let o = out::Sin::sig(outputs); let freq = inp::Sin::freq(inputs); let det = inp::Sin::det(inputs); let isr = 1.0 / self.srate; let mut last_val = 0.0; for frame in 0..ctx.nframes() { let freq = denorm_offs::Sampl::freq(freq, det.read(frame), frame); // ... } // ... } ``` There are three buffer/parameter function access modules loaded in this example: ```ignore use crate::dsp::{denorm_offs, inp, out}; ``` `inp` holds a sub module for each of the available nodes. That means: `inp::Sin`, `inp::Ad`, ... Those submodules each have a function that returns the corresponding buffer from the `inputs` vector of buffers. That means `inp::Sin::det(inputs)` gives you a reference to a [ProcBuf] you can read the normalized signal inputs (range -1 to 1) from. It works similarly with `out::Sin::sig`, which provides you with a [ProcBuf] reference to write your output to. `denorm_offs` is a special module, that offers you functions to access the denormalized value of a specific input parameter with a modulation offset. Commonly you want to use the `denorm` module to access the denormalized values. That means values in human understandable form and that can be used in your DSP arithmetics more easily. For instance `denorm::TsLFO::time` from `node_tslfo.rs`: ```ignore use crate::dsp::{denorm, inp, out}; let time = inp::TsLFO::time(inputs); for frame in 0..ctx.nframes() { let time_ms = denorm::TsLFO::time(time, frame).clamp(0.1, 300000.0); // ... } ``` `denorm::TsLFO::time` is a function that takes the [ProcBuf] with the raw normalized input signal samples and returns the denormalized values in milliseconds for a specific frame. To get a hang of all the possibilities I suggest diving a bit into the other node source code a bit. ### Node Beautification To make nodes responsive in HexoSynth the `DspNode::process` function receives the [LedPhaseVals]. These should be written after the inner loop that calculates the samples. The first context value is the _LED value_, it should be in the range between -1 and 1. The most easy way to set it is by using the last written sample from your loop: ```ignore ctx_vals[0].set(out.read(ctx.nframes() - 1)); ``` But consider giving it a more meaningful value if possible. The `node_ad.rs` sets the LED value to the internal phase value of the envelope instead of it's output. The second value in [LedPhaseVals] is the _Phase value_. It usually has special meaning for the node specific visualizations. Such as TSeq emits the position of the playhead for instance. The CQnt quantizer emits the most recently activated key to the GUI using the Phase value. Consider also providing a visualization graph if possible. You can look eg at `node_ad.rs` or `node_tslfo.rs` or many others how to provide a visualization graph function: ```ignore impl DspNode for TsLFO { fn graph_fun() -> Option { Some(Box::new(|gd: &dyn GraphAtomData, _init: bool, x: f32, xn: f32| -> f32 { // ... })) } } ``` Let me explain the callback function parameters quickly: - `gd: &dyn GraphAtomData` this trait object gives you access to the input paramters of this node. And also the LED and Phase values. - `init: bool` allows you to detect when the first sample of the graph is being drawn/requested. You can use this to reset any state that is carried with the callback. - `x: f32` is the current X position of the graph. Use this to derive the Y value which must be returned from the callback. - `xn: f32` is the next value for X. This is useful for determining if your function might reaches a min or max between _x_ and _xn_, so you could for instance return the min or max value now instead of the next sample. ### Automated Testing of Your Node First lets discuss shortly why automated tests are necessary. HexoDSP has an automated test suite to check if any changes on the internal DSP helpers break something. Or if some changes on some DSP node accidentally broke something. Or if a platform behaves weirdly. Or even if upstream crates that are included broke or changed something essential. A few things you can test your DSP code for: - Is non 0.0 signal emitted? - Is the signal inside the -1..1 or 0..1 range? - Does the signal level change in expected ways if the input parameters are changed? - Does the frequency spectrum peak at expected points in the FFT output? - Does the frequency spectrum change to expected points in the FFT output when an input parameter changed? Try to nail down the characteristics of your DSP node with a few tests as well as possible. For the FFT and other tests there are helper functions in `tests/common/mod.rs` The start of your `tests/node_*.rs` file usually should look like this: ```ignore mod common; use common::*; #[test] fn check_node_ad_1() { 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("ad", "sig") .node_inp("out", "ch1") .place(&mut matrix, 0, 0).unwrap(); matrix.sync().unwrap(); let ad = NodeId::Ad(0); // ... } ``` Lets dissect this a bit. The beginning of each test case should setup an instance of the DSP engine of HexoDSP using [crate::new_node_engine]. It returns a [crate::NodeConfigurator] and a [crate::NodeExecutor]. The first is responsible for setting up the DSP graph and modifying it at runtime. The latter ([crate::NodeExecutor]) is responsible for executing the DSP graph and generate output samples. ```ignore let (node_conf, mut node_exec) = new_node_engine(); ``` The [crate::Matrix] abstraction encapsulates the configurator and provides you an interface to layout the nodes in a hexagonal grid. It is currently the easiest API for using HexoDSP. The two parameters to _new_ are the width and height of the hex grid. ```ignore let mut matrix = Matrix::new(node_conf, 3, 3); ``` Next step is to create a DSP chain of nodes and place that onto the hexagonal matrix. Luckily a simpler API has been created with the [crate::MatrixCellChain], that lets you build DSP chains on the fly using only names of the nodes and the corresponding input/output ports: ```ignore // Create a new cell chain that points in to the given direction (CellDir::B => to bottom). let mut chain = MatrixCellChain::new(CellDir::B); chain.node_out("ad", "sig") // Add a Node::Ad(0) cell, with the "sig" output set .node_inp("out", "ch1") // Add a Node::Out(0) cell, with the "ch1" input set .place(&mut matrix, 0, 0).unwrap(); ``` After placing the new cells, we need to synchronize it with the audio backend: ```ignore matrix.sync().unwrap(); ``` The `sync` is necessary to update the DSP graph. Next you usually want to define short variable names for the [NodeId] that refer to the DSP node instances: ```ignore let ad = NodeId::Ad(0); ``` The [NodeId] interface offers you functions to get the input parameter index from a name like `out.inp("ch1")` or the output port index from a name: `ad.out("sig")`. You can have multiple instances for a node. The number in the parenthesis are the instance index of that node. After you have setup everything for the test, you usually want to modify a paramter and look at the values the graph returns. ```ignore #[test] fn check_node_ad_1() { // ... // matrix setup code above // ... let ad = NodeId::Ad(0); // Fetch parameter id: let trig_p = ad.inp_param("trig").unwrap(); // Set parameter: matrix.set_param(trig_p, SAtom::param(1.0)); /// Run the DSP graph for 25 milliseconds of audio. let res = run_for_ms(&mut node_exec, 25.0); // `res` now contains two vectors. one for first channel "ch1" // and one for the second channel "ch2". assert_decimated_slope_feq!( res.0, // .... ) } ``` ***Attention: This is important to keep in mind:*** After using `matrix.set_param(...)` to set a paramter, keep in mind that the parameter values will be smoothed. That means it will take a few milliseconds until `trig_p` reaches the 1.0. In case of the Ad node that means the trigger threshold won't be triggered at the first sample, but a few milliseconds later! */ #[allow(non_upper_case_globals)] mod node_ad; #[allow(non_upper_case_globals)] mod node_allp; #[allow(non_upper_case_globals)] mod node_amp; #[allow(non_upper_case_globals)] mod node_biqfilt; #[allow(non_upper_case_globals)] mod node_bosc; #[allow(non_upper_case_globals)] mod node_bowstri; #[allow(non_upper_case_globals)] mod node_comb; #[allow(non_upper_case_globals)] mod node_cqnt; #[allow(non_upper_case_globals)] mod node_delay; #[allow(non_upper_case_globals)] mod node_fbwr_fbrd; #[allow(non_upper_case_globals)] mod node_map; #[allow(non_upper_case_globals)] mod node_mix3; #[allow(non_upper_case_globals)] mod node_mux9; #[allow(non_upper_case_globals)] mod node_noise; #[allow(non_upper_case_globals)] mod node_out; #[allow(non_upper_case_globals)] mod node_pverb; #[allow(non_upper_case_globals)] mod node_quant; #[allow(non_upper_case_globals)] mod node_rndwk; #[allow(non_upper_case_globals)] mod node_sampl; #[allow(non_upper_case_globals)] mod node_sfilter; #[allow(non_upper_case_globals)] mod node_sin; #[allow(non_upper_case_globals)] mod node_smap; #[allow(non_upper_case_globals)] mod node_test; #[allow(non_upper_case_globals)] mod node_tseq; #[allow(non_upper_case_globals)] mod node_tslfo; #[allow(non_upper_case_globals)] mod node_vosc; #[allow(non_upper_case_globals)] mod node_scope; pub mod biquad; pub mod dattorro; pub mod helpers; mod satom; pub mod tracker; use crate::nodes::NodeAudioContext; use crate::nodes::NodeExecContext; use crate::util::AtomicFloat; use std::sync::Arc; pub type LedPhaseVals<'a> = &'a [Arc]; pub use satom::*; use crate::fa_ad_mult; use crate::fa_amp_neg_att; use crate::fa_biqfilt_ord; use crate::fa_biqfilt_type; use crate::fa_bosc_wtype; use crate::fa_comb_mode; use crate::fa_cqnt; use crate::fa_cqnt_omax; use crate::fa_cqnt_omin; use crate::fa_delay_mode; use crate::fa_distort; use crate::fa_map_clip; use crate::fa_mux9_in_cnt; use crate::fa_noise_mode; use crate::fa_out_mono; use crate::fa_quant; use crate::fa_sampl_dclick; use crate::fa_sampl_dir; use crate::fa_sampl_pmode; use crate::fa_sfilter_type; use crate::fa_smap_clip; use crate::fa_smap_mode; use crate::fa_test_s; use crate::fa_tseq_cmode; use crate::fa_vosc_ovrsmpl; use node_ad::Ad; use node_allp::AllP; use node_amp::Amp; use node_biqfilt::BiqFilt; use node_bosc::BOsc; use node_bowstri::BowStri; use node_comb::Comb; use node_cqnt::CQnt; use node_delay::Delay; use node_fbwr_fbrd::FbRd; use node_fbwr_fbrd::FbWr; use node_map::Map; use node_mix3::Mix3; use node_mux9::Mux9; use node_noise::Noise; use node_out::Out; use node_pverb::PVerb; use node_quant::Quant; use node_rndwk::RndWk; use node_sampl::Sampl; use node_sfilter::SFilter; use node_sin::Sin; use node_smap::SMap; use node_test::Test; use node_tseq::TSeq; use node_tslfo::TsLFO; use node_vosc::VOsc; use node_scope::Scope; pub const MIDI_MAX_FREQ: f32 = 13289.75; pub const MAX_BLOCK_SIZE: usize = 128; /// A context structure that holds temporary information about the /// currently executed node. /// This structure is created by the [crate::nodes::NodeExecutor] on the fly. pub struct NodeContext<'a> { /// The bitmask that indicates which input ports are used/connected /// to some output. pub in_connected: u64, /// The bitmask that indicates which output ports are used/connected /// to some input. pub out_connected: u64, /// The node parameters, which are usually not accessed directly. pub params: &'a [ProcBuf], } /// This trait is an interface between the graph functions /// and the AtomDataModel of the UI. pub trait GraphAtomData { fn get(&self, param_idx: u32) -> Option; fn get_denorm(&self, param_idx: u32) -> f32; fn get_norm(&self, param_idx: u32) -> f32; fn get_phase(&self) -> f32; fn get_led(&self) -> f32; } pub type GraphFun = Box f32>; /// This trait represents a DspNode for the [crate::matrix::Matrix] pub trait DspNode { /// Number of outputs this node has. fn outputs() -> usize; /// Updates the sample rate for the node. fn set_sample_rate(&mut self, _srate: f32); /// Reset any internal state of the node. fn reset(&mut self); /// The code DSP function. /// /// * `ctx` is the audio context, which informs the node about /// the number of samples to process. It also provides input/output /// ports for the in/out nodes. /// * `ectx` is the execution context, which provides global stuff /// for all nodes to potentially use. For instance it's used /// by the `FbWr` and `FbRd` nodes to share an audio buffer. /// * `atoms` are un-smoothed parameters. they can hold integer settings, /// samples or even strings. /// * `params` are smoother paramters, those who usually have a knob /// associated with them. /// * `inputs` contain all the possible inputs. In contrast to `params` /// these inputs might be overwritten by outputs of other nodes. /// * `outputs` are the output buffers of this node. fn process( &mut self, ctx: &mut T, ectx: &mut NodeExecContext, nctx: &NodeContext, atoms: &[SAtom], inputs: &[ProcBuf], outputs: &mut [ProcBuf], led: LedPhaseVals, ); /// A function factory for generating a graph for the generic node UI. fn graph_fun() -> Option { None } } /// A processing buffer with the exact right maximum size. /// This is an unsafe abstraction, and should be used with a lot of care. /// You will have to manually free the buffer, and take care if you /// make copies of these. /// /// This is an abstraction for the inner most DSP processing, where I /// don't want to spend a nanosecond too much on accessing buffers. /// /// The main user is [crate::nodes::NodeProg], which takes extra care /// of allocating and managing the [ProcBuf] instances. /// ///``` /// let mut buf = hexodsp::dsp::ProcBuf::new(); /// /// buf.write(0, 0.42); /// buf.write(1, 0.13); /// buf.write(2, 0.37); /// /// assert_eq!(((buf.read(0) * 100.0).floor()), 42.0); /// assert_eq!(((buf.read(1) * 100.0).floor()), 13.0); /// assert_eq!(((buf.read(2) * 100.0).floor()), 37.0); /// /// buf.free(); // YOU MUST DO THIS! ///``` #[derive(Clone, Copy)] pub struct ProcBuf(*mut [f32; MAX_BLOCK_SIZE]); impl ProcBuf { /// Creates a new ProcBuf with the size of [MAX_BLOCK_SIZE]. pub fn new() -> Self { ProcBuf(Box::into_raw(Box::new([0.0; MAX_BLOCK_SIZE]))) } /// Create a new null ProcBuf, that can't be used. pub fn null() -> Self { ProcBuf(std::ptr::null_mut()) } } impl crate::monitor::MonitorSource for &ProcBuf { /// Copies the contents of this [ProcBuf] to the given `slice`. /// /// * `len` - the number of samples to copy from this [ProcBuf]. /// * `slice` - the slice to copy to. fn copy_to(&self, len: usize, slice: &mut [f32]) { unsafe { slice.copy_from_slice(&(*self.0)[0..len]) } } } unsafe impl Send for ProcBuf {} unsafe impl Sync for ProcBuf {} //unsafe impl Sync for HexoSynthShared {} impl ProcBuf { /// Writes the sample `v` at `idx`. #[inline] pub fn write(&mut self, idx: usize, v: f32) { unsafe { (*self.0)[idx] = v; } } /// Writes the samples from `slice` to this [ProcBuf]. /// Be careful, the `slice` must not exceed [MAX_BLOCK_SIZE], or else /// you will get UB. #[inline] pub fn write_from(&mut self, slice: &[f32]) { unsafe { (*self.0)[0..slice.len()].copy_from_slice(slice); } } /// Reads a sample at `idx`. Be careful to not let the `idx` /// land outside of [MAX_BLOCK_SIZE]. #[inline] pub fn read(&self, idx: usize) -> f32 { unsafe { (*self.0)[idx] } } /// Fills the [ProcBuf] with the sample `v`. #[inline] pub fn fill(&mut self, v: f32) { unsafe { (*self.0).fill(v); } } /// Checks if this is a [ProcBuf::null]. #[inline] pub fn is_null(&self) -> bool { self.0.is_null() } /// Deallocates the [ProcBuf]. If you still keep around /// other copies of this [ProcBuf], you will most likely land in /// UB land. pub fn free(&self) { if !self.0.is_null() { drop(unsafe { Box::from_raw(self.0) }); } } } impl std::fmt::Debug for ProcBuf { fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { unsafe { write!(f, "ProcBuf(")?; if self.0.is_null() { write!(f, "NULL ")?; } else { for i in 0..MAX_BLOCK_SIZE { write!(f, "{:5.4} ", (*self.0)[i])?; } } write!(f, ")") } } } impl std::fmt::Display for ProcBuf { fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { unsafe { write!(f, "ProcBuf(0: {})", (*self.0)[0]) } } } //#[derive(Debug, Clone, Copy)] //enum UIParamDesc { // Knob { width: usize, prec: usize, unit: &'static str }, // Setting { labels: &'static [&'static str], unit: &'static str }, //} #[derive(Debug, Clone, Copy, PartialOrd, PartialEq)] pub enum UIType { Generic, LfoA, EnvA, OscA, } #[derive(Debug, Clone, Copy, PartialOrd, PartialEq)] pub enum UICategory { None, Osc, Mod, NtoM, Signal, Ctrl, IOUtil, } impl UICategory { pub fn default_color_idx(&self) -> u8 { match self { UICategory::None => 17, UICategory::Osc => 0, UICategory::Mod => 7, UICategory::NtoM => 4, UICategory::Signal => 2, UICategory::Ctrl => 12, UICategory::IOUtil => 10, } } } // The following macros define normalize/denormalize functions: macro_rules! n_id { ($x: expr) => { $x }; } macro_rules! d_id { ($x: expr) => { $x }; } macro_rules! define_lin { ($n_id: ident $d_id: ident $min: expr, $max: expr) => { macro_rules! $n_id { ($x: expr) => { (($x - $min) / ($max - $min) as f32).abs() }; } macro_rules! $d_id { ($x: expr) => { $min * (1.0 - $x) + $max * $x }; } }; } macro_rules! define_exp { ($n_id: ident $d_id: ident $min: expr, $max: expr) => { macro_rules! $n_id { ($x: expr) => { (($x - $min) / ($max - $min) as f32).abs().sqrt() }; } macro_rules! $d_id { ($x: expr) => {{ let x: f32 = $x * $x; $min * (1.0 - x) + $max * x }}; } }; } macro_rules! define_exp4 { ($n_id: ident $d_id: ident $min: expr, $max: expr) => { macro_rules! $n_id { ($x: expr) => { (($x - $min) / ($max - $min) as f32).abs().sqrt().sqrt() }; } macro_rules! $d_id { ($x: expr) => {{ let x: f32 = $x * $x * $x * $x; $min * (1.0 - x) + $max * x }}; } }; } macro_rules! define_exp6 { ($n_id: ident $d_id: ident $min: expr, $max: expr) => { macro_rules! $n_id { ($x: expr) => { (($x - $min) / ($max - $min) as f32).abs().powf(1.0 / 6.0) }; } macro_rules! $d_id { ($x: expr) => {{ let x: f32 = ($x).powf(6.0); $min * (1.0 - x) + $max * x }}; } }; } #[macro_export] macro_rules! n_pit { ($x: expr) => { 0.1 * (($x as f32).max(0.01) / 440.0).log2() }; } #[macro_export] macro_rules! d_pit { ($x: expr) => {{ let note: f32 = ($x as f32) * 10.0; 440.0 * (2.0_f32).powf(note.clamp(-10.0, 10.0)) }}; } // The following macros define detune parameter behaviour: // 0.2 => 24.0 // 0.1 => 12.0 // 0.008333333 => 1.0 // 0.000083333 => 0.001 macro_rules! n_det { ($x: expr) => { $x / 120.0 }; } macro_rules! d_det { ($x: expr) => { $x * 120.0 }; } /// The rounding function for detune UI knobs macro_rules! r_det { ($x: expr, $coarse: expr) => { if $coarse { n_det!((d_det!($x)).round()) } else { n_det!((d_det!($x) * 100.0).round() / 100.0) } }; } /// The rounding function for -1 to 1 signal knobs macro_rules! r_s { ($x: expr, $coarse: expr) => { if $coarse { ($x * 10.0).round() / 10.0 } else { ($x * 100.0).round() / 100.0 } }; } /// The rounding function for milliseconds knobs macro_rules! r_dc_ms { ($x: expr, $coarse: expr) => { if $coarse { n_declick!((d_declick!($x)).round()) } else { n_declick!((d_declick!($x) * 10.0).round() / 10.0) } }; } /// The rounding function for milliseconds knobs macro_rules! r_ems { ($x: expr, $coarse: expr) => { if $coarse { n_env!((d_env!($x)).round()) } else { n_env!((d_env!($x) * 10.0).round() / 10.0) } }; } /// The rounding function for milliseconds knobs macro_rules! r_tms { ($x: expr, $coarse: expr) => { if $coarse { if d_time!($x) > 1000.0 { n_time!((d_time!($x) / 100.0).round() * 100.0) } else if d_time!($x) > 100.0 { n_time!((d_time!($x) / 10.0).round() * 10.0) } else { n_time!((d_time!($x)).round()) } } else { n_time!((d_time!($x) * 10.0).round() / 10.0) } }; } /// The rounding function for milliseconds knobs macro_rules! r_fms { ($x: expr, $coarse: expr) => { if $coarse { if d_ftme!($x) > 1000.0 { n_ftme!((d_ftme!($x) / 100.0).round() * 100.0) } else if d_ftme!($x) > 100.0 { n_ftme!((d_ftme!($x) / 10.0).round() * 10.0) } else { n_ftme!((d_ftme!($x)).round()) } } else { n_ftme!((d_ftme!($x) * 10.0).round() / 10.0) } }; } /// The rounding function for milliseconds knobs that also have a 0.0 setting macro_rules! r_tmz { ($x: expr, $coarse: expr) => { if $coarse { if d_timz!($x) > 1000.0 { n_timz!((d_timz!($x) / 100.0).round() * 100.0) } else if d_timz!($x) > 100.0 { n_timz!((d_timz!($x) / 10.0).round() * 10.0) } else { n_timz!((d_timz!($x)).round()) } } else { n_timz!((d_timz!($x) * 10.0).round() / 10.0) } }; } /// The rounding function for freq knobs (n_pit / d_pit) macro_rules! r_fq { ($x: expr, $coarse: expr) => { if $coarse { ($x * 10.0).round() / 10.0 } else { let p = d_pit!($x); if p < 10.0 { n_pit!((p * 10.0).round() / 10.0) } else if p < 100.0 { n_pit!(p.round()) } else if p < 1000.0 { n_pit!((p / 10.0).round() * 10.0) } else if p < 10000.0 { n_pit!((p / 100.0).round() * 100.0) } else { n_pit!((p / 1000.0).round() * 1000.0) } } }; } /// The rounding function for vs (v scale) UI knobs macro_rules! r_vps { ($x: expr, $coarse: expr) => { if $coarse { n_vps!((d_vps!($x)).round()) } else { n_vps!((d_vps!($x) * 10.0).round() / 10.0) } }; } /// The rounding function for LFO time knobs macro_rules! r_lfot { ($x: expr, $coarse: expr) => { if $coarse { let denv = d_lfot!($x); if denv < 10.0 { let hz = 1000.0 / denv; let hz = (hz / 10.0).round() * 10.0; n_lfot!(1000.0 / hz) } else if denv < 250.0 { n_lfot!((denv / 5.0).round() * 5.0) } else if denv < 1500.0 { n_lfot!((denv / 50.0).round() * 50.0) } else if denv < 2500.0 { n_lfot!((denv / 100.0).round() * 100.0) } else if denv < 5000.0 { n_lfot!((denv / 500.0).round() * 500.0) } else if denv < 60000.0 { n_lfot!((denv / 1000.0).round() * 1000.0) } else { n_lfot!((denv / 5000.0).round() * 5000.0) } } else { let denv = d_lfot!($x); let o = if denv < 10.0 { let hz = 1000.0 / denv; let hz = hz.round(); n_lfot!(1000.0 / hz) } else if denv < 100.0 { n_lfot!(denv.round()) } else if denv < 1000.0 { n_lfot!((denv / 5.0).round() * 5.0) } else if denv < 2500.0 { n_lfot!((denv / 10.0).round() * 10.0) } else if denv < 25000.0 { n_lfot!((denv / 100.0).round() * 100.0) } else { n_lfot!((denv / 500.0).round() * 500.0) }; o } }; } /// The default steps function: macro_rules! stp_d { () => { (20.0, 100.0) }; } /// The UI steps to control parameters with a finer fine control: macro_rules! stp_m { () => { (20.0, 200.0) }; } /// The UI steps to control parameters with a very fine fine control: macro_rules! stp_f { () => { (20.0, 1000.0) }; } // Rounding function that does nothing macro_rules! r_id { ($x: expr, $coarse: expr) => { $x }; } // Default formatting function macro_rules! f_def { ($formatter: expr, $v: expr, $denorm_v: expr) => { write!($formatter, "{:6.3}", $denorm_v) }; } // Default formatting function with low precision macro_rules! f_deflp { ($formatter: expr, $v: expr, $denorm_v: expr) => { write!($formatter, "{:5.2}", $denorm_v) }; } // Default formatting function with very low precision macro_rules! f_defvlp { ($formatter: expr, $v: expr, $denorm_v: expr) => { write!($formatter, "{:4.1}", $denorm_v) }; } macro_rules! f_freq { ($formatter: expr, $v: expr, $denorm_v: expr) => { if ($denorm_v >= 1000.0) { write!($formatter, "{:6.0}Hz", $denorm_v) } else if ($denorm_v >= 100.0) { write!($formatter, "{:6.1}Hz", $denorm_v) } else { write!($formatter, "{:6.2}Hz", $denorm_v) } }; } macro_rules! f_ms { ($formatter: expr, $v: expr, $denorm_v: expr) => { if $denorm_v >= 1000.0 { write!($formatter, "{:6.0}ms", $denorm_v) } else if $denorm_v >= 100.0 { write!($formatter, "{:5.1}ms", $denorm_v) } else { write!($formatter, "{:5.2}ms", $denorm_v) } }; } macro_rules! f_lfot { ($formatter: expr, $v: expr, $denorm_v: expr) => { if $denorm_v < 10.0 { write!($formatter, "{:5.1}Hz", 1000.0 / $denorm_v) } else if $denorm_v < 250.0 { write!($formatter, "{:4.1}ms", $denorm_v) } else if $denorm_v < 1500.0 { write!($formatter, "{:4.0}ms", $denorm_v) } else if $denorm_v < 10000.0 { write!($formatter, "{:5.2}s", $denorm_v / 1000.0) } else { write!($formatter, "{:5.1}s", $denorm_v / 1000.0) } }; } macro_rules! f_det { ($formatter: expr, $v: expr, $denorm_v: expr) => {{ let sign = if $denorm_v < 0.0 { -1.0 } else { 1.0 }; let semitones = $denorm_v.trunc().abs(); let cents = ($denorm_v.fract() * 100.0).round().abs(); if (cents > 0.1) { write!($formatter, "{:2.0}s {:3.0}c", sign * semitones, cents) } else { write!($formatter, "{:2.0}s", sign * semitones) } }}; } // norm-fun denorm-min // denorm-fun denorm-max define_exp! {n_gain d_gain 0.0, 2.0} define_exp! {n_att d_att 0.0, 1.0} define_exp! {n_declick d_declick 0.0, 50.0} define_exp! {n_env d_env 0.0, 1000.0} define_exp6! {n_lfot d_lfot 0.1,300000.0} define_exp! {n_time d_time 0.5, 5000.0} define_exp! {n_ftme d_ftme 0.1, 1000.0} define_exp! {n_timz d_timz 0.0, 5000.0} // Special linear gain factor for the Out node, to be able // to reach more exact "1.0". define_lin! {n_ogin d_ogin 0.0, 2.0} define_lin! {n_pgin d_pgin 1.0, 10.0} define_lin! {n_vps d_vps 0.0, 20.0} // A note about the input-indicies: // // Atoms and Input parameters share the same global ID space // because thats how the client of the Matrix API needs to refer to // them. Beyond the Matrix API the atom data is actually split apart // from the parameters, because they are not smoothed. // // The index there only matters for addressing the atoms in the global atom vector. // // But the actually second index here is for referring to the atom index // relative to the absolute count of atom data a Node has. // It is used by the [Matrix] to get the global ParamId for the atom data // when iterating through the atoms of a Node and initializes the default data // for new nodes. macro_rules! node_list { ($inmacro: ident) => { $inmacro! { nop => Nop, amp => Amp UIType::Generic UICategory::Signal // node_param_idx // name denorm round format steps norm norm denorm // norm_fun fun fun fun def min max default (0 inp n_id d_id r_id f_def stp_d -1.0, 1.0, 0.0) (1 gain n_gain d_gain r_id f_def stp_d 0.0, 1.0, 1.0) (2 att n_att d_att r_id f_def stp_d 0.0, 1.0, 1.0) {3 0 neg_att setting(1) mode fa_amp_neg_att 0 1} [0 sig], mix3 => Mix3 UIType::Generic UICategory::NtoM (0 ch1 n_id d_id r_id f_def stp_d -1.0, 1.0, 0.0) (1 ch2 n_id d_id r_id f_def stp_d -1.0, 1.0, 0.0) (2 ch3 n_id d_id r_id f_def stp_d -1.0, 1.0, 0.0) (3 gain1 n_gain d_gain r_id f_def stp_d 0.0, 1.0, 1.0) (4 gain2 n_gain d_gain r_id f_def stp_d 0.0, 1.0, 1.0) (5 gain3 n_gain d_gain r_id f_def stp_d 0.0, 1.0, 1.0) (6 ogain n_gain d_gain r_id f_def stp_d 0.0, 1.0, 1.0) [0 sig], mux9 => Mux9 UIType::Generic UICategory::NtoM ( 0 slct n_id d_id r_id f_def stp_d 0.0, 1.0, 0.0) ( 1 t_rst n_id d_id r_id f_def stp_d -1.0, 1.0, 0.0) ( 2 t_up n_id d_id r_id f_def stp_d -1.0, 1.0, 0.0) ( 3 t_down n_id d_id r_id f_def stp_d -1.0, 1.0, 0.0) ( 4 in_1 n_id d_id r_id f_def stp_d -1.0, 1.0, 0.0) ( 5 in_2 n_id d_id r_id f_def stp_d -1.0, 1.0, 0.0) ( 6 in_3 n_id d_id r_id f_def stp_d -1.0, 1.0, 0.0) ( 7 in_4 n_id d_id r_id f_def stp_d -1.0, 1.0, 0.0) ( 8 in_5 n_id d_id r_id f_def stp_d -1.0, 1.0, 0.0) ( 9 in_6 n_id d_id r_id f_def stp_d -1.0, 1.0, 0.0) (10 in_7 n_id d_id r_id f_def stp_d -1.0, 1.0, 0.0) (11 in_8 n_id d_id r_id f_def stp_d -1.0, 1.0, 0.0) (12 in_9 n_id d_id r_id f_def stp_d -1.0, 1.0, 0.0) {13 0 in_cnt setting(3) mode fa_mux9_in_cnt 0 8} [0 sig], smap => SMap UIType::Generic UICategory::Ctrl (0 inp n_id d_id r_id f_def stp_d -1.0, 1.0, 0.0) (1 min n_id d_id r_s f_def stp_d -1.0, 1.0, -1.0) (2 max n_id d_id r_s f_def stp_d -1.0, 1.0, 1.0) {3 1 mode setting(0) mode fa_smap_mode 0 3} {4 0 clip setting(0) mode fa_smap_clip 0 1} [0 sig], map => Map UIType::Generic UICategory::Ctrl (0 inp n_id d_id r_id f_def stp_d -1.0, 1.0, 0.0) (1 atv n_id d_id r_id f_def stp_d -1.0, 1.0, 1.0) (2 offs n_id d_id r_s f_def stp_d -1.0, 1.0, 0.0) (3 imin n_id d_id r_s f_def stp_d -1.0, 1.0, -1.0) (4 imax n_id d_id r_s f_def stp_d -1.0, 1.0, 1.0) (5 min n_id d_id r_s f_def stp_d -1.0, 1.0, -1.0) (6 max n_id d_id r_s f_def stp_d -1.0, 1.0, 1.0) {7 0 clip setting(0) mode fa_map_clip 0 1} [0 sig], quant => Quant UIType::Generic UICategory::Ctrl (0 freq n_pit d_pit r_id f_freq stp_d -1.0, 0.5647131, 440.0) (1 oct n_id d_id r_s f_def stp_d -1.0, 1.0, 0.0) {2 0 keys setting(0) keys fa_quant 0 0} [0 sig] [1 t], cqnt => CQnt UIType::Generic UICategory::Ctrl (0 inp n_id d_id r_id f_def stp_d 0.0, 1.0, 0.0) (1 oct n_id d_id r_s f_def stp_d -1.0, 1.0, 0.0) {2 0 keys setting(0) keys fa_cqnt 0 0} {3 1 omin setting(0) mode fa_cqnt_omin 0 4} {4 2 omax setting(0) mode fa_cqnt_omax 0 4} [0 sig] [1 t], tseq => TSeq UIType::Generic UICategory::Mod (0 clock n_id d_id r_id f_def stp_d 0.0, 1.0, 0.0) (1 trig n_id n_id r_id f_def stp_d -1.0, 1.0, 0.0) {2 0 cmode setting(1) mode fa_tseq_cmode 0 2} [0 trk1] [1 trk2] [2 trk3] [3 trk4] [4 trk5] [5 trk6] [6 gat1] [7 gat2] [8 gat3] [9 gat4] [10 gat5] [11 gat6], sampl => Sampl UIType::Generic UICategory::Osc (0 freq n_pit d_pit r_fq f_def stp_d -1.0, 0.564713133, 440.0) (1 trig n_id n_id r_id f_def stp_d -1.0, 1.0, 0.0) (2 offs n_id n_id r_id f_def stp_d 0.0, 1.0, 0.0) (3 len n_id n_id r_id f_def stp_d 0.0, 1.0, 1.0) (4 dcms n_declick d_declick r_dc_ms f_ms stp_m 0.0, 1.0, 3.0) (5 det n_det d_det r_det f_det stp_f -0.2, 0.2, 0.0) {6 0 sample audio_unloaded("") sample f_def 0 0} {7 1 pmode setting(0) mode fa_sampl_pmode 0 1} {8 2 dclick setting(0) mode fa_sampl_dclick 0 1} {9 3 dir setting(0) mode fa_sampl_dir 0 1} [0 sig], // node_param_idx // name denorm round format steps norm norm denorm // norm_fun fun fun fun def min max default sin => Sin UIType::Generic UICategory::Osc (0 freq n_pit d_pit r_fq f_freq stp_d -1.0, 0.5647131, 440.0) (1 det n_det d_det r_det f_det stp_f -0.2, 0.2, 0.0) [0 sig], bosc => BOsc UIType::Generic UICategory::Osc (0 freq n_pit d_pit r_fq f_freq stp_d -1.0, 0.5647131, 440.0) (1 det n_det d_det r_det f_det stp_f -0.2, 0.2, 0.0) (2 pw n_id n_id r_id f_def stp_d 0.0, 1.0, 0.5) {3 0 wtype setting(0) mode fa_bosc_wtype 0 3} [0 sig], vosc => VOsc UIType::Generic UICategory::Osc (0 freq n_pit d_pit r_fq f_freq stp_d -1.0, 0.5647131, 440.0) (1 det n_det d_det r_det f_det stp_f -0.2, 0.2, 0.0) (2 d n_id n_id r_id f_def stp_d 0.0, 1.0, 0.5) (3 v n_id n_id r_id f_def stp_d 0.0, 1.0, 0.5) (4 vs n_vps d_vps r_vps f_defvlp stp_d 0.0, 1.0, 0.0) (5 damt n_id n_id r_id f_def stp_d 0.0, 1.0, 0.0) {6 0 dist setting(0) mode fa_distort 0 3} {7 1 ovrsmpl setting(1) mode fa_vosc_ovrsmpl 0 1} [0 sig], bowstri => BowStri UIType::Generic UICategory::Osc (0 freq n_pit d_pit r_fq f_freq stp_d -1.0, 0.5647131, 440.0) (1 det n_det d_det r_det f_det stp_f -0.2, 0.2, 0.0) (2 vel n_id n_id r_id f_def stp_d 0.0, 1.0, 0.5) (3 force n_id n_id r_id f_def stp_d 0.0, 1.0, 0.5) (4 pos n_id n_id r_id f_def stp_d 0.0, 1.0, 0.5) [0 sig], out => Out UIType::Generic UICategory::IOUtil (0 ch1 n_id d_id r_id f_def stp_d -1.0, 1.0, 0.0) (1 ch2 n_id d_id r_id f_def stp_d -1.0, 1.0, 0.0) (2 gain n_ogin d_ogin r_id f_def stp_d 0.0, 1.0, 1.0) // node_param_idx UI widget type (mode, knob, sample) // | atom_idx | format fun // | | name constructor| | min max // | | | | def|ult_v|lue | / // | | | | | | | | | {3 0 mono setting(0) mode fa_out_mono 0 1}, fbwr => FbWr UIType::Generic UICategory::IOUtil (0 inp n_id d_id r_id f_def stp_d -1.0, 1.0, 0.0), fbrd => FbRd UIType::Generic UICategory::IOUtil (0 atv n_id d_id r_id f_def stp_d -1.0, 1.0, 1.0) [0 sig], scope => Scope UIType::Generic UICategory::IOUtil (0 inp n_id d_id r_id f_def stp_d -1.0, 1.0, 0.0) [0 sig], ad => Ad UIType::Generic UICategory::Mod (0 inp n_id d_id r_id f_def stp_d -1.0, 1.0, 1.0) (1 trig n_id d_id r_id f_def stp_d -1.0, 1.0, 0.0) (2 atk n_env d_env r_ems f_ms stp_m 0.0, 1.0, 3.0) (3 dcy n_env d_env r_ems f_ms stp_m 0.0, 1.0, 10.0) (4 ashp n_id d_id r_id f_def stp_d 0.0, 1.0, 0.5) (5 dshp n_id d_id r_id f_def stp_d 0.0, 1.0, 0.5) {6 0 mult setting(0) mode fa_ad_mult 0 2} [0 sig] [1 eoet], tslfo => TsLFO UIType::Generic UICategory::Mod (0 time n_lfot d_lfot r_lfot f_lfot stp_f 0.0, 1.0, 1000.0) (1 trig n_id d_id r_id f_def stp_d -1.0, 1.0, 0.0) (2 rev n_id d_id r_id f_def stp_d 0.0, 1.0, 0.5) [0 sig], rndwk => RndWk UIType::Generic UICategory::Mod (0 trig n_id d_id r_id f_def stp_d -1.0, 1.0, 0.0) (1 step n_id d_id r_id f_def stp_d 0.0, 1.0, 0.2) (2 offs n_id d_id r_id f_def stp_d -1.0, 1.0, 0.0) (3 min n_id d_id r_id f_def stp_d 0.0, 1.0, 0.0) (4 max n_id d_id r_id f_def stp_d 0.0, 1.0, 1.0) (5 slew n_timz d_timz r_tmz f_ms stp_m 0.0, 1.0, 75.0) [0 sig], delay => Delay UIType::Generic UICategory::Signal (0 inp n_id d_id r_id f_def stp_d -1.0, 1.0, 0.0) (1 trig n_id d_id r_id f_def stp_d -1.0, 1.0, 0.0) (2 time n_time d_time r_tms f_ms stp_m 0.0, 1.0, 250.0) (3 fb n_id d_id r_id f_def stp_d -1.0, 1.0, 0.0) (4 mix n_id d_id r_id f_def stp_d 0.0, 1.0, 0.5) {5 0 mode setting(0) mode fa_delay_mode 0 1} [0 sig], allp => AllP UIType::Generic UICategory::Signal (0 inp n_id d_id r_id f_def stp_d -1.0, 1.0, 0.0) (1 time n_ftme d_ftme r_fms f_ms stp_m 0.0, 1.0, 25.0) (2 g n_id d_id r_id f_def stp_d -1.0, 1.0, 0.7) [0 sig], comb => Comb UIType::Generic UICategory::Signal (0 inp n_id d_id r_id f_def stp_d -1.0, 1.0, 0.0) (1 time n_ftme d_ftme r_fms f_ms stp_m 0.0, 1.0, 25.0) (2 g n_id d_id r_id f_def stp_d -1.0, 1.0, 0.7) {3 0 mode setting(0) mode fa_comb_mode 0 1} [0 sig], noise => Noise UIType::Generic UICategory::Osc (0 atv n_id d_id r_id f_def stp_d -1.0, 1.0, 0.5) (1 offs n_id d_id r_s f_def stp_d -1.0, 1.0, 0.0) {2 0 mode setting(0) mode fa_noise_mode 0 1} [0 sig], sfilter => SFilter UIType::Generic UICategory::Signal (0 inp n_id d_id r_id f_def stp_d -1.0, 1.0, 0.0) (1 freq n_pit d_pit r_fq f_freq stp_d -1.0, 0.5647131, 1000.0) (2 res n_id d_id r_id f_def stp_d 0.0, 1.0, 0.5) {3 0 ftype setting(8) mode fa_sfilter_type 0 13} [0 sig], biqfilt => BiqFilt UIType::Generic UICategory::Signal (0 inp n_id d_id r_id f_def stp_d -1.0, 1.0, 0.0) (1 freq n_pit d_pit r_fq f_freq stp_d -1.0, 0.5647131, 1000.0) (2 q n_id d_id r_id f_def stp_d 0.0, 1.0, 0.5) (3 gain n_ogin d_ogin r_id f_def stp_d 0.0, 1.0, 1.0) {4 0 ftype setting(0) mode fa_biqfilt_type 0 1} {5 1 order setting(0) mode fa_biqfilt_ord 0 3} [0 sig], pverb => PVerb UIType::Generic UICategory::Signal ( 0 in_l n_id d_id r_id f_def stp_d -1.0, 1.0, 0.0) ( 1 in_r n_id d_id r_id f_def stp_d -1.0, 1.0, 0.0) ( 2 predly n_timz d_timz r_tmz f_ms stp_m 0.0, 1.0, 0.0) ( 3 size n_id d_id r_id f_def stp_d 0.0, 1.0, 0.5) ( 4 dcy n_id d_id r_id f_def stp_d 0.0, 1.0, 0.25) ( 5 ilpf n_pit d_pit r_fq f_freq stp_d -1.0, 0.5647131, 22050.0) ( 6 ihpf n_pit d_pit r_fq f_freq stp_d -1.0, 0.5647131, 0.0) ( 7 dif n_id d_id r_id f_def stp_d 0.0, 1.0, 1.0) ( 8 dmix n_id d_id r_id f_def stp_d 0.0, 1.0, 1.0) ( 9 mspeed n_id d_id r_id f_def stp_d 0.0, 1.0, 0.0) (10 mshp n_id d_id r_id f_def stp_d 0.0, 1.0, 0.5) (11 mdepth n_id d_id r_id f_def stp_d 0.0, 1.0, 0.2) (12 rlpf n_pit d_pit r_fq f_freq stp_d -1.0, 0.5647131, 22050.0) (13 rhpf n_pit d_pit r_fq f_freq stp_d -1.0, 0.5647131, 0.0) (14 mix n_id d_id r_id f_def stp_d 0.0, 1.0, 0.5) [0 sig_l] [1 sig_r], test => Test UIType::Generic UICategory::IOUtil (0 f n_id d_id r_id f_def stp_d 0.0, 1.0, 0.5) {1 0 p param(0.0) knob fa_test_s 0 10} {2 1 trig param(0.0) knob fa_test_s 0 0} [0 sig] [1 tsig] [2 out2] [3 out3] [4 out4] [5 outc], } }; } impl UICategory { #[allow(unused_assignments)] pub fn get_node_ids(&self, mut skip: usize, mut fun: F) { macro_rules! make_cat_lister { ($s1: ident => $v1: ident, $($str: ident => $variant: ident UIType:: $gui_type: ident UICategory:: $ui_cat: ident $(($in_idx: literal $para: ident $n_fun: ident $d_fun: ident $r_fun: ident $f_fun: ident $steps: ident $min: expr, $max: expr, $def: expr))* $({$in_at_idx: literal $at_idx: literal $atom: ident $at_fun: ident ($at_init: expr) $at_ui: ident $fa_fun: ident $amin: literal $amax: literal})* $([$out_idx: literal $out: ident])* ,)+ ) => { $(if UICategory::$ui_cat == *self { if skip == 0 { fun(NodeId::$variant(0)); } else { skip -= 1 } })+ } } node_list! {make_cat_lister}; } } #[derive(Debug, Clone, Copy)] pub enum RandNodeSelector { Any, OnlyUseful, } fn rand_node_satisfies_spec(nid: NodeId, sel: RandNodeSelector) -> bool { if let NodeId::Nop = nid { return false; } match sel { RandNodeSelector::Any => true, RandNodeSelector::OnlyUseful => match nid { NodeId::Nop => false, NodeId::Out(_) => false, NodeId::FbRd(_) => false, NodeId::Test(_) => false, _ => true, }, } } pub fn get_rand_node_id(count: usize, sel: RandNodeSelector) -> Vec { let mut sm = crate::dsp::helpers::SplitMix64::new_time_seed(); let mut out = vec![]; let mut cnt = 0; while cnt < 100 && out.len() < count { let cur = ALL_NODE_IDS[sm.next_u64() as usize % ALL_NODE_IDS.len()]; if rand_node_satisfies_spec(cur, sel) { out.push(cur); } cnt += 1; } while out.len() < count { out.push(NodeId::Nop); } out } /// Holds information about the node type that was allocated. /// It stores the names of inputs, output and atoms for uniform /// access. /// /// The [crate::NodeConfigurator] allocates and holds instances /// of this type for access by [NodeId]. /// See also [crate::NodeConfigurator::node_by_id] and /// [crate::Matrix::info_for]. #[derive(Clone)] pub struct NodeInfo { node_id: NodeId, inputs: Vec<&'static str>, atoms: Vec<&'static str>, outputs: Vec<&'static str>, input_help: Vec<&'static str>, output_help: Vec<&'static str>, node_help: &'static str, node_desc: &'static str, node_name: &'static str, norm_v: std::rc::Rc f32>, denorm_v: std::rc::Rc f32>, } impl std::fmt::Debug for NodeInfo { fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> Result<(), std::fmt::Error> { f.debug_struct("NodeInfo").field("node_id", &self.node_id).finish() } } macro_rules! make_node_info_enum { ($s1: ident => $v1: ident, $($str: ident => $variant: ident UIType:: $gui_type: ident UICategory:: $ui_cat: ident $(($in_idx: literal $para: ident $n_fun: ident $d_fun: ident $r_fun: ident $f_fun: ident $steps: ident $min: expr, $max: expr, $def: expr))* $({$in_at_idx: literal $at_idx: literal $atom: ident $at_fun: ident ($at_init: expr) $at_ui: ident $fa_fun: ident $amin: literal $amax: literal})* $([$out_idx: literal $out: ident])* ,)+ ) => { impl NodeInfo { /// Allocates a new [NodeInfo] from a [NodeId]. /// Usually you access [NodeInfo] in the UI thread via /// [crate::NodeConfigurator::node_by_id] /// or [crate::Matrix::info_for]. pub fn from_node_id(nid: NodeId) -> Self { match nid { NodeId::$v1 => NodeInfo { node_id: crate::dsp::NodeId::Nop, inputs: vec![], atoms: vec![], outputs: vec![], input_help: vec![], output_help: vec![], node_help: "Nop Help", node_desc: "Nop Desc", node_name: "Nop", norm_v: std::rc::Rc::new(|_i, x| x), denorm_v: std::rc::Rc::new(|_i, x| x), }, $(NodeId::$variant(_) => crate::dsp::ni::$variant(nid)),+ } } } /// Refers to an input paramter or atom of a specific /// [Node] referred to by a [NodeId]. /// /// To obtain a [ParamId] you use one of these: /// * [NodeId::atom_param_by_idx] /// * [NodeId::inp_param_by_idx] /// * [NodeId::param_by_idx] /// * [NodeId::inp_param] /// /// To obtain an input and output index for a port use: /// * [NodeId::inp] /// * [NodeId::out] /// ///``` /// use hexodsp::*; /// let freq_param = NodeId::Sin(2).inp_param("freq").unwrap(); /// /// assert!(!freq_param.is_atom()); /// /// // Access the UI min/max and fine/coarse step values of this paramter: /// assert_eq!(freq_param.param_min_max().unwrap(), ((-1.0, 0.5647131), (20.0, 100.0))); /// /// // Access the default value: /// assert_eq!(freq_param.as_atom_def().f(), 0.0); /// /// // Normalize a value (convert frequency to the 0.0 to 1.0 range) /// assert_eq!(freq_param.norm(220.0), -0.1); /// /// // Denormalize a value (convert 0.0 to 1.0 range to frequency) /// assert_eq!(freq_param.denorm(-0.1), 220.0); ///``` #[derive(Debug, Clone, Copy, PartialOrd, PartialEq, Eq, Ord, Hash)] pub struct ParamId { name: &'static str, node: NodeId, idx: u8, } impl ParamId { pub fn none() -> Self { Self { name: "NOP", node: NodeId::Nop, idx: 0, } } pub fn node_id(&self) -> NodeId { self.node } pub fn inp(&self) -> u8 { self.idx } pub fn name(&self) -> &'static str { self.name } /// Returns true if the [ParamId] has been associated with /// the atoms of a Node, and not the paramters. Even if the /// Atom is a `param()`. pub fn is_atom(&self) -> bool { match self.node { NodeId::$v1 => false, $(NodeId::$variant(_) => { match self.idx { $($in_idx => false,)* $($in_at_idx => true,)* _ => false, } }),+ } } pub fn atom_ui(&self) -> Option<&'static str> { match self.node { NodeId::$v1 => None, $(NodeId::$variant(_) => { match self.idx { $($in_at_idx => Some(stringify!($at_ui)),)* _ => None, } }),+ } } pub fn param_steps(&self) -> Option<(f32, f32)> { match self.node { NodeId::$v1 => None, $(NodeId::$variant(_) => { match self.idx { $($in_idx => Some(($min, $max)),)* _ => None, } }),+ } } pub fn param_min_max(&self) -> Option<((f32, f32), (f32, f32))> { match self.node { NodeId::$v1 => None, $(NodeId::$variant(_) => { match self.idx { $($in_idx => Some((($min, $max), $steps!())),)* _ => None, } }),+ } } pub fn format(&self, f: &mut dyn std::io::Write, v: f32) -> Option> { match self.node { NodeId::$v1 => None, $(NodeId::$variant(_) => { match self.idx { $($in_idx => Some($f_fun!(f, v, $d_fun!(v))),)* $($in_at_idx => Some($fa_fun!(f, v, v)),)* _ => None, } }),+ } } pub fn setting_min_max(&self) -> Option<(i64, i64)> { match self.node { NodeId::$v1 => None, $(NodeId::$variant(_) => { match self.idx { $($in_at_idx => Some(($amin, $amax)),)* _ => None, } }),+ } } pub fn as_atom_def(&self) -> SAtom { match self.node { NodeId::$v1 => SAtom::param(0.0), $(NodeId::$variant(_) => { match self.idx { $($in_idx => SAtom::param(crate::dsp::norm_def::$variant::$para()),)* $($in_at_idx => SAtom::$at_fun($at_init),)* _ => SAtom::param(0.0), } }),+ } } pub fn norm_def(&self) -> f32 { match self.node { NodeId::$v1 => 0.0, $(NodeId::$variant(_) => { match self.idx { $($in_idx => crate::dsp::norm_def::$variant::$para(),)* _ => 0.0, } }),+ } } pub fn round(&self, v: f32, coarse: bool) -> f32 { match self.node { NodeId::$v1 => 0.0, $(NodeId::$variant(_) => { match self.idx { $($in_idx => crate::dsp::round::$variant::$para(v, coarse),)* _ => 0.0, } }),+ } } pub fn norm(&self, v: f32) -> f32 { match self.node { NodeId::$v1 => 0.0, $(NodeId::$variant(_) => { match self.idx { $($in_idx => crate::dsp::norm_v::$variant::$para(v),)* _ => 0.0, } }),+ } } pub fn denorm(&self, v: f32) -> f32 { match self.node { NodeId::$v1 => 0.0, $(NodeId::$variant(_) => { match self.idx { $($in_idx => crate::dsp::denorm_v::$variant::$para(v),)* _ => 0.0, } }),+ } } } /// This enum is a collection of all implemented modules (aka nodes) /// that are implemented. The associated `u8` index is the so called /// _instance_ of the corresponding [Node] type. /// /// This is the primary way in this library to refer to a specific node /// in the node graph that is managed by [crate::NodeConfigurator] /// and executed by [crate::NodeExecutor]. /// /// To see how to actually use this, refer to the documentation /// of [crate::Cell], where you will find an example. #[derive(Debug, Clone, Copy, PartialOrd, PartialEq, Eq, Ord, Hash)] pub enum NodeId { $v1, $($variant(u8)),+ } impl std::fmt::Display for NodeId { fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { match self { NodeId::$v1 => write!(f, "{}", stringify!($v1)), $(NodeId::$variant(i) => write!(f, "{} {}", stringify!($variant), i)),+ } } } impl NodeId { pub fn to_instance(&self, instance: usize) -> NodeId { match self { NodeId::$v1 => NodeId::$v1, $(NodeId::$variant(_) => NodeId::$variant(instance as u8)),+ } } pub fn graph_fun(&self) -> Option { match self { NodeId::$v1 => None, $(NodeId::$variant(_) => crate::dsp::$variant::graph_fun()),+ } } pub fn eq_variant(&self, other: &NodeId) -> bool { match self { NodeId::$v1 => *other == NodeId::$v1, $(NodeId::$variant(_) => if let NodeId::$variant(_) = other { true } else { false }),+ } } pub fn from_node_info(ni: &NodeInfo) -> NodeId { ni.to_id() } pub fn label(&self) -> &'static str { match self { NodeId::$v1 => stringify!($v1), $(NodeId::$variant(_) => stringify!($variant)),+ } } pub fn name(&self) -> &'static str { match self { NodeId::$v1 => stringify!($s1), $(NodeId::$variant(_) => stringify!($str)),+ } } pub fn from_str(name: &str) -> Self { match name { stringify!($s1) => NodeId::$v1, $(stringify!($str) => NodeId::$variant(0)),+, _ => NodeId::Nop, } } pub fn ui_type(&self) -> UIType { match self { NodeId::$v1 => UIType::Generic, $(NodeId::$variant(_) => UIType::$gui_type),+ } } pub fn ui_category(&self) -> UICategory { match self { NodeId::$v1 => UICategory::None, $(NodeId::$variant(_) => UICategory::$ui_cat),+ } } /// Consistently initialize the phase for oscillators. /// This does some fixed phase offset for the first 3 /// instances, which is usually relied on by the automated /// tests. #[inline] pub fn init_phase(&self) -> f32 { // The first 3 instances get a fixed predefined phase to // not mess up the automated tests so easily. match self.instance() { 0 => 0.0, 1 => 0.05, 2 => 0.1, // 0.25 just to protect against sine cancellation _ => crate::dsp::helpers::rand_01() * 0.25 } } /// This maps the atom index of the node to the absolute /// ParamId in the GUI (and in the [crate::matrix::Matrix]). /// The Atom/Param duality is a bit weird because they share /// the same ID namespace for the UI. But in the actual /// backend, they are split. So the actual splitting happens /// in the [crate::matrix::Matrix]. pub fn atom_param_by_idx(&self, idx: usize) -> Option { match self { NodeId::$v1 => None, $(NodeId::$variant(_) => { match idx { $($at_idx => Some(ParamId { node: *self, name: stringify!($atom), idx: $in_at_idx, }),)* _ => None, } }),+ } } pub fn inp_param_by_idx(&self, idx: usize) -> Option { match self { NodeId::$v1 => None, $(NodeId::$variant(_) => { match idx { $($in_idx => Some(ParamId { node: *self, name: stringify!($para), idx: $in_idx, }),)* _ => None, } }),+ } } pub fn param_by_idx(&self, idx: usize) -> Option { match self { NodeId::$v1 => None, $(NodeId::$variant(_) => { match idx { $($in_idx => Some(ParamId { node: *self, name: stringify!($para), idx: $in_idx, }),)* $($in_at_idx => Some(ParamId { node: *self, name: stringify!($atom), idx: $in_at_idx, }),)* _ => None, } }),+ } } pub fn inp_param(&self, name: &str) -> Option { match self { NodeId::$v1 => None, $(NodeId::$variant(_) => { match name { $(stringify!($para) => Some(ParamId { node: *self, name: stringify!($para), idx: $in_idx, }),)* $(stringify!($atom) => Some(ParamId { node: *self, name: stringify!($atom), idx: $in_at_idx, }),)* _ => None, } }),+ } } pub fn inp(&self, name: &str) -> Option { match self { NodeId::$v1 => None, $(NodeId::$variant(_) => { match name { $(stringify!($para) => Some($in_idx),)* _ => None, } }),+ } } pub fn inp_name_by_idx(&self, idx: u8) -> Option<&'static str> { match self { NodeId::$v1 => None, $(NodeId::$variant(_) => { match idx { $($in_idx => Some(stringify!($para)),)* $($in_at_idx => Some(stringify!($atom)),)* _ => None, } }),+ } } pub fn out_name_by_idx(&self, idx: u8) -> Option<&'static str> { match self { NodeId::$v1 => None, $(NodeId::$variant(_) => { match idx { $($out_idx => Some(stringify!($out)),)* _ => None, } }),+ } } pub fn out(&self, name: &str) -> Option { match self { NodeId::$v1 => None, $(NodeId::$variant(_) => { match name { $(stringify!($out) => Some($out_idx),)* _ => None, } }),+ } } pub fn instance(&self) -> usize { match self { NodeId::$v1 => 0, $(NodeId::$variant(i) => *i as usize),+ } } } pub const ALL_NODE_IDS : &'static [NodeId] = &[$(NodeId::$variant(0)),+]; #[allow(non_snake_case, unused_variables)] pub mod round { $(pub mod $variant { $(#[inline] pub fn $para(x: f32, coarse: bool) -> f32 { $r_fun!(x, coarse) })* })+ } #[allow(non_snake_case)] pub mod denorm_v { $(pub mod $variant { $(#[inline] pub fn $para(x: f32) -> f32 { $d_fun!(x) })* })+ } #[allow(non_snake_case)] pub mod norm_def { $(pub mod $variant { $(#[inline] pub fn $para() -> f32 { $n_fun!($def) })* })+ } #[allow(non_snake_case)] pub mod norm_v { $(pub mod $variant { $(#[inline] pub fn $para(v: f32) -> f32 { $n_fun!(v) })* })+ } #[allow(non_snake_case)] pub mod denorm { $(pub mod $variant { $(#[inline] pub fn $para(buf: &crate::dsp::ProcBuf, frame: usize) -> f32 { $d_fun!(buf.read(frame)) })* })+ } #[allow(non_snake_case)] pub mod denorm_offs { $(pub mod $variant { $(#[inline] pub fn $para(buf: &crate::dsp::ProcBuf, offs_val: f32, frame: usize) -> f32 { $d_fun!(buf.read(frame) + offs_val) })* })+ } #[allow(non_snake_case)] pub mod inp_dir { $(pub mod $variant { $(#[inline] pub fn $para(buf: &crate::dsp::ProcBuf, frame: usize) -> f32 { buf.read(frame) })* })+ } #[allow(non_snake_case)] pub mod inp { $(pub mod $variant { $(#[inline] pub fn $para(inputs: &[crate::dsp::ProcBuf]) -> &crate::dsp::ProcBuf { &inputs[$in_idx] })* })+ } #[allow(non_snake_case)] pub mod at { $(pub mod $variant { $(#[inline] pub fn $atom(atoms: &[crate::dsp::SAtom]) -> &crate::dsp::SAtom { &atoms[$at_idx] })* })+ } #[allow(non_snake_case)] pub mod out_dir { $(pub mod $variant { $(#[inline] pub fn $out(outputs: &mut [crate::dsp::ProcBuf], frame: usize, v: f32) { outputs[$out_idx].write(frame, v); })* })+ } #[allow(non_snake_case)] pub mod out { $(pub mod $variant { $(#[inline] pub fn $out(outputs: &mut [crate::dsp::ProcBuf]) -> &mut crate::dsp::ProcBuf { &mut outputs[$out_idx] })* })+ } #[allow(non_snake_case)] pub mod out_buf { $(pub mod $variant { $(#[inline] pub fn $out(outputs: &mut [crate::dsp::ProcBuf]) -> crate::dsp::ProcBuf { outputs[$out_idx] })* })+ } #[allow(non_snake_case)] pub mod out_idx { $(pub mod $variant { $(#[inline] pub fn $out() -> usize { $out_idx })* })+ } #[allow(non_snake_case)] pub mod is_out_con { $(pub mod $variant { $(#[inline] pub fn $out(nctx: &crate::dsp::NodeContext) -> bool { nctx.out_connected & (1 << $out_idx) != 0x0 })* })+ } #[allow(non_snake_case)] pub mod is_in_con { $(pub mod $variant { $(#[inline] pub fn $para(nctx: &crate::dsp::NodeContext) -> bool { nctx.in_connected & (1 << $in_idx) != 0x0 })* })+ } #[allow(unused_mut)] mod ni { $( pub fn $variant(node_id: crate::dsp::NodeId) -> crate::dsp::NodeInfo { let mut input_help = vec![$(crate::dsp::$variant::$para,)*]; $(input_help.push(crate::dsp::$variant::$atom);)* crate::dsp::NodeInfo { node_id, inputs: vec![$(stringify!($para),)*], atoms: vec![$(stringify!($atom),)*], outputs: vec![$(stringify!($out),)*], input_help, output_help: vec![$(crate::dsp::$variant::$out,)*], node_help: crate::dsp::$variant::HELP, node_desc: crate::dsp::$variant::DESC, node_name: stringify!($variant), norm_v: std::rc::Rc::new(|i, x| match i { $($in_idx => crate::dsp::norm_v::$variant::$para(x),)+ _ => x, }), denorm_v: std::rc::Rc::new(|i, x| match i { $($in_idx => crate::dsp::denorm_v::$variant::$para(x),)+ _ => x, }), } } )+ } impl NodeInfo { pub fn from(s: &str) -> Self { match s { $(stringify!($str) => crate::dsp::ni::$variant(NodeId::$variant(0)),)+ _ => NodeInfo::from_node_id(NodeId::Nop), } } pub fn name(&self) -> &'static str { self.node_name } pub fn in_name(&self, in_idx: usize) -> Option<&'static str> { if let Some(s) = self.inputs.get(in_idx) { Some(*s) } else { Some(*(self.atoms.get(in_idx)?)) } } pub fn at_name(&self, in_idx: usize) -> Option<&'static str> { Some(*(self.atoms.get(in_idx)?)) } pub fn out_name(&self, out_idx: usize) -> Option<&'static str> { Some(*(self.outputs.get(out_idx)?)) } pub fn in_help(&self, in_idx: usize) -> Option<&'static str> { Some(*self.input_help.get(in_idx)?) } pub fn out_help(&self, out_idx: usize) -> Option<&'static str> { Some(*(self.output_help.get(out_idx)?)) } pub fn norm(&self, in_idx: usize, x: f32) -> f32 { (*self.norm_v)(in_idx, x) } pub fn denorm(&self, in_idx: usize, x: f32) -> f32 { (*self.denorm_v)(in_idx, x) } pub fn desc(&self) -> &'static str { self.node_desc } pub fn help(&self) -> &'static str { self.node_help } pub fn out_count(&self) -> usize { self.outputs.len() } pub fn in_count(&self) -> usize { self.inputs.len() } pub fn at_count(&self) -> usize { self.atoms.len() } pub fn to_id(&self) -> NodeId { self.node_id } pub fn default_output(&self) -> Option { if self.out_count() > 0 { Some(0) } else { None } } pub fn default_input(&self) -> Option { if self.in_count() > 0 { Some(0) } else { None } } } } } macro_rules! make_node_enum { ($s1: ident => $v1: ident, $($str: ident => $variant: ident UIType:: $gui_type: ident UICategory:: $ui_cat: ident $(($in_idx: literal $para: ident $n_fun: ident $d_fun: ident $r_fun: ident $f_fun: ident $steps: ident $min: expr, $max: expr, $def: expr))* $({$in_at_idx: literal $at_idx: literal $atom: ident $at_fun: ident ($at_init: expr) $at_ui: ident $fa_fun: ident $amin: literal $amax: literal})* $([$out_idx: literal $out: ident])* ,)+ ) => { /// Represents the actually by the DSP thread ([crate::NodeExecutor]) /// executed [Node]. You don't construct this directly, but let the /// [crate::NodeConfigurator] or more abstract types like /// [crate::Matrix] do this for you. See also [NodeId] for a way to /// refer to these. /// /// The method [Node::process] is called by [crate::NodeExecutor] /// and comes with the overhead of a big `match` statement. /// /// This is the only point of primitive polymorphism inside /// the DSP graph. Dynamic polymorphism via the trait object /// is not done, as I hope the `match` dispatch is a slight bit faster /// because it's more static. /// /// The size of a [Node] is also limited and protected by a test /// in the test suite. The size should not be needlessly increased /// by implementations, in the hope to achieve better /// cache locality. All allocated [Node]s are held in a big /// continuous vector inside the [crate::NodeExecutor]. /// /// The function [node_factory] is responsible for actually creating /// the [Node]. #[derive(Debug, Clone)] pub enum Node { /// An empty node that does nothing. It's a placeholder /// for non allocated nodes. $v1, $($variant { node: $variant },)+ } impl Node { /// Returns the [NodeId] that can be used to refer to this node. /// The node does not store it's instance index, so you have to /// provide it. If the instance is of no meaning for the /// use case pass 0 to `instance`. pub fn to_id(&self, instance: usize) -> NodeId { match self { Node::$v1 => NodeId::$v1, $(Node::$variant { .. } => NodeId::$variant(instance as u8)),+ } } /// Resets any state of this [Node], such as /// any internal state variables or counters or whatever. /// The [Node] should just behave as if it was freshly returned /// from [node_factory]. pub fn reset(&mut self) { match self { Node::$v1 => {}, $(Node::$variant { node } => { node.reset(); }),+ } } /// Sets the current sample rate this [Node] should operate at. pub fn set_sample_rate(&mut self, sample_rate: f32) { match self { Node::$v1 => {}, $(Node::$variant { node } => { node.set_sample_rate(sample_rate); }),+ } } } } } node_list! {make_node_info_enum} node_list! {make_node_enum} pub fn node_factory(node_id: NodeId) -> Option<(Node, NodeInfo)> { macro_rules! make_node_factory_match { ($s1: expr => $v1: ident, $($str: ident => $variant: ident UIType:: $gui_type: ident UICategory:: $ui_cat: ident $(($in_idx: literal $para: ident $n_fun: ident $d_fun: ident $r_fun: ident $f_fun: ident $steps: ident $min: expr, $max: expr, $def: expr))* $({$in_at_idx: literal $at_idx: literal $atom: ident $at_fun: ident ($at_init: expr) $at_ui: ident $fa_fun: ident $amin: literal $amax: literal})* $([$out_idx: literal $out: ident])* ,)+ ) => { match node_id { $(NodeId::$variant(_) => Some(( Node::$variant { node: $variant::new(&node_id) }, NodeInfo::from_node_id(node_id), )),)+ _ => None, } } } node_list! {make_node_factory_match} } impl Node { /// This function is the heart of any DSP. /// It dispatches this call to the corresponding [Node] implementation. /// /// You don't want to call this directly, but let [crate::NodeConfigurator] and /// [crate::NodeExecutor] do their magic for you. /// /// The slices get passed a [ProcBuf] which is a super _unsafe_ /// buffer, that requires special care and invariants to work safely. /// /// Arguments: /// * `ctx`: The [NodeAudioContext] usually provides global context information /// such as access to the actual buffers of the audio driver or access to /// MIDI events. /// * `atoms`: The [SAtom] settings the user can set in the UI or via /// other means. These are usually non interpolated/smoothed settings. /// * `params`: The smoothed input parameters as set by the user (eg. in the UI). /// There is usually no reason to use these, because any parameter can be /// overridden by assigning an output port to the corresponding input. /// This is provided for the rare case that you still want to use the /// value the user set in the interface, and not the input Ctrl signal. /// * `inputs`: For each `params` parameter there is a input port. /// This slice will contain either a buffer from `params` or some output /// buffer from some other (previously executed) [Node]s output. /// * `outputs`: The output buffers this node will write it's signal/Ctrl /// results to. /// * `led`: Contains the feedback [LedPhaseVals], which are used /// to communicate the current value (set once per `process()` call, usually at the end) /// of the most important internal signal. Usually stuff like the output /// value of an oscillator, envelope or the current sequencer output /// value. It also provides a second value, a so called _phase_ /// which is usually used by graphical frontends to determine /// the phase of the oscillator, envelope or the sequencer to /// display some kind of position indicator. #[inline] pub fn process( &mut self, ctx: &mut T, ectx: &mut NodeExecContext, nctx: &NodeContext, atoms: &[SAtom], inputs: &[ProcBuf], outputs: &mut [ProcBuf], led: LedPhaseVals, ) { macro_rules! make_node_process { ($s1: ident => $v1: ident, $($str: ident => $variant: ident UIType:: $gui_type: ident UICategory:: $ui_cat: ident $(($in_idx: literal $para: ident $n_fun: ident $d_fun: ident $r_fun: ident $f_fun: ident $steps: ident $min: expr, $max: expr, $def: expr))* $({$in_at_idx: literal $at_idx: literal $atom: ident $at_fun: ident ($at_init: expr) $at_ui: ident $fa_fun: ident $amin: literal $amax: literal})* $([$out_idx: literal $out: ident])* ,)+ ) => { match self { Node::$v1 => {}, $(Node::$variant { node } => node.process(ctx, ectx, nctx, atoms, inputs, outputs, led),)+ } } } node_list! {make_node_process} } } #[cfg(test)] mod tests { use super::*; #[test] fn check_node_size_staying_small() { assert_eq!(std::mem::size_of::(), 56); assert_eq!(std::mem::size_of::(), 2); assert_eq!(std::mem::size_of::(), 24); } #[test] fn check_pitch() { assert_eq!(d_pit!(-0.2).round() as i32, 110_i32); assert_eq!((n_pit!(110.0) * 100.0).round() as i32, -20_i32); assert_eq!(d_pit!(0.0).round() as i32, 440_i32); assert_eq!((n_pit!(440.0) * 100.0).round() as i32, 0_i32); assert_eq!(d_pit!(0.3).round() as i32, 3520_i32); assert_eq!((n_pit!(3520.0) * 100.0).round() as i32, 30_i32); for i in 1..999 { let x = (((i as f32) / 1000.0) - 0.5) * 2.0; let r = d_pit!(x); //d// println!("x={:8.5} => {:8.5}", x, r); assert_eq!((n_pit!(r) * 10000.0).round() as i32, (x * 10000.0).round() as i32); } } }