The parametric equalizer control consists of a series of filters that are applied successively to the signal. More...

Enumerations
enum	HPI_FILTER_TYPE { HPI_FILTER_TYPE_BYPASS = 0, HPI_FILTER_TYPE_LOWSHELF = 1, HPI_FILTER_TYPE_HIGHSHELF = 2, HPI_FILTER_TYPE_EQ_BAND = 3, HPI_FILTER_TYPE_LOWPASS = 4, HPI_FILTER_TYPE_HIGHPASS = 5, HPI_FILTER_TYPE_BANDPASS = 6, HPI_FILTER_TYPE_BANDSTOP = 7 }
	Equalizer filter types. More...
Functions
hpi_err_t	HPI_ParametricEQ_GetInfo (const hpi_hsubsys_t phSubSys, hpi_handle_t hControl, uint16_t pwNumberOfBands, uint16_t *pwOnOff)
	Find out the number of available bands of a parametric equalizer, and whether it is enabled or not.
hpi_err_t	HPI_ParametricEQ_SetState (const hpi_hsubsys_t *phSubSys, hpi_handle_t hControl, uint16_t wOnOff)
	Turn a parametric equalizer on or off.
hpi_err_t	HPI_ParametricEQ_GetBand (const hpi_hsubsys_t phSubSys, hpi_handle_t hControl, uint16_t wIndex, uint16_t pnType, uint32_t pdwFrequencyHz, short pnQ100, short *pnGain0_01dB)
	Get the settings of one of the filters in a parametric equalizer.
hpi_err_t	HPI_ParametricEQ_SetBand (const hpi_hsubsys_t *phSubSys, hpi_handle_t hControl, uint16_t wIndex, uint16_t nType, uint32_t dwFrequencyHz, short nQ100, short nGain0_01dB)
	Set up one of the filters in a parametric equalizer.
hpi_err_t	HPI_ParametricEQ_GetCoeffs (const hpi_hsubsys_t *phSubSys, hpi_handle_t hControl, uint16_t wIndex, short coeffs[5])
	Retrieve the calculated IIR filter coefficients (scaled by 1000 into integers).

Detailed Description

The parametric equalizer control consists of a series of filters that are applied successively to the signal.

The number of filters available is obtained by calling HPI_ParametricEQ_GetInfo(), then the characteristics of each filter are configured using HPI_ParametricEQ_SetBand().

The equalizer as a whole can be turned on and off using HPI_ParametricEQ_SetState(). Filters can still be set up when the equalizer is switched off.

Equalizers are typically located on a LineIn input node or an OutStream node.

Obtain a control handle to an equalizer like this:

err = HPI_MixerGetControl(
                phSubSys,
                hMixer,
                HPI_SOURCENODE_LINEIN, 0,
                0,0,  // No destination node
                HPI_CONTROL_PARAMETRIC_EQ,
                &hControl
                );

Enumeration Type Documentation

enum HPI_FILTER_TYPE

Equalizer filter types.

Used by HPI_ParametricEQ_SetBand()

Enumerator:

HPI_FILTER_TYPE_BYPASS	Filter is turned off.
HPI_FILTER_TYPE_LOWSHELF	EQ low shelf.
HPI_FILTER_TYPE_HIGHSHELF	EQ high shelf.
HPI_FILTER_TYPE_EQ_BAND	EQ gain.
HPI_FILTER_TYPE_LOWPASS	Standard low pass.
HPI_FILTER_TYPE_HIGHPASS	Standard high pass.
HPI_FILTER_TYPE_BANDPASS	Standard band pass.
HPI_FILTER_TYPE_BANDSTOP	Standard band stop/notch.

Function Documentation

hpi_err_t HPI_ParametricEQ_GetInfo	(	const hpi_hsubsys_t *	phSubSys,
		hpi_handle_t	hControl,
		uint16_t *	pwNumberOfBands,
		uint16_t *	pwOnOff
	)

