Band-limited oscillator featuring PolyBLEP anti-aliasing and analog-modeled integration. More...

#include <Oscillator.h>

Public Types
enum class	Waveform { Sine , Saw , Square , Triangle }

enum class	AntiAliasing { MinBLEP , PolyBLEP }
	Discontinuity correction used when hard sync is off. More...

Public Member Functions
void	prepare (double sampleRate) noexcept
	Prepares the oscillator with the system sample rate.

void	prepare (const AudioSpec &spec) noexcept
	Prepares the oscillator from an AudioSpec configuration.

void	setFrequency (T freq) noexcept
	Sets the oscillator's fundamental frequency.

void	setWaveform (Waveform w) noexcept
	Changes the active waveform.

void	setAntiAliasing (AntiAliasing mode) noexcept
	Selects the discontinuity correction for the non-synced waveforms.

AntiAliasing	getAntiAliasing () const noexcept
	Returns the discontinuity correction in use (see setAntiAliasing()).

void	setSyncRatio (T ratio) noexcept
	Enables band-limited hard sync.

void	setPhase (T phase) noexcept
	Forces the oscillator phase to a specific value.

void	reset () noexcept
	Hard-resets the oscillator phase and integrator state.

T	getNextSample () noexcept
	Computes and returns the next single audio sample.

void	processBlock (T *buffer, size_t numSamples) noexcept
	Fills a buffer with generated samples.

T	getSample () noexcept
	Generator contract alias for getNextSample() (GeneratorProcessor).

void	generateBlock (AudioBufferView< T > buffer) noexcept
	Fills every channel of the view with the generated waveform. Satisfies the GeneratorProcessor concept. The oscillator is mono, so all channels receive the same signal (channel 0 is generated, the rest copy it).

T	getPhase () const noexcept

T	getFrequency () const noexcept

Waveform	getWaveform () const noexcept

T	getSyncRatio () const noexcept

Detailed Description

template<typename T>
class dspark::Oscillator< T >

Band-limited oscillator featuring PolyBLEP anti-aliasing and analog-modeled integration.

This oscillator provides high-quality waveform generation suitable for both audio-rate synthesis and low-frequency modulation (LFO). Every discontinuity of the Saw and Square waves is corrected with a table minBLEP (MinBlepTable) – a causal minimum-phase band-limited step whose alias rejection (~-90 dB measured) is some 35-70 dB better than a 2-point PolyBLEP across the keyboard. The Triangle wave is generated via a leaky integrator driven by the band-limited square, providing an analog-style curve. Under hard sync (setSyncRatio) the same kernel corrects the slave edges and the reset jumps. Exception: a hard-synced Sine has no value discontinuity, only a derivative kink at the reset, which the minBLEP does not address; its residual alias floor is ~-64 dB (a minBLAMP table is the future direction).

A band-limited step rings (Gibbs), and a minimum-phase one puts all of that ringing after the edge: minBLEP saw and square peaks reach about 1.45x full scale, so leave ~3.5 dB of headroom. For modulation duty, where that overshoot is unwanted and aliasing is irrelevant, select AntiAliasing::PolyBLEP (the waveforms then stay within [-1, 1]).

Note: This class is not internally thread-safe: apply parameter changes (e.g. setFrequency) from the audio thread between process calls, publishing values from other threads via atomics, as the framework effects do.

Template Parameters

T	Sample type (must be float or double).

Definition at line 73 of file Oscillator.h.

Member Enumeration Documentation

◆ AntiAliasing

template<typename T >

enum class dspark::Oscillator::AntiAliasing

strong

Discontinuity correction used when hard sync is off.

Enumerator
MinBLEP	Minimum-phase band-limited step table (default; audio duty).
PolyBLEP	2-point polynomial step (no overshoot; LFO duty).

Definition at line 81 of file Oscillator.h.

◆ Waveform

template<typename T >

enum class dspark::Oscillator::Waveform

strong

Enumerator
Sine
Saw
Square
Triangle

Definition at line 78 of file Oscillator.h.

Member Function Documentation

◆ generateBlock()

template<typename T >

void dspark::Oscillator< T >::generateBlock ( AudioBufferView< T > buffer )

inlinenoexcept

Fills every channel of the view with the generated waveform. Satisfies the GeneratorProcessor concept. The oscillator is mono, so all channels receive the same signal (channel 0 is generated, the rest copy it).

Definition at line 334 of file Oscillator.h.

◆ getAntiAliasing()

template<typename T >

AntiAliasing dspark::Oscillator< T >::getAntiAliasing ( ) const

inlinenoexcept

Returns the discontinuity correction in use (see setAntiAliasing()).

Definition at line 162 of file Oscillator.h.

◆ getFrequency()

template<typename T >

T dspark::Oscillator< T >::getFrequency ( ) const

inlinenoexcept

Definition at line 352 of file Oscillator.h.

◆ getNextSample()

template<typename T >

T dspark::Oscillator< T >::getNextSample ( )

inlinenoexcept

Computes and returns the next single audio sample.

Returns: A band-limited sample. PolyBLEP output stays in [-1.0, 1.0]; minBLEP edges (the default, and hard sync) ring to ~1.45x full scale – Gibbs, see setAntiAliasing().

Definition at line 246 of file Oscillator.h.

◆ getPhase()

template<typename T >

T dspark::Oscillator< T >::getPhase ( ) const

inlinenoexcept

Definition at line 351 of file Oscillator.h.

◆ getSample()

template<typename T >

T dspark::Oscillator< T >::getSample ( )

inlinenoexcept

Generator contract alias for getNextSample() (GeneratorProcessor).

