Polymorphic base for all DSP. More...

#include <hart_dsp.hpp>

Inheritance diagram for DSPBase< SampleType >:

Public Member Functions
virtual void	prepare (double sampleRateHz, size_t numInputChannels, size_t numOutputChannels, size_t maxBlockSizeFrames)=0
	Prepare for processing.

virtual void	process (const AudioBuffer< SampleType > &input, AudioBuffer< SampleType > &output, const EnvelopeBuffers &envelopeBuffers, ChannelFlags channelsToProcess)=0
	Processes the audio.

virtual void	reset ()
	Resets to initial state.

virtual void	setValue (int paramId, double value)=0
	Sets DSP value.

virtual double	getValue (int) const
	Retrieves DSP value.

virtual bool	supportsChannelLayout (size_t numInputChannels, size_t numOutputChannels) const =0
	Tells the runner (host) whether this effect supports a specific i/o configuration.

virtual void	represent (std::ostream &stream) const =0
	Makes a text representation of this DSP effect for test failure outputs.

virtual bool	supportsEnvelopeFor (int) const
	Tells whether this effect accepts automation envelopes for a particular parameter.

virtual bool	supportsSampleRate (double) const
	Tells whether this effect supports given sample rate.

virtual std::unique_ptr< DSPBase< SampleType > >	copy () const
	Returns a smart pointer with a copy of this object.

virtual std::unique_ptr< DSPBase< SampleType > >	move ()=0
	Returns a smart pointer with a moved instance of this object.

virtual	~DSPBase ()=default
	Destructor.

	DSPBase ()=default
	Default constructor.

	DSPBase (const DSPBase &other)
	Copies from another DSP effect instance.

	DSPBase (DSPBase &&other) noexcept
	Move constructor.

DSPBase &	operator= (const DSPBase &other)
	Copies from another DSP effect instance.

DSPBase &	operator= (DSPBase &&other) noexcept
	Move assignment.

bool	hasEnvelopeFor (int paramId)
	Checks if there's an automation envelope attached to a specific parameter.

void	prepareWithEnvelopes (double sampleRateHz, size_t numInputChannels, size_t numOutputChannels, size_t maxBlockSizeFrames)
	Prepares all the attached envelopes and the effect itself for processing.

void	resetWithEnvelopes ()
	Resets the DSP instance, and all associated Envelopes.

ChannelFlags	getChannelsToProcess ()
	Returns a structure indicating which channels should be processed by this DSP.

void	processWithEnvelopes (const AudioBuffer< SampleType > &input, AudioBuffer< SampleType > &output)
	Renders all the automation envelopes and processes the audio.

void	representWithActiveChannels (std::ostream &stream) const
	Makes a text representation of this DSP with optional "atChannels" appendix.

Protected Attributes
std::unordered_map< int, std::unique_ptr< Envelope > >	m_envelopes

ChannelFlags	m_channelsToProcess {true}

Detailed Description

template<typename SampleType>
class hart::DSPBase< SampleType >

Polymorphic base for all DSP.

Warning: This class exists only for type erasure and polymorphism. Do NOT inherit custom DSP from this class directly. Inherit from hart::DSP instead.

Definition at line 32 of file hart_dsp.hpp.

Constructor & Destructor Documentation

◆ ~DSPBase()

template<typename SampleType >

virtual ~DSPBase ( )

virtualdefault

Destructor.

◆ DSPBase() [1/3]

template<typename SampleType >

DSPBase ( )

default

Default constructor.

◆ DSPBase() [2/3]

template<typename SampleType >

DSPBase ( const DSPBase< SampleType > & other )

inline

Copies from another DSP effect instance.

Attached automation envelopes are deep-copied

Definition at line 138 of file hart_dsp.hpp.

◆ DSPBase() [3/3]

template<typename SampleType >

DSPBase ( DSPBase< SampleType > && other )

inlinenoexcept

Move constructor.

Attached automation envelopes are moved as well

Definition at line 147 of file hart_dsp.hpp.

Member Function Documentation

◆ prepare()

template<typename SampleType >

virtual void prepare	(	double	sampleRateHz,
		size_t	numInputChannels,
		size_t	numOutputChannels,
		size_t	maxBlockSizeFrames
	)

