#include <CUAudioMixer.h>

Inheritance diagram for cugl::audio::AudioMixer:

Public Member Functions
	AudioMixer ()

	~AudioMixer ()

virtual bool	init () override

bool	init (Uint8 width)

virtual bool	init (Uint8 channels, Uint32 rate) override

bool	init (Uint8 width, Uint8 channels, Uint32 rate)

virtual void	dispose () override

std::shared_ptr< AudioNode >	attach (Uint8 slot, const std::shared_ptr< AudioNode > &input)

std::shared_ptr< AudioNode >	detach (Uint8 slot)

virtual bool	completed () override

virtual Uint32	read (float *buffer, Uint32 frames) override

Uint8	getWidth () const

bool	setWidth (Uint8 width)

virtual void	setReadSize (Uint32 size) override

float	getKnee () const

void	setKnee (float knee)

virtual bool	mark () override

virtual bool	unmark () override

virtual bool	reset () override

virtual Sint64	advance (Uint32 frames) override

virtual Sint64	getPosition () const override

virtual Sint64	setPosition (Uint32 position) override

virtual double	getElapsed () const override

virtual double	setElapsed (double time) override

virtual double	getRemaining () const override

virtual double	setRemaining (double time) override

Public Member Functions inherited from cugl::audio::AudioNode
	AudioNode ()

virtual	~AudioNode ()

virtual bool	init ()

virtual bool	init (Uint8 channels, Uint32 rate)

virtual void	dispose ()

Uint8	getChannels () const

Uint32	getRate () const

float	getGain ()

virtual void	setGain (float gain)

Uint32	getReadSize () const

virtual void	setReadSize (Uint32 size)

const std::string	getClassName () const

const std::string	getName () const

void	setName (const std::string name)

Sint32	getTag () const

void	setTag (Sint32 tag)

virtual std::string	toString (bool verbose=false) const

	operator std::string () const

Callback	getCallback ()

void	setCallback (Callback callback)

virtual bool	isPaused ()

virtual bool	pause ()

virtual bool	resume ()

virtual bool	completed ()

virtual Uint32	read (float *buffer, Uint32 frames)

virtual bool	mark ()

virtual bool	unmark ()

virtual bool	reset ()

virtual Sint64	advance (Uint32 frames)

virtual Sint64	getPosition () const

virtual Sint64	setPosition (Uint32 position)

virtual double	getElapsed () const

virtual double	setElapsed (double time)

virtual double	getRemaining () const

virtual double	setRemaining (double time)

Static Public Member Functions
static std::shared_ptr< AudioMixer >	alloc (Uint8 width=8)

static std::shared_ptr< AudioMixer >	alloc (Uint8 width, Uint8 channels, Uint32 rate)

Static Public Attributes
static const Uint8	DEFAULT_WIDTH

static const float	DEFAULT_KNEE

Static Public Attributes inherited from cugl::audio::AudioNode
static const Uint32	DEFAULT_CHANNELS

static const Uint32	DEFAULT_SAMPLING

Additional Inherited Members
Public Types inherited from cugl::audio::AudioNode
enum	Action : int { COMPLETE = 0 , INTERRUPT = 1 , FADE_OUT = 2 , FADE_IN = 3 , FADE_DIP = 4 , LOOPBACK = 5 }

typedef std::function< void(const std::shared_ptr< AudioNode > &node, Action type)>	Callback

Protected Member Functions inherited from cugl::audio::AudioNode
void	notify (const std::shared_ptr< AudioNode > &node, Action action)

Protected Attributes inherited from cugl::audio::AudioNode
Uint8	_channels

Uint32	_sampling

bool	_booted

std::atomic< float >	_ndgain

std::atomic< bool >	_paused

std::atomic< bool >	_polling

Callback	_callback

std::atomic< bool >	_calling

Sint32	_tag

Uint32	_readsize

std::string	_localname

std::string	_classname

size_t	_hashOfName

bool	_locked

Detailed Description

This class represents an audio mixer.

This mixer can take (a fixed number of) input streams and combine them together into a single output stream. The input streams must all have the same number of channels and sample rate as this node.

