#include <CUAudioFader.h>

Inheritance diagram for cugl::audio::AudioFader:

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< AudioNode >	detach ()

std::shared_ptr< AudioNode >	getInput ()

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< AudioFader >	alloc ()

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

static std::shared_ptr< AudioFader >	alloc (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 player with no associated source.

The player has no channels or source file, so read options will do nothing. The player 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

frames The 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

input The 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

channels	The number of audio channels
rate	The 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

node	The 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

buffer	The read buffer to store the results
frames	The 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

buffer	The read buffer to store the results
frames	The 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

buffer	The read buffer to store the results
frames	The 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

duration The 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

duration	The fade-in time in seconds
wrap	Whether 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

duration The 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

fadeout	The fade-out time in seconds
fadein	The 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

input The 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

channels	The number of audio channels
rate	The 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

buffer	The read buffer to store the results
frames	The 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

time	The 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

position the 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

time	The 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:

include/cugl/audio/graph/CUAudioFader.h

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ AudioFader()

◆ ~AudioFader()

Member Function Documentation

◆ advance()

◆ alloc() [1/3]

◆ alloc() [2/3]

◆ alloc() [3/3]

◆ attach()

◆ completed()

◆ detach()

◆ dispose()

◆ doFadeIn()

◆ doFadeOut()

◆ doFadePause()

◆ fadeIn()

◆ fadeOut()

◆ fadePause() [1/2]

◆ fadePause() [2/2]

◆ getElapsed()

◆ getInput()

◆ getPosition()

◆ getRemaining()

◆ init() [1/3]

◆ init() [2/3]

◆ init() [3/3]

◆ isFadeIn()

◆ isFadeOut()

◆ isFadePause()

◆ isPaused()

◆ mark()

◆ pause()

◆ read()

◆ reset()

◆ resume()

◆ setElapsed()

◆ setPosition()

◆ setRemaining()

◆ unmark()

Member Data Documentation

◆ _diphalf

◆ _dipmark

◆ _dipstart

◆ _dipstop

◆ _fadedip

◆ _fadein

◆ _fadeout

◆ _inmark

◆ _input

◆ _mutex

◆ _outdone

◆ _outkeep

◆ _outmark