Detailed Description

The entity that coordinates playing all audio tracks.

The mixer is the center of ge211's audio facilities. It is used to load audio files as Music_tracks and Sound_effects, and to play and control them. However, Mixer itself has no public constructor, and you will not construct your own. Rather, a Mixer is constructed, if possible, when Abstract_game is initialized, and this mixer can be accessed by your game via the Abstract_game::mixer member function. The member function returns a reference to an uncopyable object.

This mixer has one music channel, and some fixed number (usually 8) of sound effects channels. This means that it can play one Music_track and up to (usually) 8 Sound_effects simultaneously.

For playing background music, one Music_track can be attached to the mixer at any given time, using Mixer::attach_music. Once a Music_track is attached, it can be played with Mixer::resume_music and paused with Mixer::pause_music. A Music_track can be both attached and played in one step with Mixer::play_music. The music channel is always in one of four states, of type audio::Mixer::State, which can be retrieved by Mixer::get_music_state. Note that the validity of music operations depends on what state the mixer's music channel is in. For example, it is an error to attach a Music_track to the mixer when music is already playing or fading out.

For playing sound effects, multiple Sound_effects can be attached to the mixer simultaneously. A Sound_effect is attached and played using the Mixer::play_effect member function, which also allows specifying the volume of the sound effect. If nothing further is done, the sound effect plays to completion and then detaches, making room to attach more sound effects; however, Mixer::play_effect returns a Sound_effect_handle, which can be used to control the sound effect while it is playing as well.

Definition at line 190 of file ge211_audio.hxx.

Public Types
enum	State { detached, playing, fading_out, paused }
	The state of an audio channel. More...

Public Member Functions
bool	is_enabled () const
	Returns whether the mixer is enabled. More...

Playing music
void	play_music (Music_track, bool forever=false)
	Attaches the given music track to this mixer and starts it playing. More...

void	attach_music (Music_track)
	Attaches the given music track to this mixer. More...

void	resume_music (Duration fade_in=Duration(0), bool forever=false)
	Plays the currently attached music from the current saved position. More...

void	pause_music (Duration fade_out=Duration(0))
	Pauses the currently attached music, fading out if requested. More...

void	rewind_music ()
	Rewinds the music to the beginning. More...

const Music_track &	get_music () const
	Gets the Music_track currently attached to this Mixer, if any.

State	get_music_state () const
	Returns the current state of the attached music, if any. More...

double	get_music_volume () const
	Returns the music volume as a number from 0.0 to 1.0. More...

void	set_music_volume (double unit_value)
	Sets the music volume, on a scale from 0.0 to 1.0.

Playing sound effects
int	available_effect_channels () const
	How many effect channels are currently unused? If this is positive, then we can play an additional sound effect with Mixer::play_effect.

Sound_effect_handle	play_effect (Sound_effect effect, double volume=1.0)
	Plays the given effect track on this mixer, at the specified volume. More...

Sound_effect_handle	try_play_effect (Sound_effect effect, double volume=1.0)
	Attempts to play the given effect track on this mixer, returning an empty Sound_effect_handle if no effect channel is available. More...

void	pause_all_effects ()
	Pauses all currently-playing effects.

void	resume_all_effects ()
	Unpauses all currently-paused effects.

Constructors, assignment operators, and destructor
	Mixer (const Mixer &)=delete
	The mixer cannot be copied.

	Mixer (const Mixer &&)=delete
	The mixer cannot be moved.

Mixer &	operator= (const Mixer &)=delete
	The mixer cannot be copied.

Mixer &	operator= (const Mixer &&)=delete
	The mixer cannot be moved.

	~Mixer ()
	Destructor, to clean up the mixer's resources.

Member Enumeration Documentation

◆ State

enum State

strong

The state of an audio channel.

Enumerator
detached	No track is attached to the channel, or no channel is attached to the handle.
playing	Actively playing.
fading_out	In the process of fading out from playing to paused (for music) or to halted and detached (for sound effects).
paused	Attached but not playing.

Definition at line 199 of file ge211_audio.hxx.

Member Function Documentation

◆ attach_music()

void attach_music ( Music_track music )

Attaches the given music track to this mixer.

