Signal defined by a user-provided function. More...

#include <hart_signal_function.hpp>

Inheritance diagram for SignalFunction< SampleType >:

Public Member Functions
	SignalFunction (std::function< void(AudioBuffer< SampleType > &)> signalFunction, const std::string &label={}, Loop loop=Loop::yes)
	Constructs a signal from a user-defined function.

void	renderNextBlock (AudioBuffer< SampleType > &output) override
	Renders next block audio for the signal.

void	prepare (double sampleRateHz, size_t numOutputChannels, size_t) override
	Prepare the signal for rendering.

void	reset () override
	Resets the Signal to initial state.

void	represent (std::ostream &stream) const override
	Makes a text representation of this Signal for test failure outputs.

Public Member Functions inherited from Signal< SampleType, SignalFunction< SampleType > >
SignalFunction< SampleType > &	followedBy (DerivedDSP &&dsp) &
	Adds a DSP effect to the end of signal's DSP chain.

SignalFunction< SampleType > &&	followedBy (DerivedDSP &&dsp) &&
	Adds a DSP effect to the end of signal's DSP chain.

SignalFunction< SampleType > &	followedBy (std::unique_ptr< DSPBase< SampleType > > dsp) &
	Adds a DSP effect to the end of signal's DSP chain.

SignalFunction< SampleType > &&	followedBy (std::unique_ptr< DSPBase< SampleType > > dsp) &&
	Adds a DSP effect to the end of signal's DSP chain.

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

std::unique_ptr< SignalBase< SampleType > >	move () override
	Returns a smart pointer with a moved instance of this object.

SignalFunction< SampleType > &	skipTo (double startTimestampSeconds) &
	Skips the signal to a specific timestamp.

SignalFunction< SampleType > &&	skipTo (double startTimestampSeconds) &&
	Skips the signal to a specific timestamp.

SignalFunction< SampleType >	operator- () const
	Returns a copy of this signal, but with flipped phase.

SignalFunction< SampleType >	operator~ () const
	Returns a copy of this signal, but with flipped phase.

Public Member Functions inherited from SignalBase< SampleType >
	SignalBase ()=default
	Default constructor.

	SignalBase (const SignalBase &other)
	Copies other signal.

	SignalBase (SignalBase &&other) noexcept
	Moves from other signal.

virtual	~SignalBase ()=default
	Destructor.

SignalBase &	operator= (const SignalBase &other)
	Copies from other signal.

SignalBase &	operator= (SignalBase &&other) noexcept
	Moves from other signal.

virtual bool	supportsNumChannels (size_t) const
	Tells the host whether this Signal is capable of generating audio for a certain amount of channels.

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

void	prepareWithDSPChain (double sampleRateHz, size_t numOutputChannels, size_t maxBlockSizeFrames)
	Prepares the signal and all attached effects in the DSP chain for rendering.

void	renderNextBlockWithDSPChain (AudioBuffer< SampleType > &output)
	Renders next block audio for the signal and all the effects in the DSP chain.

virtual void	resetWithDSPChain ()
	Resets to Signal and all the effects attached to its DSP chain to initial state.

size_t	getDSPChainSize () const
	Returns the size of the DSP chain attached to the Signal.

DSPBase< SampleType > *	getDSP (int index=-1) const
	Access a specific element in the DSP chain.

std::unique_ptr< DSPBase< SampleType > >	popDSP (int index=-1)
	Extract a specific element in the DSP chain by removing it.

Additional Inherited Members
Protected Member Functions inherited from SignalBase< SampleType >
void	setNumChannels (size_t numChannels)

size_t	getNumChannels ()

Protected Attributes inherited from SignalBase< SampleType >
size_t	m_numChannels = 1

double	m_startTimestampSeconds = 0.0

std::vector< std::unique_ptr< DSPBase< SampleType > > >	m_dspChain

Related Symbols inherited from Signal< SampleType, SignalFunction< SampleType > >
MixedSignal< SampleType >	operator- (const Signal< SampleType, DerivedSignalTypeLHS > &lhs, const Signal< SampleType, DerivedSignalTypeRHS > &rhs)
	Subtracts one signal from another, resulting in a new mixed signal.

MixedSignal< SampleType >	operator+ (const Signal< SampleType, DerivedSignalTypeLHS > &lhs, const Signal< SampleType, DerivedSignalTypeRHS > &rhs)
	Adds one signal to another, resulting in a new mixed signal.

std::ostream &	operator<< (std::ostream &stream, const SignalBase< SampleType > &signal)
	Prints readable text representation of the Signal object into the I/O stream.

auto	operator>> (SignalFunction< SampleType > &signal, DerivedDSP &&dsp) -> decltype(signal.followedBy(std::forward< DerivedDSP >(dsp)))
	Adds a DSP effect to the end of signal's DSP chain by transfering it.

auto	operator>> (SignalFunction< SampleType > &&signal, DerivedDSP &&dsp) -> decltype(std::move(signal).followedBy(std::forward< DerivedDSP >(dsp)))
	Adds a DSP effect to the end of signal's DSP chain by transfering it.

