interpolators.lib

//#################################### interpolators.lib ########################################
// A library to handle interpolator in Faust. Its official prefix is `in`.
//########################################################################################

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

declare name "Interpolators Library";
declare version "0.1";

ba = library("basics.lib");
ro = library("routes.lib");
ma = library("maths.lib");
ru = library("runtime.lib");

//=================================================
// Code taken from Jamona TTInterpolate.h
// https://github.com/jamoma/JamomaCore/blob/master/Foundation/library/includes/TTInterpolate.h
//=================================================

// Two points interpolation functions

interpolate_linear(dv,v0,v1) = v0 + dv*(v1-v0);  // (faster than v0*(1-dv)+v1*dv which is currently not optimized...)

interpolate_cosine(dv,v0,v1) = v0 + a2*(v1-v0) with { a2 = 0.5 * (1.0 - cos(dv*ma.PI)); };

// For points interpolation functions

/*
See: https://www.paulinternet.nl/?page=bicubic
*/

interpolate_cubic(dv,v0,v1,v2,v3) 
	= v1 + 0.5 *dv*(v2 - v0 + dv*(2.0*v0 - 5.0*v1 + 4.0*v2 - v3 + dv*(3.0*(v1 - v2) + v3 - v0)));

//=================================================
// 'gen' has 1 reader input and produce N outputs
// 'idv' is a fractional read index
//=================================================

// Interpolator on two points (current and next index)

interpolator_two_points(gen, idv, interpolate_two_points) = (gen(id0), gen(id1))
                                                        : ro.interleave(outputs(gen), 2)
                                                        : par(i, outputs(gen), interpolate_two_points(dv))
with {
    id0 = ru.int_part(idv); // index integer part
    id1 = id0 + 1;          // next index
    dv = ru.frac_part(idv); // index fractional part in [0..1]
};

// To be used in 'interpolatorSelector'
interpolator_null(gen, idv) = interpolator_two_points(gen, idv, \(dv,v0,v1).(v0));

interpolator_linear(gen, idv) = interpolator_two_points(gen, idv, interpolate_linear);

interpolator_cosine(gen, idv) = interpolator_two_points(gen, idv, interpolate_cosine);

// Interpolator on four points (previous, current and two next indexes)

interpolator_four_points(gen, idv, interpolate_four_points) = (gen(id0), gen(id1), gen(id2), gen(id3))
                                                            : ro.interleave(outputs(gen), 4)
                                                            : par(i, outputs(gen), interpolate_four_points(dv))
with {
    id0 = id1 - 1;          // previous index
    id1 = ru.int_part(idv); // index integer part
    id2 = id1 + 1;          // next index
    id3 = id2 + 1;          // next index
    dv = ru.frac_part(idv); // index fractional part in [0..1]
};

interpolator_cubic(gen, idv) = interpolator_four_points(gen, idv, interpolate_cubic);

// Enumeration of interpolation algorithms
MAX_INTER = 4;

linear = 0;
cosine = 1;
cubic  = 2;
nointerp = MAX_INTER-1;

// Generic configurable interpolator (with selector between in [0..3]). The value 3 is used for no interpolation.

interpolator_select(gen, idv, sel) = ba.selectmulti(interpolators, sel)
with {
	interpolators = (interpolator_linear(gen, idv),
                    interpolator_cosine(gen, idv),
                    interpolator_cubic(gen, idv),
                    interpolator_null(gen, idv));
};

/*
Use-case with 'waveform'. Here the signal given to 'interpolator_XXX' has the form (idx, dv), see float.lib and double.lib

waveform_linear(wf, step) = in.interpolator_linear(gen, (int(idv),ma.frac(idv)))
with {
    gen(idx) = wf,idx : rdtable;            
    index = +(step)~_; 	// starting from 'step'
    idv = index-step;  	// starting from 0
};

waveform_cosine(wf, step) = in.interpolator_cosine(gen, (int(idv),ma.frac(idv)))
with {
    gen(idx) = wf,idx : rdtable;            
    index = +(step)~_; 	// starting from 'step'
    idv = index-step;  	// starting from 0
};

waveform_cubic(wf, step) = in.interpolator_cubic(gen, (int(idv),ma.frac(idv)))
with {
    gen(idx) = wf,idx : rdtable;            
    index = +(step)~_; 	// starting from 'step'
    idv = index-step;  	// starting from 0
};

wf = waveform {0.0, 10.0, 20.0, 30.0, 40.0, 50.0, 60.0, 50.0, 40.0, 30.0, 20.0};
process = waveform_linear(wf, 0.25), waveform_cosine(wf, 0.25), waveform_cubic(wf, 0.25);

test1 = in.interpolator_linear(gen, (0,dv))
with {
    // signal to interpolate
    gen(id) = waveform {3.0, -1.0}, id : rdtable;              	
    dv = waveform {0.0, 0.25, 0.50, 0.75, 1.0}, (index-1) : rdtable;
    // test index signal
    index = +(1)~_; 	// starting from one
};

test2 = in.interpolator_cosine(gen, (0,dv))
with {
    // signal to interpolate
    gen(id) = waveform {3.0, -1.0}, id : rdtable;            
    // test index signal
    dv = waveform {0.0, 0.3333333333, 0.50, 0.6666666666, 1.0}, (index-1) : rdtable;  
    index = +(1)~_; 	// starting from one
};

*/