Filter.java
/**
* This file is part of reSID, a MOS6581 SID emulator engine.
* Copyright (C) 2004 Dag Lem <resid@nimrod.no>
* <p>
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2 of the License or
* (at your option) any later version.
* <p>
* 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 General Public License for more details.
* <p>
* You should have received a copy of the GNU General Public License
* along with this program; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
* ---------------------------------------------------------------------------
* Filter distortion code written by Antti S. Lankila 2007 - 2008.
*
* @author Ken Händel
*
*/
package builder.resid.residfp;
/**
* The SID filter is modeled with a two-integrator-loop biquadratic filter,
* which has been confirmed by Bob Yannes to be the actual circuit used in the
* SID chip.
* <p>
* Measurements show that excellent emulation of the SID filter is achieved,
* except when high resonance is combined with high sustain levels. In this case
* the SID op-amps are performing less than ideally and are causing some
* peculiar behavior of the SID filter. This, however, seems to have more effect
* on the overall amplitude than on the color of the sound.
* <p>
* The theory for the filter circuit can be found in "Microelectric Circuits" by
* Adel S. Sedra and Kenneth C. Smith. The circuit is modeled based on the
* explanation found there except that an additional inverter is used in the
* feedback from the bandpass output, allowing the summer op-amp to operate in
* single-ended mode. This yields inverted filter outputs with levels
* independent of Q, which corresponds with the results obtained from a real
* SID.
* <p>
* We have been able to model the summer and the two integrators of the circuit
* to form components of an IIR filter. Vhp is the output of the summer, Vbp is
* the output of the first integrator, and Vlp is the output of the second
* integrator in the filter circuit.
* <p>
* According to Bob Yannes, the active stages of the SID filter are not really
* op-amps. Rather, simple NMOS inverters are used. By biasing an inverter into
* its region of quasi-linear operation using a feedback resistor from input to
* output, a MOS inverter can be made to act like an op-amp for small signals
* centered around the switching threshold.
* <p>
* Qualified guesses at SID filter schematics are depicted below.
*
* <pre>
* SID filter
* ----------
*
* -----------------------------------------------
* | |
* | ---Rq-- |
* | | | |
* | ------------<A]-----R1--------- |
* | | | |
* | | ---C---| ---C---|
* | | | | | |
* | --R1-- ---R1-- |---Rs--| |---Rs--|
* | | | | | | | |
* ----R1--|-----[A>--|--R-----[A>--|--R-----[A>--|
* | | | |
* vi -----R1-- | | |
*
* vhp vbp vlp
*
*
* vi - input voltage
* vhp - highpass output
* vbp - bandpass output
* vlp - lowpass output
* [A> - op-amp
* R1 - summer resistor
* Rq - resistor array controlling resonance (4 resistors)
* R - NMOS FET voltage controlled resistor controlling cutoff frequency
* Rs - shunt resitor
* C - capacitor
*
*
*
* SID integrator
* --------------
*
* V+
*
* |
* |
* -----|
* | |
* | ||--
* -||
* ---C--- ||->
* | | |
* |---Rs-----------|---- vo
* | |
* | ||--
* vi ---- -----|------------||
* | ˆ | ||->
* |___| | |
* ----- | |
* | | |
* |---R2-- |
* |
* R1 V-
* |
* |
*
* Vw
* ----------------------------------------------------------------------------
* </pre>
*
* @author Ken Händel
*/
public abstract class Filter {
/**
* Filter enabled.
*/
private boolean enabled = true;
/** Read-only inspection; does not clock or alter the filter. */
public final boolean isEnabled() { return enabled; }
/**
* Filter cutoff frequency.
*/
protected int fc;
/**
* Filter resonance.
*/
protected int res;
/**
* Selects which inputs to route through filter.
*/
private byte filt;
protected boolean filt1, filt2, filt3, filtE;
/**
* Switch voice 3 off.
*/
protected boolean voice3off;
/**
* Highpass, bandpass, and lowpass filter modes.
*/
protected boolean hp, bp, lp;
protected float vol; /* to avoid integer-to-float conversion at output */
protected double clockFrequency;
protected float Vhp, Vbp, Vlp;
/* Resonance/Distortion/Type3/Type4 helpers. */
protected float _1_div_Q;
protected float resonanceFactor;
/**
* SID clocking - 1 cycle
*
* @param v1 voice 1 in
* @param v2 voice 2 in
* @param v3 voice 3 in
* @param vE external audio in
* @return filtered output
*/
protected abstract float clock(float v1, float v2, float v3, float vE);
protected final void zeroDenormals() {
/* We only need this for systems that don't do -msse and -mfpmath=sse */
if (Vbp > -1e-12f && Vbp < 1e-12f) {
Vbp = 0;
}
if (Vlp > -1e-12f && Vlp < 1e-12f) {
Vlp = 0;
}
}
public abstract void setCurveAndDistortionDefaults();
public void setNonLinearity(float nonlinearity) {
}
protected void resetState() {
}
protected void updatedMixing() {
}
/**
* Enable filter.
*
* @param enable filter enable
*/
public void enable(final boolean enable) {
if (!enabled && enable) {
enabled = enable;
writeRES_FILT(filt);
} else if (enabled && !enable) {
enabled = enable;
filt1 = filt2 = filt3 = filtE = false;
updatedMixing();
}
}
protected void setClockFrequency(final double clock) {
clockFrequency = clock;
updatedCenterFrequency();
}
public abstract float[] getCurveProperties();
public abstract void setCurveProperties(float a, float b, float c, float d);
public abstract float[] getDistortionProperties();
public abstract void setDistortionProperties(float a, float b, float c);
/**
* SID reset.
*/
protected final void reset() {
Vhp = Vbp = Vlp = 0;
writeFC_LO((byte) 0);
writeFC_HI((byte) 0);
writeMODE_VOL((byte) 0);
writeRES_FILT((byte) 0);
resetState();
}
// ----------------------------------------------------------------------------
// Register functions.
// ----------------------------------------------------------------------------
/**
* Register functions.
*
* @param fc_lo fc low
*/
protected final void writeFC_LO(final byte fc_lo) {
fc = fc & 0x7f8 | fc_lo & 0x007;
updatedCenterFrequency();
}
/**
* Register functions.
*
* @param fc_hi fc high
*/
protected final void writeFC_HI(final byte fc_hi) {
fc = fc_hi << 3 & 0x7f8 | fc & 0x007;
updatedCenterFrequency();
}
/**
* Register functions.
*
* @param res_filt res filter
*/
protected final void writeRES_FILT(final byte res_filt) {
filt = res_filt;
res = res_filt >> 4 & 0x0f;
updatedResonance();
if (enabled) {
filt1 = (filt & 1) != 0;
filt2 = (filt & 2) != 0;
filt3 = (filt & 4) != 0;
filtE = (filt & 8) != 0;
}
updatedMixing();
}
/**
* Register functions.
*
* @param mode_vol volume and filter mode
*/
protected final void writeMODE_VOL(final byte mode_vol) {
vol = (mode_vol & 0xf) / 15.f;
lp = (mode_vol & 0x10) != 0;
bp = (mode_vol & 0x20) != 0;
hp = (mode_vol & 0x40) != 0;
voice3off = (mode_vol & 0x80) == 0;
updatedMixing();
}
/**
* Set the filter cutoff frequency.
*/
protected abstract void updatedCenterFrequency();
/**
* Set the filter resonance.
*/
protected abstract void updatedResonance();
}