Alc/filters/defs.h

   1 #ifndef ALC_FILTER_H
   2 #define ALC_FILTER_H
   3
   4 #include "AL/al.h"
   5 #include "math_defs.h"
   6
   7 /* Filters implementation is based on the "Cookbook formulae for audio
   8  * EQ biquad filter coefficients" by Robert Bristow-Johnson
   9  * http://www.musicdsp.org/files/Audio-EQ-Cookbook.txt
  10  */
  11 /* Implementation note: For the shelf filters, the specified gain is for the
  12  * reference frequency, which is the centerpoint of the transition band. This
  13  * better matches EFX filter design. To set the gain for the shelf itself, use
  14  * the square root of the desired linear gain (or halve the dB gain).
  15  */
  16
  17 typedef enum BiquadType {
  18     /** EFX-style low-pass filter, specifying a gain and reference frequency. */
  19     BiquadType_HighShelf,
  20     /** EFX-style high-pass filter, specifying a gain and reference frequency. */
  21     BiquadType_LowShelf,
  22     /** Peaking filter, specifying a gain and reference frequency. */
  23     BiquadType_Peaking,
  24
  25     /** Low-pass cut-off filter, specifying a cut-off frequency. */
  26     BiquadType_LowPass,
  27     /** High-pass cut-off filter, specifying a cut-off frequency. */
  28     BiquadType_HighPass,
  29     /** Band-pass filter, specifying a center frequency. */
  30     BiquadType_BandPass,
  31 } BiquadType;
  32
  33 typedef struct BiquadFilter {
  34     ALfloat z1, z2; /* Last two delayed components for direct form II. */
  35     ALfloat b0, b1, b2; /* Transfer function coefficients "b" (numerator) */
  36     ALfloat a1, a2; /* Transfer function coefficients "a" (denominator; a0 is
  37                      * pre-applied). */
  38 } BiquadFilter;
  39 /* Currently only a C-based filter process method is implemented. */
  40 #define BiquadFilter_process BiquadFilter_processC
  41
  42 /**
  43  * Calculates the rcpQ (i.e. 1/Q) coefficient for shelving filters, using the
  44  * reference gain and shelf slope parameter.
  45  * \param gain 0 < gain
  46  * \param slope 0 < slope <= 1
  47  */
  48 inline ALfloat calc_rcpQ_from_slope(ALfloat gain, ALfloat slope)
  49 {
  50     return sqrtf((gain + 1.0f/gain)*(1.0f/slope - 1.0f) + 2.0f);
  51 }
  52 /**
  53  * Calculates the rcpQ (i.e. 1/Q) coefficient for filters, using the normalized
  54  * reference frequency and bandwidth.
  55  * \param f0norm 0 < f0norm < 0.5.
  56  * \param bandwidth 0 < bandwidth
  57  */
  58 inline ALfloat calc_rcpQ_from_bandwidth(ALfloat f0norm, ALfloat bandwidth)
  59 {
  60     ALfloat w0 = F_TAU * f0norm;
  61     return 2.0f*sinhf(logf(2.0f)/2.0f*bandwidth*w0/sinf(w0));
  62 }
  63
  64 inline void BiquadFilter_clear(BiquadFilter *filter)
  65 {
  66     filter->z1 = 0.0f;
  67     filter->z2 = 0.0f;
  68 }
  69
  70 /**
  71  * Sets up the filter state for the specified filter type and its parameters.
  72  *
  73  * \param filter The filter object to prepare.
  74  * \param type The type of filter for the object to apply.
  75  * \param gain The gain for the reference frequency response. Only used by the
  76  *             Shelf and Peaking filter types.
  77  * \param f0norm The normalized reference frequency (ref_freq / sample_rate).
  78  *               This is the center point for the Shelf, Peaking, and BandPass
  79  *               filter types, or the cutoff frequency for the LowPass and
  80  *               HighPass filter types.
  81  * \param rcpQ The reciprocal of the Q coefficient for the filter's transition
  82  *             band. Can be generated from calc_rcpQ_from_slope or
  83  *             calc_rcpQ_from_bandwidth depending on the available data.
  84  */
  85 void BiquadFilter_setParams(BiquadFilter *filter, BiquadType type, ALfloat gain, ALfloat f0norm, ALfloat rcpQ);
  86
  87 inline void BiquadFilter_copyParams(BiquadFilter *restrict dst, const BiquadFilter *restrict src)
  88 {
  89     dst->b0 = src->b0;
  90     dst->b1 = src->b1;
  91     dst->b2 = src->b2;
  92     dst->a1 = src->a1;
  93     dst->a2 = src->a2;
  94 }
  95
  96 void BiquadFilter_processC(BiquadFilter *filter, ALfloat *restrict dst, const ALfloat *restrict src, ALsizei numsamples);
  97
  98 inline void BiquadFilter_passthru(BiquadFilter *filter, ALsizei numsamples)
  99 {
 100     if(LIKELY(numsamples >= 2))
 101     {
 102         filter->z1 = 0.0f;
 103         filter->z2 = 0.0f;
 104     }
 105     else if(numsamples == 1)
 106     {
 107         filter->z1 = filter->z2;
 108         filter->z2 = 0.0f;
 109     }
 110 }
 111
 112 #endif /* ALC_FILTER_H */