/*
* 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_