Find out the number of available bands of a parametric equalizer, and whether it is enabled or not.

Returns:: 0 on success, or one of the HPI_ERROR_CODES.

Parameters:

phSubSys	Vestigial subsys handle (unused), may be set to NULL
hControl	Equalizer control handle.
pwNumberOfBands	Returned number of bands available.
pwOnOff	Returned enabled status. 1 indicates enabled and 0 indicates disabled.

hpi_err_t HPI_ParametricEQ_SetState	(	const hpi_hsubsys_t *	phSubSys,
		hpi_handle_t	hControl,
		uint16_t	wOnOff
	)

Turn a parametric equalizer on or off.

Returns:: 0 on success, or one of the HPI_ERROR_CODES.

Parameters:

phSubSys	Vestigial subsys handle (unused), may be set to NULL
hControl	Equalizer control handle
wOnOff	State setting, one of the HPI_SWITCH_STATES

hpi_err_t HPI_ParametricEQ_GetBand	(	const hpi_hsubsys_t *	phSubSys,
		hpi_handle_t	hControl,
		uint16_t	wIndex,
		uint16_t *	pnType,
		uint32_t *	pdwFrequencyHz,
		short *	pnQ100,
		short *	pnGain0_01dB
	)

Get the settings of one of the filters in a parametric equalizer.

See HPI_ParametricEQ_SetBand() for details of parameter interpretation.

Returns:: 0 on success, or one of the HPI_ERROR_CODES.

Parameters:

phSubSys	Vestigial subsys handle (unused), may be set to NULL
hControl	Equalizer control handle
wIndex	Index of band to Get.
pnType	Returned band type.
pdwFrequencyHz	Returned band frequency.
pnQ100	Returned filter Q * 100.
pnGain0_01dB	Returned filter gain in 100ths of a dB.

hpi_err_t HPI_ParametricEQ_SetBand	(	const hpi_hsubsys_t *	phSubSys,
		hpi_handle_t	hControl,
		uint16_t	wIndex,
		uint16_t	nType,
		uint32_t	dwFrequencyHz,
		short	nQ100,
		short	nGain0_01dB
	)

Set up one of the filters in a parametric equalizer.

Set the parameters for one equalizer filter. The overall equalizer response will be a product of all its filter responses.

Returns:: 0 on success, or one of the HPI_ERROR_CODES.

Parameters:

phSubSys	Vestigial subsys handle (unused), may be set to NULL
hControl	Equalizer control handle.
wIndex	Index of band to set.
nType	The kind of filter that the band will implement has many different options. In the following descriptions, low and high frequencies mean relative to dwBandFrequency. "Elsewhere" means at frequencies different from dwBandFrequency, how different depends on Q (look at the following figures) HPI_FILTER_TYPE_BYPASS The filter is bypassed (turned off). Other parameters are ignored HPI_FILTER_TYPE_LOWPASS Has unity gain at low frequencies, and attenuation tending towards infinite at high frequencies. nGain0_01dB parameter is ignored. See "lp" in the following diagrams. HPI_FILTER_TYPE_HIGHPASS Has unity gain at high frequencies, and attenuation tending towards infinite at low frequencies. nGain0_01dB parameter is ignored. (Not illustrated, basically the opposite of lowpass) HPI_FILTER_TYPE_BANDPASS Has unity gain at dwFrequencyHz and tends towards infinite attenuation elsewhere. nGain0_01dB parameter is ignored. See "bp" in the following diagrams. HPI_FILTER_TYPE_BANDSTOP Maximum attenuation at dwFrequencyHz, tends towards unity gain elsewhere. nGain0_01dB parameter is ignored. See "bs" in the following diagrams. HPI_FILTER_TYPE_LOWSHELF Has gain of nGain0_01dB at low frequencies and unity gain at high frequencies. See "ls" in the following diagrams. HPI_FILTER_TYPE_HIGHSHELF Has gain of nGain0_01dB at high frequencies and unity gain at low frequencies. See "hs" in the following diagrams. HPI_FILTER_TYPE_EQ_BAND Has gain of nGain0_01dB at dwFrequencyHz and unity gain elsewhere. See "eq" in the following diagrams.
dwFrequencyHz	is the defining frequency of the filter. It is the center frequency of types HPI_FILTER_TYPE_ BANDPASS, HPI_FILTER_TYPE_BANDSTOP, HPI_FILTER_TYPE_EQ_BAND. It is the -3dB frequency of HPI_FILTER_TYPE_LOWPASS, HPI_FILTER_TYPE_HIGHPASS when Q=1 or resonant frequency when Q>1 and it is the half gain frequency of HPI_FILTER_TYPE_LOWSHELF, HPI_FILTER_TYPE_HIGHSHELF. The maximum allowable value is half the current adapter samplerate i.e. Fs/2. When the adapter samplerate is changed, the equalizer filters will be recalculated. If this results in the band frequency being greater than Fs/2, then the filter will be turned off.
nQ100	controls filter sharpness. To allow the use of an integer parameter, Filter Q = dwQ100/100. In the following figure, gain is 20dB (10x) (nGain0_01dB=2000) and sampling frequency is normalized to 1Hz (10^0) and nFrequency is 0.1 x sampling frequency. Q=[0.2 0.5 1 2 4 8]. Q can also be thought of as affecting bandwidth or shelf slope of some of these filters. Bandwidth is measured in octaves (between -3 dB frequencies for BPF and notch or between midpoint (dBgain/2) gain frequencies for peaking EQ). The relationship between bandwidth and Q is: 1/Q = 2sinh[ln(2)/2bandwidthomega/sin(omega)] (digital filter using BLT) or 1/Q = 2sinh[ln(2)/2bandwidth]) (analog filter prototype) Where omega = 2pifrequency/sampleRate Shelf slope S, a "shelf slope" parameter (for shelving EQ only). When S = 1, the shelf slope is as steep as it can be and remain monotonically increasing or decreasing gain with frequency. The shelf slope, in dB/octave, remains proportional to S for all other values. The relationship between shelf slope and Q is 1/Q = sqrt[(A + 1/A)(1/S - 1) + 2] where A = 10^(dBgain/40) Effect of Q on EQ filters
nGain0_01dB	The gain is expressed in milliBels (100ths of a decibel). Allowable range is -1000 to +1000 mB. Usable range will likely be less than this. This parameter is only applicable to the equalizer filter types HPI_FILTER_TYPE_LOWSHELF,HPI_FILTER_TYPE_HIGHSHELF and HPI_FILTER_TYPE_EQ_BAND. Other filters always have unity gain in the passband. In the following figure, Q=1.0 and sampling frequency is normalized to 1Hz (10^0) and nFrequency is 0.1 x sampling frequency. dBgain=[-20 -10 0 10 20] For example, to produce the upper (red) curve in the "Filtertype_eq_band" graph: err= HPI_ParametricEQ_SetBand( phSubsys, hMicrophoneControl, HPI_FILTER_TYPE_EQ_BAND, 4410 // 4.41khz 100 // Q=1 20*100, // 20dB ); Effect of gain on EQ filters

hpi_err_t HPI_ParametricEQ_GetCoeffs	(	const hpi_hsubsys_t *	phSubSys,
		hpi_handle_t	hControl,
		uint16_t	wIndex,
		short	coeffs[5]
	)

Retrieve the calculated IIR filter coefficients (scaled by 1000 into integers).

Returns:: 0 on success, or one of the HPI_ERROR_CODES.

Parameters:

phSubSys	Vestigial subsys handle (unused), may be set to NULL
hControl	Equalizer control handle.
wIndex	Index of band to Get.
coeffs	Returned IIR filter coefficients * 1000 a1,a2,b0,b1,b2 (a0==0).

Parametric Equalizer control

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

Function Documentation