#include <CUAudioNode.h>

Inheritance diagram for cugl::audio::AudioNode:

Public Types
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

Public Member Functions
	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)

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 Attributes
const static Uint32	DEFAULT_CHANNELS

const static Uint32	DEFAULT_SAMPLING

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

Protected Attributes
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 is a node in the audio graph

This class provides the base of any nodes in the audio graph. All nodes work on a pull model, where reading from a node reads from all of its input nodes (if any exist).

When deciding on the number of channels, SDL supports 1 (mono), 2 (stereo), 4 (quadrophonic), 6 (5.1 surround), or 8 (7.1 surround) channels for playback. Stereo and quadraphonic are arranged left-right, front-back. For 5.1 surround, they are arranged in the following order.

front-left
front-right
center
subwoofer/low-frequency
rear left
rear right

For 7.1 surround, they are arranged in the same order with the following additional channels.

side left
side right

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. The only exception to this rule is by another (custom) audio graph node in its audio thread methods.

For polymorphic reasons, this class has several optional methods. These methods are not guaranteed to be supported in all classes. However, if a method is not supported, it returns a simple error value and will not crash the program.

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

Member Typedef Documentation

◆ Callback

cugl::audio::AudioNode::Callback

This type represents a callback function for AudioNode

The callback is executed when an audio action occurs. The second parameter in the callback is the type of action that took place. See the description of each audio node

Parameters

node	The audio player for this callback.
type	The type of action completed.

Member Enumeration Documentation

◆ Action

enum cugl::audio::AudioNode::Action : int

An enumeration of possible node actions.

These are possible things that that can happen to audio, and which we might want to be notified about. Not all actions are supported by all nodes. Indeed, this enumeration provides a collection of all possible actions supported by subclasses of AudioNode.

This list is not comprehensive and can change at any time. Never use the numeric values directly.

Enumerator
COMPLETE	This audio node has completed normally
INTERRUPT	This audio node completed via an abnormal interruption
FADE_OUT	An audio node completed as the result of a fade-out.
FADE_IN	The audio node has completed an initial fade-in.
FADE_DIP	The audio node has paused after a temporary fade-out.
LOOPBACK	This audio node has reset and looped back to the beginning

Constructor & Destructor Documentation

◆ AudioNode()

cugl::audio::AudioNode::AudioNode ( )

Creates a degenerate audio graph node

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

NEVER USE A CONSTRUCTOR WITH NEW. If you want to allocate a graph node on the heap, use one of the static constructors instead.

◆ ~AudioNode()

virtual cugl::audio::AudioNode::~AudioNode ( )

virtual

Deletes the audio graph node, disposing of all resources

Member Function Documentation

◆ advance()

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

inlinevirtual

Advances the stream by the given number of frames.

OPTIONAL METHOD: This method is not supported by all node subclasses. It will return the number of frames advanced if it is successful/supported and -1 otherwise.

This method only advances the read position, it does not actually read data into a buffer. This method is generally not supported for nodes with real-time input like AudioInput.

Parameters

frames The number of frames to advance

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

Reimplemented in cugl::audio::AudioSpinner, cugl::audio::AudioScheduler, cugl::audio::AudioOutput, cugl::audio::AudioFader, cugl::audio::AudioMixer, cugl::audio::AudioPanner, cugl::audio::AudioSynchronizer, cugl::audio::AudioResampler, and cugl::audio::AudioPlayer.

◆ completed()

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

inlinevirtual

Returns true if this audio node has no more data.

An audio node is typically completed if it return 0 (no frames read) on subsequent calls to read(). However, for infinite-running audio threads, it is possible for this method to return true even when data can still be read; in that case the node is notifying that it should be shut down.

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

Reimplemented in cugl::audio::AudioSpinner, cugl::audio::AudioInput, cugl::audio::AudioFader, cugl::audio::AudioOutput, cugl::audio::AudioPanner, cugl::audio::AudioSynchronizer, cugl::audio::AudioResampler, and cugl::audio::AudioPlayer.

◆ dispose()

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

virtual

