SDL Audio Device instance IDs. More...
Public Member Functions | |
| constexpr | AudioDevice ()=default |
| Default ctor. | |
| constexpr | AudioDevice (const AudioDeviceID resource) |
| Constructs from AudioDeviceParam. More... | |
| constexpr | AudioDevice (const AudioDevice &other)=delete |
| Copy constructor. | |
| constexpr | AudioDevice (AudioDevice &&other) |
| Move constructor. | |
| constexpr | AudioDevice (const AudioDeviceRef &other)=delete |
| constexpr | AudioDevice (AudioDeviceRef &&other)=delete |
| AudioDevice (AudioDeviceParam devid, OptionalRef< const AudioSpec > spec) | |
| Open a specific audio device. More... | |
| ~AudioDevice () | |
| Destructor. | |
| AudioDevice & | operator= (AudioDevice other) |
| Assignment operator. | |
| constexpr AudioDeviceID | get () const |
| Retrieves underlying AudioDeviceID. | |
| constexpr AudioDeviceID | release () |
| Retrieves underlying AudioDeviceID and clear this. | |
| constexpr auto | operator<=> (const AudioDevice &other) const =default |
| Comparison. | |
| constexpr bool | operator== (std::nullptr_t _) const |
| Comparison. | |
| constexpr | operator bool () const |
| Converts to bool. | |
| constexpr | operator AudioDeviceParam () const |
| Converts to AudioDeviceParam. | |
| void | Close () |
| Close a previously-opened audio device. More... | |
| const char * | GetName () const |
| Get the human-readable name of a specific audio device. More... | |
| AudioSpec | GetFormat (int *sample_frames=nullptr) const |
| Get the current audio format of a specific audio device. More... | |
| OwnArray< int > | GetChannelMap () const |
| Get the current channel map of an audio device. More... | |
| bool | IsPhysical () const |
| Determine if an audio device is physical (instead of logical). More... | |
| bool | IsPlayback () const |
| Determine if an audio device is a playback device (instead of recording). More... | |
| void | Pause () |
| Use this function to pause audio playback on a specified device. More... | |
| void | Resume () |
| Use this function to unpause audio playback on a specified device. More... | |
| bool | Paused () const |
| Use this function to query if an audio device is paused. More... | |
| float | GetGain () const |
| Get the gain of an audio device. More... | |
| void | SetGain (float gain) |
| Change the gain of an audio device. More... | |
| void | BindAudioStreams (std::span< AudioStreamRef > streams) |
| Bind a list of audio streams to an audio device. More... | |
| void | BindAudioStream (AudioStreamParam stream) |
| Bind a single audio stream to an audio device. More... | |
| void | SetPostmixCallback (AudioPostmixCallback callback, void *userdata) |
| Set a callback that fires when data is about to be fed to an audio device. More... | |
| void | SetPostmixCallback (AudioPostmixCB callback) |
| Set a callback that fires when data is about to be fed to an audio device. More... | |
| AudioStream | OpenStream (OptionalRef< const AudioSpec > spec, AudioStreamCallback callback, void *userdata) |
| Convenience function for straightforward audio init for the common case. More... | |
| AudioStream | OpenStream (OptionalRef< const AudioSpec > spec, AudioStreamCB callback) |
| Convenience function for straightforward audio init for the common case. More... | |
Detailed Description
Zero is used to signify an invalid/null device.
- Since
- This datatype is available since SDL 3.2.0.
- Category:
- Resource
Constructor & Destructor Documentation
◆ AudioDevice() [1/2]
|
inlineexplicitconstexpr |
- Parameters
-
resource a AudioDeviceID to be wrapped.
This assumes the ownership, call release() if you need to take back.
◆ AudioDevice() [2/2]
|
inline |
You can open both playback and recording devices through this function. Playback devices will take data from bound audio streams, mix it, and send it to the hardware. Recording devices will feed any bound audio streams with a copy of any incoming data.
An opened audio device starts out with no audio streams bound. To start audio playing, bind a stream and supply audio data to it. Unlike SDL2, there is no audio callback; you only bind audio streams and make sure they have data flowing into them (however, you can simulate SDL2's semantics fairly closely by using AudioStream.AudioStream instead of this function).
If you don't care about opening a specific device, pass a devid of either AUDIO_DEVICE_DEFAULT_PLAYBACK or AUDIO_DEVICE_DEFAULT_RECORDING. In this case, SDL will try to pick the most reasonable default, and may also switch between physical devices seamlessly later, if the most reasonable default changes during the lifetime of this opened device (user changed the default in the OS's system preferences, the default got unplugged so the system jumped to a new default, the user plugged in headphones on a mobile device, etc). Unless you have a good reason to choose a specific device, this is probably what you want.
You may request a specific format for the audio device, but there is no promise the device will honor that request for several reasons. As such, it's only meant to be a hint as to what data your app will provide. Audio streams will accept data in whatever format you specify and manage conversion for you as appropriate. AudioDevice.GetFormat can tell you the preferred format for the device before opening and the actual format the device is using after opening.
It's legal to open the same device ID more than once; each successful open will generate a new logical AudioDevice that is managed separately from others on the same physical device. This allows libraries to open a device separately from the main app and bind its own streams without conflicting.
It is also legal to open a device ID returned by a previous call to this function; doing so just creates another logical device on the same physical device. This may be useful for making logical groupings of audio streams.
This function returns the opened device ID on success. This is a new, unique AudioDevice that represents a logical device.
Some backends might offer arbitrary devices (for example, a networked audio protocol that can connect to an arbitrary server). For these, as a change from SDL2, you should open a default device ID and use an SDL hint to specify the target if you care, or otherwise let the backend figure out a reasonable default. Most backends don't offer anything like this, and often this would be an end user setting an environment variable for their custom need, and not something an application should specifically manage.
When done with an audio device, possibly at the end of the app's life, one should call AudioDevice.Close() on the returned device id.
- Parameters
-
devid the device instance id to open, or AUDIO_DEVICE_DEFAULT_PLAYBACK or AUDIO_DEVICE_DEFAULT_RECORDING for the most reasonable default device. spec the requested device configuration. Can be nullptr to use reasonable defaults.
- Postcondition
- the device ID on success.
- Exceptions
-
Error on failure.
- Thread safety:
- It is safe to call this function from any thread.
- Since
- This function is available since SDL 3.2.0.
The documentation for this class was generated from the following file:
- SDL3pp/SDL3pp_audio.h
