CUGL 2.1
Cornell University Game Library
Public Types | Public Member Functions | Static Public Attributes | Protected Member Functions | Protected Attributes | List of all members
cugl::audio::AudioNode Class Reference

#include <CUAudioNode.h>

Inheritance diagram for cugl::audio::AudioNode:
cugl::audio::AudioFader cugl::audio::AudioInput cugl::audio::AudioMixer cugl::audio::AudioOutput cugl::audio::AudioPanner cugl::audio::AudioPlayer cugl::audio::AudioRedistributor cugl::audio::AudioResampler cugl::audio::AudioScheduler cugl::audio::AudioSpinner cugl::audio::AudioSynchronizer

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.

  1. front-left
  2. front-right
  3. center
  4. subwoofer/low-frequency
  5. rear left
  6. rear right

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

  1. side left
  2. 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

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
nodeThe audio player for this callback.
typeThe type of action completed.

Member Enumeration Documentation

◆ Action

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
framesThe 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::AudioRedistributor, cugl::audio::AudioFader, cugl::audio::AudioResampler, cugl::audio::AudioMixer, cugl::audio::AudioPanner, cugl::audio::AudioSynchronizer, 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::AudioRedistributor, cugl::audio::AudioOutput, cugl::audio::AudioResampler, cugl::audio::AudioPanner, cugl::audio::AudioSynchronizer, cugl::audio::AudioMixer, 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::AudioRedistributor, cugl::audio::AudioMixer, cugl::audio::AudioResampler, cugl::audio::AudioPanner, cugl::audio::AudioPlayer, and cugl::audio::AudioSynchronizer.

◆ 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::AudioOutput, cugl::audio::AudioInput, cugl::audio::AudioRedistributor, cugl::audio::AudioResampler, cugl::audio::AudioFader, cugl::audio::AudioMixer, cugl::audio::AudioPanner, cugl::audio::AudioSynchronizer, 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::AudioOutput, cugl::audio::AudioInput, cugl::audio::AudioRedistributor, cugl::audio::AudioFader, cugl::audio::AudioResampler, cugl::audio::AudioMixer, cugl::audio::AudioPanner, cugl::audio::AudioSynchronizer, 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::AudioRedistributor, cugl::audio::AudioResampler, cugl::audio::AudioFader, cugl::audio::AudioMixer, cugl::audio::AudioPanner, cugl::audio::AudioSynchronizer, 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::AudioRedistributor, cugl::audio::AudioResampler, cugl::audio::AudioSynchronizer, cugl::audio::AudioMixer, and cugl::audio::AudioPanner.

◆ 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
channelsThe number of audio channels
rateThe sample rate (frequency) in HZ
Returns
true if initialization was successful

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

◆ 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::AudioRedistributor, cugl::audio::AudioFader, cugl::audio::AudioResampler, cugl::audio::AudioMixer, cugl::audio::AudioPanner, cugl::audio::AudioSynchronizer, 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
bufferThe read buffer to store the results
framesThe 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::AudioOutput, cugl::audio::AudioFader, cugl::audio::AudioRedistributor, cugl::audio::AudioResampler, cugl::audio::AudioPanner, cugl::audio::AudioSynchronizer, cugl::audio::AudioMixer, 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::AudioRedistributor, cugl::audio::AudioFader, cugl::audio::AudioResampler, cugl::audio::AudioMixer, cugl::audio::AudioPanner, cugl::audio::AudioSynchronizer, 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
callbackthe 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
timeThe elapsed time in seconds.
Returns
the new elapsed time in seconds.

Reimplemented in cugl::audio::AudioSpinner, cugl::audio::AudioScheduler, cugl::audio::AudioOutput, cugl::audio::AudioInput, cugl::audio::AudioRedistributor, cugl::audio::AudioResampler, cugl::audio::AudioFader, cugl::audio::AudioMixer, cugl::audio::AudioPanner, cugl::audio::AudioSynchronizer, 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
gainthe (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
nameA 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
positionthe 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::AudioOutput, cugl::audio::AudioInput, cugl::audio::AudioRedistributor, cugl::audio::AudioResampler, cugl::audio::AudioFader, cugl::audio::AudioMixer, cugl::audio::AudioPanner, cugl::audio::AudioSynchronizer, 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
timeThe remaining time in seconds.
Returns
the new remaining time in seconds.

Reimplemented in cugl::audio::AudioSpinner, cugl::audio::AudioOutput, cugl::audio::AudioInput, cugl::audio::AudioResampler, cugl::audio::AudioRedistributor, cugl::audio::AudioFader, cugl::audio::AudioMixer, cugl::audio::AudioPanner, cugl::audio::AudioSynchronizer, 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
tagAn 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
verboseWhether 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::AudioRedistributor, cugl::audio::AudioFader, cugl::audio::AudioResampler, cugl::audio::AudioMixer, cugl::audio::AudioPanner, cugl::audio::AudioSynchronizer, 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: