A PolySynth manages polyphony and rendering of SynthVoice instances. More...

#include <C:/Users/Andres/source/repos/casm_viewer/external/tinc/external/allolib/include/al/scene/al_PolySynth.hpp>

Inheritance diagram for al::PolySynth:

Public Types
typedef const std::function< void(AudioIOData &internalVoiceIO, Pose &channelPose)>	BusRoutingCallback

Public Member Functions
	PolySynth (TimeMasterMode masterMode=TimeMasterMode::TIME_MASTER_AUDIO)

int	triggerOn (SynthVoice voice, int offsetFrames=0, int id=-1, void userData=nullptr)
	trigger Puts voice in active voice lit and calls triggerOn() for it More...

void	triggerOff (int id)
	trigger release of voice with id

virtual void	allNotesOff ()
	Turn off all notes immediately (without calling triggerOff() )

template<class TSynthVoice >
TSynthVoice *	getVoice (bool forceAlloc=false)
	Get a reference to a voice. More...

SynthVoice *	getVoice (std::string name, bool forceAlloc=false)
	Get a reference to a free voice by voice type name. More...

SynthVoice *	getFreeVoice ()
	Get the first available voice with minimal checks. More...

virtual void	render (AudioIOData &io)
	render all the active voices into the audio buffers More...

virtual void	render (Graphics &g)
	render graphics for all active voices

virtual void	update (double dt=0)
	update internal state for all voices.

template<class TSynthVoice >
void	allocatePolyphony (int number)

template<class TSynthVoice >
void	disableAllocation ()

void	disableAllocation (std::string name)

void	allocatePolyphony (std::string name, int number)

void	insertFreeVoice (SynthVoice *voice)
	Use this function to insert a voice allocated externally into the free voice pool. More...

bool	popFreeVoice (SynthVoice *voice)
	Remove voice from the free voice pool. More...

void	setDefaultUserData (void *userData)
	Set default user data to set to voices before the are returned by getVoice() More...

void	setTimeMaster (TimeMasterMode masterMode)
	Set time master context. More...

PolySynth &	append (AudioCallback &v)
	Insert an AudioCallback object at the end of the callback queue. More...

PolySynth &	prepend (AudioCallback &v)
	Insert an AudioCallback object at the head of the callback queue. More...

PolySynth &	insertBefore (AudioCallback &v, AudioCallback &beforeThis)
	Insert an AudioCallback object before another in the queue. More...

PolySynth &	insertAfter (AudioCallback &v, AudioCallback &afterThis)
	Insert an AudioCallback object after another in the queue. More...

PolySynth &	remove (AudioCallback &v)
	Remove an AudioCallback object from the queue. More...

void	print (std::ostream &stream=std::cout)
	prints details of the allocated voices (free, active and queued) More...

void	gain (float gainValue)
	Set audio output gain. More...

float	gain ()
	get current audio gain More...

void	registerTriggerOnCallback (std::function< bool(SynthVoice voice, int offsetFrames, int id, void userData)> cb, void *userData=nullptr)
	register a callback to be notified of a trigger on event

void	registerTriggerOffCallback (std::function< bool(int id, void userData)> cb, void userData=nullptr)
	register a callback to be notified of a trigger off event

void	registerFreeCallback (std::function< bool(int id, void userData)> cb, void userData=nullptr)
	register a callback to be notified of a note is moved to the free pool from the active list

void	registerAllocateCallback (std::function< void(SynthVoice voice, void )> cb, void *userData=nullptr)
	register a callback to be notified of allocation of a voice.

template<class TSynthVoice >
void	registerSynthClass (std::string name="", bool allowAutoAllocation=true)

SynthVoice *	allocateVoice (std::string name)

template<class TSynthVoice >
TSynthVoice *	allocateVoice ()

bool	verbose ()

void	verbose (bool verbose)

SynthVoice *	getActiveVoices ()

SynthVoice *	getFreeVoices ()
	getFreeVoices More...

void	setVoiceMaxOutputChannels (uint16_t channels)
	Determines the number of output channels allocated for the internal AudioIOData objects. More...

void	setVoiceBusChannels (uint16_t channels)
	Determines the number of buses for the internal AudioIOData objects. More...

void	setBusRoutingCallback (BusRoutingCallback cb)
	setBusRoutingCallback More...

void	setChannelMap (std::vector< size_t > channelMap)
	Set channel map for output. More...

void	setCpuClockGranularity (double timeSecs)
	Set the time in seconds to wait between sequencer updates when time master is CPU. More...

