r8b::CDSPResampler Class Reference

The master sample rate converter (resampler) class. More...

#include <CDSPResampler.h>

Inheritance diagram for r8b::CDSPResampler:

Public Member Functions
	CDSPResampler (const double SrcSampleRate, const double DstSampleRate, const int aMaxInLen, const double ReqTransBand=2.0, const double ReqAtten=206.91, const EDSPFilterPhaseResponse ReqPhase=fprLinearPhase)
virtual void	clear ()
virtual int	getInLenBeforeOutPos (const int ReqOutPos) const
int	getInLenBeforeOutStart (const int ReqOutPos=0)
int	getInputRequiredForOutput (const int ReqOutSamples) const
virtual int	getLatency () const
virtual double	getLatencyFrac () const
virtual int	getMaxOutLen (const int) const
template<typename Tin , typename Tout >
void	oneshot (const Tin *ip, int iplen, Tout *op, int oplen)
virtual int	process (double *ip0, int l, double *&op0)
virtual void	clear ()=0
virtual int	getInLenBeforeOutPos (const int ReqOutPos) const =0
virtual int	getLatency () const =0
virtual double	getLatencyFrac () const =0
virtual int	getMaxOutLen (const int MaxInLen) const =0
virtual int	process (double *ip, int l0, double *&op0)=0

Detailed Description

The master sample rate converter (resampler) class.

This class can be considered the "master" sample rate converter (resampler) class since it combines all functionality of this library into a single front-end class that performs sample rate conversion to/from any sample rate, including non-integer sample rates.

Note that objects of this class can be constructed on the stack as it has a small member data size. The default template parameters of this class are suited for 27-bit fixed point resampling.

Use the CDSPResampler16 class for 16-bit resampling.

Use the CDSPResampler16IR class for 16-bit impulse response resampling.

Use the CDSPResampler24 class for 24-bit resampling (including 32-bit floating point resampling).

Constructor & Destructor Documentation

CDSPResampler()

r8b::CDSPResampler::CDSPResampler	(	const double	SrcSampleRate,
		const double	DstSampleRate,
		const int	aMaxInLen,
		const double	ReqTransBand = 2.0,
		const double	ReqAtten = 206.91,
		const EDSPFilterPhaseResponse	ReqPhase = fprLinearPhase
	)

Constructor initalizes the resampler object.

Note that increasing the transition band and decreasing attenuation reduces the filter length, this in turn reduces the "input before output" delay. However, the filter length has only a minor influence on the overall resampling speed.

It should be noted that the ReqAtten specifies the minimal difference between the loudest input signal component and the produced aliasing artifacts during resampling. For example, if ReqAtten=100 was specified when performing 2x upsampling, the analysis of the resulting signal may display high-frequency components which are quieter than the loudest part of the input signal by only 100 decibel meaning the high-frequency part did not become "magically" completely silent after resampling. You have to specify a higher ReqAtten value if you need a totally clean high-frequency content. On the other hand, it may not be reasonable to have a high-frequency content cleaner than the input signal itself: if the input signal is 16-bit, setting ReqAtten to 180 will make its high-frequency content 24-bit, but the original part of the signal will remain 16-bit.

Parameters

SrcSampleRate	Source signal's sample rate. Both sample rates can be specified as a ratio, e.g. SrcSampleRate = 1.0, DstSampleRate = 2.0.
DstSampleRate	Destination signal's sample rate. The "power of 2" ratios between the source and destination sample rates force resampler to use several fast "power of 2" resampling steps, without using fractional interpolation at all.
aMaxInLen	The maximal planned length of the input buffer (in samples) that will be passed to the resampler. The resampler relies on this value as it allocates intermediate buffers. Input buffers longer than this value should never be supplied to the resampler. Note that upsampling produces more samples than was provided on input, so at higher upsampling ratios it is advisable to use smaller MaxInLen values to reduce memory footprint. When downsampling, a larger MaxInLen is suggested in order to increase downsampling performance.
ReqTransBand	Required transition band, in percent of the spectral space of the input signal (or the output signal if downsampling is performed) between filter's -3 dB point and the Nyquist frequency. The range is from CDSPFIRFilter::getLPMinTransBand() to CDSPFIRFilter::getLPMaxTransBand(), inclusive. When upsampling 88200 or 96000 audio to higher sample rates the ReqTransBand can be considerably increased, up to 30. The selection of ReqTransBand depends on the level of desire to preserve the high-frequency content. While values 0.5 to 2 are extremely "greedy" settings, not necessary in most cases, values 2 to 3 can be used in most cases. Values 3 to 4 are relaxed settings, but they still offer a flat frequency response up to 21kHz with 44.1k source or destination sample rate.
ReqAtten	Required stop-band attenuation in decibel, in the range CDSPFIRFilter::getLPMinAtten() to CDSPFIRFilter::getLPMaxAtten(), inclusive. The actual attenuation may be 0.40-4.46 dB higher. The general formula for selecting the ReqAtten is 6.02 * Bits + 40, where "Bits" is the bit resolution (e.g. 16, 24), "40" is an added resolution for dynamic signals; this value can be decreased to 20 to 10 if the signal being resampled is non-dynamic (e.g., an impulse response or filter, with a non-steep frequency response).
ReqPhase	Required filter's phase response. Note that this setting does not affect interpolator's phase response which is always linear-phase. Also note that if the "power of 2" resampling was engaged by the resampler together with the minimum-phase response, the audio stream may become fractionally delayed, depending on the minimum-phase filter's actual fractional delay. Linear-phase filters do not have fractional delay.

