A processor that performs multi-channel oversampling. More...

#include <juce_Oversampling.h>

Collaboration diagram for juce::dsp::Oversampling< SampleType >:

[legend]

Public Types
enum	FilterType { filterHalfBandFIREquiripple = 0, filterHalfBandPolyphaseIIR, numFilterTypes }
	The type of filter that can be used for the oversampling processing. More...

Public Member Functions
	Oversampling (size_t numChannels, size_t factor, FilterType type, bool isMaxQuality=true, bool useIntegerLatency=false)
	Constructor. More...

	Oversampling (size_t numChannels=1)
	The default constructor. More...

	~Oversampling ()
	Destructor. More...

void	addDummyOversamplingStage ()
	Adds a new "dummy" oversampling stage, which does nothing to the signal. More...

void	addOversamplingStage (FilterType, float normalisedTransitionWidthUp, float stopbandAmplitudedBUp, float normalisedTransitionWidthDown, float stopbandAmplitudedBDown)
	Adds a new oversampling stage to the Oversampling class, multiplying the current oversampling factor by two. More...

void	clearOversamplingStages ()
	Removes all the previously registered oversampling stages, so you can add your own from scratch. More...

SampleType	getLatencyInSamples () const noexcept
	Returns the latency in samples of the overall processing. More...

size_t	getOversamplingFactor () const noexcept
	Returns the current oversampling factor. More...

void	initProcessing (size_t maximumNumberOfSamplesBeforeOversampling)
	Must be called before any processing, to set the buffer sizes of the internal buffers of the oversampling processing. More...

void	processSamplesDown (AudioBlock< SampleType > &outputBlock) noexcept
	Must be called to perform the downsampling, after the upsampling and the non-linear processing. More...

AudioBlock< SampleType >	processSamplesUp (const AudioBlock< const SampleType > &inputBlock) noexcept
	Must be called to perform the upsampling, prior to any oversampled processing. More...

void	reset () noexcept
	Resets the processing pipeline, ready to oversample a new stream of data. More...

void	setUsingIntegerLatency (bool shouldUseIntegerLatency) noexcept

Public Attributes
size_t	factorOversampling = 1

size_t	numChannels = 1

Private Member Functions
SampleType	getUncompensatedLatency () const noexcept

void	updateDelayLine ()

Private Attributes
DelayLine< SampleType, DelayLineInterpolationTypes::Thiran >	delay { 8 }

SampleType	fractionalDelay = 0

bool	isReady = false

bool	shouldUseIntegerLatency = false

OwnedArray< OversamplingStage >	stages

Detailed Description

template<typename SampleType>
class juce::dsp::Oversampling< SampleType >

A processor that performs multi-channel oversampling.

This class can be configured to do a factor of 2, 4, 8 or 16 times oversampling, using multiple stages, with polyphase allpass IIR filters or FIR filters, and latency compensation.

The principle of oversampling is to increase the sample rate of a given non-linear process to prevent it from creating aliasing. Oversampling works by upsampling the input signal N times, processing the upsampled signal with the increased internal sample rate, then downsampling the result to get back to the original sample rate.

Choose between FIR or IIR filtering depending on your needs in terms of latency and phase distortion. With FIR filters the phase is linear but the latency is maximised. With IIR filtering the phase is compromised around the Nyquist frequency but the latency is minimised.

See also: FilterDesign.

@tags{DSP}

Member Enumeration Documentation

◆ FilterType

template<typename SampleType >

enum juce::dsp::Oversampling::FilterType

The type of filter that can be used for the oversampling processing.

Enumerator
filterHalfBandFIREquiripple
filterHalfBandPolyphaseIIR
numFilterTypes

Constructor & Destructor Documentation

◆ Oversampling() [1/2]

template<typename SampleType >

juce::dsp::Oversampling< SampleType >::Oversampling ( size_t numChannels = 1 )

explicit

The default constructor.

