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

#include <CUAudioMixer.h>

Inheritance diagram for cugl::audio::AudioMixer:
cugl::audio::AudioNode

Public Member Functions

 AudioMixer ()
 
 ~AudioMixer ()
 
virtual bool init () override
 
bool init (Uint8 width)
 
virtual bool init (Uint8 channels, Uint32 rate) override
 
bool init (Uint8 width, Uint8 channels, Uint32 rate)
 
virtual void dispose () override
 
std::shared_ptr< AudioNodeattach (Uint8 slot, const std::shared_ptr< AudioNode > &input)
 
std::shared_ptr< AudioNodedetach (Uint8 slot)
 
virtual bool completed () override
 
virtual Uint32 read (float *buffer, Uint32 frames) override
 
Uint8 getWidth () const
 
bool setWidth (Uint8 width)
 
float getKnee () const
 
void setKnee (float knee)
 
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< AudioMixeralloc (Uint8 width=8)
 
static std::shared_ptr< AudioMixeralloc (Uint8 width, Uint8 channels, Uint32 rate)
 

Static Public Attributes

static const Uint8 DEFAULT_WIDTH
 
static const float DEFAULT_KNEE
 
- Static Public Attributes inherited from cugl::audio::AudioNode
const static Uint32 DEFAULT_CHANNELS
 
const static Uint32 DEFAULT_SAMPLING
 

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
 
- 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 mixer.

This mixer can take (a fixed number of) input streams and combine them together into a single output stream. The input streams must all have the same number of channels and sample rate as this node.

Mixing works by adding together all of the streams. This means that the results may exceed the range [-1,1], causing clipping. The mixer provides a "soft-knee" option (disabled by default) for confining the results to the range [-1,1]. When a knee k is specified, all values [-k,k] will not be effected, but values outside of this range will asymptotically bend to the range [-1,1].

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

◆ AudioMixer()

cugl::audio::AudioMixer::AudioMixer ( )

Creates a degenerate mixer that takes no inputs

The mixer has no width and therefore cannot accept any inputs. The mixer must be initialized to be used.

◆ ~AudioMixer()

cugl::audio::AudioMixer::~AudioMixer ( )
inline

Deletes this mixer, disposing of all resources.

Member Function Documentation

◆ advance()

virtual Sint64 cugl::audio::AudioMixer::advance ( Uint32  frames)
overridevirtual

Advances the stream by the given number of frames.

DELEGATED METHOD: This method delegates its call to all currently attached input nodes. It returns -1 if there are no attached input nodes, or if just one of the input nodes cannot be advanced. However, any input that was successfully advanced remains advanced.

This method is ideal for a mixer composed of AudioPlayer objects. It will equally reset all of the components, keeping them in sync.

Parameters
framesThe number of frames to advace
Returns
the actual number of frames advanced; -1 if not supported

Reimplemented from cugl::audio::AudioNode.

◆ alloc() [1/2]

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

Returns a newly allocated mixer 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 exactly which audio nodes are supported by this mixer. A mixer can only mix nodes that agree on both sample rate and frequency.

Parameters
widthThe number of audio nodes that may be attached to this mixer
channelsThe number of audio channels
rateThe sample rate (frequency) in HZ
Returns
a newly allocated mixer with the given number of channels and sample rate

◆ alloc() [2/2]

static std::shared_ptr<AudioMixer> cugl::audio::AudioMixer::alloc ( Uint8  width = 8)
inlinestatic

Returns a newly allocated mixer 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 exactly which audio nodes are supported by this mixer. A mixer can only mix nodes that agree on both sample rate and frequency.

Parameters
widthThe number of audio nodes that may be attached to this mixer
Returns
a newly allocated mixer with default stereo settings

◆ attach()

std::shared_ptr<AudioNode> cugl::audio::AudioMixer::attach ( Uint8  slot,
const std::shared_ptr< AudioNode > &  input 
)

Attaches an input node to this mixer.

The input is attached at the given slot. Any input node previously at that slot is removed (and returned by this method).

Parameters
slotThe slot for the input node
inputThe input node to attach
Returns
the input node previously at the given slot

◆ completed()

virtual bool cugl::audio::AudioMixer::completed ( )
overridevirtual

Returns true if this audio node has no more data.

DELEGATED METHOD: This method delegates its call to all currently attached input nodes. It returns true if there are no attached input nodes, or if all of the input nodes are complete.

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::AudioMixer::detach ( Uint8  slot)

Detaches the input node at the given slot.

The input node detached is returned by this method.

