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

#include <CUAudioFader.h>

Inheritance diagram for cugl::audio::AudioFader:
cugl::audio::AudioNode

Public Member Functions

 AudioFader ()
 
 ~AudioFader ()
 
virtual bool init () override
 
virtual bool init (Uint8 channels, Uint32 rate) override
 
bool init (const std::shared_ptr< AudioNode > &input)
 
virtual void dispose () override
 
bool attach (const std::shared_ptr< AudioNode > &node)
 
std::shared_ptr< AudioNodedetach ()
 
std::shared_ptr< AudioNodegetInput ()
 
void fadeIn (double duration)
 
bool isFadeIn ()
 
void fadeOut (double duration, bool wrap=false)
 
bool isFadeOut ()
 
void fadePause (double duration)
 
bool isFadePause ()
 
void fadePause (double fadeout, double fadein)
 
virtual bool isPaused () override
 
virtual bool pause () override
 
virtual bool resume () override
 
virtual Uint32 read (float *buffer, Uint32 frames) override
 
virtual bool completed () 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 ()
 
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)
 

Static Public Member Functions

static std::shared_ptr< AudioFaderalloc ()
 
static std::shared_ptr< AudioFaderalloc (Uint8 channels, Uint32 rate)
 
static std::shared_ptr< AudioFaderalloc (const std::shared_ptr< AudioNode > &input)
 

Protected Member Functions

Uint32 doFadeIn (float *buffer, Uint32 frames)
 
Uint32 doFadeOut (float *buffer, Uint32 frames)
 
Uint32 doFadePause (float *buffer, Uint32 frames)
 
- Protected Member Functions inherited from cugl::audio::AudioNode
void notify (const std::shared_ptr< AudioNode > &node, Action action)
 

Protected Attributes

std::shared_ptr< AudioNode_input
 
std::mutex _mutex
 
Sint64 _inmark
 
Uint64 _fadein
 
Sint64 _outmark
 
Uint64 _fadeout
 
bool _outdone
 
bool _outkeep
 
Uint64 _fadedip
 
Sint64 _dipmark
 
Uint64 _dipstop
 
bool _diphalf
 
bool _dipstart
 
- 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
 

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

Detailed Description

This class adds fade-in and fade-out support to an audio node.

Fading is an important part of any audio engine. Without fading, an audio source will click when paused or stopped. This node should be inserted into an audio graph anywhere the user might need to pause/resume audio on demand.

We have decoupled fade-in and out from AudioPlayer since we want to apply it to arbitrary audio graphs. We have also decoupled it from AudioScheduler, since we do not want fade support to require a scheduler, and the scheduler API is complicated enough as it is. By factoring this out into its own node, it is easier for us to support nonlinear fades (such as with an easing function).

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 audio node supports the callback functions in AudioNode#setCallback. This function function is called whenever a fade-in or fade-out has completed successfully (without interruption).

Constructor & Destructor Documentation

◆ AudioFader()

cugl::audio::AudioFader::AudioFader ( )

Creates a degenerate audio fader.

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

◆ ~AudioFader()

cugl::audio::AudioFader::~AudioFader ( )
inline

Deletes this audio player, disposing of all resources.

Member Function Documentation

◆ advance()

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

Advances the stream by the given number of frames.

This method only advances the read position, it does not actually read data into a buffer.

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/3]

static std::shared_ptr<AudioFader> cugl::audio::AudioFader::alloc ( )
inlinestatic

Returns a newly allocated fader with the default stereo settings

The number of channels is two, for stereo output. The sample rate is the modern standard of 48000 HZ. Any input node must agree with these settings.

Returns
a newly allocated fader with the default stereo settings

◆ alloc() [2/3]

static std::shared_ptr<AudioFader> cugl::audio::AudioFader::alloc ( const std::shared_ptr< AudioNode > &  input)
inlinestatic

Returns a newly allocated fader for the given input node.

This node acquires the channels and sample rate of the input. If input is nullptr, this method will fail.

Parameters
inputThe audio node to fade
Returns
a newly allocated fader for the given input node.

◆ alloc() [3/3]

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

Returns a newly allocated fader with the given number of channels and sample rate

Any input node must agree with these settings.

Parameters
channelsThe number of audio channels
rateThe sample rate (frequency) in HZ
Returns
a newly allocated fader with the given number of channels and sample rate

◆ attach()

bool cugl::audio::AudioFader::attach ( const std::shared_ptr< AudioNode > &  node)

Attaches an audio node to this fader.

This method will fail if the channels of the audio node do not agree with this fader.

Parameters
nodeThe audio node to fade
Returns
true if the attachment was successful

◆ completed()

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

Returns true if this audio node has no more data.

A completed audio node is one that will return 0 (no frames read) on subsequent threads read.

Returns
true if this audio node has no more data.

Reimplemented from cugl::audio::AudioNode.

◆ detach()