Disposes any resources allocated for this node

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 in cugl::audio::AudioSpinner, cugl::audio::AudioScheduler, cugl::audio::AudioFader, cugl::audio::AudioMixer, cugl::audio::AudioPanner, cugl::audio::AudioPlayer, cugl::audio::AudioSynchronizer, and cugl::audio::AudioResampler.

◆ getCallback()

Callback cugl::audio::AudioNode::getCallback ( )

Returns the callback function for this node

The callback function is called whenever an action takes places. Actions are subclass dependent. See the class documentation for what callbacks are supported.

Returns: the callback function for this node

◆ getChannels()

Uint8 cugl::audio::AudioNode::getChannels ( ) const

inline

Returns the number of output channels of this node

The standard values are 1 for mono or 2 for stereo. However, we allow greater values for surround sound. The semantics of each channel are system dependent.

Returns: the number of output channels of this node

◆ getClassName()

const std::string& cugl::audio::AudioNode::getClassName ( ) const

inline

Returns the class name for this node.

This string allows us to do some efficient dynamic typing.

Returns: the class name for this node.

◆ getElapsed()

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

inlinevirtual

Returns the elapsed time in seconds.

OPTIONAL METHOD: This method is not supported by all node subclasses. It will return the elapsed time in seconds if it is successful/supported and -1 otherwise.

In some nodes like AudioInput, this method is only supported if mark() is set. In that case, the times will be the number of seconds since the mark. Other nodes like AudioPlayer measure from the start of the stream.

Returns: the elapsed time in seconds.

Reimplemented in cugl::audio::AudioSpinner, cugl::audio::AudioScheduler, cugl::audio::AudioInput, cugl::audio::AudioOutput, cugl::audio::AudioFader, cugl::audio::AudioMixer, cugl::audio::AudioPanner, cugl::audio::AudioSynchronizer, cugl::audio::AudioResampler, and cugl::audio::AudioPlayer.

◆ getGain()

float cugl::audio::AudioNode::getGain ( )

Returns the current (volume) gain of this node.

During processing, the sample data is multiplied by the gain. This value is generally between 0 and 1, though it may be any float. The result for values outside the range [0,1] are undefined.

Returns: the current (volume) gain of this node.

◆ getName()

const std::string& cugl::audio::AudioNode::getName ( ) const

inline

Returns a string that is used to identify the node.

This name is primarily used in debugging. For best results, a name should be unique within an audio graph. It is empty if undefined.

Returns: a string that is used to identify the node.

◆ getPosition()

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

inlinevirtual

Returns the current frame position of this audio node

OPTIONAL METHOD: This method is not supported by all node subclasses. It will return the current position if it is successful/supported and -1 otherwise.

In some nodes like AudioInput, this method is only supported if mark() is set. In that case, the position will be the number of frames since the mark. Other nodes like AudioPlayer measure from the start of the stream.

Returns: the current frame position of this audio node.

Reimplemented in cugl::audio::AudioSpinner, cugl::audio::AudioScheduler, cugl::audio::AudioInput, cugl::audio::AudioOutput, cugl::audio::AudioFader, cugl::audio::AudioMixer, cugl::audio::AudioPanner, cugl::audio::AudioSynchronizer, cugl::audio::AudioResampler, and cugl::audio::AudioPlayer.

◆ getRate()

Uint32 cugl::audio::AudioNode::getRate ( ) const

inline

Returns the sample rate of this node

The sample rate is that of the output produced by the read methods. If this node reads from other nodes, it may or may not agree with their frequency, particularly if the effect is a resampler.

Returns: the sample rate of this node

◆ getRemaining()

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

inlinevirtual

Returns the remaining time in seconds.

OPTIONAL METHOD: This method is not supported by all node subclasses. It will return the elapsed time in seconds if it is successful/supported and -1 otherwise.

In some nodes like AudioInput, this method is only supported if setRemaining() has been called. In that case, the node will be marked as completed after the given number of seconds. This may or may not actually move the read head. For example, in AudioPlayer it will skip to the end of the sample. However, in AudioInput it will simply time out after the given time.

Returns: the remaining time in seconds.

