net.beadsproject.beads.ugens
Class BiquadFilter

java.lang.Object
  extended by net.beadsproject.beads.core.Bead
      extended by net.beadsproject.beads.core.UGen
          extended by net.beadsproject.beads.ugens.IIRFilter
              extended by net.beadsproject.beads.ugens.BiquadFilter
All Implemented Interfaces:
DataBeadReceiver

public class BiquadFilter
extends IIRFilter
implements DataBeadReceiver

A simple implementation of a multi-channel biquad filter. It calculates coefficients based on three parameters (frequency, Q, and gain - the latter only relevant for EQ and shelving filters), each of which may be specified by a static float or by the output of a UGen.

Filter parameters may be set with individual setter functions ( setFreq, setQ, and setGain), or by passing a DataBead with the appropriate properties to setParams. (Messaging the filter with a DataBead is equivalent to calling setParams.) Setter methods return the instance, so they may be strung together:

filt.setFreq(200).setQ(30).setGain(.4);

BiquadFilterMulti can be used with pre-programmed algorithms that calculate coefficients for various filter types. (See setType(int) for a list of available types.)

BiquadFilterMulti can also implement a user-defined filter algorithm by calling setCustomType(CustomCoeffCalculator).

Version:
0.9.5.1
Author:
Benito Crawford

Nested Class Summary
 class BiquadFilter.CustomCoeffCalculator
          CustomCoeffCalculator provides a mechanism to define custom filter coefficients for a biquad filter based on frequency and Q.
protected  class BiquadFilter.ValCalculator
           
 
Nested classes/interfaces inherited from class net.beadsproject.beads.ugens.IIRFilter
IIRFilter.IIRFilterAnalysis
 
Nested classes/interfaces inherited from class net.beadsproject.beads.core.UGen
UGen.OutputInitializationRegime, UGen.OutputPauseRegime
 
Field Summary
protected  float a0
           
protected  float a1
           
protected  float a2
           
protected  double ampResponse
           
static int AP
          Indicates an all-pass filter; coefficients are calculated from equations given in "Cookbook formulae for audio EQ biquad filter coefficients" by Robert Bristow-Johnson.
protected  boolean areAllStatic
           
protected  float b0
           
protected  float b1
           
protected  float b2
           
static int BESSEL_HP
          Indicates a Bessel high-pass filter; only frequency is relevant.
static int BESSEL_LP
          Indicates a Bessel low-pass filter; only frequency is relevant.
static int BP_PEAK
          Indicates a band-pass filter with constant peak gain; coefficients are calculated from equations given in "Cookbook formulae for audio EQ biquad filter coefficients" by Robert Bristow-Johnson.
static int BP_SKIRT
          Indicates a band-pass filter with constant skirt gain; coefficients are calculated from equations given in "Cookbook formulae for audio EQ biquad filter coefficients" by Robert Bristow-Johnson.
static int BUTTERWORTH_HP
          Indicates a Butterworth high-pass filter; only the frequency parameter is relevant.
static int BUTTERWORTH_LP
          Indicates a Butterworth low-pass filter; only the frequency parameter is relevant.
static int CUSTOM_FILTER
          Indicates a user-defined filter; see setCustomType.
protected  float freq
           
protected  UGen freqUGen
           
protected  double frImag
           
protected  double frReal
           
protected  float gain
           
protected  UGen gainUGen
           
static int HIGH_SHELF
          Indicates a high-shelf filter; coefficients are calculated from equations given in "Cookbook formulae for audio EQ biquad filter coefficients" by Robert Bristow-Johnson.
static int HP
          Indicates a high-pass filter; coefficients are calculated from equations given in "Cookbook formulae for audio EQ biquad filter coefficients" by Robert Bristow-Johnson.
protected  boolean isFreqStatic
           
protected  boolean isGainStatic
           
protected  boolean isQStatic
           
static int LOW_SHELF
          Indicates a low-shelf filter; coefficients are calculated from equations given in "Cookbook formulae for audio EQ biquad filter coefficients" by Robert Bristow-Johnson.
static int LP
          Indicates a low-pass filter; coefficients are calculated from equations given in "Cookbook formulae for audio EQ biquad filter coefficients" by Robert Bristow-Johnson.
static int NOTCH
          Indicates a notch (band-reject) filter; coefficients are calculated from equations given in "Cookbook formulae for audio EQ biquad filter coefficients" by Robert Bristow-Johnson.
static int PEAKING_EQ
          Indicates a peaking-EQ filter; coefficients are calculated from equations given in "Cookbook formulae for audio EQ biquad filter coefficients" by Robert Bristow-Johnson.
