//################################ envelopes.lib ##########################################
// This library contains a collection of envelope generators. Its official prefix is `en`.
//########################################################################################

/************************************************************************
************************************************************************
FAUST library file, GRAME section

Except where noted otherwise, Copyright (C) 2003-2017 by GRAME,
Centre National de Creation Musicale.
----------------------------------------------------------------------
GRAME LICENSE

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.
************************************************************************
************************************************************************/

declare name "Faust Envelope Library";
declare version "0.0";
declare author "GRAME";
declare copyright "GRAME";
declare license "LGPL with exception";

ma = library("maths.lib");
ba = library("basics.lib");
si = library("signals.lib");

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

//------------------------`(en.)smoothEnvelope`------------------------
// An envelope with an exponential attack and release.
// `smoothEnvelope` is a standard Faust function.
//
// #### Usage
//
// ```
// smoothEnvelope(ar,t) : _
// ```
//
// * `ar`: attack and release duration (s)
// * `t`: trigger signal (attack is triggered when `t>0`, release is triggered 
// when `t=0`)
//----------------------------------------------------------------
// Author: RM
smoothEnvelope(ar,t) = t : si.smooth(ba.tau2pole(ar));

//-----------------------`(en.)ar`--------------------------
// AR (Attack, Release) envelope generator (useful to create percussion envelopes).
// `ar` is a standard Faust function.
//
// #### Usage
//
// ```
// ar(a,r,t) : _
// ```
//
// Where:
//
// * `a`: attack (sec)
// * `r`: release (sec)
// * `t`: trigger signal (attack is triggered when `t>0`, release is triggered 
// when `t=0`)
//-----------------------------------------------------
// Author: RM
ar(a,r,t) = cnt(totalTime,totalTime,on) : ba.bpf.start(0,0) :
	ba.bpf.point(attTime,1) : ba.bpf.end(attTime+relTime,0)