Mixing works by adding together all of the streams. This means that the results may exceed the range [-1,1], causing clipping. The mixer provides a "soft-knee" option (disabled by default) for confining the results to the range [-1,1]. When a knee k is specified, all values [-k,k] will not be effected, but values outside of this range will asymptotically bend to the range [-1,1].

The audio graph should only be accessed in the main thread. In addition, no methods marked as AUDIO THREAD ONLY should ever be accessed by the user.

This class does not support any actions for the AudioNode#setCallback.

Constructor & Destructor Documentation

◆ AudioMixer()

cugl::audio::AudioMixer::AudioMixer ( )

Creates a degenerate mixer that takes no inputs

The mixer has no width and therefore cannot accept any inputs. The mixer must be initialized to be used.

◆ ~AudioMixer()

cugl::audio::AudioMixer::~AudioMixer ( )

inline

Deletes this mixer, disposing of all resources.

Member Function Documentation

◆ advance()

virtual Sint64 cugl::audio::AudioMixer::advance ( Uint32 frames )

overridevirtual

Advances the stream by the given number of frames.

DELEGATED METHOD: This method delegates its call to all currently attached input nodes. It returns -1 if there are no attached input nodes, or if just one of the input nodes cannot be advanced. However, any input that was successfully advanced remains advanced.

This method is ideal for a mixer composed of AudioPlayer objects. It will equally reset all of the components, keeping them in sync.

Parameters

frames The number of frames to advace

Returns: the actual number of frames advanced; -1 if not supported

Reimplemented from cugl::audio::AudioNode.

◆ alloc() [1/2]

static std::shared_ptr< AudioMixer > cugl::audio::AudioMixer::alloc	(	Uint8	width,
		Uint8	channels,
		Uint32	rate
	)

inlinestatic

Returns a newly allocated mixer with the given number of channels and sample rate

These values determine the buffer the structure for all read operations. In addition, they also detemine exactly which audio nodes are supported by this mixer. A mixer can only mix nodes that agree on both sample rate and frequency.

Parameters

width	The number of audio nodes that may be attached to this mixer
channels	The number of audio channels
rate	The sample rate (frequency) in HZ

Returns: a newly allocated mixer with the given number of channels and sample rate

◆ alloc() [2/2]

static std::shared_ptr< AudioMixer > cugl::audio::AudioMixer::alloc ( Uint8 width = 8 )

inlinestatic

Returns a newly allocated mixer with default stereo settings

The number of channels is two, for stereo output. The sample rate is the modern standard of 48000 HZ.

These values determine the buffer the structure for all read operations. In addition, they also detemine exactly which audio nodes are supported by this mixer. A mixer can only mix nodes that agree on both sample rate and frequency.

Parameters

width The number of audio nodes that may be attached to this mixer

Returns: a newly allocated mixer with default stereo settings

◆ attach()

std::shared_ptr< AudioNode > cugl::audio::AudioMixer::attach	(	Uint8	slot,
		const std::shared_ptr< AudioNode > &	input
	)

Attaches an input node to this mixer.

The input is attached at the given slot. Any input node previously at that slot is removed (and returned by this method).

Parameters

slot	The slot for the input node
input	The input node to attach

Returns: the input node previously at the given slot

◆ completed()

virtual bool cugl::audio::AudioMixer::completed ( )

overridevirtual

Returns true if this audio node has no more data.

DELEGATED METHOD: This method delegates its call to all currently attached input nodes. It returns true if there are no attached input nodes, or if all of the input nodes are complete.

An audio node is typically completed if it return 0 (no frames read) on subsequent calls to read().

Returns: true if this audio node has no more data.

Reimplemented from cugl::audio::AudioNode.

◆ detach()

std::shared_ptr< AudioNode > cugl::audio::AudioMixer::detach ( Uint8 slot )

Detaches the input node at the given slot.

The input node detached is returned by this method.

Parameters

slot	The slot for the input node

Returns: the input node detached from the slot

◆ dispose()

virtual void cugl::audio::AudioMixer::dispose ( )

overridevirtual

Disposes any resources allocated for this mixer

The state of the node is reset to that of an uninitialized constructor. Unlike the destructor, this method allows the node to be reinitialized.

Reimplemented from cugl::audio::AudioNode.

◆ getElapsed()

virtual double cugl::audio::AudioMixer::getElapsed ( ) const

overridevirtual

Returns the elapsed time in seconds.

If mark() was called previously, this value is the number of seconds since the mark. Otherwise, it is the number of seconds since the start of this stream. Calling reset() will reset this position even if not all of the inputs were reset.

This method is ideal for a mixer composed of AudioPlayer objects. In that case, it will return the synchronous elapsed time of all of the players.

Returns: the elapsed time in seconds.

Reimplemented from cugl::audio::AudioNode.

◆ getKnee()

float cugl::audio::AudioMixer::getKnee ( ) const

Returns the "soft knee" of this mixer, or -1 if not set

The soft knee is used to ensure that the results fit in the range [-1,1]. If the knee is k, then values in the range [-k,k] are unaffected, but values outside of this range are asymptotically clamped to the range [-1,1], using the formula (x-k+k*k)/x.

If the value is 0, then this mixer will hard clamp to [-1,1]. If it is negative, all inputs will be mixed exactly with no distortion.

Returns: the "soft knee" of this mixer, or -1 if not set

◆ getPosition()

virtual Sint64 cugl::audio::AudioMixer::getPosition ( ) const

overridevirtual

Returns the current frame position of this audio node

If mark() was called previously, this value is the number of frames since the mark. Otherwise, it is the number of frames since the start of this stream. Calling reset() will reset this position even if not all of the inputs were reset.

This method is ideal for a mixer composed of AudioPlayer objects. In that case, it will return the synchronous position of all of the players.

Returns: the current frame position of this audio node.

Reimplemented from cugl::audio::AudioNode.

◆ getRemaining()

virtual double cugl::audio::AudioMixer::getRemaining ( ) const

overridevirtual

Returns the remaining time in seconds.

DELEGATED METHOD: This method delegates its call to all currently attached input nodes. The value returned is the maximum value across all nodes. It returns -1 if there are no attached input node, or if any attached node does not support this method.

This method is ideal for a mixer composed of AudioPlayer objects. In that case, it will return the maximum remaining time across all of the players.

Returns: the remaining time in seconds.

Reimplemented from cugl::audio::AudioNode.

◆ getWidth()

Uint8 cugl::audio::AudioMixer::getWidth ( ) const

inline

Returns the width of this mixer.

The width is the number of supported input slots.

Returns: the width of this mixer.

◆ init() [1/4]

virtual bool cugl::audio::AudioMixer::init ( )

overridevirtual

Initializes the mixer with default stereo settings

The number of channels is two, for stereo output. The sample rate is the modern standard of 48000 HZ.

These values determine the buffer the structure for all read operations. In addition, they also detemine exactly which audio nodes are supported by this mixer. A mixer can only mix nodes that agree on both sample rate and frequency.

Returns: true if initialization was successful

Reimplemented from cugl::audio::AudioNode.

◆ init() [2/4]

virtual bool cugl::audio::AudioMixer::init	(	Uint8	channels,
		Uint32	rate
	)

overridevirtual

Initializes the mixer with the given number of channels and sample rate

These values determine the buffer the structure for all read operations. In addition, they also detemine exactly which audio nodes are supported by this mixer. A mixer can only mix nodes that agree on both sample rate and frequency.

Parameters

channels	The number of audio channels
rate	The sample rate (frequency) in HZ

Returns: true if initialization was successful

Reimplemented from cugl::audio::AudioNode.

◆ init() [3/4]

bool cugl::audio::AudioMixer::init ( Uint8 width )

Initializes the mixer with default stereo settings

The number of channels is two, for stereo output. The sample rate is the modern standard of 48000 HZ.

These values determine the buffer the structure for all read operations. In addition, they also detemine exactly which audio nodes are supported by this mixer. A mixer can only mix nodes that agree on both sample rate and frequency.

Parameters

width The number of audio nodes that may be attached to this mixer

Returns: true if initialization was successful

◆ init() [4/4]

bool cugl::audio::AudioMixer::init	(	Uint8	width,
		Uint8	channels,
		Uint32	rate
	)

Initializes the mixer with the given number of channels and sample rate

These values determine the buffer the structure for all read operations. In addition, they also detemine exactly which audio nodes are supported by this mixer. A mixer can only mix nodes that agree on both sample rate and frequency.

Parameters

width	The number of audio nodes that may be attached to this mixer
channels	The number of audio channels
rate	The sample rate (frequency) in HZ

Returns: true if initialization was successful

◆ mark()

virtual bool cugl::audio::AudioMixer::mark ( )

overridevirtual

Marks the current read position in the audio steam.

DELEGATED METHOD: This method delegates its call to all currently attached input nodes. It returns false if there are no attached input nodes, or if just one of the input nodes does not support marking. However, any input that was successfully marked remains marked.

This method is typically used by reset() to determine where to restore the read position. For some nodes (like AudioInput), this method may start recording data to a buffer, which will continue until reset() is called.

Input nodes added to the mixer after this method is called are not affected.

Returns: true if the read position was marked across all inputs.

Reimplemented from cugl::audio::AudioNode.

◆ read()

virtual Uint32 cugl::audio::AudioMixer::read	(	float *	buffer,
		Uint32	frames
	)

overridevirtual

Reads up to the specified number of frames into the given buffer

AUDIO THREAD ONLY: Users should never access this method directly, unless part of a custom audio graph node.

The buffer should have enough room to store frames * channels elements. The channels are interleaved into the output buffer.

Reading the buffer has no affect on the read position. You must manually move the frame position forward. This is to allow for a frame window to be reread if necessary.

Parameters

buffer	The read buffer to store the results
frames	The maximum number of frames to read

Returns: the actual number of frames read

Reimplemented from cugl::audio::AudioNode.

◆ reset()

virtual bool cugl::audio::AudioMixer::reset ( )

overridevirtual

Resets the read position to the marked position of the audio stream.

DELEGATED METHOD: This method delegates its call to all currently attached input nodes. It returns false if there are no attached input nodes, or if just one of the input nodes cannot be reset. However, However, any input that was successfully reset remains reset.

This method is ideal for a mixer composed of AudioPlayer objects. It will equally unmark all of the components, keeping them in sync.

Returns: true if the read position was moved.

Reimplemented from cugl::audio::AudioNode.

◆ setElapsed()

virtual double cugl::audio::AudioMixer::setElapsed ( double time )

overridevirtual

Sets the read position to the elapsed time in seconds.

DELEGATED METHOD: This method delegates its call to all currently attached input nodes. It returns -1 if there are no attached input nodes, or if just one of the input nodes cannot be repositioned. However, any input that was successfully repositioned remains repositioned.

This method is ideal for a mixer composed of AudioPlayer objects. In that case, it will set the synchronous position of all of the players.

Parameters

time	The elapsed time in seconds.

Returns: the new elapsed time in seconds.

Reimplemented from cugl::audio::AudioNode.

◆ setKnee()

void cugl::audio::AudioMixer::setKnee ( float knee )

Sets the "soft knee" of this mixer.

The soft knee is used to ensure that the results fit in the range [-1,1]. If the knee is k, then values in the range [-k,k] are unaffected, but values outside of this range are asymptotically clamped to the range [-1,1], using the formula (x-k+k*k)/x

If the value is 0, then this mixer will hard clamp to [-1,1]. If it is negative, all inputs will be mixed exactly with no distortion.

Parameters

knee	the "soft knee" of this mixer

◆ setPosition()

virtual Sint64 cugl::audio::AudioMixer::setPosition ( Uint32 position )

overridevirtual

Sets the current frame position of this audio node.

DELEGATED METHOD: This method delegates its call to all currently attached input nodes. It returns -1 if there are no attached input nodes, or if just one of the input nodes cannot be repositioned. However, any input that was successfully repositioned remains repositioned.

This method is ideal for a mixer composed of AudioPlayer objects. In that case, it will set the synchronous position of all of the players.

Parameters

position the current frame position of this audio node.

Returns: the new frame position of this audio node.

Reimplemented from cugl::audio::AudioNode.

◆ setReadSize()

virtual void cugl::audio::AudioMixer::setReadSize ( Uint32 size )

overridevirtual

Sets the typical read size of this node.

Some audio nodes need an internal buffer for operations like mixing or resampling. In that case, it helps to know the requested read size ahead of time. The capacity is the minimal required read amount of the AudioEngine and corresponds to AudioEngine#getReadSize.

It is not actually necessary to set this size. However for nodes with internal buffer, setting this value can optimize performance.

This method is not synchronized because it is assumed that this value will never change while the audio engine in running. The average user should never call this method explicitly. You should always call AudioEngine#setReadSize instead.

Parameters

size	The typical read size of this node.

Reimplemented from cugl::audio::AudioNode.

◆ setRemaining()

virtual double cugl::audio::AudioMixer::setRemaining ( double time )

overridevirtual

Sets the remaining time in seconds.

DELEGATED METHOD: This method delegates its call to all currently attached input nodes. The value set is the relative to the maximum remaining time across all inputs. Any input with less than the remaining time is advanced forward so that it remains in sync with the maximal input.

This method returns returns -1 if there are no attached input node, or if any attached node does not support this method. However, any repositioned input will remain repositioned.

This method is ideal for a mixer composed of AudioPlayer objects. In that case, it will set the synchronous position of all of the players.

Parameters

time	The remaining time in seconds.

Returns: the new remaining time in seconds.

Reimplemented from cugl::audio::AudioNode.

◆ setWidth()

bool cugl::audio::AudioMixer::setWidth ( Uint8 width )

Sets the width of this mixer.

The width is the number of supported input slots. This method will only succeed if the mixer is paused. Otherwise, it will fail.

Once the width is adjusted, the children will be reassigned in order. If the new width is less than the old width, children at the end of the mixer will be dropped.

Returns: true if the mixer width was reset

◆ unmark()

virtual bool cugl::audio::AudioMixer::unmark ( )

overridevirtual

Clears the current marked position.

DELEGATED METHOD: This method delegates its call to all currently attached input nodes. It returns false if there are no attached input nodes, or if just one of the input nodes does not support marking. However, any input that was successfully unmarked remains unmarked.

If the method mark() started recording to a buffer (such as with AudioInput), this method will stop recording and release the buffer. When the mark is cleared, reset() may or may not work depending upon the specific node.

This method is ideal for a mixer composed of AudioPlayer objects. It will equally mark all of the components, keeping them in sync.

Returns: true if the read position was marked.

Reimplemented from cugl::audio::AudioNode.

Member Data Documentation

◆ DEFAULT_KNEE

const float cugl::audio::AudioMixer::DEFAULT_KNEE

static

The standard knee value for preventing clipping

◆ DEFAULT_WIDTH

const Uint8 cugl::audio::AudioMixer::DEFAULT_WIDTH

static

The default number of inputs supported (typically 8)

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

cugl/include/cugl/audio/graph/CUAudioMixer.h

Public Member Functions

Static Public Member Functions

Static Public Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ AudioMixer()

◆ ~AudioMixer()

Member Function Documentation

◆ advance()

◆ alloc() [1/2]

◆ alloc() [2/2]

◆ attach()

◆ completed()

◆ detach()

◆ dispose()

◆ getElapsed()

◆ getKnee()

◆ getPosition()

◆ getRemaining()

◆ getWidth()

◆ init() [1/4]

◆ init() [2/4]

◆ init() [3/4]

◆ init() [4/4]

◆ mark()

◆ read()

◆ reset()

◆ setElapsed()

◆ setKnee()

◆ setPosition()

◆ setReadSize()

◆ setRemaining()

◆ setWidth()

◆ unmark()

Member Data Documentation

◆ DEFAULT_KNEE

◆ DEFAULT_WIDTH