A Processor that applies various types of distortion to an audio signal. More...

#include <distortion.h>

Inheritance diagram for vital::Distortion:

Public Types
enum	{ kAudio , kType , kDrive , kNumInputs }

enum	{ kAudioOut , kDriveOut , kNumOutputs }

enum	Type { kSoftClip , kHardClip , kLinearFold , kSinFold , kBitCrush , kDownSample , kNumTypes }
	Distortion algorithms supported by this class. More...

Public Member Functions
	Distortion ()
	Constructs a Distortion object with the default number of inputs/outputs.

virtual	~Distortion ()
	Default destructor.

virtual Processor *	clone () const override
	Creates a clone of this Processor. (Not implemented for Distortion).

virtual void	process (int num_samples) override
	Processes a block of audio using the stored input buffer.

virtual void	processWithInput (const poly_float *audio_in, int num_samples) override
	Processes a block of audio using a provided input buffer.

template<poly_float()(poly_float, poly_float) distort, poly_float()(poly_float) scale>
void	processTimeInvariant (int num_samples, const poly_float audio_in, const poly_float drive, poly_float *audio_out)
	Processes samples with a time-invariant distortion function (no dynamic changes).

void	processDownSample (int num_samples, const poly_float audio_in, const poly_float drive, poly_float *audio_out)
	Processes samples using a downsampling approach for distortion.

Public Member Functions inherited from vital::Processor
	Processor (int num_inputs, int num_outputs, bool control_rate=false, int max_oversample=1)
	Constructs a Processor with a given number of inputs/outputs and oversampling.

virtual	~Processor ()
	Virtual destructor.

virtual bool	hasState () const
	Indicates whether this Processor requires per-voice state.

virtual void	init ()
	Called after constructor, used for any additional initialization. Subclasses can override. Sets the initialized flag.

virtual void	reset (poly_mask reset_mask)
	Called to reset the Processor's per-voice state (e.g., on note-on).

virtual void	hardReset ()
	Called to perform a "hard" reset for all voices.

bool	initialized ()
	Returns whether this Processor has been initialized.

virtual void	setSampleRate (int sample_rate)
	Updates the sample rate of this Processor (scaled by oversampling).

virtual void	setOversampleAmount (int oversample)
	Sets the oversampling amount and updates the effective sample rate.

force_inline bool	enabled () const
	Checks if this Processor is enabled.

virtual void	enable (bool enable)
	Enables or disables this Processor.

force_inline int	getSampleRate () const
	Retrieves the current (effective) sample rate.

force_inline int	getOversampleAmount () const
	Retrieves the current oversampling factor.

force_inline bool	isControlRate () const
	Checks if this Processor is running at control rate (buffer_size == 1).

virtual void	setControlRate (bool control_rate)
	Sets whether this Processor runs at control rate.

force_inline poly_mask	getResetMask (int input_index) const
	Retrieves a mask indicating which voices triggered a note-on event. Compares the input's trigger_value to kVoiceOn.

force_inline void	clearOutputBufferForReset (poly_mask reset_mask, int input_index, int output_index) const
	Clears output samples for voices that are about to be reset, based on the trigger offset.

bool	inputMatchesBufferSize (int input=0)
	Checks whether the buffer size of a particular input matches the size needed by this Processor.

bool	checkInputAndOutputSize (int num_samples)
	Checks if all inputs and outputs have buffers big enough for `num_samples`.

virtual bool	isPolyphonic () const
	Checks if this Processor is polyphonic by querying its ProcessorRouter.

void	plug (const Output *source)
	Connects an external Output to this Processor's first input.

void	plug (const Output *source, unsigned int input_index)
	Connects an external Output to a specified input index.

void	plug (const Processor *source)
	Connects the first output of a Processor to this Processor's first input.

void	plug (const Processor *source, unsigned int input_index)
	Connects the first output of a Processor to a specified input index.

void	plugNext (const Output *source)
	Connects an external Output to the first available (unplugged) input.

void	plugNext (const Processor *source)
	Connects the first output of a Processor to the first available (unplugged) input.