Note: This creates a "dummy" oversampling stage, which needs to be removed before adding proper oversampling stages.

Parameters

numChannels the number of channels to process with this object

See also: clearOversamplingStages, addOversamplingStage

◆ Oversampling() [2/2]

template<typename SampleType >

juce::dsp::Oversampling< SampleType >::Oversampling	(	size_t	numChannels,
		size_t	factor,
		FilterType	type,
		bool	isMaxQuality = `true`,
		bool	useIntegerLatency = `false`
	)

Constructor.

Parameters

numChannels	the number of channels to process with this object
factor	the processing will perform 2 ^ factor times oversampling
type	the type of filter design employed for filtering during oversampling
isMaxQuality	if the oversampling is done using the maximum quality, where the filters will be more efficient but the CPU load will increase as well
useIntegerLatency	if true this processor will add some fractional delay at the end of the signal path to ensure that the overall latency of the oversampling is an integer

◆ ~Oversampling()

template<typename SampleType >

juce::dsp::Oversampling< SampleType >::~Oversampling ( )

Destructor.

Member Function Documentation

◆ addDummyOversamplingStage()

template<typename SampleType >

void juce::dsp::Oversampling< SampleType >::addDummyOversamplingStage ( )

Adds a new "dummy" oversampling stage, which does nothing to the signal.

Using one can be useful if your application features a customisable oversampling factor and if you want to select the current one from an OwnedArray without changing anything in the processing code.

See also: OwnedArray, clearOversamplingStages, addOversamplingStage

◆ addOversamplingStage()

template<typename SampleType >

void juce::dsp::Oversampling< SampleType >::addOversamplingStage	(	FilterType	,
		float	normalisedTransitionWidthUp,
		float	stopbandAmplitudedBUp,
		float	normalisedTransitionWidthDown,
		float	stopbandAmplitudedBDown
	)

Adds a new oversampling stage to the Oversampling class, multiplying the current oversampling factor by two.

This is used with the default constructor to create custom oversampling chains, requiring a call to the clearOversamplingStages before any addition.

Note: Upsampling and downsampling filtering have different purposes, the former removes upsampling artefacts while the latter removes useless frequency content created by the oversampled process, so usually the attenuation is increased when upsampling compared to downsampling.

Parameters

normalisedTransitionWidthUp	a value between 0 and 0.5 which specifies how much the transition between passband and stopband is steep, for upsampling filtering (the lower the better)
stopbandAmplitudedBUp	the amplitude in dB in the stopband for upsampling filtering, must be negative
normalisedTransitionWidthDown	a value between 0 and 0.5 which specifies how much the transition between passband and stopband is steep, for downsampling filtering (the lower the better)
stopbandAmplitudedBDown	the amplitude in dB in the stopband for downsampling filtering, must be negative

See also: clearOversamplingStages

◆ clearOversamplingStages()

template<typename SampleType >

void juce::dsp::Oversampling< SampleType >::clearOversamplingStages ( )

Removes all the previously registered oversampling stages, so you can add your own from scratch.

See also: addOversamplingStage, addDummyOversamplingStage

◆ getLatencyInSamples()

template<typename SampleType >

SampleType juce::dsp::Oversampling< SampleType >::getLatencyInSamples ( ) const

noexcept

Returns the latency in samples of the overall processing.

You can use this information in your main processor to compensate the additional latency involved with the oversampling, for example with a dry / wet mixer, and to report the latency to the DAW.

Note: If you have not opted to use an integer latency then the latency may not be integer, so you might need to round its value or to compensate it properly in your processing code since plug-ins can only report integer latency values in samples to the DAW.

◆ getOversamplingFactor()

template<typename SampleType >

size_t juce::dsp::Oversampling< SampleType >::getOversamplingFactor ( ) const

noexcept

Returns the current oversampling factor.

◆ getUncompensatedLatency()

template<typename SampleType >

