r8b Namespace Reference

The "r8brain-free-src" library namespace. More...

Classes
class	CDSPBlockConvolver
	Single-block overlap-save convolution processing class. More...
class	CDSPFIRFilter
	Calculation and storage class for FIR filters. More...
class	CDSPFIRFilterCache
	FIR filter cache class. More...
class	CDSPFracDelayFilterBank
	Sinc function-based fractional delay filter bank class. More...
class	CDSPFracDelayFilterBankCache
	Fractional delay filter cache class. More...
class	CDSPFracInterpolator
	Fractional delay filter bank-based interpolator class. More...
class	CDSPHBDownsampler
	Half-band downsampler class. More...
class	CDSPHBUpsampler
	Half-band upsampling class. More...
class	CDSPProcessor
	The base virtual class for DSP processing algorithms. More...
class	CDSPRealFFT
	Real-valued FFT transform class. More...
class	CDSPRealFFTKeeper
	A "keeper" class for real-valued FFT transform objects. More...
class	CDSPResampler
	The master sample rate converter (resampler) class. More...
class	CDSPResampler16
	The resampler class for 16-bit resampling. More...
class	CDSPResampler16IR
	The resampler class for 16-bit impulse response resampling. More...
class	CDSPResampler24
	The resampler class for 24-bit resampling. More...
class	CDSPSincFilterGen
	Sinc function-based FIR filter generator class. More...
class	CFixedBuffer
	Templated memory buffer class for element buffers of fixed capacity. More...
class	CPtrKeeper
	Pointer-to-object "keeper" class with automatic deletion. More...
class	CSineGen
	Sine signal generator class. More...
class	CStdClassAllocator
	The default base class for objects created on heap. More...
class	CStdMemAllocator
	The default base class for objects that allocate blocks of memory. More...
class	CSyncKeeper
	A "keeper" class for CSyncObject-based synchronization. More...
class	CSyncObject
	Multi-threaded synchronization object class. More...
class	ooura_fft
	A wrapper class around Takuya OOURA's FFT functions. More...

Enumerations
enum	EDSPFilterPhaseResponse { fprLinearPhase = 0 , fprMinPhase }

Functions
template<typename T >
T *	alignptr (T *const ptr, const uintptr_t align)
double	asinh (const double v)
double	besselI0 (const double x)
double	calcFIRFilterGroupDelay (const double *const flt, const int fltlen, const double th)
void	calcFIRFilterResponse (const double *flt, int fltlen, const double th, double &re0, double &im0, const int fltlat=0)
void	calcMinPhaseTransform (double *const Kernel, const int KernelLen, const int LenMult=2, const bool DoFinalMul=true, double *const DCGroupDelay=NULL)
void	calcSpline2p8Coeffs (double *const c, const double xm3, const double xm2, const double xm1, const double x0, const double x1, const double x2, const double x3, const double x4)
void	calcSpline3p4Coeffs (double *const c, const double *const y)
void	calcSpline3p6Coeffs (double *const c, const double *const y)
void	calcSpline3p8Coeffs (double *const c, const double xm3, const double xm2, const double xm1, const double x0, const double x1, const double x2, const double x3, const double x4)
double	clampr (const double Value, const double minv, const double maxv)
double	convertResponseToLog (const double re, const double im)
void	findFIRFilterResponseLevelRtoL (const double *const flt, const int fltlen, const double maxg, double &th, const double thend)
void	findFIRFilterResponseMaxLtoR (const double *const flt, const int fltlen, double &maxg, double &maxth, const double thend)
void	findFIRFilterResponseMinLtoR (const double *const flt, const int fltlen, double &ming, double &minth, const double thend)
bool	findGCD (double l, double s, double &GCD)
double	gauss (const double v)
int	getBitOccupancy (const int v)
bool	getWholeStepping (const double SSampleRate, const double DSampleRate, int &ResInStep, int &ResOutStep)
template<typename T >
T	max (const T &v1, const T &v2)
template<typename T >
T	min (const T &v1, const T &v2)
void	normalizeFIRFilter (double *const p, const int l, const double DCGain, const int pstep=1)
double	pow_a (const double v, const double p)
double	sqr (const double x)
void	updateScanStep (double &step, const double curg, double &prevg_log, const double prec, const double maxstep, const double minstep=1e-11)

Detailed Description

The "r8brain-free-src" library namespace.