void	useInput (Input *input)
	Uses an existing Input object as this Processor's first input.

void	useInput (Input *input, int index)
	Uses an existing Input object at a specified input index.

void	useOutput (Output *output)
	Uses an existing Output object as this Processor's first output.

void	useOutput (Output *output, int index)
	Uses an existing Output object at a specified output index.

int	connectedInputs ()
	Counts how many inputs are connected to a real source (not null_source_).

virtual void	unplugIndex (unsigned int input_index)
	Removes the connection at a specified input index, if any.

virtual void	unplug (const Output *source)
	Removes a connection to a given Output from all inputs.

virtual void	unplug (const Processor *source)
	Removes connections to all outputs from a given Processor.

virtual void	numInputsChanged ()
	Called when the number of inputs changes (e.g., new connections). Subclasses may override for dynamic behavior.

force_inline void	router (ProcessorRouter *router)
	Sets the ProcessorRouter that owns or manages this Processor.

force_inline ProcessorRouter *	router () const
	Returns the ProcessorRouter that currently owns this Processor.

ProcessorRouter *	getTopLevelRouter () const
	Gets the topmost (root) ProcessorRouter by traversing parent routers.

virtual void	registerInput (Input *input, int index)
	Registers a new input, appending it to the input list.

virtual Output *	registerOutput (Output *output, int index)
	Registers a new Output in the output list at a specified index.

virtual void	registerInput (Input *input)
	Registers a new Input by appending it to the end of the input list.

virtual Output *	registerOutput (Output *output)
	Registers a new Output by appending it to the end of the output list.

force_inline int	numInputs () const
	Returns the total number of Input pointers (owned or otherwise).

force_inline int	numOutputs () const
	Returns the total number of Output pointers (owned or otherwise).

force_inline int	numOwnedInputs () const
	Returns how many Input objects this Processor owns.

force_inline int	numOwnedOutputs () const
	Returns how many Output objects this Processor owns.

force_inline Input *	input (unsigned int index=0) const
	Retrieves the Input pointer at a given index.

force_inline bool	isInputSourcePolyphonic (int index=0)
	Checks if the input source at a given index is polyphonic.

force_inline Input *	ownedInput (unsigned int index=0) const
	Retrieves an owned Input pointer at a given index.

force_inline Output *	output (unsigned int index=0) const
	Retrieves the Output pointer at a given index.

force_inline Output *	ownedOutput (unsigned int index=0) const
	Retrieves an owned Output pointer at a given index.

void	setPluggingStart (int start)
	Sets the position at which `plugNext` starts searching for an open input.

Static Public Member Functions
static force_inline poly_float	driveDbScale (poly_float db)
	Scales a drive (dB) value into a linear multiplier for standard distortions.

static force_inline poly_float	bitCrushScale (poly_float db)
	Scales a drive (dB) value for bitcrush distortion (controls quantization level).

static force_inline poly_float	downSampleScale (poly_float db)
	Scales a drive (dB) value for downsampling distortion.

static poly_float	getDriveValue (int type, poly_float input_drive)
	Converts an input drive in dB to a linear multiplier depending on distortion type.

static poly_float	getDrivenValue (int type, poly_float value, poly_float drive)
	Applies the specified distortion to a single sample given the drive multiplier.

Static Public Attributes
static constexpr mono_float	kMaxDrive = 30.0f
	Maximum allowed drive in decibels.

static constexpr mono_float	kMinDrive = -30.0f
	Minimum allowed drive in decibels.

static constexpr float	kPeriodScale = 1.0f / 88200.0f
	Factor used to scale downsampling period relative to sample rate.

static constexpr mono_float	kMinDistortionMult = 32.0f / INT_MAX
	Minimum distortion multiplier used for certain distortion styles (e.g., bitcrush).

Additional Inherited Members
Protected Member Functions inherited from vital::Processor
Output *	addOutput (int oversample=1)
	Creates and registers a new Output. Handles control rate vs. audio rate.

Input *	addInput ()
	Creates and registers a new Input, initially connected to null_source_.

