A versatile Low-Frequency Oscillator (LFO) for audio synthesis, supporting multiple sync modes and smoothing options. More...

#include <synth_lfo.h>

Inheritance diagram for vital::SynthLfo:

Classes
struct	LfoState
	Holds the state of the LFO for either control-rate or audio-rate processing. More...

Public Types
enum	{ kFrequency , kPhase , kAmplitude , kNoteTrigger , kSyncType , kSmoothMode , kFade , kSmoothTime , kStereoPhase , kDelay , kNoteCount , kNumInputs }
	Indices of input parameters to the LFO. More...

enum	{ kValue , kOscPhase , kOscFrequency , kNumOutputs }
	Indices of output parameters from the LFO. More...

enum	SyncType { kTrigger , kSync , kEnvelope , kSustainEnvelope , kLoopPoint , kLoopHold , kNumSyncTypes }
	Different synchronization modes for the LFO. More...

enum	{ kTime , kTempo , kDottedTempo , kTripletTempo , kKeytrack , kNumSyncOptions }
	Different time interpretation modes for synchronizing the LFO. More...

Public Member Functions
force_inline poly_float	getValueAtPhase (mono_float *buffer, poly_float resolution, poly_int max_index, poly_float phase)
	Retrieves the LFO value at a given phase using a cubic interpolation on the line generator data.

force_inline poly_float	getValueAtPhase (poly_float phase)
	Retrieves the LFO value at a given phase using the internal line generator source.

	SynthLfo (LineGenerator *source)
	Constructs a SynthLfo processor with a given LineGenerator source.

force_inline poly_mask	getReleaseMask ()
	Determines which voices are in the release state based on note triggers.

virtual Processor *	clone () const override
	Clones the SynthLfo processor, creating a new instance with the same settings.

void	process (int num_samples) override
	Processes a block of samples, updating the LFO output.

void	correctToTime (double seconds)
	Updates the LFO to align with a given time in seconds, enabling synchronization with an external clock.

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	processWithInput (const poly_float *audio_in, int num_samples)
	An optional processing function taking explicit input buffer. Fallback is an assertion failure (not supported).

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 Attributes
static constexpr mono_float	kMaxPower = 20.0f

static constexpr float	kHalfLifeRatio = 0.2f

static constexpr float	kMinHalfLife = 0.0002f

Protected Member Functions
void	processTrigger ()
	Handles trigger events (note on/off), resets, and updates masks for held states.

void	processControlRate (int num_samples)
	Processes the LFO at control rate (e.g., once per block) instead of every sample.

poly_float	processAudioRateEnvelope (int num_samples, poly_float current_phase, poly_float current_offset, poly_float delta_offset)
	Processes the LFO in "Envelope" sync mode at audio rate.

poly_float	processAudioRateSustainEnvelope (int num_samples, poly_float current_phase, poly_float current_offset, poly_float delta_offset)
	Processes the LFO in "Sustain Envelope" mode at audio rate.

poly_float	processAudioRateLfo (int num_samples, poly_float current_phase, poly_float current_offset, poly_float delta_offset)
	Processes the LFO in regular LFO mode (Trigger or Sync) at audio rate.

poly_float	processAudioRateLoopPoint (int num_samples, poly_float current_phase, poly_float current_offset, poly_float delta_offset)
	Processes the LFO in "LoopPoint" mode at audio rate.

poly_float	processAudioRateLoopHold (int num_samples, poly_float current_phase, poly_float current_offset, poly_float delta_offset)
	Processes the LFO in "LoopHold" mode at audio rate.

void	processAudioRate (int num_samples)
	Processes the LFO at audio rate (per sample).

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
bool	was_control_rate_
	Tracks if the previous processing block was at control rate.

LfoState	control_rate_state_
	State used during control-rate processing.

LfoState	audio_rate_state_
	State used during audio-rate processing.

