component lowpass "Low-pass filter";
notes """

\\fBgain\\fR pin setting

The digital filter implemented is equivalent to a unity-gain
continuous-time single-pole low-pass filter that is preceded
by a zero-order-hold and sampled at a fixed period.  For a pole
at \\fB-a\\fR (radians/seconds) the corresponding continuous-time
lowpass filter LaPlace transfer function is:

\\fBH(s) = a/(s + a)\\fR

For a sampling period \\fBT\\fR (seconds), the gain for this
Hal lowpass component is:

\\fBgain = 1 - e^(-a * T)\\fR

e = 2.71828 https://en.wikipedia.org/wiki/E_(mathematical_constant)

\\fBExamples:\\fR
     T = 0.001 seconds (typical servo thread period)
     a = (2*pi*100)    (\\fB100Hz\\fR bandwidth single pole)
  gain = \\fB0.466\\fR

     T = 0.001 seconds (typical servo thread period)
     a = (2*pi*10)     ( \\fB10Hz\\fR bandwidth single pole)
  gain = \\fB0.0609\\fR

     T = 0.001 seconds (typical servo thread period)
     a = (2*pi*1)      ( \\fB1Hz\\fR bandwidth single pole)
  gain = \\fB0.0063\\fR
""";
pin in float in;
pin out float out " out += (in - out) * gain ";
pin in bit load "When TRUE, copy \\fBin\\fR to \\fBout\\fR instead of applying the filter equation.";
param rw float gain;
function _;
license "GPL";
author "Jeff Epler";
notes "The effect of a specific \\fBgain\\fR value is dependent on the period of the function that \\fBlowpass.\\fIN\\fR is added to.";
;;
FUNCTION(_) {
    if(load)
	out = in;
    else
	out += (in - out) * gain;
}