pure virtual

Prepare for processing.

In real-time DSP, such methods are usually used for allocating memory and other non-realtime-safe and heavyweight operations. But keep in mind that that HART does not do real-time processing, so this merely follows common real-time DSP design conventions, where non-realtime operations are done in a separate callback like this one. This method is guaranteed to be called after supportsChannelLayout() and supportsSampleRate(), but before process(). It is guaranteed that the number of input and output channels obeys supportsChannelLayout() and supportsSampleRate() preferences. It is guaranteed that all subsequent process() calls will be in line with the arguments received in this callback.

Parameters

sampleRateHz	sample rate at which the audio should be interpreted and processed
numInputChannels	Number of input channels
numOutputChannels	Number of output channels
maxBlockSizeFrames	Maximum block size in frames (samples)

Implemented in DSPFunction< SampleType >, Mute< SampleType >, StereoToMidSide< SampleType >, GainDb< SampleType >, GainLinear< SampleType >, and HardClip< SampleType >.

◆ process()

template<typename SampleType >

virtual void process	(	const AudioBuffer< SampleType > &	input,
		AudioBuffer< SampleType > &	output,
		const EnvelopeBuffers &	envelopeBuffers,
		ChannelFlags	channelsToProcess
	)

pure virtual

Processes the audio.

Depending on circumstances, this callback will either be called once to process an entire piece of audio from start to finish, or called repeatedly, one block at a time (see AudioTestBuilder::withBlockSize()). All audio blocks except the last one are guaranteed to be equal to maxBlockSizeFrames set in prepare() callback. It is guaranteed that input and output buffers are equal in length in frames (samples) to each, but they might have different number of channels. Use supportsChannelLayout() to indicate whether the effect supports a specific i/o configuration or not, as it will be called before prepare(). It is guaranteed that envelopeBuffers will only contain the values for all attached envelopes for this instance of DSP effect, and will not contain any data (including key with empty item) if there's no envelope attached to a specific parameter ID in this effects's instance. It will never contain envelopes for IDs that get rejected by supportsEnvelopeFor(). Each vector in the envelopeBuffers map is guaranteed to be at least as large as input (and output) block. For partial blocks, only the first input.getNumFrames() elements contain valid data for the current block; the rest may be stale or uninitialized. DSP implementations are expected to ignore values beyond that index range.

Note: This method may be called in a replacing manner, i. e. input and output may be references to the same object.

Warning: Remember that the very last block of audio is almost always smaller than the block size set in prepare(), so be careful with buffer bounds.

Note: Note that this method does not have to be real-time safe, as all rendering always happens offline. Also note that, unlike real-time audio applications, this method is called on the same thread as all others like prepare().

Parameters

input	Input audio block
output	Output audio block
envelopeBuffers	Envelope values for this block, see EnvelopeBuffers
channelsToProcess	Channels that need processing. Process channels that are marked `true`, bypass ones marked `false`.

Implemented in HardClip< SampleType >, Mute< SampleType >, DSPFunction< SampleType >, StereoToMidSide< SampleType >, GainDb< SampleType >, and GainLinear< SampleType >.

◆ reset()

template<typename SampleType >

virtual void reset ( )

inlinevirtual

Resets to initial state.

Ideally should be implemented in a way that audio produced after resetting is identical to audio produced after instantiation

Reimplemented in DSPFunction< SampleType >, GainDb< SampleType >, GainLinear< SampleType >, HardClip< SampleType >, Mute< SampleType >, and StereoToMidSide< SampleType >.

Definition at line 74 of file hart_dsp.hpp.

◆ setValue()

template<typename SampleType >

virtual void setValue	(	int	paramId,
		double	value
	)

pure virtual

Sets DSP value.

Parameters

paramId	Some ID that your subclass understands; use of enums is encouraged for readability
value	Value of the param in an appropriate unit; use of SI units is encouraged (i.e. s instead of ms. Hz instead of kHz) to make better use of unit literals (see Units)

Warning: This method is only called to set a fixed value before processing, and is not called to do automation (via hart::Envelope) If you want your class to support automation for a specific parameter, override supportsEnvelopeFor(), and then use envelopeBuffers provided in process() callback.