poly_mask	held_mask_
	A mask indicating which voices are currently held (for sustain envelope modes).

poly_int	trigger_sample_
	The sample index at which the note was triggered.

poly_float	trigger_delay_
	The delay (in seconds) to apply before the LFO starts after a trigger.

LineGenerator *	source_
	The LineGenerator providing the waveform data for the LFO.

std::shared_ptr< double >	sync_seconds_
	Shared pointer to an external time reference for syncing.

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.

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

Detailed Description

A versatile Low-Frequency Oscillator (LFO) for audio synthesis, supporting multiple sync modes and smoothing options.

The SynthLfo class generates low-frequency modulation signals from a LineGenerator source. It supports:

Various sync types (triggered, synced to host/tempo, envelope-like, looping)
Phase offset adjustments, stereo offsets, delay times, fade-in times, and smoothing.
Both control-rate and audio-rate processing, adapting seamlessly between them.

Member Enumeration Documentation

◆ anonymous enum

anonymous enum

Indices of input parameters to the LFO.

kFrequency: Controls the speed (frequency) of the LFO cycle.
kPhase: Sets a base phase offset for the LFO.
kAmplitude: Adjusts the output amplitude (scaling the final LFO value).
kNoteTrigger: Triggers the LFO, resetting phase or starting envelopes depending on sync type.
kSyncType: Determines the synchronization mode (trigger, sync, envelope, loop, etc.).
kSmoothMode: Enables smoothing of the LFO output using a half-life parameter.
kFade: Controls a fade-in time for the LFO after being triggered.
kSmoothTime: Sets the smoothing time (half-life) for transitions.
kStereoPhase: Applies a stereo phase offset between left/right channels.
kDelay: Sets a delay time before the LFO starts outputting values.
kNoteCount: Indicates how many notes/voices are currently active for voice encoding.

Enumerator
kFrequency
kPhase
kAmplitude
kNoteTrigger
kSyncType
kSmoothMode
kFade
kSmoothTime
kStereoPhase
kDelay
kNoteCount
kNumInputs

◆ anonymous enum

anonymous enum

Indices of output parameters from the LFO.

kValue: The LFO's main output value (the modulating signal).
kOscPhase: The encoded current phase and voice information.
kOscFrequency: The current frequency of the LFO in Hz.

Enumerator
kValue
kOscPhase
kOscFrequency
kNumOutputs

◆ anonymous enum

anonymous enum

Different time interpretation modes for synchronizing the LFO.

Not all are necessarily used here, but it's a reference for future expansions:

kTime: Use absolute time.
kTempo: Sync to tempo as normal quarters.
kDottedTempo: Sync to dotted rhythm times.
kTripletTempo: Sync to triplet rhythm times.
kKeytrack: Key-tracks frequency based on note pitch.

Enumerator
kTime
kTempo
kDottedTempo
kTripletTempo
kKeytrack
kNumSyncOptions

◆ SyncType

enum vital::SynthLfo::SyncType

Different synchronization modes for the LFO.

kTrigger: Triggers the LFO on note start, repeating cycles.
kSync: Syncs LFO phase to a global time reference.
kEnvelope: LFO acts as a one-shot envelope, stopping after reaching the end.
kSustainEnvelope: Envelope-like, but can be held at a certain phase until note release.
kLoopPoint: Loops from the end back to a specified loop point, creating a custom cycle.
kLoopHold: Loops and holds at a point when triggered, producing interesting loop-hold behavior.

Enumerator
kTrigger
kSync
kEnvelope
kSustainEnvelope
kLoopPoint
kLoopHold
kNumSyncTypes

Constructor & Destructor Documentation

◆ SynthLfo()

vital::SynthLfo::SynthLfo ( LineGenerator * source )

Constructs a SynthLfo processor with a given LineGenerator source.

Parameters

source Pointer to a LineGenerator that provides the waveform data for the LFO.

Member Function Documentation

