 |
CUGL
Cornell University Game Library
|
#include <CUAudioEngine.h>
Public Types | |
| enum | State { State::INACTIVE, State::PLAYING, State::PAUSED } |
Public Member Functions | |
| void | playMusic (const std::shared_ptr< Music > &music, bool loop=false, float volume=-1.0f, float fade=0.0f) |
| const Music * | currentMusic () const |
| State | getMusicState () const |
| bool | isMusicLoop () const |
| void | setMusicLoop (bool loop) |
| float | getMusicVolume () const |
| void | setMusicVolume (float volume) |
| float | getMusicDuration () const |
| double | getMusicElapsed () const |
| double | getMusicRemaining () const |
| void | setMusicElapsed (double time) |
| void | setMusicRemaining (double time) |
| void | stopMusic (float fade=0.0f) |
| void | clearMusicQueue () |
| void | pauseMusic () |
| void | resumeMusic () |
| void | setMusicListener (std::function< void(Music *, bool)> callback) |
| std::function< void(Music *, bool)> | getMusicListener () const |
| void | gcMusic (bool status) |
| void | queueMusic (const std::shared_ptr< Music > &music, bool loop=false, float volume=-1.0f, float fade=0.0f) |
| const std::vector< const Music * > | getMusicQueue () const |
| size_t | getMusicQueueSize () const |
| void | advanceMusicQueue (unsigned int steps=0) |
| bool | playEffect (const std::string &key, const std::shared_ptr< Sound > &sound, bool loop=false, float volume=-1.0f, bool force=false) |
| bool | playEffect (const char *key, const std::shared_ptr< Sound > &sound, bool loop=false, float volume=-1.0f, bool force=false) |
| size_t | getAvailableChannels () const |
| State | getEffectState (const std::string &key) const |
| State | getEffectState (const char *key) const |
| bool | isActiveEffect (const std::string &key) const |
| bool | isActiveEffect (const char *key) const |
| const Sound * | currentEffect (const std::string &key) const |
| const Sound * | currentEffect (const char *key) const |
| bool | isEffectLoop (const std::string &key) const |
| bool | isEffectLoop (const char *key) const |
| void | setEffectLoop (const std::string &key, bool loop) |
| void | setEffectLoop (const char *key, bool loop) |
| float | getEffectVolume (const std::string &key) const |
| float | getEffectVolume (const char *key) const |
| void | setEffectVolume (const std::string &key, float volume) |
| void | setEffectVolume (const char *key, float volume) |
| float | getEffectDuration (const std::string &key) const |
| float | getEffectDuration (const char *key) const |
| float | getEffectElapsed (const std::string &key) const |
| float | getEffectElapsed (const char *key) const |
| float | getEffectRemaining (const std::string &key) const |
| float | getEffectRemaining (const char *key) const |
| void | setEffectElapsed (const std::string &key, float time) |
| void | setEffectElapsed (const char *key, float time) |
| void | setEffectRemaining (const std::string &key, float time) |
| void | setEffectRemaining (const char *key, float time) |
| void | stopEffect (const std::string &key) |
| void | stopEffect (const char *key) |
| void | pauseEffect (const std::string &key) |
| void | pauseEffect (const char *key) |
| void | resumeEffect (std::string key) |
| void | resumeEffect (const char *key) |
| void | stopAllEffects () |
| void | pauseAllEffects () |
| void | resumeAllEffects () |
| void | setEffectListener (std::function< void(const std::string &key, bool)> callback) |
| std::function< void(const std::string &key, bool)> | getEffectListener () const |
| void | gcEffect (int id, bool status) |
| void | stopAll () |
| void | pauseAll () |
| void | resumeAll () |
Static Public Member Functions | |
| static AudioEngine * | get () |
| static void | start (unsigned int channels=AUDIO_INPUT_CHANNELS) |
| static void | stop () |
Class provides a singleton audio engine
This class is a simple (e.g. 2000-era) audio engine. It exposes a flat channel structure and there is no mixer graph for advanced effects such as 3D audio. If you need these features, use AudioEngineHD instead.
This class allows one music asset to be played at a time, though it does allow you to queue up music asset. All other sounds should be preloaded. The user specifies sound instances (there may be may sound instances for a single asset) by a predefined key. This cuts down on the overhead of managing the sound identifier.
You cannot create new instances of this class. Instead, you should access the singleton through the three static methods: start(), stop() and get().
IMPORTANT: Like the OpenGL context, this class is not thread-safe. It is only safe to access this class in the main application thread. This means it should never be called in a call-back function as those are typically executed in the host thread. If you need to access the AudioEngine in a callback function, you should use the Application#schedule method to delay until the main thread is next available.
|
strong |
| void cugl::AudioEngine::advanceMusicQueue | ( | unsigned int | steps = 0 | ) |
Advances ahead in the music queue.
The value step is the number of songs to skip over. A value of 0 will simply skip over the active music to the next element of the queue. Each value above 0 will skip over one more element in the queue. If this skipping empties the queue, no music will play.
| steps | number of elements to skip in the queue |
| void cugl::AudioEngine::clearMusicQueue | ( | ) |
Clears the music queue, but does not release any other resources.
This method does not stop the current background music from playing. It only clears pending music assets from the queue.
| const Sound* cugl::AudioEngine::currentEffect | ( | const std::string & | key | ) | const |
Returns the sound asset attached to the given key.
If there is no active sound effect for the given key, this method returns nullptr.
| key | the reference key for the sound effect |
|
inline |
Returns the sound asset attached to the given key.
If there is no active sound effect for the given key, this method returns nullptr.
| key | the reference key for the sound effect |
| const Music* cugl::AudioEngine::currentMusic | ( | ) | const |
Returns the music asset currently playing
If there is no active background music, this method returns nullptr.
| void cugl::AudioEngine::gcEffect | ( | int | id, |
| bool | status | ||
| ) |
Callback function for when a sound effect channel finishes
This method is called when the active sound effect completes. It garbage collects the sound effect, allowing its key to be reused.
This method is never intended to be accessed by general users. It is only publicly visible because this makes our cross-platform code cleaner.
| id | The sound channel being garbage collected |
| status | True if the music terminated normally, false otherwise. |
| void cugl::AudioEngine::gcMusic | ( | bool | status | ) |
Callback function for when a music channel finishes
This method is called when the active music completes. If there is any music waiting in the queue, it plays it immediately (using the second channel for a smooth transition). Otherwise, it sets _musicData to nullptr.
This method is never intended to be accessed by general users. It is only publicly visible because this makes our cross-platform code cleaner.
| status | True if the music terminated normally, false otherwise. |
|
inlinestatic |
Returns the singleton instance of the audio engine.
If the audio engine has not been started, then this method will return nullptr.
|
inline |
Returns the number of channels available for sound effects.
There are a limited number of channels available for sound effects. If all channels are in use, this method will return 0. If you go over the number available, you cannot play another sound unless you force it. In that case, it will grab the channel from the longest playing sound effect.
| float cugl::AudioEngine::getEffectDuration | ( | const std::string & | key | ) | const |
Returns the duration of the sound effect, in seconds.
Because the asset is fully decompressed at load time, the result of this method is reasonably accurate.
If the key does not correspond to a channel, this method raises an error.
| key | the reference key for the sound effect |
|
inline |
Returns the duration of the sound effect, in seconds.
Because the asset is fully decompressed at load time, the result of this method is reasonably accurate.
If the key does not correspond to a channel, this method raises an error.
| key | the reference key for the sound effect |
| float cugl::AudioEngine::getEffectElapsed | ( | const std::string & | key | ) | const |
Returns the elapsed time of the sound effect, in seconds
The elapsed time is the current position of the sound from the beginning. It does not include any time spent on a continuous loop. Because the asset is fully decompressed at load time, the result of this method is reasonably accurate.
If the key does not correspond to a channel, this method raises an error.
| key | the reference key for the sound effect |
|
inline |
Returns the elapsed time of the sound effect, in seconds
The elapsed time is the current position of the sound from the beginning. It does not include any time spent on a continuous loop. Because the asset is fully decompressed at load time, the result of this method is reasonably accurate.
If the key does not correspond to a channel, this method raises an error.
| key | the reference key for the sound effect |
|
inline |
Returns the callback for sound effects
This cllabck function is called whenever a sound effect completes. It is called whether or not the sound completed normally or if it was terminated manually. However, the second parameter can be used to distinguish the two cases.
| float cugl::AudioEngine::getEffectRemaining | ( | const std::string & | key | ) | const |
Returns the time remaining for the sound effect, in seconds
The time remaining is just duration-elapsed. This method does not take into account whether the sound is on a loop. Because the asset is fully decompressed at load time, the result of this method is reasonably accurate.
If the key does not correspond to a channel, this method raises an error.
| key | the reference key for the sound effect |
|
inline |
Returns the time remaining for the sound effect, in seconds
The time remaining is just duration-elapsed. This method does not take into account whether the sound is on a loop. Because the asset is fully decompressed at load time, the result of this method is reasonably accurate.
If the key does not correspond to a channel, this method raises an error.
| key | the reference key for the sound effect |
| State cugl::AudioEngine::getEffectState | ( | const std::string & | key | ) | const |
Returns the current state of the sound effect for the given key.
If there is no sound effect for the given key, it returns State::INACTIVE.
| key | the reference key for the sound effect |
|
inline |
Returns the current state of the sound effect for the given key.
If there is no sound effect for the given key, it returns State::INACTIVE.
| key | the reference key for the sound effect |
| float cugl::AudioEngine::getEffectVolume | ( | const std::string & | key | ) | const |
Returns the current volume of the sound effect.
If the key does not correspond to a channel, this method raises an error.
| key | the reference key for the sound effect |
|
inline |
Returns the current volume of the sound effect.
If the key does not correspond to a channel, this method raises an error.
| key | the reference key for the sound effect |
| float cugl::AudioEngine::getMusicDuration | ( | ) | const |
Returns the length of background music, in seconds.
This is only the duration of the active background music. All other music in the queue is ignored. If there is no active background music, this method will return 0.
This information is retrieved from the decoder. As the file is completely decoded at load time, the result of this method is reasonably accurate.
| double cugl::AudioEngine::getMusicElapsed | ( | ) | const |
Returns the elapsed time of the background music, in seconds
The elapsed time is the current position of the music from the beginning. It does not include any time spent on a continuous loop. If there is no active background music, this method will return 0.
This information is not guaranteed to be accurate. Attempting to time the playback of streaming data (as opposed to a fully in-memory PCM buffer) is very difficult and not cross-platform. We have tried to be reasonably accurate, but from our tests we can only guarantee accuracy within a 10th of a second.
|
inline |
Returns the callback for background music
This callback function is called whenever a background music track completes. It is called whether or not the music completed normally or if it was terminated manually. However, the second parameter can be used to distinguish the two cases.
| const std::vector<const Music*> cugl::AudioEngine::getMusicQueue | ( | ) | const |
Returns the list of assets for the music queue
| size_t cugl::AudioEngine::getMusicQueueSize | ( | ) | const |
Returns the size of the music queue
| double cugl::AudioEngine::getMusicRemaining | ( | ) | const |
Returns the time remaining for the background music, in seconds
The time remaining is just duration-elapsed. This method does not take into account whether the music is on a loop. It also does not include the duration of any music waiting in the queue. If there is no active background music, this method will return 0.
This information is not guaranteed to be accurate. Attempting to time the playback of streaming data (as opposed to a fully in-memory PCM buffer) is very difficult and not cross-platform. We have tried to be reasonably accurate, but from our tests we can only guarantee accuracy within a 10th of a second.
| State cugl::AudioEngine::getMusicState | ( | ) | const |
Returns the current state of the background music
| float cugl::AudioEngine::getMusicVolume | ( | ) | const |
Returns the volume of the background music
If there is no active background music, this method will return 0.
|
inline |
Returns true if the key is associated with an active channel.
| key | the reference key for the sound effect |
|
inline |
Returns true if the key is associated with an active channel.
| key | the reference key for the sound effect |
| bool cugl::AudioEngine::isEffectLoop | ( | const std::string & | key | ) | const |
Returns true if the sound effect is in a continuous loop.
If the key does not correspond to a channel, this method raises an error.
| key | the reference key for the sound effect |
|
inline |
Returns true if the sound effect is in a continuous loop.
If the key does not correspond to a channel, this method raises an error.
| key | the reference key for the sound effect |
| bool cugl::AudioEngine::isMusicLoop | ( | ) | const |
Returns true if the background music is in a continuous loop.
If there is no active background music, this method will return false.
| void cugl::AudioEngine::pauseAll | ( | ) |
Pauses all sounds, both music and sound effects.
This method allows them to be resumed later. You should generally call this method just before the app pages to the background.
| void cugl::AudioEngine::pauseAllEffects | ( | ) |
Pauses all sound effects, allowing them to be resumed later.
Sound effects already paused will remain paused.
| void cugl::AudioEngine::pauseEffect | ( | const std::string & | key | ) |
Pauses the sound effect for the given key.
If the key does not correspond to a channel, this method raises an error.
| key | the reference key for the sound effect |
|
inline |
Pauses the sound effect for the given key.
If the key does not correspond to a channel, this method raises an error.
| key | the reference key for the sound effect |
| void cugl::AudioEngine::pauseMusic | ( | ) |
Pauses the background music, allowing it to be resumed later.
This method has no effect on the music queue.
| bool cugl::AudioEngine::playEffect | ( | const std::string & | key, |
| const std::shared_ptr< Sound > & | sound, | ||
| bool | loop = false, |
||
| float | volume = -1.0f, |
||
| bool | force = false |
||
| ) |
Plays the given sound effect, and associates it with the specified key.
Sound effects are associated with a reference key. This allows the application to easily reference the sound state without having to internally manage pointers to the audio channel.
If the key is already associated with an active sound channel, this method will stop the existing sound and replace it with this one. It is the responsibility of the application layer to manage key usage.
There are a limited number of channels available for sound effects. If you go over the number available, the sound will not play unless force is true. In that case, it will grab the channel from the longest playing sound effect.
| key | The reference key for the sound effect |
| sound | The sound effect to play |
| loop | Whether to loop the sound effect continuously |
| volume | The sound effect (< 0 to use asset default volume) |
| force | Whether to force another sound to stop. |
|
inline |
Plays the given sound effect, and associates it with the specified key.
Sound effects are associated with a reference key. This allows the application to easily reference the sound state without having to internally manage pointers to the audio channel.
If the key is already associated with an active sound channel, this method will stop the existing sound and replace it with this one. It is the responsibility of the application layer to manage key usage.
There are a limited number of channels available for sound effects. If you go over the number available, the sound will not play unless force is true. In that case, it will grab the channel from the longest playing sound effect.
| key | The reference key for the sound effect |
| sound | The sound effect to play |
| loop | Whether to loop the sound effect continuously |
| volume | The sound effect (< 0 to use asset default volume) |
| force | Whether to force another sound to stop. |
| void cugl::AudioEngine::playMusic | ( | const std::shared_ptr< Music > & | music, |
| bool | loop = false, |
||
| float | volume = -1.0f, |
||
| float | fade = 0.0f |
||
| ) |
Plays given music asset as a background track.
Music is handled differently from sound effects. Music is streamed instead of being pre-loaded, so your music files can be much larger. In addition, you can only play one music asset at a time. However, it is possible to queue music assets for immediate playback once the active asset is finished.
This method immediately plays the provided asset. Hence it overrides and clears the music queue. To safely play an asset without affecting the music queue, use the method queueMusic instead.
When it begins playing, it will start at full volume unless you provide a number of seconds to fade in. Note that looping a song will cause it to block the queue indefinitely until you turn off looping for that asset {
| music | The music asset to play |
| loop | Whether to loop the music continuously |
| volume | The music volume (< 0 to use asset default volume) |
| fade | The number of seconds to fade in |
| void cugl::AudioEngine::queueMusic | ( | const std::shared_ptr< Music > & | music, |
| bool | loop = false, |
||
| float | volume = -1.0f, |
||
| float | fade = 0.0f |
||
| ) |
Adds the given music asset to the background music queue
Music is handled differently from sound effects. Music is streamed instead of being pre-loaded, so your music files can be much larger. In addition, you can only play one music asset at a time. However, it is possible to queue music assets for immediate playback once the active asset is finished.
If the queue is empty and there is no active music, this method will play the music immediately. Otherwise, it will add the music to the queue, and it will play as soon as it is removed from the queue.
When it begins playing, it will start at full volume unless you provide a number of seconds to fade in. Note that looping a song will cause it to block the queue indefinitely until you turn off looping for that asset {
| music | The music asset to queue |
| loop | Whether to loop the music continuously |
| volume | The music volume (< 0 to use asset default volume) |
| fade | The number of seconds to fade in |
| void cugl::AudioEngine::resumeAll | ( | ) |
Resumes all paused sounds, both music and sound effects.
You should generally call this method right after the app returns from the background.
| void cugl::AudioEngine::resumeAllEffects | ( | ) |
Resumes all paused sound effects.
| void cugl::AudioEngine::resumeEffect | ( | std::string | key | ) |
Resumes the sound effect for the given key.
If the key does not correspond to a channel, this method raises an error.
| key | the reference key for the sound effect |
|
inline |
Resumes the sound effect for the given key.
If the key does not correspond to a channel, this method raises an error.
| key | the reference key for the sound effect |
| void cugl::AudioEngine::resumeMusic | ( | ) |
Resumes the background music assuming that it was paused previously.
This method has no effect on the music queue.
| void cugl::AudioEngine::setEffectElapsed | ( | const std::string & | key, |
| float | time | ||
| ) |
Sets the elapsed time of the sound effect, in seconds
The elapsed time is the current position of the sound from the beginning. It does not include any time spent on a continuous loop. Because the asset is fully decompressed at load time, the result of this method is reasonably accurate.
If the key does not correspond to a channel, this method raises an error.
| key | the reference key for the sound effect |
| time | the new position of the sound effect |
|
inline |
Sets the elapsed time of the sound effect, in seconds
The elapsed time is the current position of the sound from the beginning. It does not include any time spent on a continuous loop. Because the asset is fully decompressed at load time, the result of this method is reasonably accurate.
If the key does not correspond to a channel, this method raises an error.
| key | the reference key for the sound effect |
| time | the new position of the sound effect |
|
inline |
Sets the callback for sound effects
This cllabck function is called whenever a sound effect completes. It is called whether or not the sound completed normally or if it was terminated manually. However, the second parameter can be used to distinguish the two cases.
| callback | The callback for sound effects |
| void cugl::AudioEngine::setEffectLoop | ( | const std::string & | key, |
| bool | loop | ||
| ) |
Sets whether the sound effect is in a continuous loop.
If the key does not correspond to a channel, this method raises an error.
| key | the reference key for the sound effect |
| loop | whether the sound effect is in a continuous loop |
|
inline |
Sets whether the sound effect is in a continuous loop.
If the key does not correspond to a channel, this method raises an error.
| key | the reference key for the sound effect |
| loop | whether the sound effect is in a continuous loop |
| void cugl::AudioEngine::setEffectRemaining | ( | const std::string & | key, |
| float | time | ||
| ) |
Sets the time remaining for the sound effect, in seconds
The time remaining is just duration-elapsed. This method does not take into account whether the sound is on a loop. Because the asset is fully decompressed at load time, the result of this method is reasonably accurate.
If the key does not correspond to a channel, this method raises an error.
| key | the reference key for the sound effect |
| time | the new time remaining for the sound effect |
|
inline |
Sets the time remaining for the sound effect, in seconds
The time remaining is just duration-elapsed. This method does not take into account whether the sound is on a loop. Because the asset is fully decompressed at load time, the result of this method is reasonably accurate.
If the key does not correspond to a channel, this method raises an error.
| key | the reference key for the sound effect |
| time | the new time remaining for the sound effect |
| void cugl::AudioEngine::setEffectVolume | ( | const std::string & | key, |
| float | volume | ||
| ) |
Sets the current volume of the sound effect.
If the key does not correspond to a channel, this method raises an error.
| key | the reference key for the sound effect |
| volume | the current volume of the sound effect |
|
inline |
Sets the current volume of the sound effect.
If the key does not correspond to a channel, this method raises an error.
| key | the reference key for the sound effect |
| volume | the current volume of the sound effect |
| void cugl::AudioEngine::setMusicElapsed | ( | double | time | ) |
Sets the elapsed time of the background music, in seconds
The elapsed time is the current position of the music from the beginning. It does not include any time spent on a continuous loop.
This adjustment is not guaranteed to be accurate. Attempting to time the playback of streaming data (as opposed to a fully in-memory PCM buffer) is very difficult and not cross-platform. We have tried to be reasonably accurate, but from our tests we can only guarantee accuracy within a 10th of a second.
If there is no active background music, this method will raise an error.
| time | the new position of the background music |
|
inline |
Sets the callback for background music
This callback function is called whenever a background music track completes. It is called whether or not the music completed normally or if it was terminated manually. However, the second parameter can be used to distinguish the two cases.
| callback | The callback for background music |
| void cugl::AudioEngine::setMusicLoop | ( | bool | loop | ) |
Sets whether the background music is on a continuous loop.
If loop is true, this will block the queue until it is set to false again. This can be desired behavior, as it gives you a way to control the speed of the queue processing.
If there is no active background music, this method will raise an error.
| loop | whether the background music should be on a continuous loop |
| void cugl::AudioEngine::setMusicRemaining | ( | double | time | ) |
Sets the time remaining for the background music, in seconds
The time remaining is just duration-elapsed. It does not take into account whether the music is on a loop. It also does not include the duration of any music waiting in the queue.
If there is no active background music, this method will raise an error.
This adjustment is not guaranteed to be accurate. Attempting to time the playback of streaming data (as opposed to a fully in-memory PCM buffer) is very difficult and not cross-platform. We have tried to be reasonably accurate, but from our tests we can only guarantee accuracy within a 10th of a second.
| time | the new time remaining of the background music |
| void cugl::AudioEngine::setMusicVolume | ( | float | volume | ) |
Sets the volume of the background music
If there is no active background music, this method will raise an error.
| volume | the volume of the background music |
|
static |
Starts the singleton audio engine.
Once this method is called, the method get() will no longer return nullptr. Calling the method multiple times (without calling stop) will have no effect.
Sounds and music cannot be loaded until this engine is initialized. They depend on this engine for asset management.
The provided parameter indicates the number of simultaneously supported sounds.
| channels | The maximum number of sound effect channels to support |
|
static |
Stops the singleton audio engine, releasing all resources.
Once this method is called, the method get() will return nullptr. Calling the method multiple times (without calling stop) will have no effect.
Sounds and music cannot be loaded until this engine is initialized again. They depend on this engine for asset management.
| void cugl::AudioEngine::stopAll | ( | ) |
Stops all sounds, both music and sound effects.
This effectively clears the sound engine.
| void cugl::AudioEngine::stopAllEffects | ( | ) |
Stops all sound effects, removing them from the engine.
You will need to add the effects again if you wish to replay them.
| void cugl::AudioEngine::stopEffect | ( | const std::string & | key | ) |
Stops the sound effect for the given key, removing it.
If the key does not correspond to a channel, this method raises an error. The effect will be removed from the audio engine entirely. You will need to add it again if you wish to replay it.
| key | the reference key for the sound effect |
|
inline |
Stops the sound effect for the given key, removing it.
If the key does not correspond to a channel, this method raises an error. The effect will be removed from the audio engine entirely. You will need to add it again if you wish to replay it.
| key | the reference key for the sound effect |
| void cugl::AudioEngine::stopMusic | ( | float | fade = 0.0f | ) |
Stops the background music and clears the entire queue.
Before the music is stopped, this method gives the user an option to fade out the music. If the argument is 0, it will halt the music immediately. Otherwise it will fade to completion over the given number of seconds (or until the end of the song).
This method also clears the queue of any further music.
| fade | The number of seconds to fade out |
1.8.10