Parameters
slotThe slot for the input node
Returns
the input node detached from the slot

◆ dispose()

virtual void cugl::audio::AudioMixer::dispose ( )
overridevirtual

Disposes any resources allocated for this mixer

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.

◆ getElapsed()

virtual double cugl::audio::AudioMixer::getElapsed ( ) const
overridevirtual

Returns the elapsed time in seconds.

If mark() was called previously, this value is the number of seconds since the mark. Otherwise, it is the number of seconds since the start of this stream. Calling reset() will reset this position even if not all of the inputs were reset.

This method is ideal for a mixer composed of AudioPlayer objects. In that case, it will return the synchronous elapsed time of all of the players.

Returns
the elapsed time in seconds.

Reimplemented from cugl::audio::AudioNode.

◆ getKnee()

float cugl::audio::AudioMixer::getKnee ( ) const

Returns the "soft knee" of this mixer, or -1 if not set

The soft knee is used to ensure that the results fit in the range [-1,1]. If the knee is k, then values in the range [-k,k] are unaffected, but values outside of this range are asymptotically clamped to the range [-1,1], using the formula (x-k+k*k)/x.

If the value is 0, then this mixer will hard clamp to [-1,1]. If it is negative, all inputs will be mixed exactly with no distortion.

Returns
the "soft knee" of this mixer, or -1 if not set

◆ getPosition()

virtual Sint64 cugl::audio::AudioMixer::getPosition ( ) const
overridevirtual

Returns the current frame position of this audio node

If mark() was called previously, this value is the number of frames since the mark. Otherwise, it is the number of frames since the start of this stream. Calling reset() will reset this position even if not all of the inputs were reset.

This method is ideal for a mixer composed of AudioPlayer objects. In that case, it will return the synchronous position of all of the players.

Returns
the current frame position of this audio node.

Reimplemented from cugl::audio::AudioNode.

◆ getRemaining()

virtual double cugl::audio::AudioMixer::getRemaining ( ) const
overridevirtual

Returns the remaining time in seconds.

DELEGATED METHOD: This method delegates its call to all currently attached input nodes. The value returned is the maximum value across all nodes. It returns -1 if there are no attached input node, or if any attached node does not support this method.

This method is ideal for a mixer composed of AudioPlayer objects. In that case, it will return the maximum remaining time across all of the players.

Returns
the remaining time in seconds.

Reimplemented from cugl::audio::AudioNode.

◆ getWidth()

Uint8 cugl::audio::AudioMixer::getWidth ( ) const
inline

Returns the width of this mixer.

The width is the number of supported input slots.

Returns
the width of this mixer.

◆ init() [1/4]

virtual bool cugl::audio::AudioMixer::init ( )
overridevirtual

Initializes the mixer 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 exactly which audio nodes are supported by this mixer. A mixer can only mix nodes that agree on both sample rate and frequency.

Returns
true if initialization was successful

Reimplemented from cugl::audio::AudioNode.

◆ init() [2/4]

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

Initializes the mixer 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 exactly which audio nodes are supported by this mixer. A mixer can only mix nodes that agree on both sample rate and frequency.

Parameters
channelsThe number of audio channels
rateThe sample rate (frequency) in HZ
Returns
true if initialization was successful

Reimplemented from cugl::audio::AudioNode.

◆ init() [3/4]

bool cugl::audio::AudioMixer::init ( Uint8  width)

Initializes the mixer 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 exactly which audio nodes are supported by this mixer. A mixer can only mix nodes that agree on both sample rate and frequency.

Parameters
widthThe number of audio nodes that may be attached to this mixer
Returns
true if initialization was successful

◆ init() [4/4]

bool cugl::audio::AudioMixer::init ( Uint8  width,
Uint8  channels,
Uint32  rate 
)

Initializes the mixer 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 exactly which audio nodes are supported by this mixer. A mixer can only mix nodes that agree on both sample rate and frequency.

Parameters
widthThe number of audio nodes that may be attached to this mixer
channelsThe number of audio channels
rateThe sample rate (frequency) in HZ
Returns
true if initialization was successful

◆ mark()

virtual bool cugl::audio::AudioMixer::mark ( )
overridevirtual

Marks the current read position in the audio steam.

DELEGATED METHOD: This method delegates its call to all currently attached input nodes. It returns false if there are no attached input nodes, or if just one of the input nodes does not support marking. However, any input that was successfully marked remains marked.

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.

Input nodes added to the mixer after this method is called are not affected.

Returns
true if the read position was marked across all inputs.

Reimplemented from cugl::audio::AudioNode.

◆ read()

