#include <CUAudioRedistributor.h>

Inheritance diagram for cugl::audio::AudioRedistributor:

Public Member Functions
	AudioRedistributor ()

	~AudioRedistributor ()

virtual bool	init () override

virtual bool	init (Uint8 channels, Uint32 rate) override

bool	init (const std::shared_ptr< AudioNode > &input, Uint8 channels)

bool	init (const std::shared_ptr< AudioNode > &input, Uint8 channels, const float *matrix)

virtual void	dispose () override

bool	attach (const std::shared_ptr< AudioNode > &node)

bool	attach (const std::shared_ptr< AudioNode > &node, const float *matrix)

std::shared_ptr< AudioNode >	detach ()

std::shared_ptr< AudioNode >	getInput ()

Uint8	getConduits () const

void	setConduits (Uint8 number)

void	setConduits (Uint8 number, const float *matrix)

const float *const	getMatrix ()

void	setMatrix (const float *matrix)

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

virtual bool	completed () override

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 ()

Uint8	getChannels () const

Uint32	getRate () const

float	getGain ()

virtual void	setGain (float gain)

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 ()

Static Public Member Functions
static std::shared_ptr< AudioRedistributor >	alloc ()

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

static std::shared_ptr< AudioRedistributor >	alloc (const std::shared_ptr< AudioNode > &input, Uint8 channels)

static std::shared_ptr< AudioRedistributor >	alloc (const std::shared_ptr< AudioNode > &input, Uint8 channels, const float *matrix)

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

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

const static Uint32	DEFAULT_SAMPLING

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

std::string	_localname

std::string	_classname

size_t	_hashOfName

Detailed Description

This class represents an audio channel redistributor.

A channel redistributor is a node whose input number of channels does not match the output number of channels. This is necessary for some latops, where the output sound card requires more than two channels, even though the vast majority of applications are designed for stereo (not surround) sound.

A channel redistributor works by using a matrix to redistribute the input channels, in much the same way that a matrix decoder works. However, unlike a matrix decoder, it is possible to use a redistributor to reduce the number of channels (with a matrix whose rows are less that is columns). Furthermore, a redistributor does not support phase shifting.

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

◆ AudioRedistributor()

cugl::audio::AudioRedistributor::AudioRedistributor ( )

Creates a degenerate channel redistributor.

The redistributor has no channels, so read options will do nothing. The node must be initialized to be used.

◆ ~AudioRedistributor()

cugl::audio::AudioRedistributor::~AudioRedistributor ( )

inline

Deletes this redistributor, disposing of all resources.

Member Function Documentation

◆ advance()

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

overridevirtual

Advances the stream by the given number of frames.

DELEGATED METHOD: This method delegates its call to the input node. It returns -1 if there is no input node, indicating it is unsupported.

This method only advances the read position, it does not actually read data into a buffer.

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/4]

static std::shared_ptr<AudioRedistributor> cugl::audio::AudioRedistributor::alloc ( )

inlinestatic

Returns a newly allocated redistributor 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 whether this node can serve as an input to other nodes in the audio graph.

Returns: a newly allocated redistributor with default stereo settings

◆ alloc() [2/4]

static std::shared_ptr<AudioRedistributor> cugl::audio::AudioRedistributor::alloc	(	const std::shared_ptr< AudioNode > &	input,
		Uint8	channels
	)

inlinestatic

Returns a newly allocated redistributor with the given input and number of channels

The node acquires the sample rate of the input, but uses the given number of channels as its output channels. The redistributor will use the default redistribution algorithm for the given number of channels. If input is nullptr, this method will fail.

Parameters

input	The audio node to redistribute
channels	The number of audio channels

Returns: a newly allocated redistributor with the given input and number of channels

◆ alloc() [3/4]

static std::shared_ptr<AudioRedistributor> cugl::audio::AudioRedistributor::alloc	(	const std::shared_ptr< AudioNode > &	input,
		Uint8	channels,
		const float *	matrix
	)

inlinestatic

Returns a newly allocated redistributor with the given input and matrix

The node acquires the sample rate of the input, but uses the given number of channels as its output channels. The redistributor will use the given matrix to redistribute the audio. If input is nullptr, this method will fail.

The matrix should be an MxN matrix in row major order, where N is the number of input channels and M is the number of output channels. The provided matrix will be copied. This method will not acquire ownership of the given matrix.

Parameters

input	The audio node to redistribute
channels	The number of audio channels
matrix	The redistribution matrix

Returns: a newly allocated redistributor with the given input and matrix

◆ alloc() [4/4]

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

inlinestatic

Returns a newly allocated redistributor 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 whether this node can serve as an input to other nodes in the audio graph.

Parameters

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

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

◆ attach() [1/2]

bool cugl::audio::AudioRedistributor::attach ( const std::shared_ptr< AudioNode > & node )

Attaches an audio node to this redistributor.

The redistributor will use the use the default redistribution algorithm for the current number of channels.

Parameters

node	The audio node to redistribute

Returns: true if the attachment was successful

◆ attach() [2/2]