std::shared_ptr<AudioNode> cugl::audio::AudioFader::detach ( )

Detaches an audio node from this fader.

If the method succeeds, it returns the audio node that was removed.

Returns
The audio node to detach (or null if failed)

◆ dispose()

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

Disposes any resources allocated for this player

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.

◆ doFadeIn()

Uint32 cugl::audio::AudioFader::doFadeIn ( float *  buffer,
Uint32  frames 
)
protected

Performs a fade-in.

This method is called by read to adjust the gain for a fade-in. Depending on where the fade completes, it may not process all of the elements in the buffer.

If this method reaches the end of a fade-in, it will execute a callback function if one is provided.

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.

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

◆ doFadeOut()

Uint32 cugl::audio::AudioFader::doFadeOut ( float *  buffer,
Uint32  frames 
)
protected

Performs a fade-out.

This method is called by read to adjust the gain for a fade-in. Depending on where the fade completes, it may not process all of the elements in the buffer.

If this method reaches the end of a fade-out, it will execute a callback function if one is provided. It will also mark the node as completed.

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.

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

◆ doFadePause()

Uint32 cugl::audio::AudioFader::doFadePause ( float *  buffer,
Uint32  frames 
)
protected

Performs a fade-pause.

This method is called by read to adjust the gain for a fade-in. Depending on where the fade completes, it may not process all of the elements in the buffer.

If this method reaches the MIDDLE of a fade-pause, it will execute a callback function if one is provided. Hence the callback is to indicate when the pause has gone into effect. It will also pause the node at that time. When the node is resumed, this method will call another callback (if applicable) when the fade-in is completed.

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.

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

◆ fadeIn()

void cugl::audio::AudioFader::fadeIn ( double  duration)

Starts a fade-in from the current position.

This temporarily sets the gain to 0 and then ramps up to the correct gain over the time period duration. The effect is a linear fade-in. If this node has a callback function, it will be called when the fade-in is complete (e.g. volume has returned to normal).

Fade-in is emphemeral and it lost when the read position is moved or the fade-in is complete.

Parameters
durationThe fade-in time in seconds

◆ fadeOut()

void cugl::audio::AudioFader::fadeOut ( double  duration,
bool  wrap = false 
)

Starts a fade-out from the current position.

This will reduce the gain to 0 over the time period duration. In addition, it will mark the node as completed once it reaches 0 gain. The effect is a linear fade-out. If this node has a callback function, it will be called when the fade-out is complete (e.g. volume has reduced to 0).

If the duration is longer than the length of the audio, the volume will not drop to 0 (and the callback will not be invoked). However, if wrap is set to true, the fade-in will carry over on a reset, fadeing in from the beginning.

Moving the read position will cancel a fade out.

Parameters
durationThe fade-in time in seconds
wrapWhether to support a fade-out after reset

◆ fadePause() [1/2]

void cugl::audio::AudioFader::fadePause ( double  duration)

Starts a fade-pause from the current position.

This method will reduce the gain to 0 over the time period duration. In addition, it will pause once reaches 0 gain. When the node is resumed, it will ramp back up to the correct gain over the time period duration. Both fade effects are linear.

If this node has a callback function, it will be called twice during the pause. It will be called when the first fade-out is complete (e.g. the volume is reduced to 0) and then again when the fade-in has completed after resuming.

A fade-pause is emphemeral and it lost when the read position is moved or the fade-pause is complete.

Parameters
durationThe fade-in/out time in seconds

◆ fadePause() [2/2]

void cugl::audio::AudioFader::fadePause ( double  fadeout,
double  fadein 
)

Starts a fade-pause from the current position.

This method will reduce the gain to 0 over the time period fadeout. In addition, it will pause once reaches 0 gain. When the node is resumed, it will ramp back up to the correct gain over the time period fadein. Both fade effects are linear.

If this node has a callback function, it will be called twice during the pause. It will be called when the first fade-out is complete (e.g. the volume is reduced to 0) and then again when the fade-in has completed after resuming.

A fade-pause is emphemeral and it lost when the read position is moved or the fade-pause is complete.

Parameters
fadeoutThe fade-out time in seconds
fadeinThe fade-in time in seconds

◆ getElapsed()

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

Returns the elapsed time in seconds.

The value returned is always measured from the start of the steam, regardless of the presence of any marks.

Returns
the elapsed time in seconds.

Reimplemented from cugl::audio::AudioNode.

◆ getInput()

std::shared_ptr<AudioNode> cugl::audio::AudioFader::getInput ( )
inline

Returns the input node of this fader.

Returns
the input node of this fader.

◆ getPosition()

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

Returns the current frame position of this audio node

The value returned will always be the absolute frame position regardless of the presence of any marks.

Returns
the current frame position of this audio node.

Reimplemented from cugl::audio::AudioNode.

◆ getRemaining()

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

Returns the remaining time in seconds.