virtual Uint32 cugl::audio::AudioMixer::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, unless part of a custom audio graph node.

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

Reading the buffer has no affect on the read position. You must manually move the frame position forward. This is to allow for a frame window to be reread if necessary.

Parameters
bufferThe read buffer to store the results
framesThe maximum number of frames to read
Returns
the actual number of frames read

Reimplemented from cugl::audio::AudioNode.

◆ reset()

virtual bool cugl::audio::AudioMixer::reset ( )
overridevirtual

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

DELEGATED METHOD: This method delegates its call to all currently attached input nodes. It returns false if there are no attached input nodes, or if just one of the input nodes cannot be reset. However, However, any input that was successfully reset remains reset.

This method is ideal for a mixer composed of AudioPlayer objects. It will equally unmark all of the components, keeping them in sync.

Returns
true if the read position was moved.

Reimplemented from cugl::audio::AudioNode.

◆ setElapsed()

virtual double cugl::audio::AudioMixer::setElapsed ( double  time)
overridevirtual

Sets the read position to the elapsed time in seconds.

DELEGATED METHOD: This method delegates its call to all currently attached input nodes. It returns -1 if there are no attached input nodes, or if just one of the input nodes cannot be repositioned. However, any input that was successfully repositioned remains repositioned.

This method is ideal for a mixer composed of AudioPlayer objects. In that case, it will set the synchronous position of all of the players.

Parameters
timeThe elapsed time in seconds.
Returns
the new elapsed time in seconds.

Reimplemented from cugl::audio::AudioNode.

◆ setKnee()

void cugl::audio::AudioMixer::setKnee ( float  knee)

Sets the "soft knee" of this mixer.

The soft knee is used to ensure that the results fit in the range [-1,1]. If the knee is k, then values in the range [-k,k] are unaffected, but values outside of this range are asymptotically clamped to the range [-1,1], using the formula (x-k+k*k)/x

If the value is 0, then this mixer will hard clamp to [-1,1]. If it is negative, all inputs will be mixed exactly with no distortion.

Parameters
kneethe "soft knee" of this mixer

◆ setPosition()

virtual Sint64 cugl::audio::AudioMixer::setPosition ( Uint32  position)
overridevirtual

Sets the current frame position of this audio node.

DELEGATED METHOD: This method delegates its call to all currently attached input nodes. It returns -1 if there are no attached input nodes, or if just one of the input nodes cannot be repositioned. However, any input that was successfully repositioned remains repositioned.

This method is ideal for a mixer composed of AudioPlayer objects. In that case, it will set the synchronous position of all of the players.

Parameters
positionthe 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::AudioMixer::setRemaining ( double  time)
overridevirtual

Sets the remaining time in seconds.

DELEGATED METHOD: This method delegates its call to all currently attached input nodes. The value set is the relative to the maximum remaining time across all inputs. Any input with less than the remaining time is advanced forward so that it remains in sync with the maximal input.

This method returns returns -1 if there are no attached input node, or if any attached node does not support this method. However, any repositioned input will remain repositioned.

This method is ideal for a mixer composed of AudioPlayer objects. In that case, it will set the synchronous position of all of the players.

Parameters
timeThe remaining time in seconds.
Returns
the new remaining time in seconds.

Reimplemented from cugl::audio::AudioNode.

◆ setWidth()

bool cugl::audio::AudioMixer::setWidth ( Uint8  width)

Sets the width of this mixer.

The width is the number of supported input slots. This method will only succeed if the mixer is paused. Otherwise, it will fail.

Once the width is adjusted, the children will be reassigned in order. If the new width is less than the old width, children at the end of the mixer will be dropped.

Returns
true if the mixer width was reset

◆ unmark()

virtual bool cugl::audio::AudioMixer::unmark ( )
overridevirtual

Clears the current marked position.

DELEGATED METHOD: This method delegates its call to all currently attached input nodes. It returns false if there are no attached input nodes, or if just one of the input nodes does not support marking. However, any input that was successfully unmarked remains unmarked.

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.

This method is ideal for a mixer composed of AudioPlayer objects. It will equally mark all of the components, keeping them in sync.

Returns
true if the read position was marked.

Reimplemented from cugl::audio::AudioNode.

Member Data Documentation

◆ DEFAULT_KNEE

const float cugl::audio::AudioMixer::DEFAULT_KNEE
static

The standard knee value for preventing clipping

◆ DEFAULT_WIDTH

const Uint8 cugl::audio::AudioMixer::DEFAULT_WIDTH
static

The default number of inputs supported (typically 8)


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