Protected Attributes inherited from vital::Processor
std::shared_ptr< ProcessorState >	state_
	Shared state (sample rate, oversample, etc.)

int	plugging_start_
	The index at which `plugNext` starts searching for an unplugged input.

std::vector< std::shared_ptr< Input > >	owned_inputs_
	Inputs owned by this Processor.

std::vector< std::shared_ptr< Output > >	owned_outputs_
	Outputs owned by this Processor.

std::shared_ptr< std::vector< Input * > >	inputs_
	All inputs, owned or external.

std::shared_ptr< std::vector< Output * > >	outputs_
	All outputs, owned or external.

ProcessorRouter *	router_
	The ProcessorRouter that manages this Processor.

Static Protected Attributes inherited from vital::Processor
static const Output	null_source_
	A null (dummy) source used for unconnected inputs.

Detailed Description

A Processor that applies various types of distortion to an audio signal.

The Distortion class provides several distortion algorithms such as soft clipping, hard clipping, bitcrushing, waveshaping (folding), and downsampling. Users can specify the distortion type and drive amount, and the class will transform the audio accordingly.

Member Enumeration Documentation

◆ anonymous enum

anonymous enum

Enumerator
kAudio	Audio input buffer.
kType	Distortion type (see Type enum)
kDrive	Drive amount in dB.
kNumInputs

◆ anonymous enum

anonymous enum

Enumerator
kAudioOut	Distorted audio output.
kDriveOut	Drive values used in calculations (for reference or debugging)
kNumOutputs

◆ Type

enum vital::Distortion::Type

Distortion algorithms supported by this class.

Enumerator
kSoftClip	Soft clipping (tanh-based waveshaping)
kHardClip	Hard clipping.
kLinearFold	Linear waveform folding.
kSinFold	Sine-based waveform folding.
kBitCrush	Bitcrushing (quantizing samples)
kDownSample	Downsampling.
kNumTypes

Constructor & Destructor Documentation

◆ Distortion()

vital::Distortion::Distortion ( )

Constructs a Distortion object with the default number of inputs/outputs.

Constructs a Distortion Processor with default parameters.

Initializes the internal buffers for the last distorted value and sample accumulation (used in downsampling).

◆ ~Distortion()

virtual vital::Distortion::~Distortion ( )

inlinevirtual

Default destructor.

Member Function Documentation

◆ bitCrushScale()

static force_inline poly_float vital::Distortion::bitCrushScale ( poly_float db )

inlinestatic

Scales a drive (dB) value for bitcrush distortion (controls quantization level).

Parameters

db	The drive in decibels.

Returns: A clamped multiplier for bitcrushing, between kMinDistortionMult and 1.0f.

◆ clone()

virtual Processor * vital::Distortion::clone ( ) const

inlineoverridevirtual

Creates a clone of this Processor. (Not implemented for Distortion).

Returns: Returns nullptr.

Implements vital::Processor.

◆ downSampleScale()

static force_inline poly_float vital::Distortion::downSampleScale ( poly_float db )

inlinestatic

Scales a drive (dB) value for downsampling distortion.

Inversely affects how often samples are updated (lower drive => more frequent updates).

Parameters

db	The drive in decibels.

Returns: A scaled period factor for downsample-based distortion.

◆ driveDbScale()

static force_inline poly_float vital::Distortion::driveDbScale ( poly_float db )

inlinestatic

Scales a drive (dB) value into a linear multiplier for standard distortions.

Parameters

db	The drive in decibels.

Returns: A linear magnitude multiplier based on the provided drive.

◆ getDrivenValue()

poly_float vital::Distortion::getDrivenValue	(	int	type,
		poly_float	value,
		poly_float	drive )

static

Applies the specified distortion to a single sample given the drive multiplier.

Retrieves a distorted sample given the type and drive multiplier.

Parameters

type	The distortion type.
value	The input sample.
drive	The scaled drive multiplier (or period) as appropriate for `type`.

Returns: The distorted sample.

Chooses an appropriate function (softClip, hardClip, etc.) based on the type.

Parameters