void	processVoices ()
	Add new voices to the chain. More...

void	processVoiceTurnOff ()
	Check for voices that need trigger off and execute. More...

void	processInactiveVoices ()
	Check for voices marked as free and move them to the free voice pool. More...

Protected Types
typedef std::pair< std::function< bool(SynthVoice voice, int offsetFrames, int id, void )>, void * >	TriggerOnCallback

typedef std::pair< std::function< bool(int id, void )>, void >	TriggerOffCallback

typedef std::pair< std::function< bool(int id, void )>, void >	FreeCallback

typedef std::pair< std::function< void(SynthVoice voice, void )>, void * >	AllocationCallback

typedef std::function< SynthVoice *()>	VoiceCreatorFunc

typedef std::map< std::string, VoiceCreatorFunc >	Creators

Protected Member Functions
void	startCpuClockThread ()

void	processGain (AudioIOData &io)

virtual void	prepare (AudioIOData &io)

Protected Attributes
SynthVoice *	mVoicesToInsert {nullptr}

SynthVoice *	mFreeVoices {nullptr}
	Allocated voices available for reuse.

SynthVoice *	mActiveVoices {nullptr}

std::mutex	mVoiceToInsertLock

std::mutex	mFreeVoiceLock

std::mutex	mGraphicsLock

bool	m_useInternalAudioIO = true

bool	m_internalAudioConfigured = false

uint16_t	mVoiceMaxOutputChannels = 2

uint16_t	mVoiceMaxInputChannels = 0

uint16_t	mVoiceBusChannels = 0

std::shared_ptr< BusRoutingCallback >	mBusRoutingCallback

AudioIOData	internalAudioIO

SingleRWRingBuffer	mVoiceIdsToTurnOff {64 * sizeof(int)}

SingleRWRingBuffer	mVoiceIdsToFree {64 * sizeof(int)}

TimeMasterMode	mMasterMode

std::vector< AudioCallback * >	mPostProcessing

std::vector< TriggerOnCallback >	mTriggerOnCallbacks

std::vector< TriggerOffCallback >	mTriggerOffCallbacks

std::vector< FreeCallback >	mFreeCallbacks

std::vector< AllocationCallback >	mAllocationCallbacks

float	mAudioGain {1.0f}

int	mIdCounter {1000}

bool	mAllNotesOff {false}

void *	mDefaultUserData {nullptr}

Creators	mCreators

std::vector< std::string >	mNoAllocationList

std::vector< size_t >	mChannelMap

bool	mRunCPUClock {true}

double	mCpuGranularitySec = 0.001

std::unique_ptr< std::thread >	mCpuClockThread

bool	mVerbose {false}

Friends
class	SynthSequencer

Detailed Description

A PolySynth manages polyphony and rendering of SynthVoice instances.

Definition at line 434 of file al_PolySynth.hpp.

Member Function Documentation

◆ allocatePolyphony() [1/2]

template<class TSynthVoice >

void al::PolySynth::allocatePolyphony ( int number )

Preallocate a number of voices of a particular TSynthVoice to avoid doing realtime allocation.

Definition at line 1073 of file al_PolySynth.hpp.

◆ allocatePolyphony() [2/2]

void al::PolySynth::allocatePolyphony	(	std::string	name,
		int	number
	)

Preallocate a number of voices of a voice to avoid doing realtime allocation. The name must be registered using registerSynthClass()

◆ append()

PolySynth& al::PolySynth::append ( AudioCallback & v )

Insert an AudioCallback object at the end of the callback queue.

Parameters

v	The AudioCallback object

Returns: this instance

The callback provided is appended to the list of post processing callbacks. The post processing callbacks are run in sequence after the audio from all voices has been rendered. This can be useful for global effects, spatialization, etc.

◆ gain() [1/2]

float al::PolySynth::gain ( )

inline

get current audio gain

Returns

Definition at line 653 of file al_PolySynth.hpp.

◆ gain() [2/2]

void al::PolySynth::gain ( float gainValue )

inline

Set audio output gain.

Parameters

gainValue

Definition at line 647 of file al_PolySynth.hpp.

◆ getFreeVoice()

SynthVoice* al::PolySynth::getFreeVoice ( )

Get the first available voice with minimal checks.

Parameters

forceAlloc

Returns

This is a quick function with littl eoverhead for PolySynths that handle only one type of voice.

◆ getFreeVoices()

SynthVoice* al::PolySynth::getFreeVoices ( )

inline

getFreeVoices

Returns

This function is unsafe and should be used with extreme care. Ensure that no allocation, voice insertion or removal takes place while working with these voices.

