CUBiquadIIR.h

//
//  CUBiquadIIR.h
//  Cornell University Game Library (CUGL)
//
//  This class is represents a biquad filter that supports a wide variety of
//  of 2nd order filters (lowpass, highpass, bandpass, etc...)  It is adapted
//  from the code by Nigel Redmon at
//
//      http://www.earlevel.com/main/2012/11/26/biquad-c-source-code/
//
//  This class supports vector optimizations for SSE and Neon 64.  In timed
//  simulations, these optimizations provide at least a 3-4x performance
//  increase (and in isolated cases, much higher). These optimizations make
//  use of the matrix precomputation outlined in "Implementation of Recursive
//  Digital Filters into Vector SIMD DSP Architectures"
//
//    https://pdfs.semanticscholar.org/d150/a3f75dc033916f14029cd9101a8ea1d050bb.pdf
//
//  The algorithm in this paper performs extremely well in our tests, and even
//  out-performs Apple's Acceleration library.  However, our implementation is
//  limited to 128-bit words as 256-bit (e.g. AVX) and higher show no significant
//  increase in performance.
//
//  For performance reasons, this class does not have a (virtualized) subclass
//  relationship with other IIR or FIR filters.  However, the signature of the
//  the calculation and coefficient methods has been standardized so that it
//  can support templated polymorphism.
//
//  This class is NOT THREAD SAFE.  This is by design, for performance reasons.
//  External locking may be required when the filter is shared between multiple
//  threads (such as between an audio thread and the main thread).
//
//  CUGL MIT License:
//      This software is provided 'as-is', without any express or implied
//      warranty.  In no event will the authors be held liable for any damages
//      arising from the use of this software.
//
//      Permission is granted to anyone to use this software for any purpose,
//      including commercial applications, and to alter it and redistribute it
//      freely, subject to the following restrictions:
//
//      1. The origin of this software must not be misrepresented; you must not
//      claim that you wrote the original software. If you use this software
//      in a product, an acknowledgment in the product documentation would be
//      appreciated but is not required.
//
//      2. Altered source versions must be plainly marked as such, and must not
//      be misrepresented as being the original software.
//
//      3. This notice may not be removed or altered from any source distribution.
//
//  Author: Walker White
//  Version: 6/11/18
//
#ifndef __CU_BIQUAD_IIR_H__
#define __CU_BIQUAD_IIR_H__
 
#include <cugl/math/dsp/CUIIRFilter.h>
#include <cugl/math/CUMathBase.h>
#include <cugl/util/CUAligned.h>
#include <cstring>
#include <vector>
 
#define INV_SQRT2   0.7071067812
 
namespace cugl {
    namespace dsp {
    
class BiquadIIR {
public:
    enum class Type : int {
        UNDEFINED = 0,
        LOWPASS   = 1,
        HIGHPASS  = 2,
        BANDPASS  = 3,
        ALLPASS   = 4,
        NOTCH     = 5,
        PEAK      = 6,
        LOWSHELF  = 7,
        HIGHSHELF = 8,
        RESONANCE = 9,
    };
    
    static bool VECTORIZE;
    
private:
    unsigned _channels;
    float _b0, _b1, _b2;
    float _a1, _a2;
 
    cugl::Aligned<float> _inns;
    cugl::Aligned<float> _outs;
    
    // Optimization data structures (single channel)
    float __attribute__((__aligned__(16))) _c1[8];
    float __attribute__((__aligned__(16))) _d1[16];
    
    // Optimization data structures (dual channel)
    float __attribute__((__aligned__(16))) _c2[16];
    float __attribute__((__aligned__(16))) _d2[16];
    
    void reset();
 
 
#pragma mark SPECIALIZED FILTERS
 
    void stride(float gain, float* input, float* output, size_t size, unsigned channel);
    
    void single(float gain, float* input, float* output, size_t size);
    
    void dual(float gain, float* input, float* output, size_t size);
    
    void trio(float gain, float* input, float* output, size_t size);
    
    void quad(float gain, float* input, float* output, size_t size);
    
    void quart(float gain, float* input, float* output, size_t size);
    
public:
#pragma mark Constructors
 
    BiquadIIR();
    
    BiquadIIR(unsigned channels);
    
    BiquadIIR(unsigned channels, Type type, float frequency, float gainDB, float qVal=INV_SQRT2);
    
    BiquadIIR(const BiquadIIR& copy);
    
    BiquadIIR(BiquadIIR&& filter);
    
    ~BiquadIIR();
    
    
#pragma mark IIR Signature
 
    unsigned getChannels() const { return _channels; }
    
    void setChannels(unsigned channels);
    
    void setCoeff(const std::vector<float> &bvals, const std::vector<float> &avals);
    
    const std::vector<float> getBCoeff() const;
    
    const std::vector<float> getACoeff() const;
    
#pragma mark Specialized Attributes
 
    void setBCoeff(float b0, float b1, float b2);
 
    void setACoeff(float a1, float a2);
 
    void setType(Type type, float frequency, float gainDB, float qVal=INV_SQRT2);
    
    static float db2gain(float gainDB);
 
    static float gain2db(float gain);
 
    static float bandwidth2q(float width);
 
    static float q2Bandwidth(float qVal);
 
#pragma mark Filter Methods
 
    void step(float gain, float* input, float* output);
    
    void calculate(float gain, float* input, float* output, size_t size);
    
    void clear();
    
    size_t flush(float* output);
};
    
    }
}
 
#endif /* __CU_BIQUAD_IIR_H__ */