 |
CUGL 2.1
Cornell University Game Library
|
|
CUGL 2.1
Cornell University Game Library
|
#include <CUAudioDevices.h>
Public Member Functions | |
| Uint32 | getReadSize () const |
| Uint32 | getWriteSize () const |
| bool | isActive () |
| void | activate () |
| void | deactivate () |
| void | reset () |
| std::shared_ptr< audio::AudioOutput > | openOutput () |
| std::shared_ptr< audio::AudioOutput > | openOutput (Uint8 channels, Uint32 rate) |
| std::shared_ptr< audio::AudioOutput > | openOutput (const char *device) |
| std::shared_ptr< audio::AudioOutput > | openOutput (const std::string &device) |
| std::shared_ptr< audio::AudioOutput > | openOutput (const char *device, Uint8 channels, Uint32 rate) |
| std::shared_ptr< audio::AudioOutput > | openOutput (const std::string &device, Uint8 channels, Uint32 rate) |
| bool | closeOutput (const std::shared_ptr< audio::AudioOutput > &device) |
| std::shared_ptr< audio::AudioInput > | openInput () |
| std::shared_ptr< audio::AudioInput > | openInput (Uint8 channels, Uint32 rate, Uint32 delay) |
| std::shared_ptr< audio::AudioInput > | openInput (const char *device) |
| std::shared_ptr< audio::AudioInput > | openInput (const std::string &device) |
| std::shared_ptr< audio::AudioInput > | openInput (const char *device, Uint8 channels, Uint32 rate, Uint32 delay) |
| std::shared_ptr< audio::AudioInput > | openInput (const std::string &device, Uint8 channels, Uint32 rate, Uint32 delay) |
| bool | closeInput (const std::shared_ptr< audio::AudioInput > &device) |
Static Public Member Functions | |
| static AudioDevices * | get () |
| static void | start () |
| static void | start (Uint32 frames) |
| static void | start (Uint32 output, Uint32 input) |
| static void | stop () |
| static std::vector< std::string > | devices (bool output) |
| static std::vector< std::string > | occupied (bool output) |
Static Public Attributes | |
| static const Uint32 | DEFAULT_OUTPUT_BUFFER |
| static const Uint32 | DEFAULT_INPUT_BUFFER |
Class providing a singleton audio device manager
This class is provides the most basic support for a modern audio engine. It has a factory for managing multiple input and output devices. However, it is up to the developer to connect these together to form audio graphs. Therefore, a developer should only use this class when direct access to the audio graph is necessary. Most developers can use AudioEngine instead. As that class is built on top of this one, the developer should only ever use one of the two classes.
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 AudioManager in a callback function, you should use the Application#schedule method to delay until the main thread is next available.
| void cugl::AudioDevices::activate | ( | ) |
Activates the audio device manager.
This method is used to resume audio behavior after a call to the method deactivate(). This provides a uniform way of renabling audio devices (such as after an application switch).
This method is not the same as start(). It does not allocate any new resources.
| bool cugl::AudioDevices::closeInput | ( | const std::shared_ptr< audio::AudioInput > & | device | ) |
Closes the output device and disposes all resources.
Once this method is called, the audio::AudioOutput is invalidated and is no longer safe to use.
| device | The output device to close |
| bool cugl::AudioDevices::closeOutput | ( | const std::shared_ptr< audio::AudioOutput > & | device | ) |
Closes the output device and disposes all resources.
Once this method is called, the audio::AudioOutput is invalidated and is no longer safe to use.
| device | The output device to close |
| void cugl::AudioDevices::deactivate | ( | ) |
Deactivates the audio device manager.
This method is used to pause all output nodes and release all input nodes from recording. This is important during an application switch, such as when the game goes into the background. All of the devices may be resumed with a call to deactivate().
This method is not the same as stop(). It does not release any resources and no audio graphs are invalidated.
|
static |
Returns the list of all the audio devices
This value may change and should be polled regularly to provide an up-to-date list. The provided argument determines whether this is for output or input devices.
| output | Whether to list output (instead of input) devices |
|
inlinestatic |
Returns the singleton instance of the device manager.
If the audio manager has not been started, then this method will return nullptr.
|
inline |
Returns the size of the read buffer (in frames) for output nodes.
While output devices do not need to have uniform buffer sizes, we require this to ensure that audio graph nodes are all interchangeable. Therefore, a suitable buffer size (that works for all relevant devices) should be set at activation.
Note that the value is in frames. Therefore, output devices with different numbers of channels will have a different raw buffer size.
|
inline |
Returns the size of the write buffer (in frames) for input nodes.
While input devices do not need to have uniform buffer sizes, we require this to ensure that audio graph nodes are all interchangeable. Therefore, a suitable buffer size (that works for all relevant devices) should be set at activation.
Note that the value is in frames. Therefore, input devices with different numbers of channels will have a different raw buffer size.
| bool cugl::AudioDevices::isActive | ( | ) |
Returns true if the audio device manager is active.
An active audio manager will regularly poll data from any unpaused output node, and regular write data to any unreleased input node.
|
static |
Returns the list of devices with attached audio nodes.
If there is an audio node on the default device, this will include the current default. The provided argument determines whether this is for output or input devices.
| output | Whether to list output (instead of input) devices |
| std::shared_ptr<audio::AudioInput> cugl::AudioDevices::openInput | ( | ) |
Returns the default input device with 2 channels at 48000 Hz.
The input delay will be equal to the value getWriteSize(). This means that playback is only available after two calls to audio::AudioInput#record(). This is the minimal value for smooth real-time playback of recorded audio.
An input device is initialized with both active as false and record as true. That means it will start recording as soon as the AudioManager is activated. In addition, it is also unpaused, meaning that playback will start as soon as it is attached to an audio graph.
This node is always logically attached to the default input device. That means it will switch devices whenever the default input changes. This method may fail if the default device is in use.
| std::shared_ptr<audio::AudioInput> cugl::AudioDevices::openInput | ( | const char * | device | ) |
Returns the given input device with 2 channels at 48000 Hz.
The input delay will be equal to the value getWriteSize(). This means that playback is only available after two calls to audio::AudioInput#record(). This is the minimal value for smooth real-time playback of recorded audio.
An input device is initialized with both active as false and record as true. That means it will start recording as soon as the AudioManager is activated. In addition, it is also unpaused, meaning that playback will start as soon as it is attached to an audio graph.
This method may fail if the given device is in use.
| device | The name of the output device |
| std::shared_ptr<audio::AudioInput> cugl::AudioDevices::openInput | ( | const char * | device, |
| Uint8 | channels, | ||
| Uint32 | rate, | ||
| Uint32 | delay | ||
| ) |
Returns the given output device with the given channels and sample rate.
The delay value is the number of frames that must be recorded before a single frame. This determines the playback latency. While it is possible to have a delay of 0, this is unlikely to provide smooth real-time playback of recorded audio. That is because there are no guarantees about the thread interleaving of input and output devices. A delay of at least getWriteSize(), and maybe even more, is recommended.
An input device is initialized with both active as false and record as true. That means it will start recording as soon as the AudioManager is activated. In addition, it is also unpaused, meaning that playback will start as soon as it is attached to an audio graph.
This method may fail if the given device is in use.
| device | The name of the output device |
| channels | The number of audio channels |
| rate | The sample rate (frequency) in Hz |
| delay | The playback delay between recording and reading |
| std::shared_ptr<audio::AudioInput> cugl::AudioDevices::openInput | ( | const std::string & | device | ) |
Returns the given input device with 2 channels at 48000 Hz.
The input delay will be equal to the value getWriteSize(). This means that playback is only available after two calls to audio::AudioInput#record(). This is the minimal value for smooth real-time playback of recorded audio.
An input device is initialized with both active as false and record as true. That means it will start recording as soon as the AudioManager is activated. In addition, it is also unpaused, meaning that playback will start as soon as it is attached to an audio graph.
This method may fail if the given device is in use.
| device | The name of the output device |
| std::shared_ptr<audio::AudioInput> cugl::AudioDevices::openInput | ( | const std::string & | device, |
| Uint8 | channels, | ||
| Uint32 | rate, | ||
| Uint32 | delay | ||
| ) |
Returns the given output device with the given channels and sample rate.
The delay value is the number of frames that must be recorded before a single frame. This determines the playback latency. While it is possible to have a delay of 0, this is unlikely to provide smooth real-time playback of recorded audio. That is because there are no guarantees about the thread interleaving of input and output devices. A delay of at least getWriteSize(), and maybe even more, is recommended.
An input device is initialized with both active as false and record as true. That means it will start recording as soon as the AudioManager is activated. In addition, it is also unpaused, meaning that playback will start as soon as it is attached to an audio graph.
This method may fail if the given device is in use.
| device | The name of the output device |
| channels | The number of audio channels |
| rate | The sample rate (frequency) in Hz |
| delay | The playback delay between recording and reading |
| std::shared_ptr<audio::AudioInput> cugl::AudioDevices::openInput | ( | Uint8 | channels, |
| Uint32 | rate, | ||
| Uint32 | delay | ||
| ) |
Returns the default input device with the given channels and sample rate.
The delay value is the number of frames that must be recorded before a single frame. This determines the playback latency. While it is possible to have a delay of 0, this is unlikely to provide smooth real-time playback of recorded audio. That is because there are no guarantees about the thread interleaving of input and output devices. A delay of at least getWriteSize(), and maybe even more, is recommended.
An input device is initialized with both active as false and record as true. That means it will start recording as soon as the AudioManager is activated. In addition, it is also unpaused, meaning that playback will start as soon as it is attached to an audio graph.
This node is always logically attached to the default input device. That means it will switch devices whenever the default input changes. This method may fail if the default input device is in use.
| channels | The number of audio channels |
| rate | The sample rate (frequency) in Hz |
| delay | The playback delay between recording and reading |
| std::shared_ptr<audio::AudioOutput> cugl::AudioDevices::openOutput | ( | ) |
Returns the default output device with 2 channels at 48000 Hz.
An output device is initialized with both active and paused as false. That means it will begin playback as soon as the audio manager is activated.
This node is always logically attached to the default output device. That means it will switch devices whenever the default output changes. This method may fail if the default device is in use.
| std::shared_ptr<audio::AudioOutput> cugl::AudioDevices::openOutput | ( | const char * | device | ) |
Returns the given output device with 2 channels at 48000 Hz.
An output device is initialized with both active and paused as false. That means it will begin playback as soon as the audio manager is activated.
This method may fail if the given device is in use.
| device | The name of the output device |
| std::shared_ptr<audio::AudioOutput> cugl::AudioDevices::openOutput | ( | const char * | device, |
| Uint8 | channels, | ||
| Uint32 | rate | ||
| ) |
Returns the output device with the given channels and sample rate.
An output device is initialized with both active and paused as false. That means it will begin playback as soon as the audio manager is activated.
This method may fail if the given device is in use.
| device | The name of the output device |
| channels | The number of audio channels |
| rate | The sample rate (frequency) in Hz |
| std::shared_ptr<audio::AudioOutput> cugl::AudioDevices::openOutput | ( | const std::string & | device | ) |
Returns the given output device with 2 channels at 48000 Hz.
An output device is initialized with both active and paused as false. That means it will begin playback as soon as the audio manager is activated.
This method may fail if the given device is in use.
| device | The name of the output device |
| std::shared_ptr<audio::AudioOutput> cugl::AudioDevices::openOutput | ( | const std::string & | device, |
| Uint8 | channels, | ||
| Uint32 | rate | ||
| ) |
Returns the output device with the given channels and sample rate.
An output device is initialized with both active and paused as false. That means it will begin playback as soon as the audio manager is activated.
This method may fail if the given device is in use.
| device | The name of the output device |
| channels | The number of audio channels |
| rate | The sample rate (frequency) in Hz |
| std::shared_ptr<audio::AudioOutput> cugl::AudioDevices::openOutput | ( | Uint8 | channels, |
| Uint32 | rate | ||
| ) |
Returns the default output device with the given channels and sample rate.
An output device is initialized with both active and paused as false. That means it will begin playback as soon as the audio manager is activated.
This node is always logically attached to the default output device. That means it will switch devices whenever the default output changes. This method may fail if the default output device is in use.
| channels | The number of audio channels |
| rate | The sample rate (frequency) in Hz |
| void cugl::AudioDevices::reset | ( | ) |
Resets any stopped or failed audio devices.
This method will also roll over the default output (not input) device if it changes.
This method is necessary for when an audio device is unplugged. While SDL often does this automatically, this method is provided for platforms (e.g. CoreAudio on MacOS) where this must be done explicitly.
|
static |
Starts the singleton audio device manager.
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. In addition, an audio manager will start off as inactive, and must be activated.
Instances of audio::AudioNode (and its subclasses) cannot be initialized until this manager is activated. That is because audio nodes need a uniform buffer size (set by this method) in order to coordinate with one another.
This method will create a manager where the input and output buffer sizes are the default values.
|
static |
Starts the singleton audio device manager.
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. In addition, an audio manager will start off as inactive, and must be activated.
Instances of audio::AudioNode (and its subclasses) cannot be initialized until this manager is activated. That is because audio nodes need a uniform buffer size (set by this method) in order to coordinate with one another.
This method will create a manager where the output and input buffer share the same size.
| frames | The output and input buffer size in frames. |
|
static |
Starts the singleton audio device manager.
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. In addition, an audio manager will start off as inactive, and must be activated.
Instances of audio::AudioNode (and its subclasses) cannot be initialized until this manager is activated. That is because audio nodes need a uniform buffer size (set by this method) in order to coordinate with one another.
This method will create a manager where the output and input buffer have the specified sizes. It is not necessary for the buffer value of an input device match the buffer value of an output device. Indeed, on many systems, an input buffer size of less than 1024 samples is not supported, while output devices can process much faster than that. What is important is ensuring enough delay so that the audio graph does not outrun the input device. Therefore, an input delay of less than the input buffer size is not recommended for real-time audio processing.
| output | The size of the output buffer in frames. |
| input | The size of the input buffer in frames. |
|
static |
Stops the singleton device manager, 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. In addition, the audio manager will no longer be active.
Once this method is called, all instances of audio::AudioNode become invalid. In addition, no future instances of audio::AudioNode may be created. This method should only be called at application shutdown.
|
static |
The default input buffer size for each audio node
|
static |
The default input buffer size for each audio node
1.8.16