Reimplemented in cugl::audio::AudioSpinner, cugl::audio::AudioOutput, cugl::audio::AudioInput, cugl::audio::AudioFader, cugl::audio::AudioMixer, cugl::audio::AudioPanner, cugl::audio::AudioSynchronizer, cugl::audio::AudioResampler, and cugl::audio::AudioPlayer.

◆ getTag()

Sint32 cugl::audio::AudioNode::getTag ( ) const

inline

Returns an integer that is used to identify the node.

This tage is primarily used for debugging and/or hashing. For best results, a name should be unique within an audio graph. It is -1 if undefined.

Returns: an integer that is used to identify the node.

◆ init() [1/2]

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

virtual

Initializes the node 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 in cugl::audio::AudioSpinner, cugl::audio::AudioScheduler, cugl::audio::AudioFader, cugl::audio::AudioSynchronizer, cugl::audio::AudioMixer, cugl::audio::AudioPanner, and cugl::audio::AudioResampler.

◆ init() [2/2]

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

virtual

Initializes the node 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 in cugl::audio::AudioSpinner, cugl::audio::AudioScheduler, cugl::audio::AudioFader, cugl::audio::AudioMixer, cugl::audio::AudioSynchronizer, cugl::audio::AudioPanner, and cugl::audio::AudioResampler.

◆ isPaused()

virtual bool cugl::audio::AudioNode::isPaused ( )

virtual

Returns true if this node is currently paused

Returns: true if this node is currently paused

Reimplemented in cugl::audio::AudioFader.

◆ mark()

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

inlinevirtual

Marks the current read position in the audio steam.

OPTIONAL METHOD: This method is not supported by all node subclasses. It will return true if the mark is successful/supported and false otherwise.

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.

It is possible for reset() to be supported even if this method is not.

Returns: true if the read position was marked.

Reimplemented in cugl::audio::AudioSpinner, cugl::audio::AudioScheduler, cugl::audio::AudioInput, cugl::audio::AudioOutput, cugl::audio::AudioFader, cugl::audio::AudioMixer, cugl::audio::AudioPanner, cugl::audio::AudioSynchronizer, cugl::audio::AudioResampler, and cugl::audio::AudioPlayer.

◆ notify()

void cugl::audio::AudioNode::notify	(	const std::shared_ptr< AudioNode > &	node,
		Action	action
	)

protected

Invokes the callback functions for the given action.

The callback function can be changed at any given time while the audio is running. While the callback gets information from the audio thread, we want to execute it in the main thread, where we do not have to worry about performance issues (as much).

This means that callback execution is delayed and the callback function might change during that delay. This is a wrapper to ensure that this potential race condition happens gracefully and does not have any unexpected side effects.

◆ operator std::string()

cugl::audio::AudioNode::operator std::string ( ) const

inline

Cast from a Node to a string.

◆ pause()

virtual bool cugl::audio::AudioNode::pause ( )

virtual

Pauses this node, preventing any data from being read.

If the node is already paused, this method has no effect. Pausing will not go into effect until the next render call in the audio thread.

Returns: true if the node was successfully paused

Reimplemented in cugl::audio::AudioFader, cugl::audio::AudioOutput, and cugl::audio::AudioInput.

◆ read()

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

virtual

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 in cugl::audio::AudioSpinner, cugl::audio::AudioScheduler, cugl::audio::AudioInput, cugl::audio::AudioFader, cugl::audio::AudioOutput, cugl::audio::AudioPanner, cugl::audio::AudioSynchronizer, cugl::audio::AudioMixer, cugl::audio::AudioResampler, and cugl::audio::AudioPlayer.

◆ reset()

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

inlinevirtual

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

OPTIONAL METHOD: This method is not supported by all node subclasses. It will return true if the reset is successful/supported and false otherwise.

When no mark() is set, the result of this method is node dependent. Some nodes (such as AudioPlayer) will reset to the beginning of the stream, while others (like AudioInput) only support a rest when a mark is set. Pay attention to the return value of this method to see if the call is successful.

Returns: true if the read position was moved.

Reimplemented in cugl::audio::AudioSpinner, cugl::audio::AudioScheduler, cugl::audio::AudioInput, cugl::audio::AudioOutput, cugl::audio::AudioFader, cugl::audio::AudioMixer, cugl::audio::AudioPanner, cugl::audio::AudioSynchronizer, cugl::audio::AudioResampler, and cugl::audio::AudioPlayer.