◆ clone()

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

inlineoverridevirtual

Clones the SynthLfo processor, creating a new instance with the same settings.

Returns: A pointer to the cloned SynthLfo instance.

Implements vital::Processor.

◆ correctToTime()

void vital::SynthLfo::correctToTime ( double seconds )

Updates the LFO to align with a given time in seconds, enabling synchronization with an external clock.

Parameters

seconds The time in seconds to sync the LFO's phase offset to.

Updates the LFO's sync time reference, used for synchronization modes.

◆ getReleaseMask()

force_inline poly_mask vital::SynthLfo::getReleaseMask ( )

inline

Determines which voices are in the release state based on note triggers.

Returns: A mask of voices that are currently releasing.

◆ getValueAtPhase() [1/2]

force_inline poly_float vital::SynthLfo::getValueAtPhase	(	mono_float *	buffer,
		poly_float	resolution,
		poly_int	max_index,
		poly_float	phase )

inline

Retrieves the LFO value at a given phase using a cubic interpolation on the line generator data.

Parameters

buffer	Pointer to the cubic interpolation buffer from the LineGenerator.
resolution	The number of samples in the wave table.
max_index	The maximum valid index in the buffer.
phase	The normalized phase (0.0 to 1.0) at which to sample.

Returns: The interpolated LFO value at the given phase.

◆ getValueAtPhase() [2/2]

force_inline poly_float vital::SynthLfo::getValueAtPhase ( poly_float phase )

inline

Retrieves the LFO value at a given phase using the internal line generator source.

Parameters

phase The normalized phase at which to sample.

Returns: The interpolated LFO value at that phase.

◆ process()

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

overridevirtual

Processes a block of samples, updating the LFO output.

Automatically switches between control-rate and audio-rate processing. It handles triggers, fades, smoothing, and various synchronization modes.

Parameters

num_samples The number of samples to process in the current block.

Top-level processing method that decides between control-rate and audio-rate processing.

If transitioning from control-rate to audio-rate, it initializes the audio-rate state from the control-rate state. Then it handles triggers, and depending on the rate, calls the appropriate processing methods.

Implements vital::Processor.

◆ processAudioRate()

void vital::SynthLfo::processAudioRate ( int num_samples )

protected

Processes the LFO at audio rate (per sample).

This method selects the appropriate sync mode and processing function based on the current configuration.

◆ processAudioRateEnvelope()

poly_float vital::SynthLfo::processAudioRateEnvelope	(	int	num_samples,
		poly_float	current_phase,
		poly_float	current_offset,
		poly_float	delta_offset )

protected

Processes the LFO in "Envelope" sync mode at audio rate.

In Envelope mode, the LFO runs from 0 to 1 and then stops. This method updates the output sample-by-sample.

◆ processAudioRateLfo()

poly_float vital::SynthLfo::processAudioRateLfo	(	int	num_samples,
		poly_float	current_phase,
		poly_float	current_offset,
		poly_float	delta_offset )

protected

Processes the LFO in regular LFO mode (Trigger or Sync) at audio rate.

This mode continuously loops the waveform from 0 to 1.

◆ processAudioRateLoopHold()

poly_float vital::SynthLfo::processAudioRateLoopHold	(	int	num_samples,
		poly_float	current_phase,
		poly_float	current_offset,
		poly_float	delta_offset )

protected

Processes the LFO in "LoopHold" mode at audio rate.

In this mode, the LFO loops and holds at a specified phase until triggered again, producing a loop-hold effect.

◆ processAudioRateLoopPoint()

poly_float vital::SynthLfo::processAudioRateLoopPoint	(	int	num_samples,
		poly_float	current_phase,
		poly_float	current_offset,
		poly_float	delta_offset )

protected

Processes the LFO in "LoopPoint" mode at audio rate.

This mode loops the LFO and after reaching 1.0, jumps back to a loop point offset.