Definition at line 742 of file al_PolySynth.hpp.

◆ getVoice() [1/2]

template<class TSynthVoice >

TSynthVoice * al::PolySynth::getVoice ( bool forceAlloc = false )

Get a reference to a voice.

Parameters

forceAlloc force allocation of voice even if maximum allowed polyphony is reached

Returns

Returns a free voice from the internal dynamic allocated pool. You must call triggerVoice to put the voice back in the rendering chain after setting its properties, otherwise it will be lost.

Definition at line 1030 of file al_PolySynth.hpp.

◆ getVoice() [2/2]

SynthVoice* al::PolySynth::getVoice	(	std::string	name,
		bool	forceAlloc = `false`
	)

Get a reference to a free voice by voice type name.

Parameters

forceAlloc force allocation of voice even if maximum allowed polyphony is reached

Returns

Returns a free voice from the internal dynamic allocated pool. If voice is not available. It will be allocated. Can return nullptr if the class name and creator have not been registered with registerSynthClass()

◆ insertAfter()

PolySynth& al::PolySynth::insertAfter	(	AudioCallback &	v,
		AudioCallback &	afterThis
	)

Insert an AudioCallback object after another in the queue.

Parameters

v	The AudioCallback object
beforeThis	The callback that will come before v

Returns: this instance

The callback provided is inserted into the list of post processing callbacks.

The post processing callbacks are run in sequence after the audio from all voices has been rendered. This can be useful for global effects, spatialization, etc.

If afterThis is not found v is prepended to the callback list

◆ insertBefore()

PolySynth& al::PolySynth::insertBefore	(	AudioCallback &	v,
		AudioCallback &	beforeThis
	)

Insert an AudioCallback object before another in the queue.

Parameters

v	The AudioCallback object
beforeThis	The callback that will come after v

Returns: this instance

The callback provided is inserted into the list of post processing callbacks.

The post processing callbacks are run in sequence after the audio from all voices has been rendered. This can be useful for global effects, spatialization, etc.

If beforeThis is not found v is prepended to the callback list

◆ insertFreeVoice()

void al::PolySynth::insertFreeVoice ( SynthVoice * voice )

Use this function to insert a voice allocated externally into the free voice pool.

Parameters

voice the new voice to be added to the free voice pool

You can also use this function to return to the polysynth a voice requested that will not be used.

◆ popFreeVoice()

bool al::PolySynth::popFreeVoice ( SynthVoice * voice )

Remove voice from the free voice pool.

Parameters

voice

◆ prepend()

PolySynth& al::PolySynth::prepend ( AudioCallback & v )

Insert an AudioCallback object at the head of the callback queue.

Parameters

v	The AudioCallback object

Returns: this instance

The callback provided is prepended to the list of post processing callbacks. The post processing callbacks are run in sequence after the audio from all voices has been rendered. This can be useful for global effects, spatialization, etc.

◆ print()

void al::PolySynth::print ( std::ostream & stream = std::cout )

prints details of the allocated voices (free, active and queued)

Warning: this function is not thread safe and might crash if the audio or graphics is running. Only use for temporary debugging.

◆ processInactiveVoices()

void al::PolySynth::processInactiveVoices ( )

inline

Check for voices marked as free and move them to the free voice pool.

You need to call this function only if you are in TIME_MASTER_FREE mode. In other modes it is called in the render() function for the domain.

Definition at line 898 of file al_PolySynth.hpp.

◆ processVoices()

void al::PolySynth::processVoices ( )

inline

Add new voices to the chain.

You need to call this function only if you are in TIME_MASTER_FREE mode. In other modes it is called in the render() function for the domain.

Definition at line 804 of file al_PolySynth.hpp.

◆ processVoiceTurnOff()

void al::PolySynth::processVoiceTurnOff ( )

inline

Check for voices that need trigger off and execute.

You need to call this function only if you are in TIME_MASTER_FREE mode. In other modes it is called in the render() function for the domain.

Definition at line 855 of file al_PolySynth.hpp.

◆ registerSynthClass()

template<class TSynthVoice >

void al::PolySynth::registerSynthClass	(	std::string	name = `""`,
		bool	allowAutoAllocation = `true`
	)

inline

Register a SynthVoice class to allow instantiating it by name

This is needed for remote instantiation and for text sequence playback.

Definition at line 690 of file al_PolySynth.hpp.

◆ remove()

PolySynth& al::PolySynth::remove ( AudioCallback & v )

Remove an AudioCallback object from the queue.

