Alc/effects/equalizer.c

   1 /**
   2  * OpenAL cross platform audio library
   3  * Copyright (C) 2013 by Mike Gorchak
   4  * This library is free software; you can redistribute it and/or
   5  *  modify it under the terms of the GNU Library General Public
   6  *  License as published by the Free Software Foundation; either
   7  *  version 2 of the License, or (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  *  Library General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Library General Public
  15  *  License along with this library; if not, write to the
  16  *  Free Software Foundation, Inc.,
  17  *  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  18  * Or go to http://www.gnu.org/copyleft/lgpl.html
  19  */
  20
  21 #include "config.h"
  22
  23 #include <math.h>
  24 #include <stdlib.h>
  25
  26 #include "alMain.h"
  27 #include "alFilter.h"
  28 #include "alAuxEffectSlot.h"
  29 #include "alError.h"
  30 #include "alu.h"
  31
  32
  33 /*  The document  "Effects Extension Guide.pdf"  says that low and high  *
  34  *  frequencies are cutoff frequencies. This is not fully correct, they  *
  35  *  are corner frequencies for low and high shelf filters. If they were  *
  36  *  just cutoff frequencies, there would be no need in cutoff frequency  *
  37  *  gains, which are present.  Documentation for  "Creative Proteus X2"  *
  38  *  software describes  4-band equalizer functionality in a much better  *
  39  *  way.  This equalizer seems  to be a predecessor  of  OpenAL  4-band  *
  40  *  equalizer.  With low and high  shelf filters  we are able to cutoff  *
  41  *  frequencies below and/or above corner frequencies using attenuation  *
  42  *  gains (below 1.0) and amplify all low and/or high frequencies using  *
  43  *  gains above 1.0.                                                     *
  44  *                                                                       *
  45  *     Low-shelf       Low Mid Band      High Mid Band     High-shelf    *
  46  *      corner            center             center          corner      *
  47  *     frequency        frequency          frequency       frequency     *
  48  *    50Hz..800Hz     200Hz..3000Hz      1000Hz..8000Hz  4000Hz..16000Hz *
  49  *                                                                       *
  50  *          |               |                  |               |         *
  51  *          |               |                  |               |         *
  52  *   B -----+            /--+--\            /--+--\            +-----    *
  53  *   O      |\          |   |   |          |   |   |          /|         *
  54  *   O      | \        -    |    -        -    |    -        / |         *
  55  *   S +    |  \      |     |     |      |     |     |      /  |         *
  56  *   T      |   |    |      |      |    |      |      |    |   |         *
  57  * ---------+---------------+------------------+---------------+-------- *
  58  *   C      |   |    |      |      |    |      |      |    |   |         *
  59  *   U -    |  /      |     |     |      |     |     |      \  |         *
  60  *   T      | /        -    |    -        -    |    -        \ |         *
  61  *   O      |/          |   |   |          |   |   |          \|         *
  62  *   F -----+            \--+--/            \--+--/            +-----    *
  63  *   F      |               |                  |               |         *
  64  *          |               |                  |               |         *
  65  *                                                                       *
  66  * Gains vary from 0.126 up to 7.943, which means from -18dB attenuation *
  67  * up to +18dB amplification. Band width varies from 0.01 up to 1.0 in   *
  68  * octaves for two mid bands.                                            *
  69  *                                                                       *
  70  * Implementation is based on the "Cookbook formulae for audio EQ biquad *
  71  * filter coefficients" by Robert Bristow-Johnson                        *
  72  * http://www.musicdsp.org/files/Audio-EQ-Cookbook.txt                   */
  73
  74
  75 /* The maximum number of sample frames per update. */
  76 #define MAX_UPDATE_SAMPLES 256
  77
  78 typedef struct ALequalizerState {
  79     DERIVE_FROM_TYPE(ALeffectState);
  80
  81     /* Effect gains for each channel */
  82     ALfloat Gain[MAX_EFFECT_CHANNELS][MAX_OUTPUT_CHANNELS];
  83
  84     /* Effect parameters */
  85     ALfilterState filter[4][MAX_EFFECT_CHANNELS];
  86
  87     ALfloat SampleBuffer[4][MAX_EFFECT_CHANNELS][MAX_UPDATE_SAMPLES];
  88 } ALequalizerState;
  89
  90 static ALvoid ALequalizerState_Destruct(ALequalizerState *state);
  91 static ALboolean ALequalizerState_deviceUpdate(ALequalizerState *state, ALCdevice *device);
  92 static ALvoid ALequalizerState_update(ALequalizerState *state, const ALCdevice *device, const ALeffectslot *slot, const ALeffectProps *props);
  93 static ALvoid ALequalizerState_process(ALequalizerState *state, ALsizei SamplesToDo, const ALfloat (*restrict SamplesIn)[BUFFERSIZE], ALfloat (*restrict SamplesOut)[BUFFERSIZE], ALsizei NumChannels);
  94 DECLARE_DEFAULT_ALLOCATORS(ALequalizerState)
  95
  96 DEFINE_ALEFFECTSTATE_VTABLE(ALequalizerState);
  97
  98
  99 static void ALequalizerState_Construct(ALequalizerState *state)
 100 {
 101     int it, ft;
 102
 103     ALeffectState_Construct(STATIC_CAST(ALeffectState, state));
 104     SET_VTABLE2(ALequalizerState, ALeffectState, state);
 105
 106     /* Initialize sample history only on filter creation to avoid */
 107     /* sound clicks if filter settings were changed in runtime.   */
 108     for(it = 0; it < 4; it++)
 109     {
 110         for(ft = 0;ft < MAX_EFFECT_CHANNELS;ft++)
 111             ALfilterState_clear(&state->filter[it][ft]);
 112     }
 113 }
 114
 115 static ALvoid ALequalizerState_Destruct(ALequalizerState *state)
 116 {
 117     ALeffectState_Destruct(STATIC_CAST(ALeffectState,state));
 118 }
 119
 120 static ALboolean ALequalizerState_deviceUpdate(ALequalizerState *UNUSED(state), ALCdevice *UNUSED(device))
 121 {
 122     return AL_TRUE;
 123 }
 124
 125 static ALvoid ALequalizerState_update(ALequalizerState *state, const ALCdevice *device, const ALeffectslot *slot, const ALeffectProps *props)
 126 {
 127     ALfloat frequency = (ALfloat)device->Frequency;
 128     ALfloat gain, freq_mult;
 129     ALuint i;
 130
 131     STATIC_CAST(ALeffectState,state)->OutBuffer = device->FOAOut.Buffer;
 132     STATIC_CAST(ALeffectState,state)->OutChannels = device->FOAOut.NumChannels;
 133     for(i = 0;i < MAX_EFFECT_CHANNELS;i++)
 134         ComputeFirstOrderGains(device->FOAOut, IdentityMatrixf.m[i],
 135                                slot->Params.Gain, state->Gain[i]);
 136
 137     /* Calculate coefficients for the each type of filter. Note that the shelf
 138      * filters' gain is for the reference frequency, which is the centerpoint
 139      * of the transition band.
 140      */
 141     gain = maxf(sqrtf(props->Equalizer.LowGain), 0.0625f); /* Limit -24dB */
 142     freq_mult = props->Equalizer.LowCutoff/frequency;
 143     ALfilterState_setParams(&state->filter[0][0], ALfilterType_LowShelf,
 144         gain, freq_mult, calc_rcpQ_from_slope(gain, 0.75f)
 145     );
 146     /* Copy the filter coefficients for the other input channels. */
 147     for(i = 1;i < MAX_EFFECT_CHANNELS;i++)
 148         ALfilterState_copyParams(&state->filter[0][i], &state->filter[0][0]);
 149
 150     gain = maxf(props->Equalizer.Mid1Gain, 0.0625f);
 151     freq_mult = props->Equalizer.Mid1Center/frequency;
 152     ALfilterState_setParams(&state->filter[1][0], ALfilterType_Peaking,
 153         gain, freq_mult, calc_rcpQ_from_bandwidth(
 154             freq_mult, props->Equalizer.Mid1Width
 155         )
 156     );
 157     for(i = 1;i < MAX_EFFECT_CHANNELS;i++)
 158         ALfilterState_copyParams(&state->filter[1][i], &state->filter[1][0]);
 159
 160     gain = maxf(props->Equalizer.Mid2Gain, 0.0625f);
 161     freq_mult = props->Equalizer.Mid2Center/frequency;
 162     ALfilterState_setParams(&state->filter[2][0], ALfilterType_Peaking,
 163         gain, freq_mult, calc_rcpQ_from_bandwidth(
 164             freq_mult, props->Equalizer.Mid2Width
 165         )
 166     );
 167     for(i = 1;i < MAX_EFFECT_CHANNELS;i++)
 168         ALfilterState_copyParams(&state->filter[2][i], &state->filter[2][0]);
 169
 170     gain = maxf(sqrtf(props->Equalizer.HighGain), 0.0625f);
 171     freq_mult = props->Equalizer.HighCutoff/frequency;
 172     ALfilterState_setParams(&state->filter[3][0], ALfilterType_HighShelf,
 173         gain, freq_mult, calc_rcpQ_from_slope(gain, 0.75f)
 174     );
 175     for(i = 1;i < MAX_EFFECT_CHANNELS;i++)
 176         ALfilterState_copyParams(&state->filter[3][i], &state->filter[3][0]);
 177 }
 178
 179 static ALvoid ALequalizerState_process(ALequalizerState *state, ALsizei SamplesToDo, const ALfloat (*restrict SamplesIn)[BUFFERSIZE], ALfloat (*restrict SamplesOut)[BUFFERSIZE], ALsizei NumChannels)
 180 {
 181     ALfloat (*Samples)[MAX_EFFECT_CHANNELS][MAX_UPDATE_SAMPLES] = state->SampleBuffer;
 182     ALsizei it, kt, ft;
 183     ALsizei base;
 184
 185     for(base = 0;base < SamplesToDo;)
 186     {
 187         ALsizei td = mini(MAX_UPDATE_SAMPLES, SamplesToDo-base);
 188
 189         for(ft = 0;ft < MAX_EFFECT_CHANNELS;ft++)
 190             ALfilterState_process(&state->filter[0][ft], Samples[0][ft], &SamplesIn[ft][base], td);
 191         for(ft = 0;ft < MAX_EFFECT_CHANNELS;ft++)
 192             ALfilterState_process(&state->filter[1][ft], Samples[1][ft], Samples[0][ft], td);
 193         for(ft = 0;ft < MAX_EFFECT_CHANNELS;ft++)
 194             ALfilterState_process(&state->filter[2][ft], Samples[2][ft], Samples[1][ft], td);
 195         for(ft = 0;ft < MAX_EFFECT_CHANNELS;ft++)
 196             ALfilterState_process(&state->filter[3][ft], Samples[3][ft], Samples[2][ft], td);
 197
 198         for(ft = 0;ft < MAX_EFFECT_CHANNELS;ft++)
 199         {
 200             for(kt = 0;kt < NumChannels;kt++)
 201             {
 202                 ALfloat gain = state->Gain[ft][kt];
 203                 if(!(fabsf(gain) > GAIN_SILENCE_THRESHOLD))
 204                     continue;
 205
 206                 for(it = 0;it < td;it++)
 207                     SamplesOut[kt][base+it] += gain * Samples[3][ft][it];
 208             }
 209         }
 210
 211         base += td;
 212     }
 213 }
 214
 215
 216 typedef struct ALequalizerStateFactory {
 217     DERIVE_FROM_TYPE(ALeffectStateFactory);
 218 } ALequalizerStateFactory;
 219
 220 ALeffectState *ALequalizerStateFactory_create(ALequalizerStateFactory *UNUSED(factory))
 221 {
 222     ALequalizerState *state;
 223
 224     NEW_OBJ0(state, ALequalizerState)();
 225     if(!state) return NULL;
 226
 227     return STATIC_CAST(ALeffectState, state);
 228 }
 229
 230 DEFINE_ALEFFECTSTATEFACTORY_VTABLE(ALequalizerStateFactory);
 231
 232 ALeffectStateFactory *ALequalizerStateFactory_getFactory(void)
 233 {
 234     static ALequalizerStateFactory EqualizerFactory = { { GET_VTABLE2(ALequalizerStateFactory, ALeffectStateFactory) } };
 235
 236     return STATIC_CAST(ALeffectStateFactory, &EqualizerFactory);
 237 }
 238
 239
 240 void ALequalizer_setParami(ALeffect *UNUSED(effect), ALCcontext *context, ALenum UNUSED(param), ALint UNUSED(val))
 241 { SET_ERROR_AND_RETURN(context, AL_INVALID_ENUM); }
 242 void ALequalizer_setParamiv(ALeffect *effect, ALCcontext *context, ALenum param, const ALint *vals)
 243 {
 244     ALequalizer_setParami(effect, context, param, vals[0]);
 245 }
 246 void ALequalizer_setParamf(ALeffect *effect, ALCcontext *context, ALenum param, ALfloat val)
 247 {
 248     ALeffectProps *props = &effect->Props;
 249     switch(param)
 250     {
 251         case AL_EQUALIZER_LOW_GAIN:
 252             if(!(val >= AL_EQUALIZER_MIN_LOW_GAIN && val <= AL_EQUALIZER_MAX_LOW_GAIN))
 253                 SET_ERROR_AND_RETURN(context, AL_INVALID_VALUE);
 254             props->Equalizer.LowGain = val;
 255             break;
 256
 257         case AL_EQUALIZER_LOW_CUTOFF:
 258             if(!(val >= AL_EQUALIZER_MIN_LOW_CUTOFF && val <= AL_EQUALIZER_MAX_LOW_CUTOFF))
 259                 SET_ERROR_AND_RETURN(context, AL_INVALID_VALUE);
 260             props->Equalizer.LowCutoff = val;
 261             break;
 262
 263         case AL_EQUALIZER_MID1_GAIN:
 264             if(!(val >= AL_EQUALIZER_MIN_MID1_GAIN && val <= AL_EQUALIZER_MAX_MID1_GAIN))
 265                 SET_ERROR_AND_RETURN(context, AL_INVALID_VALUE);
 266             props->Equalizer.Mid1Gain = val;
 267             break;
 268
 269         case AL_EQUALIZER_MID1_CENTER:
 270             if(!(val >= AL_EQUALIZER_MIN_MID1_CENTER && val <= AL_EQUALIZER_MAX_MID1_CENTER))
 271                 SET_ERROR_AND_RETURN(context, AL_INVALID_VALUE);
 272             props->Equalizer.Mid1Center = val;
 273             break;
 274
 275         case AL_EQUALIZER_MID1_WIDTH:
 276             if(!(val >= AL_EQUALIZER_MIN_MID1_WIDTH && val <= AL_EQUALIZER_MAX_MID1_WIDTH))
 277                 SET_ERROR_AND_RETURN(context, AL_INVALID_VALUE);
 278             props->Equalizer.Mid1Width = val;
 279             break;
 280
 281         case AL_EQUALIZER_MID2_GAIN:
 282             if(!(val >= AL_EQUALIZER_MIN_MID2_GAIN && val <= AL_EQUALIZER_MAX_MID2_GAIN))
 283                 SET_ERROR_AND_RETURN(context, AL_INVALID_VALUE);
 284             props->Equalizer.Mid2Gain = val;
 285             break;
 286
 287         case AL_EQUALIZER_MID2_CENTER:
 288             if(!(val >= AL_EQUALIZER_MIN_MID2_CENTER && val <= AL_EQUALIZER_MAX_MID2_CENTER))
 289                 SET_ERROR_AND_RETURN(context, AL_INVALID_VALUE);
 290             props->Equalizer.Mid2Center = val;
 291             break;
 292
 293         case AL_EQUALIZER_MID2_WIDTH:
 294             if(!(val >= AL_EQUALIZER_MIN_MID2_WIDTH && val <= AL_EQUALIZER_MAX_MID2_WIDTH))
 295                 SET_ERROR_AND_RETURN(context, AL_INVALID_VALUE);
 296             props->Equalizer.Mid2Width = val;
 297             break;
 298
 299         case AL_EQUALIZER_HIGH_GAIN:
 300             if(!(val >= AL_EQUALIZER_MIN_HIGH_GAIN && val <= AL_EQUALIZER_MAX_HIGH_GAIN))
 301                 SET_ERROR_AND_RETURN(context, AL_INVALID_VALUE);
 302             props->Equalizer.HighGain = val;
 303             break;
 304
 305         case AL_EQUALIZER_HIGH_CUTOFF:
 306             if(!(val >= AL_EQUALIZER_MIN_HIGH_CUTOFF && val <= AL_EQUALIZER_MAX_HIGH_CUTOFF))
 307                 SET_ERROR_AND_RETURN(context, AL_INVALID_VALUE);
 308             props->Equalizer.HighCutoff = val;
 309             break;
 310
 311         default:
 312             SET_ERROR_AND_RETURN(context, AL_INVALID_ENUM);
 313     }
 314 }
 315 void ALequalizer_setParamfv(ALeffect *effect, ALCcontext *context, ALenum param, const ALfloat *vals)
 316 {
 317     ALequalizer_setParamf(effect, context, param, vals[0]);
 318 }
 319
 320 void ALequalizer_getParami(const ALeffect *UNUSED(effect), ALCcontext *context, ALenum UNUSED(param), ALint *UNUSED(val))
 321 { SET_ERROR_AND_RETURN(context, AL_INVALID_ENUM); }
 322 void ALequalizer_getParamiv(const ALeffect *effect, ALCcontext *context, ALenum param, ALint *vals)
 323 {
 324     ALequalizer_getParami(effect, context, param, vals);
 325 }
 326 void ALequalizer_getParamf(const ALeffect *effect, ALCcontext *context, ALenum param, ALfloat *val)
 327 {
 328     const ALeffectProps *props = &effect->Props;
 329     switch(param)
 330     {
 331         case AL_EQUALIZER_LOW_GAIN:
 332             *val = props->Equalizer.LowGain;
 333             break;
 334
 335         case AL_EQUALIZER_LOW_CUTOFF:
 336             *val = props->Equalizer.LowCutoff;
 337             break;
 338
 339         case AL_EQUALIZER_MID1_GAIN:
 340             *val = props->Equalizer.Mid1Gain;
 341             break;
 342
 343         case AL_EQUALIZER_MID1_CENTER:
 344             *val = props->Equalizer.Mid1Center;
 345             break;
 346
 347         case AL_EQUALIZER_MID1_WIDTH:
 348             *val = props->Equalizer.Mid1Width;
 349             break;
 350
 351         case AL_EQUALIZER_MID2_GAIN:
 352             *val = props->Equalizer.Mid2Gain;
 353             break;
 354
 355         case AL_EQUALIZER_MID2_CENTER:
 356             *val = props->Equalizer.Mid2Center;
 357             break;
 358
 359         case AL_EQUALIZER_MID2_WIDTH:
 360             *val = props->Equalizer.Mid2Width;
 361             break;
 362
 363         case AL_EQUALIZER_HIGH_GAIN:
 364             *val = props->Equalizer.HighGain;
 365             break;
 366
 367         case AL_EQUALIZER_HIGH_CUTOFF:
 368             *val = props->Equalizer.HighCutoff;
 369             break;
 370
 371         default:
 372             SET_ERROR_AND_RETURN(context, AL_INVALID_ENUM);
 373     }
 374 }
 375 void ALequalizer_getParamfv(const ALeffect *effect, ALCcontext *context, ALenum param, ALfloat *vals)
 376 {
 377     ALequalizer_getParamf(effect, context, param, vals);
 378 }
 379
 380 DEFINE_ALEFFECT_VTABLE(ALequalizer);