The "r8brain-free-src" sample rate converter library namespace.

Enumeration Type Documentation

EDSPFilterPhaseResponse

enum r8b::EDSPFilterPhaseResponse

Enumeration of filter's phase responses.

Enumerator
fprLinearPhase	Linear-phase response. Features a linear-phase, high-latency response, with the latency expressed as an integer value.
fprMinPhase	Minimum-phase response. Features a minimal-latency response, but the response's phase is non-linear. The latency is usually expressed as a non-integer value, and is usually small, but is never equal to zero. The minimum-phase filter is obtained from a linear-phase filter. Note that since in the context of r8brain-free-src other filters (interpolation, half-band) remain linear-phase, the resulting phase will be "intermediate". The minimum-phase transformation has precision limits: this may skew both the -3 dB point and attenuation of the filter being transformed: as it was measured, the skew happens purely at random, and in most cases is within tolerable range. In a small (1%) random subset of cases the skew is bigger and cannot be predicted. Minimum-phase transform requires 64-bit floating-point FFT; results with 32-bit float FFT are far from optimal.

Function Documentation

alignptr()

template<typename T >

T * r8b::alignptr	(	T *const	ptr,
		const uintptr_t	align
	)

This function forces the provided "ptr" pointer to be aligned to "align" bytes. Works with power-of-2 alignments only.

Parameters

ptr	Pointer to align.
align	Alignment, in bytes, power-of-2.

Template Parameters

T	Pointer's element type.

Returns

Aligned pointer.

asinh()

double r8b::asinh

(

const double

v

)

Parameters

v	Input value.

Returns

Calculated inverse hyperbolic sine of the input value.

besselI0()

double r8b::besselI0

(

const double

x

)

Parameters

x	Input value.

Returns

Calculated zero-th order modified Bessel function of the first kind of the input value. Approximate value. Coefficients by Abramowitz and Stegun.

calcFIRFilterGroupDelay()

double r8b::calcFIRFilterGroupDelay	(	const double *const	flt,
		const int	fltlen,
		const double	th
	)

Function calculates group delay of the specified FIR filter at the specified circular frequency. The group delay is calculated by evaluating the filter's response at close side-band frequencies of "th".

Parameters

flt	FIR filter's coefficients.
fltlen	Number of coefficients (taps) in the filter.
th	Circular frequency [0; pi].

Returns

Resulting group delay at the specified frequency, in samples.

calcFIRFilterResponse()

void r8b::calcFIRFilterResponse	(	const double *	flt,
		int	fltlen,
		const double	th,
		double &	re0,
		double &	im0,
		const int	fltlat = 0
	)

Function calculates frequency response of the specified FIR filter at the specified circular frequency. Phase can be calculated as atan2( im, re ).

Parameters

	flt	FIR filter's coefficients.
	fltlen	Number of coefficients (taps) in the filter.
	th	Circular frequency [0; pi].
[out]	re0	Resulting real part of the complex frequency response.
[out]	im0	Resulting imaginary part of the complex frequency response.
	fltlat	Filter's latency, in samples.

calcMinPhaseTransform()

void r8b::calcMinPhaseTransform	(	double *const	Kernel,
		const int	KernelLen,
		const int	LenMult = 2,
		const bool	DoFinalMul = true,
		double *const	DCGroupDelay = NULL
	)

Function calculates the minimum-phase transform of the filter kernel, using a discrete Hilbert transform in cepstrum domain.

For more details, see part III.B of http://www.hpl.hp.com/personal/Niranjan_Damera-Venkata/files/ComplexMinPhase.pdf

Parameters

[in,out]	Kernel	Filter kernel buffer.
	KernelLen	Filter kernel's length, in samples.
	LenMult	Kernel length multiplier. Used as a coefficient of oversampling in the frequency domain. Such oversampling is needed to improve the precision of the minimum-phase transform. If the filter's attenuation is high, this multiplier should be increased or otherwise the required attenuation will not be reached due to "smoothing" effect of this transform.
	DoFinalMul	"True" if the final multiplication after transform should be performed. Such multiplication returns the gain of the signal to its original value. This parameter can be set to "false" if normalization of the resulting filter kernel is planned to be used.
[out]	DCGroupDelay	If not NULL, this variable receives group delay at DC offset, in samples (can be a non-integer value).

calcSpline2p8Coeffs()

