CUGL 2.3
Cornell University Game Library
|
#include <CUAudioPanner.h>
Public Member Functions | |
AudioPanner () | |
~AudioPanner () | |
virtual bool | init () override |
virtual bool | init (Uint8 channels, Uint32 rate) override |
bool | init (Uint8 channels, Uint8 field, Uint32 rate) |
virtual void | dispose () override |
bool | attach (const std::shared_ptr< AudioNode > &node) |
std::shared_ptr< AudioNode > | detach () |
std::shared_ptr< AudioNode > | getInput () const |
Uint32 | getField () const |
bool | setField (Uint8 field) |
float | getPan (Uint32 field, Uint32 channel) const |
void | setPan (Uint32 field, Uint32 channel, float value) |
virtual void | setReadSize (Uint32 size) override |
virtual bool | completed () override |
virtual Uint32 | read (float *buffer, Uint32 frames) 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 () |
virtual bool | init () |
virtual bool | init (Uint8 channels, Uint32 rate) |
virtual void | dispose () |
Uint8 | getChannels () const |
Uint32 | getRate () const |
float | getGain () |
virtual void | setGain (float gain) |
Uint32 | getReadSize () const |
virtual void | setReadSize (Uint32 size) |
const std::string | getClassName () const |
const std::string | getName () const |
void | setName (const std::string name) |
Sint32 | getTag () const |
void | setTag (Sint32 tag) |
virtual std::string | toString (bool verbose=false) const |
operator std::string () const | |
Callback | getCallback () |
void | setCallback (Callback callback) |
virtual bool | isPaused () |
virtual bool | pause () |
virtual bool | resume () |
virtual bool | completed () |
virtual Uint32 | read (float *buffer, Uint32 frames) |
virtual bool | mark () |
virtual bool | unmark () |
virtual bool | reset () |
virtual Sint64 | advance (Uint32 frames) |
virtual Sint64 | getPosition () const |
virtual Sint64 | setPosition (Uint32 position) |
virtual double | getElapsed () const |
virtual double | setElapsed (double time) |
virtual double | getRemaining () const |
virtual double | setRemaining (double time) |
Static Public Member Functions | |
static std::shared_ptr< AudioPanner > | alloc () |
static std::shared_ptr< AudioPanner > | alloc (Uint8 channels, Uint32 rate) |
static std::shared_ptr< AudioPanner > | alloc (Uint8 channels, Uint8 field, Uint32 rate) |
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 | |
static const Uint32 | DEFAULT_CHANNELS |
static const 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 |
Uint32 | _readsize |
std::string | _localname |
std::string | _classname |
size_t | _hashOfName |
bool | _locked |
A class representing a general purpose audio panner.
This audio node takes another audio node as input. That node must agree with the sample rate of this node, but need not have the same number of channels. In fact, the input node must instead have getField()
number of channels. It then maps the data from this input channels to the output channels.
This mapping happens via a panning matrix. This matrix specifies the contribution (in a range of 0 to 1) of each input channel to each output channel. By default, each input channel maps fully (value 1) to the same output channel (or is dropped if that output channel does not exist). The values of this matrix may be changed at any time.
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
.
cugl::audio::AudioPanner::AudioPanner | ( | ) |
Creates a degenerate audio panner
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.
|
inline |
Deletes the audio panner, disposing of all resources
|
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 or if this method is unsupported in that node
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 advace |
Reimplemented from cugl::audio::AudioNode.
|
inlinestatic |
Returns a newly allocated panner with default stereo settings
The number of input channels (the field) and the number of output channels is two, for stereo output. The sample rate is the modern standard of 48000 HZ.
This initializer will create a default stereo panner. The initial panning matrix will map left to left and right to right.
|
inlinestatic |
Returns a newly allocated panner with the given number of channels and sample rate
The number of input channels (the field) and the number of output channels will be the same. The initial panning matrix will map each channel to itself. This is a generalization of a default stereo panner.
channels | The number of audio channels |
rate | The sample rate (frequency) in HZ |
|
inlinestatic |
Returns a newly allocated panner with the given number of input/output channels.
The number of input channels is given by field
, while channels
is the number of output channels. The initial panning matrix will map each channel to itself, and drop those input channels that do not have a corresponding output channel.
channels | The number of output channels |
field | The number of input channels |
rate | The sample rate (frequency) in HZ |
bool cugl::audio::AudioPanner::attach | ( | const std::shared_ptr< AudioNode > & | node | ) |
Attaches an audio node to this panner.
This method will fail if the channels of the audio node do not agree with the field size of this panner
node | The audio node to pan |
|
overridevirtual |
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 from cugl::audio::AudioNode.
std::shared_ptr< AudioNode > cugl::audio::AudioPanner::detach | ( | ) |
Detaches an audio node from this panner.
If the method succeeds, it returns the audio node that was removed.
|
overridevirtual |
Disposes any resources allocated for this panner
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.
|
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 or if this method is unsupported in that node
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 from cugl::audio::AudioNode.
|
inline |
Returns the input field size of this panner.
|
inline |
Returns the input node of this panner.
float cugl::audio::AudioPanner::getPan | ( | Uint32 | field, |
Uint32 | channel | ||
) | const |
Returns the matrix pan value for input field and output channel.
The pan value is the percentage (gain) of the input channel (field) that is sent to the given output channel. Technically, this value can be more than 1, but it cannot be negative.
|
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 or if this method is unsupported in that node
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 from cugl::audio::AudioNode.
|
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 or if this method is unsupported in that node
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 from cugl::audio::AudioNode.
|
overridevirtual |
Initializes the node with default stereo settings
The number of input channels (the field) and the number of output channels is two, for stereo output. The sample rate is the modern standard of 48000 HZ.
This initializer will create a default stereo panner. The initial panning matrix will map left to left and right to right.
Reimplemented from cugl::audio::AudioNode.
|
overridevirtual |
Initializes the node with the given number of channels and sample rate
The number of input channels (the field) and the number of output channels will be the same. The initial panning matrix will map each channel to itself. This is a generalization of a default stereo panner.
channels | The number of audio channels |
rate | The sample rate (frequency) in HZ |
Reimplemented from cugl::audio::AudioNode.
bool cugl::audio::AudioPanner::init | ( | Uint8 | channels, |
Uint8 | field, | ||
Uint32 | rate | ||
) |
Initializes the node with the given number of input/output channels.
The number of input channels is given by field
, while channels
is the number of output channels. The initial panning matrix will map each channel to itself, and drop those input channels that do not have a corresponding output channel.
channels | The number of output channels |
field | The number of input channels |
rate | The sample rate (frequency) in HZ |
|
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 or if this method is unsupported in that node
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 from cugl::audio::AudioNode.
|
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 AudioOutput.
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.
buffer | The read buffer to store the results |
frames | The maximum number of frames to read |
Reimplemented from cugl::audio::AudioNode.
|
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 or if this method is unsupported in that node
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 from cugl::audio::AudioNode.
|
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 or if this method is unsupported in that node
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 from cugl::audio::AudioNode.
bool cugl::audio::AudioPanner::setField | ( | Uint8 | field | ) |
Sets the input field size of this panner.
The field can only be reset if there is no attached node. Otherwise this method will fail
field | The number of input channels |
void cugl::audio::AudioPanner::setPan | ( | Uint32 | field, |
Uint32 | channel, | ||
float | value | ||
) |
Awra the matrix pan value for input field and output channel.
The pan value is the percentage (gain) of the input channel (field) that is sent to the given output channel. Technically, this value can be more than 1, but it cannot be negative.
field | The input channel |
channel | The output channel |
value | The percentage gain |
|
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 or if this method is unsupported in that node
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 from cugl::audio::AudioNode.
|
overridevirtual |
Sets the typical read size of this node.
Some audio nodes need an internal buffer for operations like mixing or resampling. In that case, it helps to know the requested read
size ahead of time. The capacity is the minimal required read amount of the AudioEngine
and corresponds to AudioEngine#getReadSize
.
It is not actually necessary to set this size. However for nodes with internal buffer, setting this value can optimize performance.
This method is not synchronized because it is assumed that this value will never change while the audio engine in running. The average user should never call this method explicitly. You should always call AudioEngine#setReadSize
instead.
size | The typical read size of this node. |
Reimplemented from cugl::audio::AudioNode.
|
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 or if this method is unsupported in that node
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 from cugl::audio::AudioNode.
|
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 or if this method is unsupported in that node
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 from cugl::audio::AudioNode.