bool cugl::audio::AudioRedistributor::attach	(	const std::shared_ptr< AudioNode > &	node,
		const float *	matrix
	)

Attaches an audio node to this redistributor.

The redistributor will use the given matrix to redistribute the audio. The matrix should be an MxN matrix in row major order, where N is the number of input channels and M is the number of output channels. The provided matrix will be copied. This method will not acquire ownership of the given matrix.

Parameters

node	The audio node to redistribute
matrix	The redistribution matrix

Returns: true if the attachment was successful

◆ completed()

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

overridevirtual

Returns true if this audio node has no more data.

DELEGATED METHOD: This method delegates its call to the input node. It returns true if there is no input node, indicating there is no data.

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::AudioRedistributor::detach ( )

Detaches an audio node from this redistributor.

If the method succeeds, it returns the audio node that was removed.

Returns: The audio node to detach (or null if failed)

◆ dispose()

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

overridevirtual

Disposes any resources allocated for this redistributor

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.

◆ getConduits()

Uint8 cugl::audio::AudioRedistributor::getConduits ( ) const

inline

Returns the number of input channels for this redistributor.

Normally this number is inferred from the whatever input node is attached to the redistributor. If no node has yet been attached, this this method returns 0 by default.

However, changing this value may require that the underlying read buffer be resized (particularly when the number of input channels is larger than the number of output channels.). Hence by setting this value ahead of time (and making sure that all attached input nodes match this size), you can improve the performance of this filter.

Assigning this value while there is still an attached audio node has undefined behavior.

Returns: the number of input channels for this redistributor.

◆ getElapsed()

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

overridevirtual

Returns the elapsed time in seconds.

DELEGATED METHOD: This method delegates its call to the input node. It returns -1 if there is no input node, indicating it is unsupported.

The value returned is always measured from the start of the steam, regardless of the presence of any marks.

Returns: the elapsed time in seconds.

Reimplemented from cugl::audio::AudioNode.

◆ getInput()

std::shared_ptr<AudioNode> cugl::audio::AudioRedistributor::getInput ( )

inline

Returns the input node of this redistributor.

Returns: the input node of this redistributor.

◆ getMatrix()

const float* const cugl::audio::AudioRedistributor::getMatrix ( )

Returns the current redistribution matrix for this redistributor.

The matrix will be an MxN matrix in row major order, where N is the number of input channels and M is the number of output channels. If the redistributor is currently using a default redistribution algorithm (based on the number of input channels), then this method will return nullptr.

Returns: the current redistribution matrix for this redistributor.

◆ getPosition()

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

overridevirtual

Returns the current frame position of this audio node

DELEGATED METHOD: This method delegates its call to the input node. It returns -1 if there is no input node, indicating it is unsupported.

The value returned will always be the absolute frame position regardless of the presence of any marks.

Returns: the current frame position of this audio node.

Reimplemented from cugl::audio::AudioNode.

◆ getRemaining()

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

overridevirtual

Returns the remaining time in seconds.

DELEGATED METHOD: This method delegates its call to the input node. It returns -1 if there is no input node, indicating it is unsupported.

The remaining time is duration from the current read position to the end of the sample. It is not effected by any fade-out.

Returns: the remaining time in seconds.

Reimplemented from cugl::audio::AudioNode.

◆ init() [1/4]

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

overridevirtual

Initializes the redistributor 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 whether this node can serve as an input to other nodes in the audio graph.

Returns: true if initialization was successful

Reimplemented from cugl::audio::AudioNode.

◆ init() [2/4]

bool cugl::audio::AudioRedistributor::init	(	const std::shared_ptr< AudioNode > &	input,
		Uint8	channels
	)

Initializes the redistributor with the given input and number of channels

The node acquires the sample rate of the input, but uses the given number of channels as its output channels. The redistributor will use the default redistribution algorithm for the given number of channels. If input is nullptr, this method will fail.

Parameters

input	The audio node to redistribute
channels	The number of audio channels

Returns: true if initialization was successful

◆ init() [3/4]

bool cugl::audio::AudioRedistributor::init	(	const std::shared_ptr< AudioNode > &	input,
		Uint8	channels,
		const float *	matrix
	)

Initializes the redistributor with the given input and matrix

The node acquires the sample rate of the input, but uses the given number of channels as its output channels. The redistributor will use the given matrix to redistribute the audio. If input is nullptr, this method will fail.

The matrix should be an MxN matrix in row major order, where N is the number of input channels and M is the number of output channels. The provided matrix will be copied. This method will not acquire ownership of the given matrix.

Parameters

input	The audio node to redistribute
channels	The number of audio channels
matrix	The redistribution matrix

Returns: true if initialization was successful

◆ init() [4/4]

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

overridevirtual

Initializes the redistributor 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 whether this node can serve as an input to other nodes in the audio graph.

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.

◆ mark()

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

overridevirtual

Marks the current read position in the audio steam.

DELEGATED METHOD: This method delegates its call to the input node. It returns false if there is no input node, indicating it is unsupported.

This method is used by reset() to determine where to restore the read position.

Returns: true if the read position was marked.

Reimplemented from cugl::audio::AudioNode.

◆ read()

