 |
CUGL 2.1
Cornell University Game Library
|
|
CUGL 2.1
Cornell University Game Library
|
#include <CUAudioEngine.h>
Public Types | |
| enum | State { State::INACTIVE, State::PLAYING, State::PAUSED } |
Public Member Functions | |
| std::shared_ptr< AudioQueue > | getMusicQueue () const |
| std::shared_ptr< AudioQueue > | allocQueue () |
| void | freeQueue (const std::shared_ptr< AudioQueue > &queue) |
| bool | play (const std::string key, const std::shared_ptr< Sound > &sound, bool loop=false, float volume=1.0f, bool force=false) |
| bool | play (const std::string key, const std::shared_ptr< audio::AudioNode > &graph, bool loop=false, float volume=1.0f, bool force=false) |
| size_t | getAvailableSlots () const |
| State | getState (const std::string key) const |
| bool | isActive (const std::string key) const |
| const std::string | getSource (const std::string key) const |
| bool | isLoop (const std::string key) const |
| void | setLoop (const std::string key, bool loop) |
| float | getVolume (const std::string key) const |
| void | setVolume (const std::string key, float volume) |
| float | getPanFactor (const std::string &key) const |
| void | setPanFactor (const std::string key, float pan) |
| float | getDuration (const std::string key) const |
| float | getTimeElapsed (const std::string key) const |
| void | setTimeElapsed (const std::string key, float time) |
| float | geTimeRemaining (const std::string key) const |
| void | setTimeRemaining (const std::string key, float time) |
| void | clear (const std::string key, float fade=DEFAULT_FADE) |
| void | pause (const std::string key, float fade=DEFAULT_FADE) |
| void | resume (std::string key) |
| void | setListener (std::function< void(const std::string key, bool)> callback) |
| std::function< void(const std::string key, bool)> | getListener () const |
| void | clearEffects (float fade=DEFAULT_FADE) |
| void | pauseEffects (float fade=DEFAULT_FADE) |
| void | resumeEffects () |
| void | clear (float fade=DEFAULT_FADE) |
| void | pause (float fade=DEFAULT_FADE) |
| void | resume () |
Static Public Member Functions | |
| static AudioEngine * | get () |
| static bool | start (Uint32 slots=DEFAULT_SLOTSIZE) |
| static bool | start (const std::shared_ptr< audio::AudioOutput > &device, Uint32 slots=DEFAULT_SLOTSIZE) |
| static void | stop () |
Class provides a singleton audio engine
This module is an attempt to combine the power of a modern DSP mixer graph with a simple 2000-era interface. Like the legacy engines, it provides a a flat slot-based structure for playing sounds, and controlling the fade and pan of each slot. However, you are not limited to playing samples in the slots. You can also add arbitrary audio nodes as well.
This class is primarily designed for the playing of sound effects. These are short sound effects that are often happening in parallel. The engine has a fixed number of slots for these sounds (historically 24) and it can only play as many sounds simultaneously as it has slots. Slots are assigned automatically by the engine. However, when you play an effect, you must assign it a unique key so that you can access it later (for volume changes, panning, early termination, etc.). This key eliminates any need for tracking the slot assigned to an effect.
Music is treated separately because seamless playback requires the ability to queue up audio assets in order. As a result, this is supported through the AudioQueue interface. However, queues are owned by and acquired from this engine. There is always one music queue available, though you do have the ability to acquire more.
You cannot create new instances of this class. Instead, you should access the singleton through the three static methods: start(), stop(), and get(). Calling these methods will initialize the AudioDevices singleton, if it is not already initialized.
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 |
| std::shared_ptr<AudioQueue> cugl::AudioEngine::allocQueue | ( | ) |
Allocates a new queue for managing audio.
Music is handled differently from sound effects. 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. Proper queue management is the keep for smooth, uninterrupted playback that responds to the user's actions.
This method allocates a secondary music queue that can be played in tandem with the primary music queue. This allows for slightly more complex music mixing. However, for true vertical layering, you should use audio::AudioMixer.
It is the programmer's responsibility to free all secondary music queues with freeQueue. However, all queues are automatically freed when this audio engine is stopped.
Calling this method will briefly pause the audio engine, if it is actively playing.
| void cugl::AudioEngine::clear | ( | const std::string | key, |
| float | fade = DEFAULT_FADE |
||
| ) |
Removes the sound effect for the given key, stopping it immediately
The effect will be removed from the audio engine entirely. You will need to add it again if you wish to replay it.
Before the effect is stopped, this method gives the user an option to fade out the effect. If the argument is 0, it will halt the sound immediately. Otherwise it will fade to completion over the given number of seconds (or until the end of the effect). Only by fading can you guarantee no audible clicks.
If the key does not correspond to an active sound effect, this method does nothing.
| key | the reference key for the sound effect |
| fade | the number of seconds to fade out |
| void cugl::AudioEngine::clear | ( | float | fade = DEFAULT_FADE | ) |
Clears all active playing sounds, both music and sound effects.
Before the sounds are stopped, this method gives the user an option to fade out the effect. If the argument is 0, it will halt all sounds immediately. Otherwise it will fade the to completion over the given number of seconds (or until the end of the effect). Only by fading can you guarantee no audible clicks.
| fade | the number of seconds to fade out |
| void cugl::AudioEngine::clearEffects | ( | float | fade = DEFAULT_FADE | ) |
Removes all sound effects from the engine, stopping them immediately.
Before the effects are stopped, this method gives the user an option to fade out the effect. If the argument is 0, it will halt all effects immediately. Otherwise it will fade the to completion over the given number of seconds (or until the end of the effect). Only by fading can you guarantee no audible clicks.
You will need to add the effects again if you wish to replay them. This method has no effect on the music queues.
| fade | the number of seconds to fade out |
| void cugl::AudioEngine::freeQueue | ( | const std::shared_ptr< AudioQueue > & | queue | ) |
Frees a previously allocated audio queue.
This method should be called to free any audio queue created by allocQueue. It is the programmer's responsibility to free all secondary music queues. However, all queues are automatically freed when this audio engine is stopped.
This method cannot be used to free the default music queue.
| queue | The audio queue to free |
|
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 slots available for sound effects.
There are a limited number of slots available for sound effects. If all slots 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 slot from the longest playing sound effect.
| float cugl::AudioEngine::getDuration | ( | const std::string | key | ) | const |
Returns the duration of the sound effect, in seconds.
Because most sound effects are fully decompressed at load time, the result of this method is reasonably accurate.
If the key does not correspond to an active sound effect, this method returns -1.
| key | the reference key for the sound effect |
| float cugl::AudioEngine::geTimeRemaining | ( | 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 most sound effects are fully decompressed at load time, the result of this method is reasonably accurate, though it is affected by device latency.
If the key does not correspond to an active sound effect, or if the sound effect is an audio node with undefined duration, this method method returns -1.
| key | the reference key for the sound effect |
|
inline |
Returns the callback for sound effects
This callback 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.
| std::shared_ptr<AudioQueue> cugl::AudioEngine::getMusicQueue | ( | ) | const |
Returns the default music queue for this audio engine
Music is managed through audio queues.The audio engine has one by default, though you can allocate more with allocQueue.
Music is handled differently from sound effects. 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. Proper queue management is the keep for smooth, uninterrupted playback that responds to the user's actions.
| float cugl::AudioEngine::getPanFactor | ( | const std::string & | key | ) | const |
Returns the stereo pan of the sound effect.
This audio engine provides limited (e.g. not full 3D) stereo panning for simple effects. The pan value is a float from -1 to 1. A value of 0 (default) plays to both channels (regardless of whether the current effect is mono or stereo). A value of -1 will play to the left channel only, while the right will play to the right channel only. Channels beyond the first two are unaffected.
In the case of stereo assets, panning to the left or right will mix the audio feed; this process will never lose audio.
If the key does not correspond to an active sound effect, this method returns 0.
| key | the reference key for the sound effect |
| const std::string cugl::AudioEngine::getSource | ( | const std::string | key | ) | const |
Returns the identifier for the asset attached to the given key.
If the current playing track is an Sound asset, then the identifier is the file name. Otherwise, it is the name of the root of the audio graph. See audio::AudioNode#getName.
| key | the reference key for the sound effect |
| State cugl::AudioEngine::getState | ( | 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 |
| float cugl::AudioEngine::getTimeElapsed | ( | 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 most sound effects are fully decompressed at load time, the result of this method is reasonably accurate, though it is affected by device latency.
If the key does not correspond to an active sound effect, or if the sound effect is an audio node with undefined duration, this method returns -1.
| key | the reference key for the sound effect |
| float cugl::AudioEngine::getVolume | ( | const std::string | key | ) | const |
Returns the current volume of the sound effect.
The volume is a value 0 to 1, where 1 is maximum volume and 0 is complete silence. If the key does not correspond to an active sound effect, this method returns 0.
Note that this is the playback volume. If the asset or audio graph had its own initial volume setting, this is independent of this setting. Indeed, this value can be though of as the percentage of the default volume.
| key | the reference key for the sound effect |
|
inline |
Returns true if the key is associated with an active sound.
| key | the reference key for the sound effect |
| bool cugl::AudioEngine::isLoop | ( | const std::string | key | ) | const |
Returns true if the sound effect is in a continuous loop.
If the key does not correspond to an active sound effect, this method returns false.
| key | the reference key for the sound effect |
| void cugl::AudioEngine::pause | ( | const std::string | key, |
| float | fade = DEFAULT_FADE |
||
| ) |
Pauses the sound effect for the given key.
Before the effect is paused, this method gives the user an option to fade out the effect. If the argument is 0, it will pause the sound immediately. Otherwise it will fade to completion over the given number of seconds (or until the end of the effect). Only by fading can you guarantee no audible clicks.
If the key does not correspond to an active sound effect, this method does nothing.
| key | the reference key for the sound effect |
| fade | the number of seconds to fade out |
| void cugl::AudioEngine::pause | ( | float | fade = DEFAULT_FADE | ) |
Pauses all sounds, both music and sound effects.
Before the sounds are paused, this method gives the user an option to fade out everything. If the argument is 0, it will pause the sounds immediately. Otherwise it will fade everythign to completion over the given number of seconds (or until the end of each sound). Only by fading can you guarantee no audible clicks.
This method allows them to be resumed later. You should generally call this method just before the app pages to the background.
| fade | the number of seconds to fade out |
| void cugl::AudioEngine::pauseEffects | ( | float | fade = DEFAULT_FADE | ) |
Pauses all sound effects, allowing them to be resumed later.
Before the effects are paused, this method gives the user an option to fade out the effect. If the argument is 0, it will pause all effects immediately. Otherwise it will fade the to completion over the given number of seconds (or until the end of the effect). Only by fading can you guarantee no audible clicks.
Sound effects already paused will remain paused. This method has no effect on the music queues.
| fade | the number of seconds to fade out |
| bool cugl::AudioEngine::play | ( | const std::string | key, |
| const std::shared_ptr< audio::AudioNode > & | graph, | ||
| bool | loop = false, |
||
| float | volume = 1.0f, |
||
| bool | force = false |
||
| ) |
Plays the given audio node, and associates it with the specified key.
This alternate version of play allows the programmer to construct custom composite audio graphs and play them as sound effects. Looping behavior is supported if the audio node has a finite duration.
As with traditional sounds, the audio node is assigned a key to allow the application to easily reference the sound state without having to internally manage pointers to the audio channel. In particular, if the audio node provided does not have a fixed duration, and can be played indefinitely, then the key must be used to stop the sound.
If the key is already associated with an active sound effect, 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 slots available for sounds. 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 |
| graph | The audio graph to play |
| loop | Whether to loop the sound effect continuously |
| volume | The music volume (relative to the default instance volume) |
| force | Whether to force another sound to stop. |
| bool cugl::AudioEngine::play | ( | const std::string | key, |
| const std::shared_ptr< Sound > & | sound, | ||
| bool | loop = false, |
||
| float | volume = 1.0f, |
||
| bool | force = false |
||
| ) |
Plays the given sound, and associates it with the specified key.
Sounds 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 effect, 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 slots available for sounds. 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 music volume (relative to the default asset volume) |
| force | Whether to force another sound to stop. |
| void cugl::AudioEngine::resume | ( | ) |
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::resume | ( | std::string | key | ) |
Resumes the sound effect for the given key.
If the key does not correspond to a channel, this method does nothing.
| key | the reference key for the sound effect |
| void cugl::AudioEngine::resumeEffects | ( | ) |
Resumes all paused sound effects.
This method has no effect on the music queues.
|
inline |
Sets the callback for sound effects
This callback 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::setLoop | ( | const std::string | key, |
| bool | loop | ||
| ) |
Sets whether the sound effect is in a continuous loop.
If the key does not correspond to an active sound effect, this method does nothing.
| key | the reference key for the sound effect |
| loop | whether the sound effect is in a continuous loop |
| void cugl::AudioEngine::setPanFactor | ( | const std::string | key, |
| float | pan | ||
| ) |
Returns the stereo pan of the sound effect.
This audio engine provides limited (e.g. not full 3D) stereo panning for simple effects. The pan value is a float from -1 to 1. A value of 0 (default) plays to both channels (regardless of whether the current effect is mono or stereo). A value of -1 will play to the left channel only, while the right will play to the right channel only. Channels beyond the first two are unaffected.
In the case of stereo assets, panning to the left or right will mix the audio feed; this process will never lose audio.
If the key does not correspond to an active sound effect, this method does nothing.
| key | the reference key for the sound effect |
| pan | the stereo pan of the sound effect |
| void cugl::AudioEngine::setTimeElapsed | ( | 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 most sound effects are fully decompressed at load time, the result of this method is reasonably accurate, though it is affected by device latency.
If the key does not correspond to an active sound effect, or if the sound effect is an audio node with undefined duration, this method does nothing.
| key | the reference key for the sound effect |
| time | the new position of the sound effect |
| void cugl::AudioEngine::setTimeRemaining | ( | 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 most sound effects are fully decompressed at load time, the result of this method is reasonably accurate, though it is affected by device latency.
If the key does not correspond to an active sound effect, or if the sound effect is an audio node with undefined duration, this method does nothing.
| key | the reference key for the sound effect |
| time | the new time remaining for the sound effect |
| void cugl::AudioEngine::setVolume | ( | const std::string | key, |
| float | volume | ||
| ) |
Sets the current volume of the sound effect.
The volume is a value 0 to 1, where 1 is maximum volume and 0 is complete silence. If the key does not correspond to an active sound effect, this method does nothing.
Note that this is the playback volume. If the asset or audio graph had its own initial volume setting, this is independent of this setting. Indeed, this value can be though of as the percentage of the default volume.
| key | the reference key for the sound effect |
| volume | the current volume of the sound effect |
|
static |
Starts the singleton audio engine on the given audio device.
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.
This version of the method assumes that the programmer has already started the AudioDevices manager. It will not restart the manager, nor will it shutdown the audio manager when done. This version of the initializer is only for programmers that need lower-level control over buffer size and sampling rate.
The parameter slots indicates the number of simultaneously supported sounds. Attempting to play more than this number of sounds may fail, it may eject a previously playing sound, depending on the settings. The default number of slots is 16.
| device | The audio device to use for this engine |
| slots | The maximum number of sound slots to support |
|
static |
Starts the singleton audio engine on the default audio device.
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.
This convenience method will start up the AudioDevices manager, and take responsibility for shutting it down when done. As a result, it will fail if the audio device manager is already active or cannot be initialized. If you need more control of the audio devices (such as to change the audio sampling rate or the buffer size), you should use start the engine with a specific output device.
The engine initialized by this method has a uniform sampling rate of 48000 Hz. This is the standard rate for phone games. However, keep in mind that CD audio is typically sampled at 44100 Hz.
The parameter slots indicates the number of simultaneously supported sounds. Attempting to play more than this number of sounds may fail, it may eject a previously playing sound, depending on the settings. The default number of slots is 16.
| slots | The maximum number of sound slots to support |
|
static |
Shutsdown 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.
If the engine was started with the convenience method start(Uint32), then this method will also stop the AudioDevices manager. Otherwise, it is the responsibility of the programmer to shutdown the device manager.
1.8.16