Parameters

v	The AudioCallback object

Returns: this instance

The callback provided is removed from the list of post processing callbacks.

If v is not found, this call has no effect.

◆ render()

virtual void al::PolySynth::render ( AudioIOData & io )

virtual

render all the active voices into the audio buffers

Parameters

io	AudioIOData containing buffers and audio I/O meta data

Reimplemented in al::DynamicScene.

◆ setBusRoutingCallback()

void al::PolySynth::setBusRoutingCallback ( BusRoutingCallback cb )

setBusRoutingCallback

Parameters

cb	This function will be called after all voices have rendered their output and prior to the function call to process spatialization. Can be used to route signals to buses.

◆ setChannelMap()

void al::PolySynth::setChannelMap ( std::vector< size_t > channelMap )

Set channel map for output.

Parameters

channelMap The index into the vector refers to the output channel in the voice buffer, the value is the channel index to write for audio output. This operation should be performed only when audio is not running. Channel mapping is ignored in DynamicScene and DistributedScene.

◆ setCpuClockGranularity()

void al::PolySynth::setCpuClockGranularity ( double timeSecs )

inline

Set the time in seconds to wait between sequencer updates when time master is CPU.

This has no effect if time master mode is not TIME_MASTER_CPU

Definition at line 794 of file al_PolySynth.hpp.

◆ setDefaultUserData()

void al::PolySynth::setDefaultUserData ( void * userData )

inline

Set default user data to set to voices before the are returned by getVoice()

Parameters

userData

Definition at line 550 of file al_PolySynth.hpp.

◆ setTimeMaster()

void al::PolySynth::setTimeMaster ( TimeMasterMode masterMode )

Set time master context.

Parameters

master domain

You should not call this function if any of the rendering domains are running.

◆ setVoiceBusChannels()

void al::PolySynth::setVoiceBusChannels ( uint16_t channels )

inline

Determines the number of buses for the internal AudioIOData objects.

Parameters

channels Always call prepare() after calling this function. The changes are only applied by prepare().

Definition at line 761 of file al_PolySynth.hpp.

◆ setVoiceMaxOutputChannels()

void al::PolySynth::setVoiceMaxOutputChannels ( uint16_t channels )

Determines the number of output channels allocated for the internal AudioIOData objects.

Parameters

channels Always call prepare() after calling this function. The changes are only applied by prepare().

◆ triggerOn()

int al::PolySynth::triggerOn	(	SynthVoice *	voice,
		int	offsetFrames = `0`,
		int	id = `-1`,
		void *	userData = `nullptr`
	)

trigger Puts voice in active voice lit and calls triggerOn() for it

Parameters

voice pointer to the voice to trigger

Returns: a unique id for the voice

You can use the id to identify the note for later triggerOff() calls. Always use a positive value for id, as negative ids have special treatment in classes like this one and SynthGUIManager

Member Data Documentation

◆ mActiveVoices

SynthVoice* al::PolySynth::mActiveVoices {nullptr}

protected

Dynamic voices that are currently active. Only modified within the master domain (set by mMasterMode)

Definition at line 963 of file al_PolySynth.hpp.

◆ mVoicesToInsert

SynthVoice* al::PolySynth::mVoicesToInsert {nullptr}

protected

Voices to be inserted in the realtime context. Internal voices are allocated in PolySynth and shared with the outside.

Definition at line 958 of file al_PolySynth.hpp.

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

al_PolySynth.hpp

Public Types

Public Member Functions

Protected Types

Protected Member Functions

Protected Attributes

Friends

Detailed Description

Member Function Documentation

◆ allocatePolyphony() [1/2]

◆ allocatePolyphony() [2/2]

◆ append()

◆ gain() [1/2]

◆ gain() [2/2]

◆ getFreeVoice()

◆ getFreeVoices()

◆ getVoice() [1/2]

◆ getVoice() [2/2]

◆ insertAfter()

◆ insertBefore()

◆ insertFreeVoice()

◆ popFreeVoice()

◆ prepend()

◆ print()

◆ processInactiveVoices()

◆ processVoices()

◆ processVoiceTurnOff()

◆ registerSynthClass()

◆ remove()

◆ render()

◆ setBusRoutingCallback()

◆ setChannelMap()

◆ setCpuClockGranularity()

◆ setDefaultUserData()

◆ setTimeMaster()

◆ setVoiceBusChannels()

◆ setVoiceMaxOutputChannels()

◆ triggerOn()

Member Data Documentation

◆ mActiveVoices

◆ mVoicesToInsert