SFML 3.1.0
Loading...
Searching...
No Matches
Typedefs | Enumerations | Functions
sf::PlaybackDevice Namespace Reference

## Typedefs

using | NotificationCallback = std::function<void(Notification notification)>
| Callable that is called to notify of changes to the playback device state.

## Enumerations

enum class | Notification { DeviceStarted , DeviceStopped , DeviceRerouted , DeviceInterruptionBegan , DeviceInterruptionEnded , DeviceUnlocked }
| Enumeration of the playback device notifications. More...

## Functions

std::vector< std::string > | getAvailableDevices ()
| Get a list of the names of all available audio playback devices.
std::optional< std::string > | getDefaultDevice ()
| Get the name of the default audio playback device.
bool | setDevice (const std::string &name)
| Set the audio playback device.
bool | setDeviceToDefault ()
| Set the audio playback device to the default.
bool | setDeviceToNull ()
| Set the audio playback device to the null device.
std::optional< std::string > | getDevice ()
| Get the name of the current audio playback device.
std::optional< std::uint32_t > | getDeviceSampleRate ()
| Get the sample rate of the current audio playback device.
bool | isDefaultDevice ()
| Check if the current playback device is the default device.
void | setNotificationCallback (NotificationCallback callback)
| Set a callback that should be called to notify of changes to the playback device state.

## Typedef Documentation

## ◆ NotificationCallback

using sf::PlaybackDevice::NotificationCallback = std::function<void(Notification notification)>

Callable that is called to notify of changes to the playback device state.

Definition at line 217 of file PlaybackDevice.hpp.

## Enumeration Type Documentation

## ◆ Notification

enum class sf::PlaybackDevice::Notification

strong

Enumeration of the playback device notifications.

Enumerator
DeviceStarted | Playback device has been started.
DeviceStopped | Playback device has been stopped.
DeviceRerouted | Playback device has been rerouted (Generated on platforms that support automatic stream routing).
DeviceInterruptionBegan | Playback device interruption has begun (Generated on Apple mobile platforms).
DeviceInterruptionEnded | Playback device interruption has ended (Generated on Apple mobile platforms).
DeviceUnlocked | Playback device has been unlocked (Generated by Emscripten/WebAudio).

Definition at line 203 of file PlaybackDevice.hpp.

## Function Documentation

## ◆ getAvailableDevices()

std::vector< std::string > sf::PlaybackDevice::getAvailableDevices | ( |  | ) |

nodiscard

Get a list of the names of all available audio playback devices.

This function returns a vector of strings containing the names of all available audio playback devices.

If the operating system reports multiple devices with the same name, a number will be appended to the name of all subsequent devices to distinguish them from each other. This guarantees that every entry returned by this function will represent a unique device.

For example, if the operating system reports multiple devices with the name "Sound Card", the entries returned would be:

- Sound Card
- Sound Card 2
- Sound Card 3
- ...

The default device, if one is marked as such, will be placed at the beginning of the vector.

If no devices are available, this function will return an empty vector.

Returns
  A vector of strings containing the device names or an empty vector if no devices are available

## ◆ getDefaultDevice()

std::optional< std::string > sf::PlaybackDevice::getDefaultDevice | ( |  | ) |

nodiscard

Get the name of the default audio playback device.

This function returns the name of the default audio playback device. If none is available, std::nullopt is returned.

Note that depending on when this function is called, the default device reported by the operating system might change e.g. when a USB audio device is plugged into or unplugged from the system.

Returns
  The name of the default audio playback device

## ◆ getDevice()

std::optional< std::string > sf::PlaybackDevice::getDevice | ( |  | ) |

nodiscard

Get the name of the current audio playback device.

Returns
  The name of the current audio playback device or std::nullopt if there is none

## ◆ getDeviceSampleRate()

std::optional< std::uint32_t > sf::PlaybackDevice::getDeviceSampleRate | ( |  | ) |

nodiscard

Get the sample rate of the current audio playback device.

Returns
  The sample rate of the current audio playback device or std::nullopt if there is none

## ◆ isDefaultDevice()

bool sf::PlaybackDevice::isDefaultDevice | ( |  | ) |

nodiscard

Check if the current playback device is the default device.

This function will return false if there is no current playback device.

Returns
  true, if the current playback device is the default device

## ◆ setDevice()

bool sf::PlaybackDevice::setDevice | ( | const std::string & | name | ) |

nodiscard

Set the audio playback device.

This function sets the audio playback device to the device with the given name. It can be called on the fly (i.e: while sounds are playing).

If there are sounds playing when the audio playback device is switched, the sounds will continue playing uninterrupted on the new audio playback device.

Parameters

  name | The name of the audio playback device

Returns
  true, if it was able to set the requested device

See also
  getAvailableDevices, getDefaultDevice, setDeviceToDefault, setDeviceToNull

## ◆ setDeviceToDefault()

bool sf::PlaybackDevice::setDeviceToDefault | ( |  | ) |

nodiscard

Set the audio playback device to the default.

This function sets the audio playback device to the default device. It can be called on the fly (i.e: while sounds are playing).

If there are sounds playing when the audio playback device is switched, the sounds will continue playing uninterrupted on the new audio playback device.

When certain backends are used, using the default device will enable automatic stream routing. When automatic stream routing is enabled, audio data is automatically sent to whichever physical audio device is currently marked as the default on the system. If the default device changes due to e.g. a device being added to or removed from the system or the user marking another device as the default, automatic stream routing will seamlessly reroute the audio data to the new default device without any manual intervention.

Automatic stream routing is currently supported when using the WASAPI or DirectSound backend on Windows or the Core Audio backend on macOS and iOS.

Depending on the order in which hardware devices are initialized e.g. after resuming from sleep, the default device might change one or more times in rapid succession before it reverts back to the state in which it was before the system went to sleep.

Returns
  true, if it was able to set the audio playback device to the default device

See also
  getAvailableDevices, getDefaultDevice, setDevice, setDeviceToNull

## ◆ setDeviceToNull()

bool sf::PlaybackDevice::setDeviceToNull | ( |  | ) |

nodiscard

Set the audio playback device to the null device.

This function sets the audio playback device to the null device. It can be called on the fly (i.e: while sounds are playing).

If there are sounds playing when the audio playback device is switched, the sounds will continue playing uninterrupted on the new audio playback device.

Audio data routed to the null device will be discarded by the backend. This can be used to keep sounds playing without having them actually output on a physical audio playback device.

Returns
  true, if it was able to set the audio playback device to the null device

See also
  getAvailableDevices, getDefaultDevice, setDevice, setDeviceToDefault

## ◆ setNotificationCallback()

void sf::PlaybackDevice::setNotificationCallback | ( | NotificationCallback | callback | ) |

Set a callback that should be called to notify of changes to the playback device state.

Warning: Do not attempt to alter the device state from within this callback. This includes changing the device and even creating/destroying sound objects since that could indirectly cause the playback device to be created/destroyed. Also do not attempt to set the notification callback from within this callback. Doing so will result in a deadlock.

When receiving a notification via this callback, store the information somewhere and react on it from another thread e.g. the main thread within the application.

Parameters

  callback | The callback that should be called to notify of changes to the playback device state