Jamoma API  0.6.0.a19
TTDCBlock.h
Go to the documentation of this file.
1 /** @file
2  *
3  * @ingroup dspLibrary
4  *
5  * @brief DC Offset Filter and Blocker
6  *
7  * @details TODO: put more info here
8  *
9  * @authors Tim Place
10  *
11  * @copyright Copyright © 2008 by Timothy Place @n
12  * This code is licensed under the terms of the "New BSD License" @n
13  * http://creativecommons.org/licenses/BSD/
14  */
15 
16 
17 #ifndef __TT_DCBLOCK_H__
18 #define __TT_DCBLOCK_H__
19 
20 #include "TTDSP.h"
21 
22 
23 /** TTDCBlock in an audio processor that filters out DC Offsets from an input.
24 
25  This class is a good example of a very simple audio filter that can process any
26  number of parallel audio channels. It has a couple of simple messages, but
27  defines no attributes beyond those that are inherited by all TTAudioObjectBases.
28 
29  TTDCBlock implements a first-order highpass filter algorithm that is
30  used pretty much everywhere (STK, ChucK, RTCMix, SuperCollider, Max, Pd, etc),
31  with the difference equation:
32 
33  y(n) = (1 * x(n)) + (-1 * x(n-1)) - (-0.9997 * y(n-1)) , n = 0, 1, 2, 3, ...
34 
35  which can be simplified to:
36 
37  y(n) = x(n) - x(n-1) + (0.9997 * y(n-1))
38 
39  and thus characterized by the Z-transform:
40 
41  Y(z) = X(z) - X(z) * z^(-1) + Y(z) * 0.9997 * z^(-1)
42 
43  meaning the transfer function is:
44 
45  H(z) = [1 - z^(-1)] / [1 + 0.9997 * z^(-1)]
46 
47  and resulting in the frequency response:
48 
49  H( e^(i*omega*T) ) = [1 - e^(-i * omega * T)] / [1 + 0.9997 * e^(-i * omega * T)]
50 
51  where $i$ is the sqrt(-1), e is Euler's log base, T is the sampling interval, and omega is 2*pi*frequency.
52 
53  In Max, it usually shows up simply as [biquad~ 1.0 -1.0 0.0 -0.9997 0.0].
54  In other places it usually shows up with the feedback coefficient set to -0.995
55  (e.g in SuperCollider and in [JOS, 2007, pp 273]).
56  The higher coefficient is desirable so as to not attenuate lowish frequencies in the spectrum,
57  but with the caveat that it also won't respond as quickly to varying amounts DC Offset.
58 
59  The power is attenuated by -3 dB at a normalized frequency of 0.1612 * pi @ 0.9997.
60  At fs=44100 this translates to cf = 22050 * 0.1612 = 3554.46 Hz.
61 
62  The power is attenuated by -3 dB at a normalized frequency of 0.1604 * pi @ 0.995.
63  At fs=44100 this translates to cf = 22050 * 0.1604 = 3536.82 Hz.
64 
65  For reference, in this last case, the power is attenuated by -6 db (magnitude attenuated by -12 dB) @ 0.0798 * pi,
66  which at fs=44100 translates to 1759.59 Hz.
67 
68  ----
69 
70  So what are benefits of this filter? In the case of biquad~ in Max, we are processing with 2 coefficients zeroed,
71  meaning that we burn the cpu for a second-order filter when we are only getting the benefit of a first-order filter.
72  Why would we want to do this instead of doing something like a using a Butterworth filter for DC Blocking?
73 
74  We could implement a nice third-order Butterworth with a cf=20 Hz @ fs=48000 that would not disturb the gain of the spectrum,
75  but... the filter does not have linear phase.
76 
77  Since we are outside of Max, we can evaluate this filter for what it is: a first-order filter.
78  The clear benefit then is its speed.
79  - however, if we used a pure FIR filter then we could potentially use SSE instructions, so:
80  how would a second-order FIR compare to this classical first-order FIR/IIR combination?
81 
82  */
83 
84 class TTDCBlock : public TTAudioObjectBase {
86 
87 protected:
88 
89  TTSampleVector mLastInput; ///< Feedback values used for the audio filter
90  TTSampleVector mLastOutput; ///< Feedback values used for the audio filter
91 
92  /** This method gets called when the inherited mMaxNumChannels attribute is changed. */
93  TTErr updateMaxNumChannels(const TTValue& oldMaxNumChannels, TTValue&);
94 
95  /** Standard single value calculate method as used by DSP objects. */
96  inline TTErr calculateValue(const TTFloat64& x, TTFloat64& y, TTPtrSizedInt channel);
97 
98  /** Standard audio processing method as used by DSP objects. */
100 
101  /** Resets the DC-Blocking filter.
102  * This algorithm uses an IIR filter, meaning that it relies on feedback. If the filter should
103  * not be producing any signal (such as turning audio off and then back on in a host) or if the
104  * feedback has become corrupted (such as might happen if a NaN is fed in) then it may be
105  * neccesary to clear the filter by calling this method.
106  * @return Returns a TTErr error code. */
107  TTErr clear();
108 };
109 
110 
111 #endif // __TT_DCBLOCK_H__
TTAudioObjectBase is the base class for all audio generating and processing objects in Jamoma DSP...
TTErr updateMaxNumChannels(const TTValue &oldMaxNumChannels, TTValue &)
This method gets called when the inherited mMaxNumChannels attribute is changed.
Definition: TTDCBlock.cpp:47
TTErr processAudio(TTAudioSignalArrayPtr inputs, TTAudioSignalArrayPtr outputs)
Standard audio processing method as used by DSP objects.
Definition: TTDCBlock.cpp:74
Jamoma DSP Library.
TTErr calculateValue(const TTFloat64 &x, TTFloat64 &y, TTPtrSizedInt channel)
Standard single value calculate method as used by DSP objects.
Definition: TTDCBlock.cpp:64
double TTFloat64
64 bit floating point number
Definition: TTBase.h:188
TTSampleVector mLastOutput
Feedback values used for the audio filter.
Definition: TTDCBlock.h:90
#define TTCLASS_SETUP(className)
TODO Doxygen: need more comments here.
Definition: TTFoundation.h:54
TTErr clear()
Resets the DC-Blocking filter.
Definition: TTDCBlock.cpp:56
std::vector< TTSampleValue > TTSampleVector
A TTSampleVector is simply a pointer to the first of an array of TTSampleValues.
Definition: TTBase.h:233
TTDCBlock in an audio processor that filters out DC Offsets from an input.
Definition: TTDCBlock.h:84
A simple container for an array of TTAudioSignal pointers.
long TTPtrSizedInt
An integer that is the same size as a pointer.
Definition: TTBase.h:240
TTErr
Jamoma Error Codes Enumeration of error codes that might be returned by any of the TTBlue functions a...
Definition: TTBase.h:342
TTSampleVector mLastInput
Feedback values used for the audio filter.
Definition: TTDCBlock.h:89
[doxygenAppendixC_copyExample]
Definition: TTValue.h:34