Implemented in GainDb< SampleType >, GainLinear< SampleType >, HardClip< SampleType >, DSPFunction< SampleType >, Mute< SampleType >, and StereoToMidSide< SampleType >.

◆ getValue()

template<typename SampleType >

virtual double getValue ( int ) const

inlinevirtual

Retrieves DSP value.

Among other things, it can be used to retrieve various readings like Gain Reduction measurements from your effect for further inspection

Parameters

paramId Some ID that your subclass understands

Returns: The value of requested parameter in a unit that your subclass understands

Note: This method is only intended for parameters that don't have an automation envelope attached to this specific instance. To get values for automated parameters, use envelopeBuffers provided in process() callback.

Reimplemented in GainDb< SampleType >, GainLinear< SampleType >, HardClip< SampleType >, and Mute< SampleType >.

Definition at line 92 of file hart_dsp.hpp.

◆ supportsChannelLayout()

template<typename SampleType >

virtual bool supportsChannelLayout	(	size_t	numInputChannels,
		size_t	numOutputChannels
	)		const

pure virtual

Tells the runner (host) whether this effect supports a specific i/o configuration.

It is guaranteed that the effect will not receive unsupported number of channels in process(). However, it is not always possible to handle gracefully channel layout being unsupported, so in some circumstances it can cause an exception or a test failure. This method is guaranteed to be called at least once before prepare()

Implemented in DSPFunction< SampleType >, GainDb< SampleType >, GainLinear< SampleType >, HardClip< SampleType >, Mute< SampleType >, and StereoToMidSide< SampleType >.

◆ represent()

template<typename SampleType >

virtual void represent ( std::ostream & stream ) const

pure virtual

Makes a text representation of this DSP effect for test failure outputs.

It is strongly encouraged to follow python's repr() conventions for returned text - basically, put something like "MyClass(value1, value2)" (with no quotes) into the stream whenever possible, or "<Readable info in angled brackets>" otherwise. Also, use built-in stream manipulators like dbPrecision wherever applicable. Use HART_DEFINE_GENERIC_REPRESENT() to get a basic implementation for this method.

Parameters

[out] stream Output stream to write to

Implemented in DSPFunction< SampleType >, GainDb< SampleType >, GainLinear< SampleType >, and HardClip< SampleType >.

◆ supportsEnvelopeFor()

template<typename SampleType >

virtual bool supportsEnvelopeFor ( int ) const

inlinevirtual

Tells whether this effect accepts automation envelopes for a particular parameter.

Parameters

paramId Some ID that your subclass understands

Returns: true if your subclass can process automation for this parameter, false otherwise

Reimplemented in GainDb< SampleType >, GainLinear< SampleType >, DSPFunction< SampleType >, HardClip< SampleType >, and Mute< SampleType >.

Definition at line 116 of file hart_dsp.hpp.

◆ supportsSampleRate()

template<typename SampleType >

virtual bool supportsSampleRate ( double ) const

inlinevirtual

Tells whether this effect supports given sample rate.

It is guaranteed to be called before prepare()

Parameters

sampleRateHz Sample rate in question

Returns: true if effect is capable of interpreting and processing in a given sample rate, false otherwise

Reimplemented in DSPFunction< SampleType >.

Definition at line 122 of file hart_dsp.hpp.

◆ copy()

template<typename SampleType >

virtual std::unique_ptr< DSPBase< SampleType > > copy ( ) const

inlinevirtual

Returns a smart pointer with a copy of this object.

Definition at line 125 of file hart_dsp.hpp.

◆ move()

template<typename SampleType >

virtual std::unique_ptr< DSPBase< SampleType > > move ( )

pure virtual

Returns a smart pointer with a moved instance of this object.

Implemented in DSP< SampleType, Derived >, DSP< SampleType, DSPFunction< SampleType > >, DSP< SampleType, GainDb< SampleType > >, DSP< SampleType, GainLinear< SampleType > >, DSP< SampleType, HardClip< SampleType > >, DSP< SampleType, Mute< SampleType > >, and DSP< SampleType, StereoToMidSide< SampleType > >.

◆ operator=() [1/2]

template<typename SampleType >

DSPBase & operator= ( const DSPBase< SampleType > & other )

inline

Copies from another DSP effect instance.

Attached automation envelopes are deep-copied