See also

EDSPFilterPhaseResponse

Member Function Documentation

clear()

virtual void r8b::CDSPResampler::clear ( )

virtual

Function clears (resets) the state of *this object and returns it to the state after construction. All input data accumulated in the internal buffer so far will be discarded.

This function makes it possible to use *this object for converting separate streams from the same source sample rate to the same destination sample rate without reconstructing the object. It is more efficient to clear the state of the resampler object than to destroy it and create a new object.

Implements r8b::CDSPProcessor.

getInLenBeforeOutPos()

virtual int r8b::CDSPResampler::getInLenBeforeOutPos ( const int  ReqOutPos ) const

virtual

Function returns the number of input samples required to advance to the specified output sample position (so that the next process() call passes this output position), starting at the cleared or after-construction state of *this object.

Note that the implementation of this function assumes the caller only needs to estimate an initial buffering requirement; passing a full sample length value (e.g., greater than 100000) may overflow the calculation or cause rounding errors.

Parameters

ReqOutPos

The required output position. Set to 0 to obtain "input length before output start" latency. Must be a non-negative value.

Returns

The number of input samples required.

Implements r8b::CDSPProcessor.

getInLenBeforeOutStart()

int r8b::CDSPResampler::getInLenBeforeOutStart

(

const int

ReqOutPos = 0

)

Function returns the number of input samples required to advance to the specified output sample position (so that the next process() call passes this output position), starting at the cleared or after-construction state of *this object.

This function works by iteratively passing 1 sample at a time until the overall output length passes the specified value. This is a relatively CPU-consuming operation. This function should be called after the clear() function call or after object's construction. The function itself calls the clear() function before return.

Note that this function can be considered a legacy function, and is now used for testing purposes. It is advised to use "instant" (much faster) getInLenBeforeOutPos() and getInputRequiredForOutput() functions instead.

Parameters

ReqOutPos

The required output position. Must be a non-negative value.

Returns

The number of input samples required.

getInputRequiredForOutput()

int r8b::CDSPResampler::getInputRequiredForOutput

(

const int

ReqOutSamples

)

const

Function returns the number of input samples required to produce at least the specified number of output samples, starting at the cleared or after-construction state of *this object.

Parameters

ReqOutSamples

The number of output samples required. If a non-positive value was specified, the function returns 0.

Returns

The number of input samples required.

getLatency()

virtual int r8b::CDSPResampler::getLatency ( ) const

virtual

Returns

The latency, in samples, which is present in the output signal. This value is usually zero if the DSP processor "consumes" the latency automatically.

Implements r8b::CDSPProcessor.

getLatencyFrac()

virtual double r8b::CDSPResampler::getLatencyFrac ( ) const

virtual

Returns

Fractional latency, in samples, which is present in the output signal. This value is usually zero if a linear-phase filtering is used. With minimum-phase filters in use, this value can be non-zero even if the getLatency() function returns zero.

Implements r8b::CDSPProcessor.

getMaxOutLen()

virtual int r8b::CDSPResampler::getMaxOutLen ( const int  ) const

virtual

Returns

This function ignores the supplied parameter and returns the maximal output buffer length that depends on the MaxInLen supplied to the constructor.

Implements r8b::CDSPProcessor.

oneshot()

template<typename Tin , typename Tout >

void r8b::CDSPResampler::oneshot	(	const Tin *	ip,
		int	iplen,
		Tout *	op,
		int	oplen
	)

Function performs resampling of an input sample buffer of the specified length in the "one-shot" mode. This function can be useful when impulse response or time-series resampling is required.

Parameters

	ip	Input buffer pointer.
	iplen	Length of the input buffer in samples.
[out]	op	Output buffer pointer.
	oplen	Length of the output buffer in samples.

Template Parameters

Tin	Input buffer's element type.
Tout	Output buffer's element type.

process()

virtual int r8b::CDSPResampler::process ( double *  ip0, int  l, double *&  op0  )

virtual

Function performs sample rate conversion.

If the source and destination sample rates are equal, the resampler will do nothing and will simply return the input buffer unchanged.

You do not need to allocate an intermediate output buffer for use with this function. If required, the resampler will allocate a suitable intermediate output buffer itself.

Parameters

	ip0	Input buffer. This buffer is never used as output buffer by this function. This pointer may be returned in "op0" if no resampling is happening (source sample rate equals destination sample rate).
	l	The number of samples available in the input buffer. Should not exceed the MaxInLen supplied in the constructor.
[out]	op0	This variable receives the pointer to the resampled data. On function's return, this pointer points to *this object's internal buffer. In real-time applications it is suggested to pass this pointer to the next output audio block and consume any data left from the previous output audio block first before calling the process() function again. The buffer pointed to by the "op0" on return is owned by the resampler, so it should not be freed by the caller.

Returns

The number of samples available in the "op0" output buffer. If the data from the output buffer "op0" is going to be written to a bigger output buffer, it is suggested to check the returned number of samples so that no overflow of the bigger output buffer happens.

Implements r8b::CDSPProcessor.