Definition at line 327 of file Oscillator.h.

◆ getSyncRatio()

template<typename T >

T dspark::Oscillator< T >::getSyncRatio ( ) const

inlinenoexcept

Definition at line 354 of file Oscillator.h.

◆ getWaveform()

template<typename T >

Waveform dspark::Oscillator< T >::getWaveform ( ) const

inlinenoexcept

Definition at line 353 of file Oscillator.h.

◆ prepare() [1/2]

template<typename T >

void dspark::Oscillator< T >::prepare ( const AudioSpec & spec )

inlinenoexcept

Prepares the oscillator from an AudioSpec configuration.

Parameters

spec	The structural audio specification of the processing chain.

Definition at line 111 of file Oscillator.h.

◆ prepare() [2/2]

template<typename T >

void dspark::Oscillator< T >::prepare ( double sampleRate )

inlinenoexcept

Prepares the oscillator with the system sample rate.

Also re-clamps the stored frequency against the new Nyquist bound, so calling prepare() again with a LOWER sample rate leaves the oscillator in a valid state (the PolyBLEP correction assumes increment <= 0.5).

Parameters

sampleRate The operating sample rate in Hz. Must be > 0.

Definition at line 96 of file Oscillator.h.

◆ processBlock()

template<typename T >

void dspark::Oscillator< T >::processBlock	(	T *	buffer,
		size_t	numSamples
	)

inlinenoexcept

Fills a buffer with generated samples.

Plain per-sample loop over getNextSample(): waveform generation is inherently serial (recursive phase/integrator state), so there is no SIMD variant and no alignment requirement on buffer.

Parameters

buffer	Destination pointer (any alignment).
numSamples	Number of samples to generate.

Definition at line 318 of file Oscillator.h.

◆ reset()

template<typename T >

void dspark::Oscillator< T >::reset ( )

inlinenoexcept

Hard-resets the oscillator phase and integrator state.

The triangle integrator is seeded at the negative steady-state peak (phase 0 drives the underlying square positive, so the steady cycle starts at -peak). Seeding at zero made the first half-cycle overshoot to (1+q)x the nominal level – an audible +4 dB pop on note retrigger.

Definition at line 230 of file Oscillator.h.

◆ setAntiAliasing()

template<typename T >

void dspark::Oscillator< T >::setAntiAliasing ( AntiAliasing mode )

inlinenoexcept

Selects the discontinuity correction for the non-synced waveforms.

MinBLEP (the default) is the audio-rate choice; its band-limited edges ring to ~1.45x full scale. PolyBLEP keeps every waveform inside [-1, 1] at the cost of far more aliasing: use it for LFOs and control signals. Pending minBLEP corrections are discarded on a change. Hard sync always uses the minBLEP.

Parameters

mode	Correction method.

Definition at line 154 of file Oscillator.h.

◆ setFrequency()

template<typename T >

void dspark::Oscillator< T >::setFrequency ( T freq )

inlinenoexcept

Sets the oscillator's fundamental frequency.

Parameters

freq	Frequency in Hz. Will be clamped between 0 and Nyquist.

Definition at line 120 of file Oscillator.h.

◆ setPhase()

template<typename T >

void dspark::Oscillator< T >::setPhase ( T phase )

inlinenoexcept

Forces the oscillator phase to a specific value.

The triangle integrator is re-seeded at its steady-state value for the requested phase, so a Triangle LFO lands on the expected waveform point immediately instead of easing in over ~1/increment samples (the stereo-spread re-phasing pattern used by Chorus relies on this). Under hard sync the slave is re-phased coherently and pending minBLEP corrections are discarded.

Parameters

phase Normalized phase in the range [0.0, 1.0).

Definition at line 203 of file Oscillator.h.

◆ setSyncRatio()

template<typename T >

void dspark::Oscillator< T >::setSyncRatio ( T ratio )

inlinenoexcept

Enables band-limited hard sync.

The oscillator's frequency becomes the sync MASTER; an internal slave runs at ratio times that frequency and is phase-reset every master cycle – the classic ripping sync timbre. Every discontinuity (the slave's own edges and the reset jump, scaled to its actual amplitude) is corrected with a table minBLEP (see MinBlepTable): a minimum-phase band-limited step whose correction is fully causal, pushing aliasing to the windowed-sinc stopband instead of the ~-40 dB envelope of a 2-point polynomial kernel.

Note: A band-limited (brickwall) rendition of the synced waveform legitimately overshoots the naive one: peaks may reach ~1.5x full scale (Gibbs), unlike the sync-off waveforms which stay within [-1, 1]. Leave headroom or follow with a gain stage.

Parameters

ratio Slave/master frequency ratio. Values <= 1 disable sync (a small guard band just above 1 also disables it – a 1:1 slave adds nothing but correction noise).

Definition at line 185 of file Oscillator.h.

◆ setWaveform()

template<typename T >

void dspark::Oscillator< T >::setWaveform ( Waveform w )

inlinenoexcept

Changes the active waveform.

Parameters

w	The desired waveform type.

Definition at line 136 of file Oscillator.h.

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

Oscillator.h

Public Types

Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ AntiAliasing

◆ Waveform

Member Function Documentation

◆ generateBlock()

◆ getAntiAliasing()

◆ getFrequency()

◆ getNextSample()

◆ getPhase()

◆ getSample()

◆ getSyncRatio()

◆ getWaveform()

◆ prepare() [1/2]

◆ prepare() [2/2]

◆ processBlock()

◆ reset()

◆ setAntiAliasing()

◆ setFrequency()

◆ setPhase()

◆ setSyncRatio()

◆ setWaveform()