Definition at line 155 of file hart_dsp.hpp.

◆ operator=() [2/2]

template<typename SampleType >

DSPBase & operator= ( DSPBase< SampleType > && other )

inlinenoexcept

Move assignment.

Attached automation envelopes are moved as well

Definition at line 169 of file hart_dsp.hpp.

◆ hasEnvelopeFor()

template<typename SampleType >

bool hasEnvelopeFor ( int paramId )

inline

Checks if there's an automation envelope attached to a specific parameter.

The envelopes are guaranteed to be attached strictly before prepare() callback, so by the time of the first process() call consider the presence or absence of envelope permanent.

Returns: Reference to itself for chaining

Definition at line 183 of file hart_dsp.hpp.

◆ prepareWithEnvelopes()

template<typename SampleType >

void prepareWithEnvelopes	(	double	sampleRateHz,
		size_t	numInputChannels,
		size_t	numOutputChannels,
		size_t	maxBlockSizeFrames
	)

inline

Prepares all the attached envelopes and the effect itself for processing.

This method is intended to be called by DSP hosts like hart::AudioTestBuilder or hart::Signal. If you're making something that owns an instance of a DSP and needs it to generate audio, you must call this method before calling processWithEnvelopes(). You must also call supportsChannelLayout() and supportsSampleRate() before calling this method.

Attention: If you're not making a custom host, you probably don't need to call this method.

Definition at line 194 of file hart_dsp.hpp.

◆ resetWithEnvelopes()

template<typename SampleType >

void resetWithEnvelopes ( )

inline

Resets the DSP instance, and all associated Envelopes.

Attention: If you're not making a custom host, you probably don't need to call this method.

Definition at line 225 of file hart_dsp.hpp.

◆ getChannelsToProcess()

template<typename SampleType >

ChannelFlags getChannelsToProcess ( )

inline

Returns a structure indicating which channels should be processed by this DSP.

See hart::DSP::atChannels(), hart::DSP::atChannel(), hart::DSP::atAllChannels()

Returns: Set of flags for each channel, see hart::ChannelFlags. true for channels that need processing, false for channels that need bypassing.

Definition at line 240 of file hart_dsp.hpp.

◆ processWithEnvelopes()

template<typename SampleType >

void processWithEnvelopes	(	const AudioBuffer< SampleType > &	input,
		AudioBuffer< SampleType > &	output
	)

inline

Renders all the automation envelopes and processes the audio.

This method is intended to be called by DSP hosts like hart::AudioTestBuilder hart::Signal. If you're making something that owns an instance of a Signal and needs it to generate audio, you must call it after calling prepareWithEnvelopes().

Attention: If you're not making a custom host, you probably don't need to call this method.

Parameters

input	Input audio block
output	Output audio block

Definition at line 252 of file hart_dsp.hpp.

◆ representWithActiveChannels()

template<typename SampleType >

void representWithActiveChannels ( std::ostream & stream ) const

inline

Makes a text representation of this DSP with optional "atChannels" appendix.

For internal use by hosts

Definition at line 273 of file hart_dsp.hpp.

Member Data Documentation

◆ m_envelopes

template<typename SampleType >

std::unordered_map<int, std::unique_ptr<Envelope> > m_envelopes

protected

Definition at line 290 of file hart_dsp.hpp.

◆ m_channelsToProcess

template<typename SampleType >

ChannelFlags m_channelsToProcess {true}

protected

Definition at line 291 of file hart_dsp.hpp.

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

include/dsp/hart_dsp.hpp

Public Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ ~DSPBase()

◆ DSPBase() [1/3]

◆ DSPBase() [2/3]

◆ DSPBase() [3/3]

Member Function Documentation

◆ prepare()

◆ process()

◆ reset()

◆ setValue()

◆ getValue()

◆ supportsChannelLayout()

◆ represent()

◆ supportsEnvelopeFor()

◆ supportsSampleRate()

◆ copy()

◆ move()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ hasEnvelopeFor()

◆ prepareWithEnvelopes()

◆ resetWithEnvelopes()

◆ getChannelsToProcess()

◆ processWithEnvelopes()

◆ representWithActiveChannels()

Member Data Documentation

◆ m_envelopes

◆ m_channelsToProcess