protected  double phaseDelay
           
protected  double phaseResponse
           
protected  float pi_over_sf
           
protected  float q
           
protected  UGen qUGen
           
protected  float samplingfreq
           
static float SQRT2
           
protected  float two_pi_over_sf
           
protected  BiquadFilter.ValCalculator vc
           
protected  double w
           
 
Fields inherited from class net.beadsproject.beads.core.UGen
bufferSize, bufIn, bufOut, context, ins, outputInitializationRegime, outputPauseRegime, outs
 
Constructor Summary
BiquadFilter(AudioContext context, int channels)
          Constructor for a multi-channel low-pass biquad filter UGen with the specified number of channels.
BiquadFilter(AudioContext context, int channels, DataBead params)
          Constructor for a multi-channel biquad filter UGen with the specified number of channels and parameters specified by a DataBead.
BiquadFilter(AudioContext context, int itype, float ifreq, float iqval)
          Constructor for frequency and Q as floats.
BiquadFilter(AudioContext context, int itype, float ifreq, UGen iqval)
          Constructor for frequency as a float and Q as a UGen.
BiquadFilter(AudioContext context, int channels, int itype)
          Constructor for a multi-channel biquad filter UGen of specified type with the specified number of channels.
BiquadFilter(AudioContext context, int channels, int itype, DataBead params)
          Constructor for a multi-channel biquad filter UGen of specified type, with the specified number of channels, and with parameters specified by a DataBead.
BiquadFilter(AudioContext context, int itype, UGen ifreq, float iqval)
          Constructor for frequency as a UGen and Q as a float.
BiquadFilter(AudioContext context, int itype, UGen ifreq, UGen iqval)
          Constructor for frequency and Q as UGens.
 
Method Summary
 void calculateBuffer()
          Called by the signal chain to update this UGen's ouput data.
 float[] getCoefficients()
          Gets an array of the current filter coefficients: {a0, a1, a2, b0, b1, b2}.
 IIRFilter.IIRFilterAnalysis getFilterResponse(float freq)
          Gets an array filled with the filter response characteristics: {frequency response (real), frequency response (imaginary), amplitude response, phase response, phase delay, group delay}.
 float getFreq()
          Deprecated. Use getFrequency().
 float getFrequency()
          Gets the current filter frequency.
 UGen getFrequencyUGen()
          Gets the frequency UGen, if there is one.
 UGen getFreqUGen()
          Deprecated. Use getFrequencyUGen().
 float getGain()
          Gets the current gain in decibels for the filter.
 UGen getGainUGen()
          Gets the gain UGen, if there is one.
 DataBead getParams()
          Gets a DataBead with the filter's parameters (whether float or UGen), stored in the keys "frequency", "q", "gain", and "filterType".
 float getQ()
          Gets the current Q-value for the filter.
 UGen getQUGen()
          Gets the Q UGen, if there is one.
 DataBead getStaticParams()
          Gets a DataBead with properties "frequency", "q", and "gain" set to their current float values and "type" set appropriately.
 int getType()
          Gets the type of the filter.
 void messageReceived(Bead message)
          Responds to an incoming message.
 void reset()
          Resets the filter in case it "explodes".
 DataBeadReceiver sendData(DataBead db)
          Equivalent to setParams(DataBead).
 BiquadFilter setCustomType(BiquadFilter.CustomCoeffCalculator cc)
          Sets a user-defined coefficient calculation algorithm.
 BiquadFilter setFreq(float freq)
          Deprecated. Use setFrequency(float).
 BiquadFilter setFreq(UGen freqUGen)
          Deprecated. Use setFrequency(UGen).
 BiquadFilter setFrequency(float freq)
          Sets the filter frequency to a float value.
 BiquadFilter setFrequency(UGen freqUGen)
          Sets a UGen to determine the filter frequency.
 BiquadFilter setGain(float ngain)
          Sets the filter gain to a float.
 BiquadFilter setGain(UGen ngain)
          Sets a UGen to determine the filter Q-value.
 BiquadFilter setParams(DataBead paramBead)
          Sets the filter parameters with a DataBead.
 BiquadFilter setQ(float nqval)
          Sets the filter Q-value to a float.
 BiquadFilter setQ(UGen nqval)
          Sets a UGen to determine the filter Q-value.
 BiquadFilter setType(int ntype)
          Sets the type of filter.
 
Methods inherited from class net.beadsproject.beads.ugens.IIRFilter
analyzeFilter, calculateFilterResponse, calculateGroupDelay, getAmplitudeResponse, getGroupDelay, getPhaseDelay, getPhaseResponse
 
