MusicKit  0.0.0
BiquadUG.h
00001 /*
00002   $Id$
00003   
00004   Defined In: The MusicKit
00005   Description:
00006     BiquadUG.h - Two-pole, two-zero, filter section, with gain.
00007 
00008     The BiquadUG unit-generator implements a two-pole, two-zero filter
00009     section in direct form.  The output space can only be y DSP memory.
00010     Therefore, only two leaf classes exist, BiquadUGx and BiquadUGy,
00011     corresponding to the two possible input spaces.
00012 
00013     The biquad transfer function is
00014 
00015                              -1         -2
00016                  1  +  b1 * z   + b2 * z
00017       H(z) = g * -------------------------
00018                              -1         -2
00019                  1  +  a1 * z   + a2 * z
00020 
00021     The biquad difference equation which implements H(z) is
00022 
00023      v(n) = g * x(n) - a1 * v(n-1) - a2 * v(n-2);
00024      y(n) =     v(n) + b1 * v(n-1) + b2 * v(n-2);
00025 
00026     where n denotes the current sample time, x(n) is the input signal at
00027     time n, y(n) is the output signal, and v(n) is an intermediate signal
00028     between the poles section and the zeros section.  This is the
00029     so-called direct-form digital filter structure, which follows
00030     immediately from the transfer function definiteion.  In the DSP, which
00031     uses fixed-point arithmetic, the so-called "transposed direct form" is
00032     used instead to avoid the possibility of internal overflow of v(n).
00033     However, the transfer function is equivalent. See Digital Signal
00034     Processing by A.V. Oppenheim and R.W.  Schafer (Prentice-Hall, 1975,
00035     p. 155) for further discussion.
00036 
00037     You instantiate a subclass of the form 
00038     BiquadUG<a><b>, where <a> = space of output and <b> = space of input.
00039 
00040   Original Author: David A. Jaffe
00041 
00042   Copyright (c) 1988-1992, NeXT Computer, Inc.
00043   Portions Copyright (c) 1994 NeXT Computer, Inc. and reproduced under license from NeXT
00044   Portions Copyright (c) 1994 Stanford University.
00045   Portions Copyright (c) 1999-2001, The MusicKit Project.
00046 */
00087 #ifndef __MK_BiquadUG_H___
00088 #define __MK_BiquadUG_H___
00089 
00090 #import <MusicKit/MKUnitGenerator.h>
00091 
00092 @interface BiquadUG : MKUnitGenerator
00093 {
00094 }
00095 
00096 
00104 - setInput:(id)aPatchPoint;
00105  /* Sets filter input. */
00106 
00107 
00115 - setOutput:(id)aPatchPoint;
00116  /* Sets filter output. */
00117 
00118 
00125 - clear;
00126  /* Clear internal filter state. */
00127 
00136 - setFirstDelayedSample:(double)d1;
00137 
00146 - setSecondDelayedSample:(double)d2;
00147 
00148  /* The following four methods set the corresponding coefficients.  See
00149   * discussion above. 
00150   */
00151 
00159 - setA1:(double)a1;
00160 
00168 - setA2:(double)a2;
00169 
00177 - setB1:(double)b1;
00178 
00186 - setB2:(double)b2;
00187 
00188 
00196 - setGain:(double)g;
00197  /* Sets gain of filter. */
00198 
00207 +(BOOL)shouldOptimize:(unsigned) arg;
00208  /* Specifies that all arguments are to be optimized if possible except the
00209   * filter state. */
00210 
00211  /* The following provide more convenient ways to talk to the filters. */
00212 
00224 - setComplexPolesRadius:(double)r angle:(double)t;
00225  /* Sets the coefficients such as to provide the specified pole radius and
00226   * angle.  The angle is in radians. */
00227 
00228 
00240 - setComplexZerosRadius:(double)r angle:(double)t;
00241  /* Sets the coefficients such as to provide the specified zero radius and
00242   * angle.  The angle is in radians. */
00243 
00244 
00256 - setComplexPolesFrequency:(double)f bandwidth:(double)b;
00257  /* Sets the coefficients such as to place the poles at the specified freq
00258   * and bandwidth. */
00259 
00260 
00272 - setComplexZerosFrequency:(double)f bandwidth:(double)b;
00273  /* Sets the coefficients such as to place the zeros at the specified freq
00274   * and bandwidth. */
00275 
00286 - setComplexPolesFrequency:(double)f t60:(double)t60;
00287 
00288 @end
00289 
00290 #endif