API for C

The API for the C Programming language. More...

Classes
struct	dh_filter_parameters
struct	dh_filter_data

Enumerations
enum	DH_FILTER_TYPE {   DH_NO_FILTER, DH_FIR_MOVING_AVERAGE_LOWPASS, DH_FIR_MOVING_AVERAGE_HIGHPASS, DH_FIR_EXPONENTIAL_MOVING_AVERAGE_LOWPASS,   DH_FIR_BRICKWALL_LOWPASS, DH_FIR_BRICKWALL_HIGHPASS, DH_FIR_BRICKWALL_BANDPASS, DH_FIR_BRICKWALL_BANDSTOP,   DH_IIR_EXPONENTIAL_LOWPASS, DH_IIR_BUTTERWORTH_LOWPASS, DH_IIR_BUTTERWORTH_HIGHPASS, DH_IIR_BUTTERWORTH_BANDPASS,   DH_IIR_BUTTERWORTH_BANDSTOP, DH_IIR_CHEBYSHEV_LOWPASS, DH_IIR_CHEBYSHEV_HIGHPASS, DH_IIR_CHEBYSHEV_BANDPASS,   DH_IIR_CHEBYSHEV_BANDSTOP, DH_IIR_CHEBYSHEV2_LOWPASS, DH_IIR_CHEBYSHEV2_HIGHPASS, DH_IIR_CHEBYSHEV2_BANDPASS,   DH_IIR_CHEBYSHEV2_BANDSTOP }
enum	DH_FILTER_RETURN_VALUE {   DH_FILTER_OK, DH_FILTER_ERROR, DH_FILTER_NO_DATA_STRUCTURE, DH_FILTER_DATA_STRUCTURE_NOT_INITIALIZED,   DH_FILTER_UNKNOWN_FILTER_TYPE, DH_FILTER_ALLOCATION_FAILED }

Functions
DH_FILTER_RETURN_VALUE	dh_filter (dh_filter_data *filter, double input, double *output)
	Runs an iteration of the filter. More...
DH_FILTER_RETURN_VALUE	dh_create_filter (dh_filter_data *filter, dh_filter_parameters *options)
	Allocates the buffers and initializes the filter. More...
DH_FILTER_RETURN_VALUE	dh_initialize_filter (dh_filter_data *filter, double value)
	Forces the filter to the steady state with output value by setting all pasts inputs and outputs to the given [value]. More...
DH_FILTER_RETURN_VALUE	dh_free_filter (dh_filter_data *filter)
DH_FILTER_RETURN_VALUE	dh_filter_set_gain (dh_filter_data *filter, double gain)
DH_FILTER_RETURN_VALUE	dh_filter_get_gain (const dh_filter_data *filter, double *gain)
DH_FILTER_RETURN_VALUE	dh_filter_get_gain_at (const dh_filter_data *filter, double frequency, dh_frequency_response_t *gain)

Detailed Description

The API for the C Programming language.

The API of the filter library is kept as simple as possible. When you create a filter, you first create a dh_filter_parameters structure and initialize its data members. The filter must be initialized via dh_create_filter().

Here is an example for the basic usage of the API:

dh_filter_parameters parameters;
// set values in parameters to create your desired filter
dh_filter_data filter;
if (dh_create_filter(&filter, &parameters) != DH_FILTER_OK) {
    // handle error
}
// the filter is ready to be used
while (do_stuff) {
    double output = 0.0;
    double input = get_input();
    if (dh_filter(&filter, input, &output) == DH_FILTER_OK) {
        // use output
    } else { 
        // handle error
    }
}
// cleanup after you are done
dh_free_filter(&filter);

Enumeration Type Documentation

DH_FILTER_RETURN_VALUE

enum DH_FILTER_RETURN_VALUE

The return value for the public API of the library.

