CUGL 2.3
Cornell University Game Library
|
#include <CUAudioNode.h>
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) |
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 Attributes | |
static const Uint32 | DEFAULT_CHANNELS |
static const 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 |
Uint32 | _readsize |
std::string | _localname |
std::string | _classname |
size_t | _hashOfName |
bool | _locked |
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.
For 7.1 surround, they are arranged in the same order with the following additional channels.
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
.
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
node | The audio player for this callback. |
type | The type of action completed. |
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.
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.
|
virtual |
Deletes the audio graph node, disposing of all resources
|
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
.
frames | The number of frames to advance |
Reimplemented in cugl::audio::AudioFader, cugl::audio::AudioMixer, cugl::audio::AudioOutput, cugl::audio::AudioPanner, cugl::audio::AudioPlayer, cugl::audio::AudioRedistributor, cugl::audio::AudioResampler, cugl::audio::AudioScheduler, cugl::audio::AudioSpinner, and cugl::audio::AudioSynchronizer.
|
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.
Reimplemented in 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::AudioSpinner, and cugl::audio::AudioSynchronizer.
|
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::AudioFader, cugl::audio::AudioMixer, cugl::audio::AudioPanner, cugl::audio::AudioPlayer, cugl::audio::AudioRedistributor, cugl::audio::AudioResampler, cugl::audio::AudioScheduler, cugl::audio::AudioSpinner, and cugl::audio::AudioSynchronizer.
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.
|
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.
|
inline |
Returns the class name for this node.
This string allows us to do some efficient dynamic typing.
|
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.
Reimplemented in 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, and cugl::audio::AudioSynchronizer.
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.
|
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.
|
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.
Reimplemented in 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, and cugl::audio::AudioSynchronizer.
|
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.
|
inline |
Returns 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.
|
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.
Reimplemented in 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::AudioSpinner, and cugl::audio::AudioSynchronizer.
|
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.
|
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.
Reimplemented in cugl::audio::AudioFader, cugl::audio::AudioMixer, cugl::audio::AudioPanner, cugl::audio::AudioRedistributor, cugl::audio::AudioResampler, cugl::audio::AudioScheduler, cugl::audio::AudioSpinner, and cugl::audio::AudioSynchronizer.
|
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.
channels | The number of audio channels |
rate | The sample rate (frequency) in HZ |
Reimplemented in cugl::audio::AudioFader, cugl::audio::AudioMixer, cugl::audio::AudioPanner, cugl::audio::AudioRedistributor, cugl::audio::AudioResampler, cugl::audio::AudioScheduler, cugl::audio::AudioSpinner, and cugl::audio::AudioSynchronizer.
|
virtual |
Returns true if this node is currently paused
Reimplemented in cugl::audio::AudioFader.
|
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.
Reimplemented in 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, and cugl::audio::AudioSynchronizer.
|
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.
|
inline |
Cast from a Node to a string.
|
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.
Reimplemented in cugl::audio::AudioFader, cugl::audio::AudioInput, and cugl::audio::AudioOutput.
|
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.
buffer | The read buffer to store the results |
frames | The maximum number of frames to read |
Reimplemented in 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, and cugl::audio::AudioSynchronizer.
|
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.
Reimplemented in 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, and cugl::audio::AudioSynchronizer.
|
virtual |
Resumes this previously paused node, allowing data to be read.
If the node is not paused, this method has no effect.
Reimplemented in cugl::audio::AudioFader, cugl::audio::AudioInput, and cugl::audio::AudioOutput.
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.
callback | the callback function for this node |
|
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.
time | The elapsed time in seconds. |
Reimplemented in 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, and cugl::audio::AudioSynchronizer.
|
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.
gain | the (volume) gain of this node. |
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.
name | A string that is used to identify the node. |
|
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.
position | the current frame position of this audio node. |
Reimplemented in 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, and cugl::audio::AudioSynchronizer.
|
virtual |
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.
size | The typical read size of this node. |
Reimplemented in cugl::audio::AudioFader, cugl::audio::AudioInput, cugl::audio::AudioMixer, cugl::audio::AudioOutput, cugl::audio::AudioPanner, cugl::audio::AudioRedistributor, cugl::audio::AudioResampler, cugl::audio::AudioScheduler, cugl::audio::AudioSpinner, and cugl::audio::AudioSynchronizer.
|
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.
time | The remaining time in seconds. |
Reimplemented in 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::AudioSpinner, and cugl::audio::AudioSynchronizer.
|
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.
tag | An integer that is used to identify the node. |
|
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.
verbose | Whether to include class information |
|
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.
Reimplemented in 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, and cugl::audio::AudioSynchronizer.
|
protected |
Whether or not the output node has been initialized
|
protected |
The callback function for when a node finishes
|
protected |
An atomic to mark that the callback is active (to give lock-free safety)
|
protected |
The number of channels output by this node
|
protected |
The class name for the specific subclass
|
protected |
A cached has value of _name.
This value is used to speed up look-ups by string.
|
protected |
A descriptive, identifying tag.
This is used to identify a node for debugging purposes.
|
protected |
Whether this device is read locked
|
protected |
The (volume) gain of this node
|
protected |
Whether or not this node is currently paused
|
protected |
Whether or not this node is in an active poll
|
protected |
The default read size of this node (in frames)
|
protected |
The sampling rate (frequency) of this node
|
protected |
An identifying integer
|
static |
The default number of channels for an audio node
|
static |
The default sampling frequency for an audio node