void r8b::calcSpline2p8Coeffs	(	double *const	c,
		const double	xm3,
		const double	xm2,
		const double	xm1,
		const double	x0,
		const double	x1,
		const double	x2,
		const double	x3,
		const double	x4
	)

Function calculates coefficients used to calculate 2rd order spline (polynomial) on the equidistant lattice, using 8 points. This function is based on the calcSpline3p8Coeffs() function, but without the 3rd order coefficient.

Parameters

[out]	c	Output coefficients buffer, length = 3.
	xm3	Point at x-3 position.
	xm2	Point at x-2 position.
	xm1	Point at x-1 position.
	x0	Point at x position.
	x1	Point at x+1 position.
	x2	Point at x+2 position.
	x3	Point at x+3 position.
	x4	Point at x+4 position.

calcSpline3p4Coeffs()

void r8b::calcSpline3p4Coeffs	(	double *const	c,
		const double *const	y
	)

Function calculates coefficients used to calculate 3rd order segment interpolation polynomial on the equidistant lattice, using 4 points.

Parameters

[out]	c	Output coefficients buffer, length = 4.
[in]	y	Equidistant point values. Value at offset 1 corresponds to x=0 point.

calcSpline3p6Coeffs()

void r8b::calcSpline3p6Coeffs	(	double *const	c,
		const double *const	y
	)

Function calculates coefficients used to calculate 3rd order segment interpolation polynomial on the equidistant lattice, using 6 points.

Parameters

[out]	c	Output coefficients buffer, length = 4.
[in]	y	Equidistant point values. Value at offset 2 corresponds to x=0 point.

calcSpline3p8Coeffs()

void r8b::calcSpline3p8Coeffs	(	double *const	c,
		const double	xm3,
		const double	xm2,
		const double	xm1,
		const double	x0,
		const double	x1,
		const double	x2,
		const double	x3,
		const double	x4
	)

Function calculates coefficients used to calculate 3rd order spline (polynomial) on the equidistant lattice, using 8 points.

Parameters

[out]	c	Output coefficients buffer, length = 4.
	xm3	Point at x-3 position.
	xm2	Point at x-2 position.
	xm1	Point at x-1 position.
	x0	Point at x position.
	x1	Point at x+1 position.
	x2	Point at x+2 position.
	x3	Point at x+3 position.
	x4	Point at x+4 position.

clampr()

double r8b::clampr	(	const double	Value,
		const double	minv,
		const double	maxv
	)

Function "clamps" (clips) the specified value so that it is not lesser than "minv", and not greater than "maxv".

Parameters

Value	Value to clamp.
minv	Minimal allowed value.
maxv	Maximal allowed value.

Returns

"Clamped" value.

convertResponseToLog()

double r8b::convertResponseToLog	(	const double	re,
		const double	im
	)

Parameters

re	Real part of the frequency response.
im	Imaginary part of the frequency response.

Returns

A magnitude response value converted from the linear scale to the logarithmic scale.

findFIRFilterResponseLevelRtoL()

void r8b::findFIRFilterResponseLevelRtoL	(	const double *const	flt,
		const int	fltlen,
		const double	maxg,
		double &	th,
		const double	thend
	)

Function locates normalized frequency at which the specified maximum filter gain is reached. The scanning is performed from higher (right) to lower (left) frequencies, scanning stops when the required gain value was crossed. Function uses an extremely efficient binary search and thus expects that the magnitude response has the "main lobe" form produced by windowing, with a minimal pass-band ripple.

Parameters

	flt	Filter response.
	fltlen	Filter response's length in samples (taps).
	maxg	Maximal gain (squared).
[out]	th	The current normalized frequency. On function's return will point to the normalized frequency where "maxg" is reached.
	thend	The leftmost frequency to scan, inclusive.

findFIRFilterResponseMaxLtoR()

void r8b::findFIRFilterResponseMaxLtoR	(	const double *const	flt,
		const int	fltlen,
		double &	maxg,
		double &	maxth,
		const double	thend
	)

Function locates normalized frequency at which the maximal filter gain is reached. The scanning is performed from lower (left) to higher (right) frequencies, the whole range is scanned.

Note: this function may "stall" in very rare cases if the magnitude response happens to be "saw-tooth" like, requiring a very small stepping to be used. If this happens, it may take dozens of seconds to complete.

Parameters

	flt	Filter response.
	fltlen	Filter response's length in samples (taps).
[out]	maxg	The current maximal gain (squared). On function's return will contain the maximal gain value (squared).
[out]	maxth	The normalized frequency where the maximal gain is currently at. On function's return will point to the normalized frequency where the maximum was reached.
	thend	The ending frequency, inclusive.

findFIRFilterResponseMinLtoR()

void r8b::findFIRFilterResponseMinLtoR	(	const double *const	flt,
		const int	fltlen,
		double &	ming,
		double &	minth,
		const double	thend
	)

Function locates normalized frequency at which the minimum filter gain is reached. The scanning is performed from lower (left) to higher (right) frequencies, the whole range is scanned.

Function expects that the magnitude response is always reducing from lower to high frequencies, starting at "minth".

Parameters

	flt	Filter response.
	fltlen	Filter response's length in samples (taps).
[out]	ming	The current minimal gain (squared). On function's return will contain the minimal gain value found (squared).
[out]	minth	The normalized frequency where the minimal gain is currently at. On function's return will point to the normalized frequency where the new minimum was found.
	thend	The ending frequency, inclusive.

findGCD()

bool r8b::findGCD	(	double	l,
		double	s,
		double &	GCD
	)

Function interatively searches for a greatest common denominator (GCD) of 2 numbers.

Parameters

	l	Number 1.
	s	Number 2.
[out]	GCD	Resulting GCD.

Returns

"True" if the greatest common denominator of 2 numbers was found.

gauss()

double r8b::gauss

(

const double

v

)

Parameters

v	Input value.

Returns

Calculated single-argument Gaussian function of the input value.

getBitOccupancy()

int r8b::getBitOccupancy

(

const int

v

)

Parameters

v	Input value.

Returns

Calculated bit occupancy of the specified input value. Bit occupancy means how many significant lower bits are necessary to store a specified value. Function treats the input value as unsigned.

getWholeStepping()

bool r8b::getWholeStepping	(	const double	SSampleRate,
		const double	DSampleRate,
		int &	ResInStep,
		int &	ResOutStep
	)

Function evaluates source and destination sample rate ratio and returns the required input and output stepping. Function returns "false" if whole stepping cannot be used to perform interpolation using these sample rates.

Parameters

	SSampleRate	Source sample rate.
	DSampleRate	Destination sample rate.
[out]	ResInStep	Resulting input step.
[out]	ResOutStep	Resulting output step.

Returns

"True" if stepping was acquired.

max()

template<typename T >

T r8b::max	(	const T &	v1,
		const T &	v2
	)

Parameters

v1	Value 1.
v2	Value 2.

Template Parameters

T	Values' type.

Returns

The maximum of 2 values.

min()

template<typename T >

T r8b::min	(	const T &	v1,
		const T &	v2
	)

Parameters

v1	Value 1.
v2	Value 2.

Template Parameters

T	Values' type.

Returns

The minimum of 2 values.

normalizeFIRFilter()

void r8b::normalizeFIRFilter	(	double *const	p,
		const int	l,
		const double	DCGain,
		const int	pstep = 1
	)

Function normalizes FIR filter so that its frequency response at DC is equal to DCGain.

Parameters

[in,out]	p	Filter coefficients.
	l	Filter length.
	DCGain	Filter's gain at DC (linear, non-decibel value).
	pstep	"p" array step.

pow_a()

double r8b::pow_a	(	const double	v,
		const double	p
	)

Parameters

v	Input value.
p	Power factor.

Returns

Returns a precise, but generally approximate pow() function's value of absolute of input value.

sqr()

double r8b::sqr

(

const double

x

)

Parameters

x	Value to square.

Returns

Squared value of the argument.

updateScanStep()

void r8b::updateScanStep	(	double &	step,
		const double	curg,
		double &	prevg_log,
		const double	prec,
		const double	maxstep,
		const double	minstep = 1e-11
	)

An utility function that performs frequency response scanning step update based on the current magnitude response's slope.

Parameters

[in,out]	step	The current scanning step. Will be updated on function's return. Must be a positive value.
	curg	Squared magnitude response at the current frequency point.
[in,out]	prevg_log	Previous magnitude response, log scale. Will be updated on function's return.
	prec	Precision multiplier, affects the size of the step.
	maxstep	The maximal allowed step.
	minstep	The minimal allowed step.