spats.lib

//#################################### spats.lib ##########################################
// This library contains a collection of tools for sound spatialization.
// Its official prefix is `sp`.
//
// #### References
// * <https://github.com/grame-cncm/faustlibraries/blob/master/spats.lib>
//########################################################################################

/************************************************************************
 ************************************************************************
FAUST library file
Copyright (C) 2003-2012 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.

 ************************************************************************
 ************************************************************************/

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

declare name "Faust Spatialization Library";
declare version "1.1.0";

//-----------------------`(sp.)panner`------------------------
// A simple linear stereo panner.
// `panner` is a standard Faust function.
//
// #### Usage
//
// ```
// _ : panner(g) : _,_
// ```
//
// Where:
//
// * `g`: the panning (0-1)
//------------------------------------------------------------
panner(g) = _ <: *(1-g), *(g);

// TODO: need demo function for panner here


//---------------`(sp.)constantPowerPan`----------------------
// Apply the constant power pan rule to a stereo signal.
// The channels are not respatialized. Their gains are simply
// adjusted. A pan of 0 preserves the left channel and silences
// the right channel. A pan of 1 has the opposite effect.
// A pan value of 0.5 applies a gain of 0.5 to both channels. 
//
// #### Usage
//
// ```
// _,_ : constantPowerPan(p) : _,_
// ```
//
// Where:
//
// * `p`: the panning (0-1)
//------------------------------------------------------------
declare dryWetMixer author "David Braun";

constantPowerPan(p, x, y) = x*gainLeft, y*gainRight
with {
    theta = ma.PI*p/2.;
    gainLeft = cos(theta)/sqrt(2.);
    gainRight = sin(theta)/sqrt(2.);
};


//-----------------------`(sp.)spat`------------------------
// GMEM SPAT: n-outputs spatializer.
// `spat` is a standard Faust function.
//
// #### Usage
//
// ```
// _ : spat(N,r,d) : si.bus(N)
// ```
//
// Where:
//
// * `N`: number of outputs (a constant numerical expression)
// * `r`: rotation (between 0 et 1)
// * `d`: distance of the source (between 0 et 1)
//------------------------------------------------------
declare spat author "Laurent Pottier, revised by Romain Michon";

spat(N,a,d)	= _ <: par(i, N, *(scaler(i, N, a, d) : si.smooth(0.9999)))
with {
	scaler(i,N,a,d) = (d/2.0+0.5)
		* sqrt(max(0.0, 1.0 - abs(fmod(a+0.5+float(N-i)/N, 1.0) - 0.5) * N * d));
};


//---------------`(sp.)stereoize`-------------
// Transform an arbitrary processor `p` into a stereo processor with 2 inputs
// and 2 outputs.
//
// #### Usage
//
// ```
// _,_ : stereoize(p) : _,_
// ```
//
// Where:
//
// * `p`: the arbitrary processor
//----------------------------------------
stereoize(p) = S(inputs(p), outputs(p))
with {
	// degenerated processor with no outputs
	S(n,0) = !,! : 0,0; 		// just in case, probably a rare case
	// processors with no inputs
	S(0,1) = !,! : p <: _,_; 	// add two fake inputs and split output
	S(0,2) = !,! : p;
	S(0,n) = !,! : p,p :> _,_;	// we are sure this will work if n is odd
	// processors with one input
	S(1,1) = p,p; 				// add two fake inputs and split output
	S(1,n) = p,p :> _,_;		// we are sure this will work if n is odd
	// processors with two inputs
	S(2,1) = p <: _,_; 			// split the output
	S(2,2) = p; 				// nothing to do, p is already stereo
	// processors with inputs > 2 and outputs > 2
	S(n,m) = _,_ <: p,p :> _,_;	// we are sure this works if n or p are odd
};

// TODO: need demo function of spat here

//////////////////////////////////////////////////////////////////////////////////////////
// UNDOCUMENTED/DISMISSED ELEMENTS
//////////////////////////////////////////////////////////////////////////////////////////

// music.lib:
	// The following functions could remain available but they would have to be
	// factorized and reimplemented using the `par` function...
	// bus2 = _,_;
	// bus3 = _,_,_;
	// bus4 = _,_,_,_;
	// bus5 = _,_,_,_,_;
	// bus6 = _,_,_,_,_,_;
	// bus7 = _,_,_,_,_,_,_;
	// bus8 = _,_,_,_,_,_,_,_;
	// gain2(g) = *(g),*(g);
	// gain3(g) = *(g),*(g),*(g);
	// gain4(g) = *(g),*(g),*(g),*(g);
	// gain5(g) = *(g),*(g),*(g),*(g),*(g);
	// gain6(g) = *(g),*(g),*(g),*(g),*(g),*(g);
	// gain7(g) = *(g),*(g),*(g),*(g),*(g),*(g),*(g);
	// gain8(g) = *(g),*(g),*(g),*(g),*(g),*(g),*(g),*(g);