virtual Uint32 cugl::audio::AudioRedistributor::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. The only exception is when the user needs to create a custom subclass of this AudioNode.

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

This method will always forward the read position after reading. Reading again may return different data.

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::AudioRedistributor::reset ( )

overridevirtual

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

DELEGATED METHOD: This method delegates its call to the input node. It returns false if there is no input node, indicating it is unsupported.

If no mark is set, this will reset to the player to the beginning of the audio sample.

Returns: true if the read position was moved.

Reimplemented from cugl::audio::AudioNode.

◆ setConduits() [1/2]

void cugl::audio::AudioRedistributor::setConduits ( Uint8 number )

Sets the number of input channels for this redistributor.

Normally this number is inferred from the whatever input node is attached to the redistributor. If no node has yet been attached, this this method returns 0 by default.

However, changing this value may require that the underlying read buffer be resized (particularly when the number of input channels is larger than the number of output channels.). Hence by setting this value ahead of time (and making sure that all attached input nodes match this size), you can improve the performance of this filter.

Assigning this value while there is still an attached audio node has undefined behavior.

Parameters

number The number of input channels for this redistributor.

◆ setConduits() [2/2]

void cugl::audio::AudioRedistributor::setConduits	(	Uint8	number,
		const float *	matrix
	)

Sets the number of input channels for this redistributor.

Normally this number is inferred from the whatever input node is attached to the redistributor. If no node has yet been attached, this this method returns 0 by default.

However, changing this value may require that the underlying read buffer be resized (particularly when the number of input channels is larger than the number of output channels.). Hence by setting this value ahead of time (and making sure that all attached input nodes match this size), you can improve the performance of this filter.

This version of the method will also allow you to set the matrix at the same time (so that it matches the number of input channels). The matrix will be an MxN matrix in row major order, where N is the number of input channels and M is the number of output channels. The provided matrix will be copied. This method will not acquire ownership of the given matrix.

Assigning this value while there is still an attached audio node has undefined behavior.

Parameters

number	The number of input channels for this redistributor.
matrix	The redistribution matrix

◆ setElapsed()

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

overridevirtual

Sets the read position to the elapsed time in seconds.

DELEGATED METHOD: This method delegates its call to the input node. It returns -1 if there is no input node, indicating it is unsupported.

The value returned is always measured from the start of the steam, regardless of the presence of any marks.

Parameters

time	The elapsed time in seconds.

Returns: the new elapsed time in seconds.

Reimplemented from cugl::audio::AudioNode.

◆ setMatrix()

void cugl::audio::AudioRedistributor::setMatrix ( const float * matrix )

Sets the current redistribution matrix for this redistributor.

The matrix will be an MxN matrix in row major order, where N is the number of input channels and M is the number of output channels. The provided matrix will be copied. This method will not acquire ownership of the given matrix.

If the redistributor is currently using a default redistribution algorithm (based on the number of input channels), then this method will return nullptr.

Parameters

matrix The redistribution matrix

◆ setPosition()

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

overridevirtual

Sets the current frame position of this audio node.

DELEGATED METHOD: This method delegates its call to the input node. It returns -1 if there is no input node, indicating it is unsupported.

The value set will always be the absolute frame position regardless of the presence of any marks.

Parameters

position the current frame position of this audio node.

Returns: the new frame position of this audio node.

Reimplemented from cugl::audio::AudioNode.

◆ setRemaining()

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

overridevirtual

Sets the remaining time in seconds.

DELEGATED METHOD: This method delegates its call to the input node. It returns -1 if there is no input node, indicating it is unsupported.

This method will move the read position so that the distance between it and the end of the same is the given number of seconds.

Parameters

time	The remaining time in seconds.

Returns: the new remaining time in seconds.

Reimplemented from cugl::audio::AudioNode.

◆ unmark()

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

overridevirtual

Clears the current marked position.

DELEGATED METHOD: This method delegates its call to the input node. It returns false if there is no input node, indicating it is unsupported.

Clearing the mark in a player is equivelent to setting the mark at the beginning of the audio asset. Future calls to reset() will return to the start of the audio stream.

Returns: true if the read position was cleared.

Reimplemented from cugl::audio::AudioNode.

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

include/cugl/audio/graph/CUAudioRedistributor.h

Public Member Functions

Static Public Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ AudioRedistributor()

◆ ~AudioRedistributor()

Member Function Documentation

◆ advance()

◆ alloc() [1/4]

◆ alloc() [2/4]

◆ alloc() [3/4]

◆ alloc() [4/4]

◆ attach() [1/2]

◆ attach() [2/2]

◆ completed()

◆ detach()

◆ dispose()

◆ getConduits()

◆ getElapsed()

◆ getInput()

◆ getMatrix()

◆ getPosition()

◆ getRemaining()

◆ init() [1/4]

◆ init() [2/4]

◆ init() [3/4]

◆ init() [4/4]

◆ mark()

◆ read()

◆ reset()

◆ setConduits() [1/2]

◆ setConduits() [2/2]

◆ setElapsed()

◆ setMatrix()

◆ setPosition()

◆ setRemaining()

◆ unmark()