type	Distortion type (e.g., soft clip, bitcrush).
value	Input sample to distort.
drive	The scaled drive multiplier or period factor (for downsampling).

Returns: The distorted sample.

◆ getDriveValue()

static poly_float vital::Distortion::getDriveValue	(	int	type,
		poly_float	input_drive )

inlinestatic

Converts an input drive in dB to a linear multiplier depending on distortion type.

Parameters

type	The distortion type (e.g., bitcrush, downsample, softclip).
input_drive	The raw drive in dB.

Returns: The scaled drive multiplier.

◆ process()

void vital::Distortion::process ( int num_samples )

overridevirtual

Processes a block of audio using the stored input buffer.

Parameters

num_samples Number of samples to process.

Implements vital::Processor.

◆ processDownSample()

void vital::Distortion::processDownSample	(	int	num_samples,
		const poly_float *	audio_in,
		const poly_float *	drive,
		poly_float *	audio_out )

Processes samples using a downsampling approach for distortion.

Parameters

num_samples	Number of samples to process.
audio_in	Pointer to the input buffer.
drive	Pointer to the drive values (which translate to sample period).
audio_out	Pointer to the output buffer.

◆ processTimeInvariant()

template<poly_float(*)(poly_float, poly_float) distort, poly_float(*)(poly_float) scale>

void vital::Distortion::processTimeInvariant	(	int	num_samples,
		const poly_float *	audio_in,
		const poly_float *	drive,
		poly_float *	audio_out )

Processes samples with a time-invariant distortion function (no dynamic changes).

Templated processing function for time-invariant distortions.

A template that expects two function pointers: one for the distortion (distort) and another for scaling the drive (scale).

Template Parameters

distort	The function pointer for the distortion method.
scale	The function pointer for drive scaling.

Parameters

num_samples	Number of samples to process.
audio_in	Pointer to the input buffer.
drive	Pointer to the drive values.
audio_out	Pointer to the output buffer.

Each sample is processed by a distortion function that takes a sample and scaled drive value, then writes the result to audio_out.

Template Parameters

distort	The distortion function pointer.
scale	The drive scaling function pointer.

Parameters

num_samples	Number of samples to process.
audio_in	Pointer to the input audio buffer.
drive	Pointer to the drive parameter buffer.
audio_out	Pointer to the output audio buffer.

◆ processWithInput()

void vital::Distortion::processWithInput	(	const poly_float *	audio_in,
		int	num_samples )

overridevirtual

Processes a block of audio using a provided input buffer.

Parameters

audio_in	Pointer to the input buffer.
num_samples	Number of samples to process.

Reimplemented from vital::Processor.

Member Data Documentation

◆ kMaxDrive

mono_float vital::Distortion::kMaxDrive = 30.0f

staticconstexpr

Maximum allowed drive in decibels.

◆ kMinDistortionMult

mono_float vital::Distortion::kMinDistortionMult = 32.0f / INT_MAX

staticconstexpr

Minimum distortion multiplier used for certain distortion styles (e.g., bitcrush).

◆ kMinDrive

mono_float vital::Distortion::kMinDrive = -30.0f

staticconstexpr

Minimum allowed drive in decibels.

◆ kPeriodScale

float vital::Distortion::kPeriodScale = 1.0f / 88200.0f

staticconstexpr

Factor used to scale downsampling period relative to sample rate.

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

/Users/davidvogel/repos/VitalHelp/src/synthesis/effects/distortion.h
/Users/davidvogel/repos/VitalHelp/src/synthesis/effects/distortion.cpp

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ anonymous enum

◆ anonymous enum

◆ Type

Constructor & Destructor Documentation

◆ Distortion()

◆ ~Distortion()

Member Function Documentation

◆ bitCrushScale()

◆ clone()

◆ downSampleScale()

◆ driveDbScale()

◆ getDrivenValue()

◆ getDriveValue()

◆ process()

◆ processDownSample()

◆ processTimeInvariant()

◆ processWithInput()

Member Data Documentation

◆ kMaxDrive

◆ kMinDistortionMult

◆ kMinDrive

◆ kPeriodScale