Methods inherited from class net.beadsproject.beads.core.UGen
addDependent, addInput, addInput, clearDependents, clearInputConnections, containsInput, crossfadeInput, getConnectedInputs, getContext, getEnvelopes, getIns, getNumberOfConnectedUGens, getNumberOfDependents, getOutBuffer, getOuts, getTimeTakenLastUpdate, getValue, getValue, getValueDouble, getValueDouble, initializeOuts, isTimerMode, isUpdated, noInputs, pause, printInBuffers, printInputList, printOutBuffers, removeAllConnections, removeConnection, removeDependent, setOutsToPause, setTimerMode, setValue, update, zeroIns, zeroOuts
 
Methods inherited from class net.beadsproject.beads.core.Bead
getKillListener, getName, isDeleted, isPaused, kill, message, setKillListener, setName, start, toString
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

LP

public static final int LP
Indicates a low-pass filter; coefficients are calculated from equations given in "Cookbook formulae for audio EQ biquad filter coefficients" by Robert Bristow-Johnson.

See Also:
Constant Field Values

HP

public static final int HP
Indicates a high-pass filter; coefficients are calculated from equations given in "Cookbook formulae for audio EQ biquad filter coefficients" by Robert Bristow-Johnson.

See Also:
Constant Field Values

BP_SKIRT

public static final int BP_SKIRT
Indicates a band-pass filter with constant skirt gain; coefficients are calculated from equations given in "Cookbook formulae for audio EQ biquad filter coefficients" by Robert Bristow-Johnson.

See Also:
Constant Field Values

BP_PEAK

public static final int BP_PEAK
Indicates a band-pass filter with constant peak gain; coefficients are calculated from equations given in "Cookbook formulae for audio EQ biquad filter coefficients" by Robert Bristow-Johnson.

See Also:
Constant Field Values

NOTCH

public static final int NOTCH
Indicates a notch (band-reject) filter; coefficients are calculated from equations given in "Cookbook formulae for audio EQ biquad filter coefficients" by Robert Bristow-Johnson.

See Also:
Constant Field Values

AP

public static final int AP
Indicates an all-pass filter; coefficients are calculated from equations given in "Cookbook formulae for audio EQ biquad filter coefficients" by Robert Bristow-Johnson.

See Also:
Constant Field Values

PEAKING_EQ

public static final int PEAKING_EQ
Indicates a peaking-EQ filter; coefficients are calculated from equations given in "Cookbook formulae for audio EQ biquad filter coefficients" by Robert Bristow-Johnson. untested!

See Also:
Constant Field Values

LOW_SHELF

public static final int LOW_SHELF
Indicates a low-shelf filter; coefficients are calculated from equations given in "Cookbook formulae for audio EQ biquad filter coefficients" by Robert Bristow-Johnson.

See Also:
Constant Field Values

HIGH_SHELF

public static final int HIGH_SHELF
Indicates a high-shelf filter; coefficients are calculated from equations given in "Cookbook formulae for audio EQ biquad filter coefficients" by Robert Bristow-Johnson.

See Also:
Constant Field Values

BUTTERWORTH_LP

public static final int BUTTERWORTH_LP
Indicates a Butterworth low-pass filter; only the frequency parameter is relevant.

See Also:
Constant Field Values

BUTTERWORTH_HP

public static final int BUTTERWORTH_HP
Indicates a Butterworth high-pass filter; only the frequency parameter is relevant.

See Also:
Constant Field Values

BESSEL_LP

public static final int BESSEL_LP
Indicates a Bessel low-pass filter; only frequency is relevant.

See Also:
Constant Field Values

BESSEL_HP

public static final int BESSEL_HP
Indicates a Bessel high-pass filter; only frequency is relevant.

See Also:
Constant Field Values

CUSTOM_FILTER

public static final int CUSTOM_FILTER
Indicates a user-defined filter; see setCustomType. This constant is not recognized by setType.

See Also:
Constant Field Values

a0

protected float a0

a1

protected float a1

a2

protected float a2

b0

protected float b0

b1

protected float b1

b2

protected float b2

freq

protected float freq

q

protected float q

gain

protected float gain

samplingfreq

protected float samplingfreq

two_pi_over_sf

protected float two_pi_over_sf

pi_over_sf

protected float pi_over_sf

SQRT2

public static final float SQRT2

w

protected double w

ampResponse

protected double ampResponse

phaseResponse

protected double phaseResponse

phaseDelay

protected double phaseDelay

frReal

protected double frReal

frImag

protected double frImag

vc