SampleType juce::dsp::Oversampling< SampleType >::getUncompensatedLatency ( ) const

privatenoexcept

◆ initProcessing()

template<typename SampleType >

void juce::dsp::Oversampling< SampleType >::initProcessing ( size_t maximumNumberOfSamplesBeforeOversampling )

Must be called before any processing, to set the buffer sizes of the internal buffers of the oversampling processing.

◆ processSamplesDown()

template<typename SampleType >

void juce::dsp::Oversampling< SampleType >::processSamplesDown ( AudioBlock< SampleType > & outputBlock )

noexcept

Must be called to perform the downsampling, after the upsampling and the non-linear processing.

The output signal is probably delayed by the internal latency of the whole oversampling behaviour, so don't forget to take this into account.

◆ processSamplesUp()

template<typename SampleType >

AudioBlock<SampleType> juce::dsp::Oversampling< SampleType >::processSamplesUp ( const AudioBlock< const SampleType > & inputBlock )

noexcept

Must be called to perform the upsampling, prior to any oversampled processing.

Returns an AudioBlock referencing the oversampled input signal, which must be used to perform the non-linear processing which needs the higher sample rate. Don't forget to set the sample rate of that processing to N times the original sample rate.

◆ reset()

template<typename SampleType >

void juce::dsp::Oversampling< SampleType >::reset ( )

noexcept

Resets the processing pipeline, ready to oversample a new stream of data.

◆ setUsingIntegerLatency()

template<typename SampleType >

void juce::dsp::Oversampling< SampleType >::setUsingIntegerLatency ( bool shouldUseIntegerLatency )

noexcept

◆ updateDelayLine()

template<typename SampleType >

void juce::dsp::Oversampling< SampleType >::updateDelayLine ( )

private

Member Data Documentation

◆ delay

template<typename SampleType >

DelayLine<SampleType, DelayLineInterpolationTypes::Thiran> juce::dsp::Oversampling< SampleType >::delay { 8 }

private

◆ factorOversampling

template<typename SampleType >

size_t juce::dsp::Oversampling< SampleType >::factorOversampling = 1

◆ fractionalDelay

template<typename SampleType >

SampleType juce::dsp::Oversampling< SampleType >::fractionalDelay = 0

private

◆ isReady

template<typename SampleType >

bool juce::dsp::Oversampling< SampleType >::isReady = false

private

◆ numChannels

template<typename SampleType >

size_t juce::dsp::Oversampling< SampleType >::numChannels = 1

◆ shouldUseIntegerLatency

template<typename SampleType >

bool juce::dsp::Oversampling< SampleType >::shouldUseIntegerLatency = false

private

◆ stages

template<typename SampleType >

OwnedArray<OversamplingStage> juce::dsp::Oversampling< SampleType >::stages

private

The documentation for this class was generated from the following file:

juce_Oversampling.h

Public Types

Public Member Functions

Public Attributes

Private Member Functions

Private Attributes

Detailed Description

template<typename SampleType> class juce::dsp::Oversampling< SampleType >

Member Enumeration Documentation

◆ FilterType

Constructor & Destructor Documentation

◆ Oversampling() [1/2]

◆ Oversampling() [2/2]

◆ ~Oversampling()

Member Function Documentation

◆ addDummyOversamplingStage()

◆ addOversamplingStage()

◆ clearOversamplingStages()

◆ getLatencyInSamples()

◆ getOversamplingFactor()

◆ getUncompensatedLatency()

◆ initProcessing()

◆ processSamplesDown()

◆ processSamplesUp()

◆ reset()

◆ setUsingIntegerLatency()

◆ updateDelayLine()

Member Data Documentation

◆ delay

◆ factorOversampling

◆ fractionalDelay

◆ isReady

◆ numChannels

◆ shouldUseIntegerLatency

◆ stages

template<typename SampleType>
class juce::dsp::Oversampling< SampleType >