frameworks/base/media/libeffects/testlibs/AudioEqualizer.h

   1 /*
   2  * Copyright 2009, The Android Open Source Project
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *     http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 #ifndef AUDIOEQUALIZER_H_
  18 #define AUDIOEQUALIZER_H_
  19
  20 #include "AudioCommon.h"
  21
  22 namespace android {
  23
  24 class AudioShelvingFilter;
  25 class AudioPeakingFilter;
  26
  27 // A parametric audio equalizer. Supports an arbitrary number of bands and
  28 // presets.
  29 // The EQ is composed of a low-shelf, zero or more peaking filters and a high
  30 // shelf, where each band has frequency and gain controls, and the peaking
  31 // filters have an additional bandwidth control.
  32 class AudioEqualizer {
  33 public:
  34     // Configuration of a single band.
  35     struct BandConfig {
  36         // Gain in millibel.
  37         int32_t gain;
  38         // Frequency in millihertz.
  39         uint32_t freq;
  40         // Bandwidth in cents (ignored on shelving filters).
  41         uint32_t bandwidth;
  42     };
  43
  44     // Preset configuration.
  45     struct PresetConfig {
  46         // Human-readable name.
  47         const char * name;
  48         // An array of size nBands where each element is a configuration for the
  49         // corresponding band.
  50         const BandConfig * bandConfigs;
  51     };
  52
  53     // This value is used when requesting current preset, and EQ is not using a
  54     // preset.
  55     static const int PRESET_CUSTOM = -1;
  56
  57     // Get the required memory size for an instance of this class.
  58     // nBands   Number of bands required in the instance.
  59     static size_t GetInstanceSize(int nBands);
  60
  61     // Create an instance of this class.
  62     // If succeeds, a respective call is expected to freeInstance(), regardless
  63     // of who owns the context memory.
  64     // pMem         A memory buffer of at least the size returned by
  65     //              GetInstanceSize(), where the instance context is to be
  66     //              stored. If NULL, it will be automatically allocated (using
  67     //              malloc).
  68     // nBands       Number of bands. Must be >= 2.
  69     // nChannels    Number of input/output channels (interlaced).
  70     // sampleRate   The input/output sample rate, in Hz.
  71     // presets      The presets configuration. May be NULL, but in that case the
  72     //              client is required not to call preset-related functions.
  73     //              This array is owned by the client and is not copied. It
  74     //              must be kept valid by the client as long as the instance is
  75     //              alive.
  76     // nPresets     Number of elements in the presets array.
  77     // returns      The instance if success. NULL if pMem is NULL and allocation
  78     //              failed.
  79     static AudioEqualizer * CreateInstance(void * pMem, int nBands,
  80                                            int nChannels,
  81                                            int sampleRate,
  82                                            const PresetConfig * presets,
  83                                            int nPresets);
  84
  85     // Reconfiguration of the filter. Changes input/output format, but does not
  86     // alter current parameter values. Causes reset of the delay lines.
  87     // nChannels  Number of input/output channels (interlaced).
  88     // sampleRate The input/output sample rate, in Hz.
  89     void configure(int nChannels, int sampleRate);
  90
  91     // Resets the filter parameters to the following values:
  92     // frequency: 0
  93     // gain: 0
  94     // bandwidth: 1200 cents.
  95     // It also disables the filter. Does not clear the delay lines.
  96     void reset();
  97
  98     // Clears delay lines. Does not alter parameter values.
  99     void clear();
 100
 101     // Frees the object. Will free the memory if the object owned it, i.e. if
 102     // a NULL pointer was passed to CreateInstance as pMem.
 103     void free();
 104
 105     // Sets gain value. Actual change will only take place upon commit().
 106     // This value will be remembered even if the filter is in disabled() state.
 107     // band     The band to set the gain for.
 108     // millibel Gain value in millibel (1/100 of decibel).
 109     void setGain(int band, int32_t millibel);
 110
 111     // Gets gain of a certain band. This is always the last value set (or
 112     // default value after reset).
 113     // band     The band to get the gain for.
 114     // returns  Gain value in millibel (1/100 of decibel).
 115     int32_t getGain(int band) const;
 116
 117     // Sets cutoff frequency value. Actual change will only take place upon
 118     // commit().
 119     // This value will be remembered even if the filter is in disabled() state.
 120     // band       The band to set the frequency for.
 121     // millihertz Frequency value in mHz.
 122     void setFrequency(int band, uint32_t millihertz);
 123
 124     // Gets frequency of a certain band. This is always the last value set (or
 125     // default value after reset).
 126     // band     The band to get the frequency for.
 127     // returns  Frequency value in mHz.
 128     uint32_t getFrequency(int band) const;
 129
 130     // Sets bandwidth value. Actual change will only take place upon commit().
 131     // This value will be remembered even if the filter is in disabled() state.
 132     // If called on the first or last band, this call is ignored.
 133     // band  The band to set the frequency for.
 134     // cents Bandwidth value in cents (1/1200 octave).
 135     void setBandwidth(int band, uint32_t cents);
 136
 137     // Gets bandwidth of a certain band. This is always the last value set (or
 138     // default value after reset). For the first and last bands, 0 is always
 139     // returned.
 140     // band     The band to get the bandwidth for.
 141     // returns  Bandwidth value in cents (1/1200 octave).
 142     uint32_t getBandwidth(int band) const;
 143
 144     // Gets lower and upper boundaries of a band.
 145     // For the low shelf, the low bound is 0 and the high bound is the band
 146     // frequency.
 147     // For the high shelf, the low bound is the band frequency and the high
 148     // bound is Nyquist.
 149     // For the peaking filters, they are the gain[dB]/2 points.
 150     void getBandRange(int band, uint32_t & low, uint32_t & high) const;
 151
 152     // Gets a human-readable name for a preset ID. Will return "Custom" if
 153     // PRESET_CUSTOM is passed.
 154     // preset       The preset ID. Must be less than number of presets.
 155     const char * getPresetName(int preset) const;
 156
 157     // Gets the number of presets.
 158     int getNumPresets() const;
 159
 160     // Gets the currently set preset ID.
 161     // Will return PRESET_CUSTOM in case the EQ parameters have been modified
 162     // manually since a preset was set.
 163     int getPreset() const;
 164
 165     // Sets the current preset by ID.
 166     // All the band parameters will be overridden.
 167     // Change will not be applied until commit() is called.
 168     // preset       The preset ID. Must be less than number of presets.
 169     //              PRESET_CUSTOM is NOT a valid value here.
 170     void setPreset(int preset);
 171
 172     // Applies all parameter changes done to this point in time.
 173     // If the filter is disabled, the new parameters will take place when it is
 174     // enabled again. Does not introduce artifacts, unless immediate is set.
 175     // immediate    Whether to apply change abruptly (ignored if filter is
 176     // disabled).
 177    void commit(bool immediate = false);
 178
 179     // Process a buffer of input data. The input and output should contain
 180     // frameCount * nChannels interlaced samples. Processing can be done
 181     // in-place, by passing the same buffer as both arguments.
 182     // pIn          Input buffer.
 183     // pOut         Output buffer.
 184     // frameCount   Number of frames to produce on each call to process().
 185     void process(const audio_sample_t * pIn, audio_sample_t * pOut,
 186                  int frameCount);
 187
 188     // Enables the filter, so it would start processing input. Does not
 189     // introduce artifacts, unless immediate is set.
 190     // immediate    Whether to apply change abruptly.
 191     void enable(bool immediate = false);
 192
 193     // Disabled (bypasses) the filter. Does not introduce artifacts, unless
 194     // immediate is set.
 195     // immediate    Whether to apply change abruptly.
 196     void disable(bool immediate = false);
 197
 198     // Returns the band with the maximum influence on a given frequency.
 199     // Result is unaffected by whether EQ is enabled or not, or by whether
 200     // changes have been committed or not.
 201     // targetFreq   The target frequency, in millihertz.
 202     int getMostRelevantBand(uint32_t targetFreq) const;
 203
 204 private:
 205     // Bottom frequency, in mHz.
 206     static const int kMinFreq = 20000;
 207     // Sample rate, in Hz.
 208     int mSampleRate;
 209     // Number of peaking filters. Total number of bands is +2.
 210     int mNumPeaking;
 211     // Preset configurations.
 212     const PresetConfig * mpPresets;
 213     // Number of elements in mpPresets;
 214     int mNumPresets;
 215     // Current preset.
 216     int mCurPreset;
 217
 218     // Memory space to free when instance is deleted, or NULL if no memory is
 219     // owned.
 220     void * mpMem;
 221     // The low-shelving filter.
 222     AudioShelvingFilter * mpLowShelf;
 223     // The high-shelving filter.
 224     AudioShelvingFilter * mpHighShelf;
 225     // An array of size mNumPeaking of peaking filters.
 226     AudioPeakingFilter * mpPeakingFilters;
 227
 228     // Constructor. Resets the filter (see reset()). Must call init() doing
 229     // anything else.
 230     // pMem       Memory buffer for bands.
 231     // nChannels  Number of input/output channels (interlaced).
 232     // sampleRate The input/output sample rate, in Hz.
 233     // ownMem     Whether pMem is owned by me.
 234     // presets      The presets configuration. May be NULL, but in that case the
 235     //              client is required not to call preset-related functions.
 236     //              This array is owned by the client and is not copied. It
 237     //              must be kept valid by the client as long as the instance is
 238     //              alive.
 239     // nPresets     Number of elements in the presets array.
 240     AudioEqualizer(void * pMem, int nBands, int nChannels, int sampleRate,
 241                    bool ownMem, const PresetConfig * presets, int nPresets);
 242 };
 243
 244 }
 245
 246 #endif // AUDIOEQUALIZER_H_