protected BiquadFilter.ValCalculator vc

freqUGen

protected UGen freqUGen

qUGen

protected UGen qUGen

gainUGen

protected UGen gainUGen

isFreqStatic

protected boolean isFreqStatic

isQStatic

protected boolean isQStatic

isGainStatic

protected boolean isGainStatic

areAllStatic

protected boolean areAllStatic
Constructor Detail

BiquadFilter

public BiquadFilter(AudioContext context,
                    int channels)
Constructor for a multi-channel low-pass biquad filter UGen with the specified number of channels.

Parameters:
context - The audio context.
channels - The number of channels.

BiquadFilter

public BiquadFilter(AudioContext context,
                    int channels,
                    int itype)
Constructor for a multi-channel biquad filter UGen of specified type with the specified number of channels. See setType for a list of supported filter types.

Parameters:
context - The AudioContext.
channels - The number of channels.
itype - The initial filter type, e.g. LP, HP, BP_SKIRT, etc.

BiquadFilter

public BiquadFilter(AudioContext context,
                    int channels,
                    DataBead params)
Constructor for a multi-channel biquad filter UGen with the specified number of channels and parameters specified by a DataBead.

Parameters:
context - The audio context.
channels - The number of channels.
params - A DataBead specifying parameter values; see setParams(DataBead).

BiquadFilter

public BiquadFilter(AudioContext context,
                    int channels,
                    int itype,
                    DataBead params)
Constructor for a multi-channel biquad filter UGen of specified type, with the specified number of channels, and with parameters specified by a DataBead.

Parameters:
context - The audio context.
channels - The number of channels.
itype - The initial filter type, e.g. LP, HP, BP_SKIRT, etc.
params - A DataBead specifying parameter values; see setParams(DataBead).

BiquadFilter

public BiquadFilter(AudioContext context,
                    int itype,
                    float ifreq,
                    float iqval)
Constructor for frequency and Q as floats. See setType for a list of supported filter types.

Parameters:
context - The AudioContext.
itype - The initial filter type, e.g. LP, HP, BP_SKIRT, etc.
ifreq - The initial frequency.
iqval - The initial Q-value.

BiquadFilter

public BiquadFilter(AudioContext context,
                    int itype,
                    UGen ifreq,
                    float iqval)
Constructor for frequency as a UGen and Q as a float. See setType for a list of supported filter types.

Parameters:
context - The AudioContext.
itype - The initial filter type, LP, HP, BP_SKIRT, etc.
ifreq - The frequency UGen.
iqval - The initial Q-value.

BiquadFilter

public BiquadFilter(AudioContext context,
                    int itype,
                    float ifreq,
                    UGen iqval)
Constructor for frequency as a float and Q as a UGen. See setType for a list of supported filter types.

Parameters:
context - The AudioContext.
itype - The initial filter type, e.g. LP, HP, BP_SKIRT, etc.
ifreq - The initial frequency.
iqval - The Q-value UGen.

BiquadFilter

public BiquadFilter(AudioContext context,
                    int itype,
                    UGen ifreq,
                    UGen iqval)
Constructor for frequency and Q as UGens. See setType for a list of supported filter types.

Parameters:
context - The AudioContext.
itype - The initial filter type, e.g. LP, HP, BP_SKIRT, etc.
ifreq - The frequency UGen.
iqval - The Q-value UGen.
Method Detail

calculateBuffer

public void calculateBuffer()
Description copied from class: UGen
Called by the signal chain to update this UGen's ouput data. Subclassses of UGen should implement the UGen's DSP perform routine here. In general this involves grabbing data from UGen.bufIn and putting data into UGen.bufOut in some way. UGen.bufIn and UGen.bufOut are 2D arrays of floats of the form float[numChannels][bufferSize]. The length of the buffers is given by UGen.bufferSize, and the number of channels of the input and output buffers are given by UGen.ins and UGen.outs respectively.

Specified by:
calculateBuffer in class UGen

reset

public void reset()
Resets the filter in case it "explodes".


setParams

public BiquadFilter setParams(DataBead paramBead)
Sets the filter parameters with a DataBead.

Use the following properties to specify filter parameters:

Parameters:
paramBead - The DataBead specifying parameters.
Returns:
This filter instance.

messageReceived

public void messageReceived(Bead message)
Description copied from class: Bead
Responds to an incoming message. Subclasses can override this in order to handle incoming messages. Typically a Bead would send a message to another Bead with itself as the arugment.

Overrides:
messageReceived in class Bead
Parameters:
message - the message

sendData

public DataBeadReceiver sendData(DataBead db)
Equivalent to setParams(DataBead).