Enumerator
DH_FILTER_OK	Function was executed successfully.
DH_FILTER_ERROR	An undefined error.
DH_FILTER_NO_DATA_STRUCTURE	No input data given to the function.
DH_FILTER_DATA_STRUCTURE_NOT_INITIALIZED	Given input data was not correctly initialized.
DH_FILTER_UNKNOWN_FILTER_TYPE	The requested filter type does not exist.
DH_FILTER_ALLOCATION_FAILED	Allocation of the buffers failed or there was not enough space in the provided buffer.

DH_FILTER_TYPE

enum DH_FILTER_TYPE

The filter types supported by this library.

Enumerator
DH_NO_FILTER	No filtering. Input = output
DH_FIR_MOVING_AVERAGE_LOWPASS	A simple moving average.
DH_FIR_MOVING_AVERAGE_HIGHPASS	A simple moving average.
DH_FIR_EXPONENTIAL_MOVING_AVERAGE_LOWPASS	A moving average filter with exponentially decaying weights.
DH_FIR_BRICKWALL_LOWPASS	A brickwall filter (windowed sinc). Delay will be half of filter order.
DH_FIR_BRICKWALL_HIGHPASS	A brickwall filter (windowed sinc). Delay will be half of filter order.
DH_FIR_BRICKWALL_BANDPASS	A brickwall filter (windowed sinc). Delay will be half of filter order.
DH_FIR_BRICKWALL_BANDSTOP	A brickwall filter (windowed sinc). Delay will be half of filter order.
DH_IIR_EXPONENTIAL_LOWPASS	Lowest order IIR filter. y[n] = w*x[n] + (1-w)*y[n-1]
DH_IIR_BUTTERWORTH_LOWPASS	A butterworth filter. Has the smoothest possible frequency response.
DH_IIR_BUTTERWORTH_HIGHPASS	A butterworth filter. Has the smoothest possible frequency response.
DH_IIR_BUTTERWORTH_BANDPASS	A butterworth filter. Has the smoothest possible frequency response.
DH_IIR_BUTTERWORTH_BANDSTOP	A butterworth filter. Has the smoothest possible frequency response.
DH_IIR_CHEBYSHEV_LOWPASS	A chebyshev type 1 filter. Ripples are in the pass band.
DH_IIR_CHEBYSHEV_HIGHPASS	A chebyshev type 1 filter. Ripples are in the pass band.
DH_IIR_CHEBYSHEV_BANDPASS	A chebyshev type 1 filter. Ripples are in the pass band.
DH_IIR_CHEBYSHEV_BANDSTOP	A chebyshev type 1 filter. Ripples are in the pass band.
DH_IIR_CHEBYSHEV2_LOWPASS	A chebyshev type 2 filter. Ripples are in the stop band.
DH_IIR_CHEBYSHEV2_HIGHPASS	A chebyshev type 2 filter. Ripples are in the stop band.
DH_IIR_CHEBYSHEV2_BANDPASS	A chebyshev type 2 filter. Ripples are in the stop band.
DH_IIR_CHEBYSHEV2_BANDSTOP	A chebyshev type 2 filter. Ripples are in the stop band.

Function Documentation

dh_create_filter()

DH_FILTER_RETURN_VALUE dh_create_filter	(	dh_filter_data *	filter,
		dh_filter_parameters *	options
	)

Allocates the buffers and initializes the filter.

A filter generated by this function will always have gain 1. If you need a different gain, call dh_filter_set_gain().

Parameters

[out]	filter	pointer to the filter structure that will be initialized.
[in]	options	the desired filter type.

Returns

DH_FILTER_RETURN_VALUE

Return values

DH_FILTER_OK	Operation was successfull
DH_FILTER_NO_DATA_STRUCTURE	You gave NULL as first argument.
DH_FILTER_UNKNOWN_FILTER_TYPE	An unknown filter was requested in the options.
DH_FILTER_ALLOCATION_FAILED	Not enough memory for the filter could be allocated.

See also

dh_filter_parameters for the possible options.

dh_filter()

DH_FILTER_RETURN_VALUE dh_filter	(	dh_filter_data *	filter,
		double	input,
		double *	output
	)