◆ processAudioRateSustainEnvelope()

poly_float vital::SynthLfo::processAudioRateSustainEnvelope	(	int	num_samples,
		poly_float	current_phase,
		poly_float	current_offset,
		poly_float	delta_offset )

protected

Processes the LFO in "Sustain Envelope" mode at audio rate.

This mode behaves like an envelope but can hold at a certain phase until a release event.

◆ processControlRate()

void vital::SynthLfo::processControlRate ( int num_samples )

protected

Processes the LFO at control rate (e.g., once per block) instead of every sample.

Parameters

num_samples The number of samples in the current block.

Processes the LFO at control rate.

This happens typically once per block (not per sample). It updates delays, fades, smoothing, and applies the selected sync mode logic to compute a single output value.

◆ processTrigger()

force_inline void vital::SynthLfo::processTrigger ( )

protected

Handles trigger events (note on/off), resets, and updates masks for held states.

Handles note trigger events, reset conditions, and updating masks and offsets.

If a note-on occurs, it can reset the LFO offset depending on the sync type. If a note-off occurs, it updates masks to reflect that the LFO may now be in a release state. Also handles delay and fade resets.

Member Data Documentation

◆ audio_rate_state_

LfoState vital::SynthLfo::audio_rate_state_

protected

State used during audio-rate processing.

◆ control_rate_state_

LfoState vital::SynthLfo::control_rate_state_

protected

State used during control-rate processing.

◆ held_mask_

poly_mask vital::SynthLfo::held_mask_

protected

A mask indicating which voices are currently held (for sustain envelope modes).

◆ kHalfLifeRatio

float vital::SynthLfo::kHalfLifeRatio = 0.2f

staticconstexpr

◆ kMaxPower

mono_float vital::SynthLfo::kMaxPower = 20.0f

staticconstexpr

◆ kMinHalfLife

float vital::SynthLfo::kMinHalfLife = 0.0002f

staticconstexpr

◆ source_

LineGenerator* vital::SynthLfo::source_

protected

The LineGenerator providing the waveform data for the LFO.

◆ sync_seconds_

std::shared_ptr<double> vital::SynthLfo::sync_seconds_

protected

Shared pointer to an external time reference for syncing.

◆ trigger_delay_

poly_float vital::SynthLfo::trigger_delay_

protected

The delay (in seconds) to apply before the LFO starts after a trigger.

◆ trigger_sample_

poly_int vital::SynthLfo::trigger_sample_

protected

The sample index at which the note was triggered.

◆ was_control_rate_

bool vital::SynthLfo::was_control_rate_

protected

Tracks if the previous processing block was at control rate.

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

/Users/davidvogel/repos/VitalHelp/src/synthesis/modulators/synth_lfo.h
/Users/davidvogel/repos/VitalHelp/src/synthesis/modulators/synth_lfo.cpp

Classes

Public Types

Public Member Functions

Static Public Attributes

Protected Member Functions

Protected Attributes

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ anonymous enum

◆ anonymous enum

◆ anonymous enum

◆ SyncType

Constructor & Destructor Documentation

◆ SynthLfo()

Member Function Documentation

◆ clone()

◆ correctToTime()

◆ getReleaseMask()

◆ getValueAtPhase() [1/2]

◆ getValueAtPhase() [2/2]

◆ process()

◆ processAudioRate()

◆ processAudioRateEnvelope()

◆ processAudioRateLfo()

◆ processAudioRateLoopHold()

◆ processAudioRateLoopPoint()

◆ processAudioRateSustainEnvelope()

◆ processControlRate()

◆ processTrigger()

Member Data Documentation

◆ audio_rate_state_

◆ control_rate_state_

◆ held_mask_

◆ kHalfLifeRatio

◆ kMaxPower

◆ kMinHalfLife

◆ source_

◆ sync_seconds_

◆ trigger_delay_

◆ trigger_sample_

◆ was_control_rate_