Specified by:
sendData in interface DataBeadReceiver
Parameters:
db - The DataBead message.
Returns:
This filter instance.

getParams

public DataBead getParams()
Gets a DataBead with the filter's parameters (whether float or UGen), stored in the keys "frequency", "q", "gain", and "filterType".

Returns:
The DataBead with stored parameters.

getStaticParams

public DataBead getStaticParams()
Gets a DataBead with properties "frequency", "q", and "gain" set to their current float values and "type" set appropriately.

Returns:
The DataBead with static float parameter values.

setType

public BiquadFilter setType(int ntype)
Sets the type of filter. To set a custom type, use setCustomType. The following types are recognized:

Parameters:
ntype - The type of filter.

getType

public int getType()
Gets the type of the filter.

Returns:
The filter type.
See Also:
setType(int)

getFrequency

public float getFrequency()
Gets the current filter frequency.

Returns:
The filter frequency.

setFrequency

public BiquadFilter setFrequency(float freq)
Sets the filter frequency to a float value. This will remove the frequency UGen, if there is one.

Parameters:
freq - The frequency.

setFrequency

public BiquadFilter setFrequency(UGen freqUGen)
Sets a UGen to determine the filter frequency.

Parameters:
freqUGen - The frequency UGen.

getFrequencyUGen

public UGen getFrequencyUGen()
Gets the frequency UGen, if there is one.

Returns:
The frequency UGen.

getFreq

@Deprecated
public float getFreq()
Deprecated. Use getFrequency().

Gets the current filter frequency.

Returns:
The filter frequency.

setFreq

@Deprecated
public BiquadFilter setFreq(float freq)
Deprecated. Use setFrequency(float).

Sets the filter frequency to a float value. This will remove the frequency UGen, if there is one.

Parameters:
freq - The frequency.

setFreq

@Deprecated
public BiquadFilter setFreq(UGen freqUGen)
Deprecated. Use setFrequency(UGen).

Sets a UGen to determine the filter frequency.

Parameters:
freqUGen - The frequency UGen.

getFreqUGen

@Deprecated
public UGen getFreqUGen()
Deprecated. Use getFrequencyUGen().

Gets the frequency UGen, if there is one.

Returns:
The frequency UGen.

setQ

public BiquadFilter setQ(float nqval)
Sets the filter Q-value to a float. This will remove the Q UGen if there is one.

Parameters:
nqval - The Q-value.

setQ

public BiquadFilter setQ(UGen nqval)
Sets a UGen to determine the filter Q-value.

Parameters:
nqval - The Q-value UGen.
Returns:
This BiquadFilter instance.

getQ

public float getQ()
Gets the current Q-value for the filter.

Returns:
The current Q-value.

getQUGen

public UGen getQUGen()
Gets the Q UGen, if there is one.

Returns:
The Q UGen.

setGain

public BiquadFilter setGain(float ngain)
Sets the filter gain to a float. This will remove the gain UGen if there is one. (Only relevant for PEAKING_EQ, LOW_SHELF, and HIGH_SHELF types.)

Parameters:
ngain - The gain in decibels (0 means no gain).

setGain

public BiquadFilter setGain(UGen ngain)
Sets a UGen to determine the filter Q-value. (Only relevant for PEAKING_EQ, LOW_SHELF, and HIGH_SHELF types.)

Parameters:
ngain - The gain UGen, specifying the gain in decibels.

getGain

public float getGain()
Gets the current gain in decibels for the filter. (Only relevant for PEAKING_EQ, LOW_SHELF, and HIGH_SHELF types.)

Returns:
The current gain.

getGainUGen

public UGen getGainUGen()
Gets the gain UGen, if there is one.

Returns:
The gain UGen.

getCoefficients

public float[] getCoefficients()
Gets an array of the current filter coefficients: {a0, a1, a2, b0, b1, b2}.

Returns:
The coefficient array.

getFilterResponse

public IIRFilter.IIRFilterAnalysis getFilterResponse(float freq)
Gets an array filled with the filter response characteristics: {frequency response (real), frequency response (imaginary), amplitude response, phase response, phase delay, group delay}.

Specified by:
getFilterResponse in class IIRFilter
Parameters:
freq - The frequency to test.
Returns:
The array.

setCustomType

public BiquadFilter setCustomType(BiquadFilter.CustomCoeffCalculator cc)
Sets a user-defined coefficient calculation algorithm. The algorithm is defined in a user-defined class that extends BiquadFilter.CustomCoeffCalculator.

Parameters:
cc - The custom coefficient calculator.