Detailed Description

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

Signal defined by a user-provided function.

This Signal allows defining input signals using a lambda or function object, instead of creating a dedicated Signal subclass.

The provided function is called during prepare() and is expected to fill an initially empty AudioBuffer with audio data. This buffer is then used as a source and streamed block-by-block during processing.

The generated buffer can either:

loop continuously (SignalFunction::Loop::yes), or
play once and output silence afterwards (SignalFunction::Loop::no)

SignalFunction can be suitable for:

Procedural signal generation (e.g. waveforms, noise)
Defining short repeating patterns (e.g. one-cycle signals)
Creating custom test signals inline in test cases

Example: // auto nyquistSignal = SignalFunction (

[] (AudioBuffer& buffer)

{

buffer.setNumFrames (2);

for (size_t channel = 0; channel < buffer.getNumChannels(); ++channel)

{

buffer[channel][0] = -1.0f;

buffer[channel][0] = 1.0f;

}

},

"Nyquist Signal",

SignalFunction::Loop::yes

);

hart::AudioBuffer
Container for audio data.
Definition hart_audio_buffer.hpp:21

hart::DSPFunction
A DSP processor defined by a user-provided function.
Definition hart_dsp_function.hpp:62

Exceptions

hart::NullPointerError	if `signalFunction` is empty
hart::ChannelLayoutError	if the function changes buffer's channel count
hart::SampleRateError	if the function changes buffer's sample rate
hart::SizeError	if the function does not allocate any frames

Definition at line 59 of file hart_signal_function.hpp.

Constructor & Destructor Documentation

◆ SignalFunction()

template<typename SampleType >

SignalFunction	(	std::function< void(AudioBuffer< SampleType > &)>	signalFunction,
		const std::string &	label = `{}`,
		Loop	loop = `Loop::yes`
	)

inline

Constructs a signal from a user-defined function.

The provided function is guaranteed to be called with an empty AudioBuffer, i.e. AudioBuffer::getNumFrames() will return zero. The function must allocate and fill the buffer with audio data. The provided buffer is guaranteed to contain valid metadata on required number of channels (see AudioBuffer::getNumChannels()) and sample rate (see AudioBuffer::getSampleRateHz()).

The buffer is owned internally and reused during processing.

Parameters

signalFunction A callable with signature: void (AudioBuffer<SampleType>&)

For the provided buffer, the function must:

Allocate number of frames necessary for your Signal
Fill the buffer with valid audio data
Preserve the number of channels and sample rate Failure to meet these requirements will result in a runtime error.

Parameters

label	A human-readable description of the signal, used in logs and failure reports. Can be empty.
loop	If set to Loop::yes, the generated buffer will repeat continuously. If set to Loop::no, the signal will output silence (zeros) after the buffer is exhausted.

Definition at line 89 of file hart_signal_function.hpp.

Member Function Documentation

◆ renderNextBlock()

template<typename SampleType >

void renderNextBlock ( AudioBuffer< SampleType > & output )

inlineoverridevirtual

Renders next block audio for the signal.

Depending on circumstances, this callback will either be called once to generate an entire piece of audio from start to finish, or called repeatedly, one block at a time. This method is guaranteed to be called strictly after prepare(), or not called at all. Number of channels and max block size are guaranteed to be in line with the ones set by prepare() callback. Assume sample rate to always be equal to the one received in the last prepare() callback. All audio blocks except the last one are guaranteed to be equal to maxBlockSizeFrames set in prepare() callback.

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

output Output audio block

Warning: Output audio buffer is not guaranteed to be pre-filled with zeros, it may contain junk data.

Implements SignalBase< SampleType >.

Definition at line 96 of file hart_signal_function.hpp.

◆ prepare()

template<typename SampleType >

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

inlineoverridevirtual

Prepare the signal for rendering.

This method is guaranteed to be called after supportsNumChannels() and supportsSampleRate(), but before renderNextBlock(). It is guaranteed that numChannels obeys supportsNumChannels() preferences, same with sampleRateHz and supportsSampleRate(). It is guaranteed that all subsequent renderNextBlock() calls will be in line with the arguments received in this callback.

Parameters

sampleRateHz	sample rate at which the audio should be generated
numOutputChannels	Number of output channels to be filled
maxBlockSizeFrames	Maximum block size in frames (samples)

Implements SignalBase< SampleType >.

Definition at line 154 of file hart_signal_function.hpp.

◆ reset()

template<typename SampleType >

void reset ( )

inlineoverridevirtual

Resets the Signal to initial state.

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

Implements SignalBase< SampleType >.

Definition at line 187 of file hart_signal_function.hpp.

◆ represent()

template<typename SampleType >

void represent ( std::ostream & stream ) const

inlineoverridevirtual

Makes a text representation of this Signal 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

Implements SignalBase< SampleType >.

Definition at line 192 of file hart_signal_function.hpp.

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

include/signals/hart_signal_function.hpp

Public Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ SignalFunction()

Member Function Documentation

◆ renderNextBlock()

◆ prepare()

◆ reset()

◆ represent()