Give the empty Music_track to detach the current track, if any, without attaching a replacement.

Preconditions

get_music_state() is paused or detached; throws exceptions::Client_logic_error if violated.

Definition at line 150 of file ge211_audio.cxx.

◆ get_music_state()

State get_music_state ( ) const

inline

Returns the current state of the attached music, if any.

The state changes in only three ways:

In response to client actions, for example, Mixer::resume_music changes the state from paused to playing
When a playing track ends, it changes from playing to paused.
When a pause-with-fade-out ends, it changes from fading_out to paused.

Cases 2 and 3 happen only between frames, and not asynchronously while computing the next frame. This means that after checking the result of get_music_state() const, that state continues to hold, and can be relied on, at least until the end of the frame, unless the client requests that it be changed (case 1).

Definition at line 290 of file ge211_audio.hxx.

◆ get_music_volume()

double get_music_volume ( ) const

Returns the music volume as a number from 0.0 to 1.0.

Initially this will be 1.0, but you can lower it with Mixer::set_music_volume.

Definition at line 422 of file ge211_audio.cxx.

◆ is_enabled()

bool is_enabled ( ) const

inline

Returns whether the mixer is enabled.

If it is then we can play audio, but if it isn't, audio operations will fail.

Definition at line 215 of file ge211_audio.hxx.

◆ pause_music()

void pause_music ( Duration fade_out = Duration(0) )

Pauses the currently attached music, fading out if requested.

Preconditions

get_music_state() is paused or playing; throws exceptions::Client_logic_error if violated.

Definition at line 198 of file ge211_audio.cxx.

◆ play_effect()

Sound_effect_handle play_effect	(	Sound_effect	effect,
		double	volume = `1.0`
	)

Plays the given effect track on this mixer, at the specified volume.

The volume must be in the unit interval. Returns a Sound_effect_handle, which can be used to control the sound effect while it's playing.

Preconditions

available_effect_channels() > 0, throws exceptions::Mixer_error if violated.
!effect.empty(), undefined behavior if violated.

Definition at line 295 of file ge211_audio.cxx.

◆ play_music()

void play_music	(	Music_track	music,
		bool	forever = `false`
	)

Attaches the given music track to this mixer and starts it playing.

Loops forever if given true for forever; otherwise when the music track finishes, the mixer rewinds and pauses it.

Equivalent to Mixer::attach_music followed by Mixer::resume_music.

Preconditions

get_music_state() is paused or detached; throws exceptions::Client_logic_error if violated.

Definition at line 144 of file ge211_audio.cxx.

◆ resume_music()

void resume_music	(	Duration	fade_in = `Duration(0)`,
		bool	forever = `false`
	)

Plays the currently attached music from the current saved position.

Fades in if given a non-zero Duration for fade_in. Loops forever if given true for forever; otherwise when the music track finishes, the mixer rewinds and pauses it.

Preconditions

get_music_state() is paused or playing; throws exceptions::Client_logic_error if violated.

Definition at line 173 of file ge211_audio.cxx.

◆ rewind_music()

void rewind_music ( )

Rewinds the music to the beginning.

Preconditions

get_music_state() is paused; throws exceptions::Client_logic_error if violated.

Definition at line 224 of file ge211_audio.cxx.

◆ try_play_effect()

Sound_effect_handle try_play_effect	(	Sound_effect	effect,
		double	volume = `1.0`
	)

Attempts to play the given effect track on this mixer, returning an empty Sound_effect_handle if no effect channel is available.

Preconditions

!effect.empty(), undefined behavior if violated.

Definition at line 306 of file ge211_audio.cxx.

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

/Users/tov/school/cs211/dev/ge211/include/ge211_audio.hxx
/Users/tov/school/cs211/dev/ge211/src/ge211_audio.cxx

Detailed Description

Public Types

Public Member Functions

Member Enumeration Documentation

◆ State

Member Function Documentation

◆ attach_music()

Preconditions

◆ get_music_state()

◆ get_music_volume()

◆ is_enabled()

◆ pause_music()

Preconditions

◆ play_effect()

Preconditions

◆ play_music()

Preconditions

◆ resume_music()

Preconditions

◆ rewind_music()

Preconditions

◆ try_play_effect()

Preconditions