Runs an iteration of the filter.

The function runs a loop for the feedforward and feedback coefficients. The ring buffer holding the past inputs and outputs will be updated.

Note

If the initialized property of the filter structure is set to false, then all past input and output values are set to the given input and the property is set to true. This only makes sense if the gain at 0 Hz is supposed to be 1 (e.g. lowpass or bandstop filters). It prevents the "initialization time" in case you filter objects that may appear and disappear.

Parameters

[in]	filter	The data structure of the filter. Must be initialized (the buffers/coefficients must be set).
[in]	input	The next input value to the filter.
[out]	output	The current output value. Parameter is optional. If it is not NULL, then the output value is written to the given address.

Returns

An enum with the result of the operation.

Return values

DH_FILTER_OK	Operation was successfull
DH_FILTER_NO_DATA_STRUCTURE	You gave NULL as first argument.
DH_FILTER_DATA_STRUCTURE_NOT_INITIALIZED	The filter data structure was not correctly initialized.

dh_filter_get_gain()

DH_FILTER_RETURN_VALUE dh_filter_get_gain	(	const dh_filter_data *	filter,
		double *	gain
	)

Gets the gain of the filter.

Parameters

[in]	filter	the filter structure
[out]	gain	pointer to output

Returns

An enum with the result of the operation.

Return values

DH_FILTER_OK	Operation was successfull
DH_FILTER_NO_DATA_STRUCTURE	You gave NULL as first argument.
DH_FILTER_DATA_STRUCTURE_NOT_INITIALIZED	The filter data structure was not correctly initialized.

dh_filter_get_gain_at()

DH_FILTER_RETURN_VALUE dh_filter_get_gain_at	(	const dh_filter_data *	filter,
		double	frequency,
		dh_frequency_response_t *	gain
	)

Gets the gain of the filter.

Parameters

[in]	filter	the filter structure
[in]	frequency	frequency/sampling_frequency where the gain is computed. Range: [0,0.5]
[out]	gain	pointer to output

Returns

An enum with the result of the operation.

Return values

DH_FILTER_OK	Operation was successfull
DH_FILTER_NO_DATA_STRUCTURE	You gave NULL as first argument.
DH_FILTER_DATA_STRUCTURE_NOT_INITIALIZED	The filter data structure was not correctly initialized.

dh_filter_set_gain()

DH_FILTER_RETURN_VALUE dh_filter_set_gain	(	dh_filter_data *	filter,
		double	gain
	)

Sets the gain of the filter to the given value.

Parameters

[in]	filter	the filter structure
[in]	gain	the desired gain

Returns

An enum with the result of the operation.

Return values

DH_FILTER_OK	Operation was successfull
DH_FILTER_NO_DATA_STRUCTURE	You gave NULL as first argument.
DH_FILTER_DATA_STRUCTURE_NOT_INITIALIZED	The filter data structure was not correctly initialized.

dh_free_filter()

DH_FILTER_RETURN_VALUE dh_free_filter

(

dh_filter_data *

filter

)

Frees the filter created with dh_create_filter().

If the filter is marked as owner of the buffer, free() will be called to clean up the allocated memory.

Parameters

[in]

filter

the filter structure that will be freed.

Returns

An enum with the result of the operation.

Return values

DH_FILTER_OK

Operation was successfull

dh_initialize_filter()

DH_FILTER_RETURN_VALUE dh_initialize_filter	(	dh_filter_data *	filter,
		double	value
	)

Forces the filter to the steady state with output value by setting all pasts inputs and outputs to the given [value].

Note

Call this function only with low-pass or band-stop filters! Usually, you do no not have to call this yourself if you use dh_create_filter().

Parameters

[in]	filter	the filter structure
[in]	value	the desired steady state

Returns

An enum with the result of the operation.

Return values

DH_FILTER_OK	Operation was successfull
DH_FILTER_NO_DATA_STRUCTURE	You gave NULL as first argument.