//################################ envelopes.lib ##########################################
// This library contains a collection of envelope generators. Its official prefix is `en`.
//
// #### References
// * <https://github.com/grame-cncm/faustlibraries/blob/master/envelopes.lib>
//########################################################################################

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

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

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

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

//-----------------------`(en.)ar`--------------------------
// AR (Attack, Release) envelope generator (useful to create percussion envelopes).
// `ar` is a standard Faust function.
//
// #### Usage
//
// ```
// ar(at,rt,t) : _
// ```
//
// Where:
//
// * `at`: attack (sec)
// * `rt`: release (sec)
// * `t`: trigger signal (attack is triggered when `t>0`, release is triggered
// when `t=0`)
//-----------------------------------------------------
declare ar author "Yann Orlarey, Stéphane Letz";
ar(at,rt,gate) = AR : max(0)
with {

    // Durations in samples
    an = max(1, at*ma.SR);
    rn = max(1, rt*ma.SR);

    // Deltas per samples
    adelta = 1/an;
    rdelta = 1/rn;

    // Attack time (starts at gate upfront and raises infinitely)
    atime = (raise*reset + upfront) ~ _
    with {
        upfront = gate > gate';
        reset = gate <= gate';
        raise(x) = (x + (x > 0));
    };

    // Attack curve
    A = atime * adelta;

    // Release curve
    D0 = 1 + an * rdelta;
    D = D0 - atime * rdelta;

    // AR part
    AR = min(A, D);

};


