CUFIRFilter.h

//
//  CUFIRFilter.h
//  Cornell University Game Library (CUGL)
//
//  This class is represents a finite impulse response filter. It is a
//  general purpose filter that allows an arbitrary number of coefficients.
//  It is significantly faster than the general purpose IIR filter when no
//  feedback terms are required.  With that said, for less than 3-order FIR
//  filters, you should use one of the more specific filters for performance
//  reasons.
//
//  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). 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_FIR_FILTER_H__
#define __CU_FIR_FILTER_H__
 
#include <cugl/math/dsp/CUIIRFilter.h>
#include <cugl/math/CUMathBase.h>
#include <cugl/util/CUAligned.h>
#include <cstring>
#include <vector>
 
namespace cugl {
    namespace dsp {
 
class FIRFilter {
private:
    unsigned _channels;
    float _b0;
    
    cugl::Aligned<float> _bval;
    cugl::Aligned<float> _inns;
    
    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:
    static bool VECTORIZE;
 
#pragma mark Constructors
 
    FIRFilter();
    
    FIRFilter(unsigned channels);
    
    FIRFilter(unsigned channels, const std::vector<float> &bvals);
    
    FIRFilter(const FIRFilter& copy);
    
    FIRFilter(FIRFilter&& filter);
    
    ~FIRFilter();
    
#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(const std::vector<float> &bvals);
 
#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_FIR_FILTER_H__ */