◆ resume()

virtual bool cugl::audio::AudioNode::resume ( )

virtual

Resumes this previously paused node, allowing data to be read.

If the node is not paused, this method has no effect.

Returns: true if the node was successfully resumed

Reimplemented in cugl::audio::AudioFader, cugl::audio::AudioOutput, and cugl::audio::AudioInput.

◆ setCallback()

void cugl::audio::AudioNode::setCallback ( Callback callback )

Sets the callback function for this node

The callback function is called whenever an action takes places. Actions are subclass dependent. See the class documentation for what callbacks are supported.

Parameters

callback the callback function for this node

◆ setElapsed()

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

inlinevirtual

Sets the read position to the elapsed time in seconds.

OPTIONAL METHOD: This method is not supported by all node subclasses. It will return the new elapsed time if it is successful/supported and -1 otherwise.

In some nodes like AudioInput, this method is only supported if mark() is set. In that case, the new time will be meaured from the mark. Other nodes like AudioPlayer measure from the start of the stream.

Parameters

time	The elapsed time in seconds.

Returns: the new elapsed time in seconds.

Reimplemented in cugl::audio::AudioSpinner, cugl::audio::AudioScheduler, cugl::audio::AudioInput, cugl::audio::AudioOutput, cugl::audio::AudioFader, cugl::audio::AudioMixer, cugl::audio::AudioPanner, cugl::audio::AudioSynchronizer, cugl::audio::AudioResampler, and cugl::audio::AudioPlayer.

◆ setGain()

virtual void cugl::audio::AudioNode::setGain ( float gain )

virtual

Sets the current (volume) gain of this node.

During processing, the sample data is multiplied by the gain. This value is generally between 0 and 1, though it may be any float. The result for values outside the range [0,1] are undefined.

Parameters

gain	the (volume) gain of this node.

◆ setName()

void cugl::audio::AudioNode::setName ( const std::string name )

Sets a string that is used to identify the node.

This name is primarily used in debugging. For best results, a name should be unique within an audio graph. It is empty if undefined.

Parameters

name	A string that is used to identify the node.

◆ setPosition()

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

inlinevirtual

Sets the current frame position of this audio node.

OPTIONAL METHOD: This method is not supported by all node subclasses. It will return the new position if it is successful/supported and -1 otherwise.

In some nodes like AudioInput, this method is only supported if mark() is set. In that case, the position will be the number of frames since the mark. Other nodes like AudioPlayer measure from the start of the stream.

Parameters

position the current frame position of this audio node.

Returns: the new frame position of this audio node.

Reimplemented in cugl::audio::AudioSpinner, cugl::audio::AudioScheduler, cugl::audio::AudioInput, cugl::audio::AudioOutput, cugl::audio::AudioFader, cugl::audio::AudioMixer, cugl::audio::AudioPanner, cugl::audio::AudioSynchronizer, cugl::audio::AudioResampler, and cugl::audio::AudioPlayer.

◆ setRemaining()

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

inlinevirtual

Sets the remaining time in seconds.

OPTIONAL METHOD: This method is not supported by all node subclasses. It will return the remaining time if it is successful/supported and -1 otherwise.

If this method is supported, then the node will be marked as completed after the given number of seconds. This may or may not actually move the read head. For example, in AudioPlayer it will skip to the end of the sample. However, in AudioInput it will simply time out after the given time.

Parameters

time	The remaining time in seconds.

Returns: the new remaining time in seconds.

Reimplemented in cugl::audio::AudioSpinner, cugl::audio::AudioOutput, cugl::audio::AudioInput, cugl::audio::AudioFader, cugl::audio::AudioMixer, cugl::audio::AudioPanner, cugl::audio::AudioSynchronizer, cugl::audio::AudioResampler, and cugl::audio::AudioPlayer.

◆ setTag()

void cugl::audio::AudioNode::setTag ( Sint32 tag )

inline

Sets an integer that is used to identify the node.

This tage is primarily used for debugging and/or hashing. For best results, a name should be unique within an audio graph. It is -1 if undefined.