with{
	cnt(count,init,trig) = \(c).(ba.if(trig>0,0,min(count, c+1)))~+(init-init');
	on = (t-t')>0;
	attTime = ma.SR*a;
	relTime = ma.SR*r;
	totalTime = attTime+relTime;
};

//------------------------`(en.)arfe`----------------------
// ARFE (Attack and Release-to-Final-value Exponentially) envelope generator.
// Approximately equal to smoothEnvelope(Attack/6.91) when Attack == Release.
//
// #### Usage
//
// ```
// arfe(a,r,f,t) : _
// ```
//
// Where:
//
// * `a`, `r`: attack (sec), release (sec)
// * `f`: final value to approach upon release (such as 0)
// * `t`: trigger signal (attack is triggered when `t>0`, release is triggered 
// when `t=0`)
//-----------------------------------------------------
// Author: JOS
// License: STK-4.3
arfe(attT60,relT60,fv,gate) = envelope with {
  ugate = gate>0;
  samps = ugate : +~(*(ugate)); // ramp time in samples
  attSamps = int(attT60 * ma.SR);
  target = select2(ugate, fv, float(gate));
  t60 = select2(ugate, relT60, attT60);
  pole = ba.tau2pole(t60/6.91);
  envelope = target : si.smooth(pole);
};

//------------------------`(en.)are`----------------------
// ARE (Attack, Release) envelope generator with Exponential segments.
// Approximately equal to smoothEnvelope(Attack/6.91) when Attack == Release.
//
// #### Usage
//
// ```
// are(a,r,t) : _
// ```
//
// Where:
//
// * `a`: attack (sec)
// * `r`: release (sec)
// * `t`: trigger signal (attack is triggered when `t>0`, release is triggered 
// when `t=0`)
//-----------------------------------------------------
// Author: JOS
// License: STK-4.3
are(attT60,relT60,gate) = arfe(attT60,relT60,0,gate);

//------------------------`(en.)asr`----------------------
// ASR (Attack, Sustain, Release) envelope generator.
// `asr` is a standard Faust function.
//
// #### Usage
//
// ```
// asr(a,s,r,t) : _
// ```
//
// Where:
//
// * `a`: attack (sec)
// * `s`: sustain (fraction of `t`: 0-1) 
// * `r`: release (sec)
// * `t`: trigger signal (attack is triggered when `t>0`, release is triggered 
// when `t=0`)
//-----------------------------------------------------
// Author: RM
asr(a,s,r,t) = on*(as) : ba.sAndH(on) : rel
with{
	on = t>0;
	off = t==0;
	attTime = ma.SR*a;
	relTime = ma.SR*r;
	sustainGain = t*s;
	as = ba.countup(attTime,off) : ba.bpf.start(0,0) :
		ba.bpf.end(attTime,sustainGain);
	rel = _,ba.countup(relTime,on) : ba.bpf.start(0) : ba.bpf.end(relTime,0);
};

//------------------------`(en.)adsr`----------------------
// ADSR (Attack, Decay, Sustain, Release) envelope generator.
// `adsr` is a standard Faust function.
//
// #### Usage
//
// ```
// adsr(a,d,s,r,t) : _
// ```
//
// Where:
//
// * `a`: attack (sec)
// * `d`: decay (sec)
// * `s`: sustain (fraction of `t`: 0-1) 
// * `r`: release (sec)
// * `t`: trigger signal (attack is triggered when `t>0`, release is triggered 
// when `t=0`)
//-----------------------------------------------------
// Author: RM
adsr(a,d,s,r,t) = on*(ads) : ba.sAndH(on) : rel
with{
	on = t>0;
	off = t==0;
	attTime = ma.SR*a;
	decTime = ma.SR*d;
	relTime = ma.SR*r : max(0.001);
	sustainGain = t*s;
	ads = ba.countup(attTime+decTime,off) : ba.bpf.start(0,0) :
		ba.bpf.point(attTime,1) : ba.bpf.end(attTime+decTime,sustainGain);
	rel = _,ba.countup(relTime,on) : ba.bpf.start(0) : ba.bpf.end(relTime,0);
};

//-----------------------------------------------------
// Old version of ADSR (originally from music.lib)...
/*
adsr(a,d,s,r,t) = env ~ (_,_) : (!,_) // the 2 'state' signals are fed back
with {
    env (p2,y) =
        (t>0) & (p2|(y>=1)),          // p2 = decay-sustain phase
        (y + p1*u - (p2&(y>s))*v*y - p3*w*y)	// y  = envelop signal
	*((p3==0)|(y>=eps)) // cut off tails to prevent denormals
    with {
		p1 = (p2==0) & (t>0) & (y<1);         // p1 = attack phase
		p3 = (t<=0) & (y>0);                  // p3 = release phase
		// #samples in attack, decay, release, must be >0
		na = ma.SR*a+(a==0.0); nd = ma.SR*d+(d==0.0); nr = ma.SR*r+(r==0.0);
		// correct zero sustain level
		z = s+(s==0.0)*ba.db2linear(-60);
		// attack, decay and (-60dB) release rates
		u = 1/na; v = 1-pow(z, 1/nd); w = 1-1/pow(z*ba.db2linear(60), 1/nr);
		// values below this threshold are considered zero in the release phase
		eps = ba.db2linear(-120);
    };
};
*/

//------------------------`(en.)adsre`----------------------
// ADSRE (Attack, Decay, Sustain, Release) envelope generator with Exponential 
// segments.
//
// #### Usage
//
// ```
// adsre(a,d,s,r,g) : _
// ```
//
// Where:
//
// * `a`: attack (sec)
// * `d`: decay (sec)
// * `s`: sustain (fraction of `t`: 0-1)
// * `r`: release (sec)
// * `t`: trigger signal (attack is triggered when `t>0`, release is triggered
// when `t=0`)
//-----------------------------------------------------
// Author: JOS
// License: STK-4.3
adsre(attT60,decT60,susLvl,relT60,gate) = envelope with {
  ugate = gate>0;
  samps = ugate : +~(*(ugate)); // ramp time in samples
  attSamps = int(attT60 * ma.SR);
  target = select2(ugate, 0.0,
           select2(samps<attSamps, (susLvl)*float(ugate), ugate));
  t60 = select2(ugate, relT60, select2(samps<attSamps, decT60, attT60));
  pole = ba.tau2pole(t60/6.91);
  envelope = target : si.smooth(pole);
};

//------------------------`(en.)asre`----------------------
// ASRE (Attack, Sustain, Release) envelope generator with Exponential segments.
//
// #### Usage
//
// ```
// asre(a,s,r,g) : _
// ```
//
// Where:
//
// * `a`: attack (sec)
// * `s`: sustain (fraction of `t`: 0-1) 
// * `r`: release (sec)
// * `t`: trigger signal (attack is triggered when `t>0`, release is triggered 
// when `t=0`)
//-----------------------------------------------------
// Author: JOS
// License: STK-4.3
asre(attT60,susLvl,relT60,gate) = envelope with {
  ugate = gate>0;
  samps = ugate : +~(*(ugate)); // ramp time in samples
  target = select2(ugate, 0.0, (susLvl)*float(ugate));
  t60 = select2(ugate, relT60, attT60);
  pole = ba.tau2pole(t60/6.91);
  envelope = target : si.smooth(pole);
};

//----------------------`(en.)dx7envelope`----------------------
// DX7 operator envelope generator with 4 independent rates and levels. It is
// essentially a 4 points BPF.
//
// #### Usage
//
// ```
// dx7_envelope(R1,R2,R3,R4,L1,L2,L3,L4,t) : _
// ```
//
// Where:
//
// * `RN`: rates in seconds
// * `LN`: levels (0-1)
// * `t`: trigger signal
//-----------------------------------------------------
// Author: RM
dx7envelope(R1,R2,R3,R4,L1,L2,L3,L4,t) = up*on : ba.sAndH(on) : down
with{
  on = t>0;
  off = t==0;
  rs1 = R1*ma.SR;
  rs2 = R2*ma.SR;
  rs3 = R3*ma.SR;
  rs4 = R4*ma.SR;
  up = ba.countup(rs1+rs2+rs3,off) : ba.bpf.start(0,L4) : ba.bpf.point(rs1,L1) :
  ba.bpf.point(rs1+rs2,L2) : ba.bpf.end(rs1+rs2+rs3,L3);
  down = _,ba.countup(rs4,on) : ba.bpf.start(0) : ba.bpf.end(rs4,L4);
};