The remaining time is duration from the current read position to the end of the sample. It is not effected by any fade-out.

Returns
the remaining time in seconds.

Reimplemented from cugl::audio::AudioNode.

◆ init() [1/3]

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

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 from cugl::audio::AudioNode.

◆ init() [2/3]

bool cugl::audio::AudioFader::init ( const std::shared_ptr< AudioNode > &  input)

Initializes a fader for the given input node.

This node acquires the channels and sample rate of the input. If input is nullptr, this method will fail.

Parameters
inputThe audio node to fade
Returns
true if initialization was successful

◆ init() [3/3]

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

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 from cugl::audio::AudioNode.

◆ isFadeIn()

bool cugl::audio::AudioFader::isFadeIn ( )

Returns true if this node is in an active fade-in.

Returns
true if this node is in an active fade-in.

◆ isFadeOut()

bool cugl::audio::AudioFader::isFadeOut ( )

Returns true if this node is in an active fade-out.

Returns
true if this node is in an active fade-out.

◆ isFadePause()

bool cugl::audio::AudioFader::isFadePause ( )

Returns true if this node is in an active fade-pause.

This method will not distinguish if the node is before or after the pause point.

Returns
true if this node is in an active fade-pause.

◆ isPaused()

virtual bool cugl::audio::AudioFader::isPaused ( )
overridevirtual

Returns true if this node is currently paused

Returns
true if this node is currently paused

Reimplemented from cugl::audio::AudioNode.

◆ mark()

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

Marks the current read position in the audio steam.

This method is used by reset() to determine where to restore the read position.

Returns
true if the read position was marked.

Reimplemented from cugl::audio::AudioNode.

◆ pause()

virtual bool cugl::audio::AudioFader::pause ( )
overridevirtual

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 from cugl::audio::AudioNode.

◆ read()

virtual Uint32 cugl::audio::AudioFader::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. 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 from cugl::audio::AudioNode.

◆ reset()

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

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

If no mark is set, this will reset to the player to the beginning of the audio sample.

Returns
true if the read position was moved.

Reimplemented from cugl::audio::AudioNode.

◆ resume()

virtual bool cugl::audio::AudioFader::resume ( )
overridevirtual

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 from cugl::audio::AudioNode.

◆ setElapsed()

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

Sets the read position to the elapsed time in seconds.

The value returned is always measured from the start of the steam, regardless of the presence of any marks.

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

Reimplemented from cugl::audio::AudioNode.

◆ setPosition()

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

Sets the current frame position of this audio node.

The value set will always be the absolute frame position regardless of the presence of any marks.

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::AudioFader::setRemaining ( double  time)
overridevirtual

Sets the remaining time in seconds.

This method will move the read position so that the distance between it and the end of the same is the given number of seconds.

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

Reimplemented from cugl::audio::AudioNode.

◆ unmark()

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

Clears the current marked position.

Clearing the mark in a player is equivelent to setting the mark at the beginning of the audio asset. Future calls to reset() will return to the start of the audio stream.

Returns
true if the read position was cleared.

Reimplemented from cugl::audio::AudioNode.

Member Data Documentation

◆ _diphalf

bool cugl::audio::AudioFader::_diphalf
protected

Whether we have completed the first half of a fade-dip

◆ _dipmark

Sint64 cugl::audio::AudioFader::_dipmark
protected

The middle (pause) frame of the fade-dip; -1 if no active fade-dip

◆ _dipstart

bool cugl::audio::AudioFader::_dipstart
protected

To prevent a race condition on pausing

◆ _dipstop

Uint64 cugl::audio::AudioFader::_dipstop
protected

The final (resume) frame of the fade-dip; 0 if no active fade-dip

◆ _fadedip

Uint64 cugl::audio::AudioFader::_fadedip
protected

The current fade-dip in frames; 0 if no active fade-dip

◆ _fadein

Uint64 cugl::audio::AudioFader::_fadein
protected

The current fade-in in frames; 0 if no active fade-in

◆ _fadeout

Uint64 cugl::audio::AudioFader::_fadeout
protected

The current fade-out in frames; 0 if no active fade-out

◆ _inmark

Sint64 cugl::audio::AudioFader::_inmark
protected

The final frame of the current fade-in; -1 if no active fade-in

◆ _input

std::shared_ptr<AudioNode> cugl::audio::AudioFader::_input
protected

The audio input node

◆ _mutex

std::mutex cugl::audio::AudioFader::_mutex
protected

This class needs a proper lock guard; too many race conditions

◆ _outdone

bool cugl::audio::AudioFader::_outdone
protected

Whether we have completed this node due to a fadeout

◆ _outkeep

bool cugl::audio::AudioFader::_outkeep
protected

Whether to persist fade-out on a reset

◆ _outmark

Sint64 cugl::audio::AudioFader::_outmark
protected

The final frame of the current fade-out; -1 if no active fade-out


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