Parameters

tag	An integer that is used to identify the node.

◆ toString()

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

virtual

Returns a string representation of this audio node for debugging purposes.

If verbose is true, the string will include class information. This allows us to unambiguously identify the class.

Parameters

verbose Whether to include class information

Returns: a string representation of this node for debugging purposes.

◆ unmark()

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

inlinevirtual

Clears the current marked position.

OPTIONAL METHOD: This method is not supported by all node subclasses. It will return true if the clear is successful/supported and false otherwise.

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.

Returns: true if the read position was cleared.

Reimplemented in cugl::audio::AudioSpinner, cugl::audio::AudioScheduler, cugl::audio::AudioInput, cugl::audio::AudioOutput, cugl::audio::AudioFader, cugl::audio::AudioMixer, cugl::audio::AudioPanner, cugl::audio::AudioSynchronizer, cugl::audio::AudioResampler, and cugl::audio::AudioPlayer.

Member Data Documentation

◆ _booted

bool cugl::audio::AudioNode::_booted

protected

Whether or not the output node has been initialized

◆ _callback

Callback cugl::audio::AudioNode::_callback

protected

The callback function for when a node finishes

◆ _calling

std::atomic<bool> cugl::audio::AudioNode::_calling

protected

An atomic to mark that the callback is active (to give lock-free safety)

◆ _channels

Uint8 cugl::audio::AudioNode::_channels

protected

The number of channels output by this node

◆ _classname

std::string cugl::audio::AudioNode::_classname

protected

The class name for the specific subclass

◆ _hashOfName

size_t cugl::audio::AudioNode::_hashOfName

protected

A cached has value of _name.

This value is used to speed up look-ups by string.

◆ _localname

std::string cugl::audio::AudioNode::_localname

protected

A descriptive, identifying tag.

This is used to identify a node for debugging purposes.

◆ _ndgain

std::atomic<float> cugl::audio::AudioNode::_ndgain

protected

The (volume) gain of this node

◆ _paused

std::atomic<bool> cugl::audio::AudioNode::_paused

protected

Whether or not this node is currently paused

◆ _polling

std::atomic<bool> cugl::audio::AudioNode::_polling

protected

Whether or not this node is in an active poll

◆ _sampling

Uint32 cugl::audio::AudioNode::_sampling

protected

The sampling rate (frequency) of this node

◆ _tag

Sint32 cugl::audio::AudioNode::_tag

protected

An identifying integer

◆ DEFAULT_CHANNELS

const static Uint32 cugl::audio::AudioNode::DEFAULT_CHANNELS

static

The default number of channels for an audio node

◆ DEFAULT_SAMPLING

const static Uint32 cugl::audio::AudioNode::DEFAULT_SAMPLING

static

The default sampling frequency for an audio node

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

include/cugl/audio/graph/CUAudioNode.h

Public Types

Public Member Functions

Static Public Attributes

Protected Member Functions

Protected Attributes

Detailed Description

Member Typedef Documentation

◆ Callback

Member Enumeration Documentation

◆ Action

Constructor & Destructor Documentation

◆ AudioNode()

◆ ~AudioNode()

Member Function Documentation

◆ advance()

◆ completed()

◆ dispose()

◆ getCallback()

◆ getChannels()

◆ getClassName()

◆ getElapsed()

◆ getGain()

◆ getName()

◆ getPosition()

◆ getRate()

◆ getRemaining()

◆ getTag()

◆ init() [1/2]

◆ init() [2/2]

◆ isPaused()

◆ mark()

◆ notify()

◆ operator std::string()

◆ pause()

◆ read()

◆ reset()

◆ resume()

◆ setCallback()

◆ setElapsed()

◆ setGain()

◆ setName()

◆ setPosition()

◆ setRemaining()

◆ setTag()

◆ toString()

◆ unmark()

Member Data Documentation

◆ _booted

◆ _callback

◆ _calling

◆ _channels

◆ _classname

◆ _hashOfName

◆ _localname

◆ _ndgain

◆ _paused

◆ _polling

◆ _sampling

◆ _tag

◆ DEFAULT_CHANNELS

◆ DEFAULT_SAMPLING