//------------------------`(en.)asr`----------------------
// ASR (Attack, Sustain, Release) envelope generator.
// `asr` is a standard Faust function.
//
// #### Usage
//
// ```
// asr(at,sl,rt,t) : _
// ```
//
// Where:
//
// * `at`: attack (sec)
// * `sl`: sustain level (between 0..1)
// * `rt`: release (sec)
// * `t`: trigger signal (attack is triggered when `t>0`, release is triggered
// when `t=0`)
//-----------------------------------------------------
declare asr author "Yann Orlarey, Stéphane Letz";
asr(at,sl,rt,gate) = AS - R : max(0)
with {

    // Durations in samples
    an = max(1, at*ma.SR);
    rn = max(1, rt*ma.SR);

    // Deltas per samples
    adelta = sl/an;
    rdelta = sl/rn;

    // Attack time (starts when gate changes and raises until gate == 0)
    atime = +(gate) ~ *(gate' >= gate);

    // Attack curve
    A = atime * adelta;

    // AS part
    AS = min(A, sl);

    // Release time starts when gate is 0
    rtime = (+(1) : *(gate == 0)) ~ _;

    // Release curve starts when gate is 0 with the current value of the envelope
    R = rtime * rdelta;

};


//------------------------`(en.)adsr`----------------------
// ADSR (Attack, Decay, Sustain, Release) envelope generator.
// `adsr` is a standard Faust function.
//
// #### Usage
//
// ```
// adsr(at,dt,sl,rt,t) : _
// ```
//
// Where:
//
// * `at`: attack time (sec)
// * `dt`: decay time (sec)
// * `sl`: sustain level (between 0..1)
// * `rt`: release time (sec)
// * `t`: trigger signal (attack is triggered when `t>0`, release is triggered
// when `t=0`)
//-----------------------------------------------------
declare adsr author "Yann Orlarey and Andrey Bundin";
adsr(at,dt,sl,rt,gate) = ADS : *(1-R) : max(0)
with {

    // Durations in samples
    an = max(1, at*ma.SR);
    dn = max(1, dt*ma.SR);
    rn = max(1, rt*ma.SR);

    // Deltas per samples
    adelta = 1/an;
    ddelta = (1-sl)/dn;

    // Attack time (starts when gate changes and raises until gate == 0)
    atime = +(gate) ~ *(gate' >= gate);

    // Attack curve
    A = atime * adelta;

    // Decay curve
    D0 = 1 + an * ddelta;
    D = D0 - atime * ddelta;

    // ADS part
    ADS = min(A, max(D, sl));

    // Release time starts when gate is 0
    rtime = (+(1) : *(gate == 0)) ~ _;

    // Release curve starts when gate is 0 with the current value of the envelope
    R = rtime/rn;

};


//------------------------`(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 (sec)
// * `t`: trigger signal (attack is triggered when `t>0`, release is triggered
// when `t=0`)
//----------------------------------------------------------------
declare smoothEnvelope author "Romain Michon";
smoothEnvelope(ar,t) = t : si.smooth(ba.tau2pole(ar));

// Generic form to be specialized
// Author: JOS, revised by Stephane Letz 
asrfe(attT60,susLvl,relT60,finLvl,gate) = envelope 
with {
  ugate = gate>0;
  target = select2(ugate, finLvl, susLvl*float(ugate));
  t60 = select2(ugate, relT60, attT60);
  pole = ba.tau2pole(t60/6.91);
  envelope = target : si.smooth(pole);
};


//------------------------`(en.)arfe`----------------------
// ARFE (Attack and Release-to-Final-value Exponentially) envelope generator.
// Approximately equal to `smoothEnvelope(Attack/6.91)` when Attack == Release.
//
// #### Usage
//
// ```
// arfe(at,rt,fl,t) : _
// ```
//
// Where:
//
// * `at`: attack (sec)
// * `rt`: release (sec)
// * `fl`: final level to approach upon release (such as 0)
// * `t`: trigger signal (attack is triggered when `t>0`, release is triggered
// when `t=0`)
//-----------------------------------------------------
declare arfe author "Julius O. Smith III, revised by Stephane Letz";
declare arfe licence "STK-4.3";

arfe(attT60,relT60,fv,gate) = asrfe(attT60,1.0,relT60,fv,gate);


//------------------------`(en.)are`----------------------
// ARE (Attack, Release) envelope generator with Exponential segments.
// Approximately equal to `smoothEnvelope(Attack/6.91)` when Attack == Release.
//
// #### Usage
//
// ```
// are(at,rt,t) : _
// ```
//
// Where:
//
// * `at`: attack (sec)
// * `rt`: release (sec)
// * `t`: trigger signal (attack is triggered when `t>0`, release is triggered
// when `t=0`)
//-----------------------------------------------------
declare are author "Julius O. Smith III, revised by Stephane Letz";
declare are licence "STK-4.3";

are(attT60,relT60,gate) = asrfe(attT60,1.0,relT60,0.0,gate);


//------------------------`(en.)asre`----------------------
// ASRE (Attack, Sustain, Release) envelope generator with Exponential segments.
//
// #### Usage
//
// ```
// asre(at,sl,rt,t) : _
// ```
//
// Where:
//
// * `at`: attack (sec)
// * `sl`: sustain level (between 0..1)
// * `rt`: release (sec)
// * `t`: trigger signal (attack is triggered when `t>0`, release is triggered
// when `t=0`)
//-----------------------------------------------------
declare asre author "Julius O. Smith III, revised by Stephane Letz";
declare asre licence "STK-4.3";

asre(attT60,susLvl,relT60,gate) = asrfe(attT60,susLvl,relT60,0.0,gate);


//------------------------`(en.)adsre`----------------------
// ADSRE (Attack, Decay, Sustain, Release) envelope generator with Exponential
// segments.
//
// #### Usage
//
// ```
// adsre(at,dt,sl,rt,t) : _
// ```
//
// Where:
//
// * `at`: attack (sec)
// * `dt`: decay (sec)
// * `sl`: sustain level (between 0..1)
// * `rt`: release (sec)
// * `t`: trigger signal (attack is triggered when `t>0`, release is triggered
// when `t=0`)
//-----------------------------------------------------
declare adsre author "Julius O. Smith III";
declare adsre licence "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);
  // if attSamps==0, go straight into the decay phase
  attPhase = (samps<attSamps) | (ugate:ba.impulsify);
  target = select2(ugate, 0.0,
           select2(attPhase, susLvl*float(ugate), ugate));
  t60 = select2(ugate, relT60, select2(attPhase, decT60, attT60));
  pole = ba.tau2pole(t60/6.91);
  envelope = target : si.smooth(pole);
};


//------------------------`(en.)ahdsre`----------------------
// AHDSRE (Attack, Hold, Decay, Sustain, Release) envelope generator with Exponential
// segments.
//
// #### Usage
//
// ```
// ahdsre(at,ht,dt,sl,rt,t) : _
// ```
//
// Where:
//
// * `at`: attack (sec)
// * `ht`: hold (sec)
// * `dt`: decay (sec)
// * `sl`: sustain level (between 0..1)
// * `rt`: release (sec)
// * `t`: trigger signal (attack is triggered when `t>0`, release is triggered
// when `t=0`)
//-----------------------------------------------------
declare ahdsre author "Julius O. Smith III, David Braun";
declare ahdsre licence "STK-4.3";

ahdsre(attT60,htT60,decT60,susLvl,relT60,gate) = envelope 
with {
  ugate = gate>0;
  samps = ugate : +~(*(ugate)); // ramp time in samples
  attSamps = int(attT60 * ma.SR);
  holdSamps = int((attT60+htT60)*ma.SR);
  attPhase = (samps<attSamps) | (ugate:ba.impulsify);
  holdPhase = (samps<holdSamps) & ugate;
  target = select2(ugate, 0.0,
           select2(holdPhase, susLvl*float(ugate), ugate));
  t60 = select2(ugate, relT60, select2(holdPhase, decT60, 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
//-----------------------------------------------------
declare dx7envelope author "Romain Michon";

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);
};