media/libeffects/AudioEqualizer.h

/*
 * Copyright 2009, The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

#ifndef AUDIOEQUALIZER_H_
#define AUDIOEQUALIZER_H_

#include "AudioCommon.h"

namespace android {

class AudioShelvingFilter;
class AudioPeakingFilter;

// A parametric audio equalizer. Supports an arbitrary number of bands and
// presets.
// The EQ is composed of a low-shelf, zero or more peaking filters and a high
// shelf, where each band has frequency and gain controls, and the peaking
// filters have an additional bandwidth control.
class AudioEqualizer {
public:
    // Configuration of a single band.
    struct BandConfig {
        // Gain in millibel.
        int32_t gain;
        // Frequency in millihertz.
        uint32_t freq;
        // Bandwidth in cents (ignored on shelving filters).
        uint32_t bandwidth;
    };

    // Preset configuration.
    struct PresetConfig {
        // Human-readable name.
        const char * name;
        // An array of size nBands where each element is a configuration for the
        // corresponding band.
        const BandConfig * bandConfigs;
    };

    // This value is used when requesting current preset, and EQ is not using a
    // preset.
    static const int PRESET_CUSTOM = -1;

    // Get the required memory size for an instance of this class.
    // nBands   Number of bands required in the instance.
    static size_t GetInstanceSize(int nBands);

    // Create an instance of this class.
    // If succeeds, a respective call is expected to freeInstance(), regardless
    // of who owns the context memory.
    // pMem         A memory buffer of at least the size returned by
    //              GetInstanceSize(), where the instance context is to be
    //              stored. If NULL, it will be automatically allocated (using
    //              malloc).
    // nBands       Number of bands. Must be >= 2.
    // nChannels    Number of input/output channels (interlaced).
    // sampleRate   The input/output sample rate, in Hz.
    // presets      The presets configuration. May be NULL, but in that case the
    //              client is required not to call preset-related functions.
    //              This array is owned by the client and is not copied. It
    //              must be kept valid by the client as long as the instance is
    //              alive.
    // nPresets     Number of elements in the presets array.
    // returns      The instance if success. NULL if pMem is NULL and allocation
    //              failed.
    static AudioEqualizer * CreateInstance(void * pMem, int nBands,
                                           int nChannels,
                                           int sampleRate,
                                           const PresetConfig * presets,
                                           int nPresets);

    // Reconfiguration of the filter. Changes input/output format, but does not
    // alter current parameter values. Causes reset of the delay lines.
    // nChannels  Number of input/output channels (interlaced).
    // sampleRate The input/output sample rate, in Hz.
    void configure(int nChannels, int sampleRate);

    // Resets the filter parameters to the following values:
    // frequency: 0
    // gain: 0
    // bandwidth: 1200 cents.
    // It also disables the filter. Does not clear the delay lines.
    void reset();

    // Clears delay lines. Does not alter parameter values.
    void clear();

    // Frees the object. Will free the memory if the object owned it, i.e. if
    // a NULL pointer was passed to CreateInstance as pMem.
    void free();

    // Sets gain value. Actual change will only take place upon commit().
    // This value will be remembered even if the filter is in disabled() state.
    // band     The band to set the gain for.
    // millibel Gain value in millibel (1/100 of decibel).
    void setGain(int band, int32_t millibel);

    // Gets gain of a certain band. This is always the last value set (or
    // default value after reset).
    // band     The band to get the gain for.
    // returns  Gain value in millibel (1/100 of decibel).
    int32_t getGain(int band) const;

    // Sets cutoff frequency value. Actual change will only take place upon
    // commit().
    // This value will be remembered even if the filter is in disabled() state.
    // band       The band to set the frequency for.
    // millihertz Frequency value in mHz.
    void setFrequency(int band, uint32_t millihertz);

    // Gets frequency of a certain band. This is always the last value set (or
    // default value after reset).
    // band     The band to get the frequency for.
    // returns  Frequency value in mHz.
    uint32_t getFrequency(int band) const;

    // Sets bandwidth value. Actual change will only take place upon commit().
    // This value will be remembered even if the filter is in disabled() state.
    // If called on the first or last band, this call is ignored.
    // band  The band to set the frequency for.
    // cents Bandwidth value in cents (1/1200 octave).
    void setBandwidth(int band, uint32_t cents);

    // Gets bandwidth of a certain band. This is always the last value set (or
    // default value after reset). For the first and last bands, 0 is always
    // returned.
    // band     The band to get the bandwidth for.
    // returns  Bandwidth value in cents (1/1200 octave).
    uint32_t getBandwidth(int band) const;

    // Gets lower and upper boundaries of a band.
    // For the low shelf, the low bound is 0 and the high bound is the band
    // frequency.
    // For the high shelf, the low bound is the band frequency and the high
    // bound is Nyquist.
    // For the peaking filters, they are the gain[dB]/2 points.
    void getBandRange(int band, uint32_t & low, uint32_t & high) const;

    // Gets a human-readable name for a preset ID. Will return "Custom" if
    // PRESET_CUSTOM is passed.
    // preset       The preset ID. Must be less than number of presets.
    const char * getPresetName(int preset) const;

    // Gets the number of presets.
    int getNumPresets() const;

    // Gets the currently set preset ID.
    // Will return PRESET_CUSTOM in case the EQ parameters have been modified
    // manually since a preset was set.
    int getPreset() const;

    // Sets the current preset by ID.
    // All the band parameters will be overridden.
    // Change will not be applied until commit() is called.
    // preset       The preset ID. Must be less than number of presets.
    //              PRESET_CUSTOM is NOT a valid value here.
    void setPreset(int preset);

    // Applies all parameter changes done to this point in time.
    // If the filter is disabled, the new parameters will take place when it is
    // enabled again. Does not introduce artifacts, unless immediate is set.
    // immediate    Whether to apply change abruptly (ignored if filter is
    // disabled).
   void commit(bool immediate = false);

    // Process a buffer of input data. The input and output should contain
    // frameCount * nChannels interlaced samples. Processing can be done
    // in-place, by passing the same buffer as both arguments.
    // pIn          Input buffer.
    // pOut         Output buffer.
    // frameCount   Number of frames to produce on each call to process().
    void process(const audio_sample_t * pIn, audio_sample_t * pOut,
                 int frameCount);

    // Enables the filter, so it would start processing input. Does not
    // introduce artifacts, unless immediate is set.
    // immediate    Whether to apply change abruptly.
    void enable(bool immediate = false);

    // Disabled (bypasses) the filter. Does not introduce artifacts, unless
    // immediate is set.
    // immediate    Whether to apply change abruptly.
    void disable(bool immediate = false);

    // Returns the band with the maximum influence on a given frequency.
    // Result is unaffected by whether EQ is enabled or not, or by whether
    // changes have been committed or not.
    // targetFreq   The target frequency, in millihertz.
    int getMostRelevantBand(uint32_t targetFreq) const;

private:
    // Bottom frequency, in mHz.
    static const int kMinFreq = 20000;
    // Sample rate, in Hz.
    int mSampleRate;
    // Number of peaking filters. Total number of bands is +2.
    int mNumPeaking;
    // Preset configurations.
    const PresetConfig * mpPresets;
    // Number of elements in mpPresets;
    int mNumPresets;
    // Current preset.
    int mCurPreset;

    // Memory space to free when instance is deleted, or NULL if no memory is
    // owned.
    void * mpMem;
    // The low-shelving filter.
    AudioShelvingFilter * mpLowShelf;
    // The high-shelving filter.
    AudioShelvingFilter * mpHighShelf;
    // An array of size mNumPeaking of peaking filters.
    AudioPeakingFilter * mpPeakingFilters;

    // Constructor. Resets the filter (see reset()). Must call init() doing
    // anything else.
    // pMem       Memory buffer for bands.
    // nChannels  Number of input/output channels (interlaced).
    // sampleRate The input/output sample rate, in Hz.
    // ownMem     Whether pMem is owned by me.
    // presets      The presets configuration. May be NULL, but in that case the
    //              client is required not to call preset-related functions.
    //              This array is owned by the client and is not copied. It
    //              must be kept valid by the client as long as the instance is
    //              alive.
    // nPresets     Number of elements in the presets array.
    AudioEqualizer(void * pMem, int nBands, int nChannels, int sampleRate,
                   bool ownMem, const PresetConfig * presets, int nPresets);
};

}

#endif // AUDIOEQUALIZER_H_