utility.h File Reference

Utilities for the filter library. More...

#include "dh/filter-types.h"
#include "dh/dh_complex.h"

Include dependency graph for utility.h:

Go to the source code of this file.

Classes
struct	dh_transfer_function_callbacks

Macros
#define	MAYBE_UNUSED(X)   (void)((X))

Functions
void	dh_compute_poles_on_s_plane (COMPLEX *ptr, size_t len)
	Computes positions of poles on the complex plane. All poles are equally spaced in quadrants 2 and 3. The poles are computed on the unit circle and then scaled with the transformed frequency. More...
void	dh_compute_polynomial_coefficients_from_roots (COMPLEX *roots, size_t len, COMPLEX *outputs)
	Computes polynomial coefficients from given array of roots. More...
void	dh_normalize_gain_at (double *numerator, size_t len_numerator, double *denominator, size_t len_denominator, double x_evaluate)
	Evaluates the polynomials at the given positions and normalizes the numerator for gain 1.0 at [x_evaluate]. More...
COMPLEX	dh_gain_at (double *numerator, size_t len_numerator, double *denominator, size_t len_denominator, double x_evaluate)
	Evaluates the polynomials at the given position and returns the gain. More...
void	dh_convolve_parameters (double *param1, double *param2, size_t len, double *out)
	Convolves two sets of FIR filter parameters to combine them into one filter. More...
DH_FILTER_RETURN_VALUE	dh_compute_transfer_function_polynomials (dh_filter_data *filter, const dh_filter_parameters *options, const dh_transfer_function_callbacks cbs)
	Computes the transfer function polynomial for a filter using the given callbacks. More...

Detailed Description

Utilities for the filter library.

This source code is licensed under the MIT license. See file "LICENSE" at the root of the repository.

Macro Definition Documentation

MAYBE_UNUSED

#define MAYBE_UNUSED

(

X

)

(void)((X))

Used to get rid of compiler warnings

Function Documentation

dh_compute_poles_on_s_plane()

void dh_compute_poles_on_s_plane	(	COMPLEX *	ptr,
		size_t	len
	)

Computes positions of poles on the complex plane. All poles are equally spaced in quadrants 2 and 3. The poles are computed on the unit circle and then scaled with the transformed frequency.

Parameters

ptr	pointer to output array
len	number of poles to compute

dh_compute_polynomial_coefficients_from_roots()

void dh_compute_polynomial_coefficients_from_roots	(	COMPLEX *	roots,
		size_t	len,
		COMPLEX *	outputs
	)

Computes polynomial coefficients from given array of roots.

Parameters

roots	array of roots
len	number of roots +1/size of output array
outputs	out struct - must have length len

dh_compute_transfer_function_polynomials()

DH_FILTER_RETURN_VALUE dh_compute_transfer_function_polynomials	(	dh_filter_data *	filter,
		const dh_filter_parameters *	options,
		const dh_transfer_function_callbacks	cbs
	)

Computes the transfer function polynomial for a filter using the given callbacks.

An analog lowpass filter is created with the given callbacks in the [cbs] argument. The roots are converted from an analog low pass to the desired characteristic and roots are appended if needed. Then the roots are converted from the s-plane to the z-plane and the polynomial is expanded. The real part of the polynomial coefficients is written to the coefficient arrays in [filter]. The order of the polynomial coefficients is inverted: index 0 is the coefficient for x**n.

This function will allocate temporary buffers.

Parameters

filter	The filter that will be initialized. Output values are written to the arrays.
options	The options for the filter that are used to compute the values.
cbs	Struct with the function pointers that are used to initialize the poles and zeros on the s-plane.

Returns

Returns DH_FILTER_OK on success, otherwise an error code is returned.

dh_convolve_parameters()

void dh_convolve_parameters	(	double *	param1,
		double *	param2,
		size_t	len,
		double *	out
	)

Convolves two sets of FIR filter parameters to combine them into one filter.

Parameters

param1	Pointer to array with feedforward coefficients of the filter that is applied first.
param2	Pointer to array with feedforward coefficients of the filter that is applied second.
len	Number of entries in array param1 and param2.
out	The output is stored in that array. Must have 2*len-1 entries.

Returns

DH_FILTER_RETURN_VALUE

dh_gain_at()

COMPLEX dh_gain_at	(	double *	numerator,
		size_t	len_numerator,
		double *	denominator,
		size_t	len_denominator,
		double	x_evaluate
	)

Evaluates the polynomials at the given position and returns the gain.

Parameters

numerator	Array of polynomial coefficients.
len_numerator	Number of entries in numerator array.
denominator	Array of polynomial coefficients.
len_denominator	Number of entries in denominator array.
x_evaluate	Position where the polynominals are evaluated on the complex unit circle.

dh_normalize_gain_at()

void dh_normalize_gain_at	(	double *	numerator,
		size_t	len_numerator,
		double *	denominator,
		size_t	len_denominator,
		double	x_evaluate
	)

Evaluates the polynomials at the given positions and normalizes the numerator for gain 1.0 at [x_evaluate].

Parameters

numerator	Array of polynomial coefficients. Will be modified in place.
len_numerator	Number of entries in numerator array.
denominator	Array of polynomial coefficients.
len_denominator	Number of entries in denominator array.
x_evaluate	Position where the polynominals are evaluated on the complex unit circle.