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::get_mixer() const member function. The member function returns a raw pointer, which will be nullptr
if the mixer could not be initialized.
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(Music_track). Once a Music_track is attached, it can be played with Mixer::resume(Duration) and paused with Mixer::pause_music(Duration). A Music_track can be both attached and played with Mixer::play_music(Music_track). The music channel is always in one of four states, of type audio::Mixer::State, which can be retrieved by Mixer::get_music_state() const. 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(Sound_effect, double) 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(Sound_effect, double) returns a Sound_effect_handle, which can be used to control the sound effect while it is playing as well.
Definition at line 142 of file ge211_audio.h.
Public Types | |
enum | State { detached, playing, fading_out, paused } |
The state of an audio channel. More... | |
Public Member Functions | |
Playing music | |
void | play_music (Music_track) |
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)) |
Plays the currently attached music from the current saved position, fading in if requested. 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, double). More... | |
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... | |
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. | |
|
strong |
The state of an audio channel.
Definition at line 146 of file ge211_audio.h.
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.
get_music_state()
is paused
or detached
; throws exceptions::Client_logic_error if violated. Definition at line 111 of file ge211_audio.cpp.
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, double).
Definition at line 345 of file ge211_audio.cpp.
|
inline |
Returns the current state of the attached music, if any.
The state changes in only three ways:
paused
to playing
playing
to paused
.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 232 of file ge211_audio.h.
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(double).
Definition at line 367 of file ge211_audio.cpp.
Pauses the currently attached music, fading out if requested.
get_music_state()
is paused
or playing
; throws exceptions::Client_logic_error if violated. Definition at line 159 of file ge211_audio.cpp.
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.
available_effect_channels() > 0
, throws exceptions::Mixer_error if violated.!effect.empty()
, undefined behavior if violated. Definition at line 256 of file ge211_audio.cpp.
void play_music | ( | Music_track | music | ) |
Attaches the given music track to this mixer and starts it playing.
Equivalent to Mixer::attach_music(Music_track) followed by Mixer::unpause_music(Duration).
get_music_state()
is paused
or detached
; throws exceptions::Client_logic_error if violated. Definition at line 105 of file ge211_audio.cpp.
Plays the currently attached music from the current saved position, fading in if requested.
get_music_state()
is paused
or playing
; throws exceptions::Client_logic_error if violated. Definition at line 134 of file ge211_audio.cpp.
void rewind_music | ( | ) |
Rewinds the music to the beginning.
get_music_state()
is paused
; throws exceptions::Client_logic_error if violated. Definition at line 185 of file ge211_audio.cpp.