sfFDN::ControllableFullWaveRectifier Class Reference

A controllable full-wave rectifier, with optional antiderivative antialiasing. More...

#include <nonlinear.h>

Inheritance diagram for sfFDN::ControllableFullWaveRectifier:

Collaboration diagram for sfFDN::ControllableFullWaveRectifier:

Public Member Functions
	ControllableFullWaveRectifier (const ControllableFullWaveRectifierOptions &options={})
	Constructs a controllable full-wave rectifier.
	ControllableFullWaveRectifier (const ControllableFullWaveRectifier &other)
ControllableFullWaveRectifier &	operator= (const ControllableFullWaveRectifier &other)
	ControllableFullWaveRectifier (ControllableFullWaveRectifier &&) noexcept
ControllableFullWaveRectifier &	operator= (ControllableFullWaveRectifier &&) noexcept
void	SetAlpha (float alpha)
	Sets the distortion amount.
float	GetAlpha () const noexcept SFFDN_NONBLOCKING
	Returns the distortion amount.
float	GetCompensationGain () const noexcept SFFDN_NONBLOCKING
	Returns the power compensation gain \(g_\mathrm{cfwr}\) of the current distortion amount.
float	Tick (float input) noexcept SFFDN_NONBLOCKING
	Processes a single sample.
void	Process (const AudioBuffer &input, AudioBuffer &output) noexcept SFFDN_NONBLOCKING override
	Processes the audio buffer.
uint32_t	InputChannelCount () const noexcept SFFDN_NONBLOCKING override
	Returns the number of input channels this processor expects.
uint32_t	OutputChannelCount () const noexcept SFFDN_NONBLOCKING override
	Returns the number of output channels this processor produces.
void	Clear () override
	Clears the antialiasing state and the dc blocker.
std::unique_ptr< AudioProcessor >	Clone () const override
	Creates a copy of the processor.
Public Member Functions inherited from sfFDN::AudioProcessor

Static Public Attributes
static constexpr float	kAntialiasingEpsilon = 1e-5f
	Threshold below which the denominator of the antialiasing approximation is considered ill-conditioned.

Additional Inherited Members
Protected Member Functions inherited from sfFDN::AudioProcessor
	AudioProcessor (const AudioProcessor &)=default
AudioProcessor &	operator= (const AudioProcessor &)=default
	AudioProcessor (AudioProcessor &&) noexcept=default
AudioProcessor &	operator= (AudioProcessor &&) noexcept=default

Detailed Description

A controllable full-wave rectifier, with optional antiderivative antialiasing.

Implements equation (3) of the paper:

\[ y(n) = g_\mathrm{cfwr} \left( (1 - \alpha) x(n) + \alpha \left| x(n) \right| \right), \qquad g_\mathrm{cfwr} = \sqrt{2 - 2 \left| \alpha - 1/2 \right|}. \]

The parameter \(\alpha\) blends between the untouched input and a full-wave rectifier, and \(g_\mathrm{cfwr}\) compensates the power lost by folding the negative half of the waveform. It is 1 at \(\alpha = 0\) and \(\alpha = 1\), where the operation is exactly energy preserving, and peaks at \(\sqrt{2}\) at \(\alpha = 0.5\), where the rectifier is a half-wave rectifier.

A rectifier generates every even harmonic of its input, so it aliases badly. Equation (4) of the paper replaces the rectifier with its first-order antiderivative antialiasing approximation

\[ \left| x(n) \right| \approx \frac{1}{2} \frac{x(n) \left| x(n) \right| - x(n-1) \left| x(n-1) \right|}{x(n) - x(n-1)}, \]

which attenuates the aliased components that fall between the harmonics. The quotient is ill-conditioned when the two consecutive samples are nearly equal, so it falls back to \(\left| x(n) + x(n-1) \right| / 2\) there.

Note

The rectifier produces a dc component. Inside a feedback loop that component accumulates until the network clips, so the processor follows itself with a dc blocker and a slow make-up gain by default. Only turn ControllableFullWaveRectifierOptions::dc_block off when the processor is used as an insert effect.

The peak gain of the operation is ControllableFullWaveRectifierOptions::alpha-dependent and reaches \(\sqrt{2}\) (+3 dB) at alpha = 0.5. The make-up gain of the dc blocker is capped, but it can still add up to +12 dB on top of that on near-silent input. Budget for both in the attenuation filters of the enclosing network.

Constructor & Destructor Documentation

ControllableFullWaveRectifier()

sfFDN::ControllableFullWaveRectifier::ControllableFullWaveRectifier ( const ControllableFullWaveRectifierOptions & options = {} )

explicit

Constructs a controllable full-wave rectifier.

Parameters

options

The configuration options.

Exceptions

std::invalid_argument

if alpha is not in [0, 1], or if dc_block is true and sample_rate is not strictly positive.

Member Function Documentation

Clear()

void sfFDN::ControllableFullWaveRectifier::Clear ( )

overridevirtual

Clears the antialiasing state and the dc blocker.

The distortion amount is left untouched.

Implements sfFDN::AudioProcessor.

Clone()

std::unique_ptr< AudioProcessor > sfFDN::ControllableFullWaveRectifier::Clone ( ) const

overridevirtual

Creates a copy of the processor.

The antialiasing and dc blocker state are carried over.

Implements sfFDN::AudioProcessor.

InputChannelCount()

uint32_t sfFDN::ControllableFullWaveRectifier::InputChannelCount ( ) const

overridevirtualnoexcept

Returns the number of input channels this processor expects.

This is always 1.

Implements sfFDN::AudioProcessor.

OutputChannelCount()

uint32_t sfFDN::ControllableFullWaveRectifier::OutputChannelCount ( ) const

overridevirtualnoexcept

Returns the number of output channels this processor produces.

This is always 1.

Implements sfFDN::AudioProcessor.

Process()

void sfFDN::ControllableFullWaveRectifier::Process ( const AudioBuffer & input, AudioBuffer & output )

overridevirtualnoexcept

Processes the audio buffer.

Note

The input and output buffers must have one channel and the same number of samples.

Implements sfFDN::AudioProcessor.

SetAlpha()

void sfFDN::ControllableFullWaveRectifier::SetAlpha

(

float

alpha

)

Sets the distortion amount.

Parameters

alpha

The distortion amount, in [0, 1].

Exceptions

std::invalid_argument

if alpha is not in [0, 1].

Note

This also updates the compensation gain \(g_\mathrm{cfwr}\).

Member Data Documentation

kAntialiasingEpsilon

float sfFDN::ControllableFullWaveRectifier::kAntialiasingEpsilon = 1e-5f

staticconstexpr

Threshold below which the denominator of the antialiasing approximation is considered ill-conditioned.

The reference implementation of the paper uses 1e-8 in double precision. sfFDN processes float32, where the numerator x(n)|x(n)| - x(n-1)|x(n-1)| is a difference of two nearly equal quantities and has already lost most of its significant digits by the time the denominator is that small. The threshold is therefore raised to a value that float32 can actually resolve. See .github/notes/shimmer-nonlinearities.md.

---

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

• include/sffdn/nonlinear.h