faust-common 0.9.95~repack1-2 / usr / share / faust / signal.lib

//#################################### signal.lib ########################################
// A library of basic elements to handle signals in Faust.
//
// It should be used using the `si` environment:
//
// ```
// si = library("signal.lib");
// process = si.functionCall;
// ```
//
// Another option is to import `stdfaust.lib` which already contains the `si`
// environment:
//
// ```
// import("stdfaust.lib");
// process = si.functionCall;
// ```
//########################################################################################

/************************************************************************
************************************************************************
FAUST library file
Copyright (C) 2003-2016 GRAME, Centre National de Creation Musicale
----------------------------------------------------------------------
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU Lesser General Public License as
published by the Free Software Foundation; either version 2.1 of the
License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public
License along with the GNU C Library; if not, write to the Free
Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
02111-1307 USA.

EXCEPTION TO THE LGPL LICENSE : As a special exception, you may create a
larger FAUST program which directly or indirectly imports this library
file and still distribute the compiled code generated by the FAUST
compiler, or a modified version of this compiled code, under your own
copyright and license. This EXCEPTION TO THE LGPL LICENSE explicitly
grants you the right to freely choose the license for the resulting
compiled code. In particular the resulting compiled code has no obligation
to be LGPL or GPL. For example you are free to choose a commercial or
closed source license or any other license if you decide so.
************************************************************************
************************************************************************/

ba = library("basic.lib");
ro = library("route.lib");

declare name "Faust Signal Routing Library";
declare version "0.0";

//=============================Functions Reference========================================
//========================================================================================

//--------------------------------`bus`-------------------------------------
// n parallel cables.
// `bus` is a standard Faust function.
//
// #### Usage
//
// ```
// bus(n)
// bus(4) : _,_,_,_
// ```
//
// Where:
//
// * `n`: is an integer known at compile time that indicates the number of parallel cables.
//-----------------------------------------------------------------------------
bus(2) = _,_; // avoids a lot of "bus(1)" labels in block diagrams
bus(n) = par(i, n, _);


//--------------`block`--------------
// Block - terminate n signals.
// `block` is a standard Faust function.
//
// #### Usage
//
// ```
// _,_,... : block(n) : _,...
// ```
//
// Where:
//
// * `n`: the number of signals to be blocked
//--------------------------------------
block(n) = par(i,n,!);


//-----------------------------`interpolate`-------------------------------
// Linear interpolation between two signals.
//
// #### Usage
//
// ```
// _,_ : interpolate(i) : _
// ```
//
// Where:
//
// * `i`: interpolation control between 0 and 1 (0: first input; 1: second input)
//-----------------------------------------------------------------------------
interpolate(i) = *(1.0-i),*(i) : +;


//-------------------`smooth`-----------------------------------
// Exponential smoothing by a unity-dc-gain one-pole lowpass.
// `smooth` is a standard Faust function.
//
// #### Usage: 
//
// ```
// _ : smooth(tau2pole(tau)) : _
// ```
//
// Where: 
//
// * `tau`: desired smoothing time constant in seconds, or
//
// ```
// hslider(...) : smooth(s) : _ 
// ```
//
// Where: 
//
// * `s`: smoothness between 0 and 1. s=0 for no smoothing, s=0.999 is "very smooth",
// s>1 is unstable, and s=1 yields the zero signal for all inputs.
// The exponential time-constant is approximately 1/(1-s) samples, when s is close to 
// (but less than) 1.
//
// #### Reference: 
//
// <https://ccrma.stanford.edu/~jos/mdft/Convolution_Example_2_ADSR.html>
//-------------------------------------------------------------
// TODO: author: JOS, revised by RM
smooth(s) = *(1.0 - s) : + ~ *(s);


//------------------------`smoo`---------------------------------------
// Smoothing function based on `smooth` ideal to smooth UI signals 
// (sliders, etc.) down. 
// `smoo` is a standard Faust function.
//
// #### Usage
//
// ```
// hslider(...) : smoo;
// ```
//---------------------------------------------------------------------
smoo = smooth(0.999);


//-----------------------`polySmooth`--------------------------------
// A smoothing function based on `smooth` that doesn't smooth when a
// trigger signal is given. This is very useful when making 
// polyphonic synthesizer to make sure that the value of the parameter
// is the right one when the note is started.
//
// #### Usage
//
// ```
// hslider(...) : polysmooth(g,s,d) : _
// ```
//
// Where:
//
// * `g`: the gate/trigger signal used when making polyphonic synths
// * `s`: the smoothness (see `smooth`)
// * `d`: the number of samples to wait before the signal start being
// 		smoothed after `g` switched to 1
//-------------------------------------------------------------------
polySmooth(g,s,d) = smooth(s*((g==(g@d)) | (g == 0)));


//-----------------------------`bsmooth`------------------------------
// Block smooth linear interpolation during a block of samples.
//
// #### Usage
//
// ```
// hslider(...) : bsmooth : _
// ```
//-----------------------------------------------------------------------
bsmooth(c) = +(i) ~ _
with { 
	i = (c-c@n)/n;
	n = min(4096, max(1, fvariable(int count, <math.h>)));
};


//-------------`lag_ud`---------------
// Lag filter with separate times for up and down.
//
// #### Usage
//
// ```
// _ : lag_ud(up, dn, signal) : _;
// ```
//----------------------------------------------------
// TODO: author Jonatan Liljedahl, revised by RM
lag_ud(up,dn) = _ <: ((>,ba.tau2pole(up),ba.tau2pole(dn):select2),_:smooth) ~ _;


//-------------------------------`dot`--------------------------------------
// Dot product for two vectors of size n.
//
// #### Usage
//
// ```
// _,_,_,_,_,_ : dot(n) : _
// ```
//
// Where:
//
// * `n`: size of the vectors (int, must be known at compile time)
//-----------------------------------------------------------------------------
dot(n) = ro.interleave(n,2) : par(i,n,*) :> _;