TSdlAudioDevice
SDL Audio Device.
Definition
Unit: Neslib.Sdl3.Audio
Properties
| Name | Description |
|---|---|
| ChannelMap | The current channel map. |
| Gain | The gain of the audio device. |
| IsPaused | Whether the audio device is paused. |
| IsPlaybackDevice | Whether this audio device is a playback device (instead of recording). |
Operators
| Name | Description |
|---|---|
| Equal(TSdlAudioDevice, TSdlAudioDevice) | Used to compare against another TSdlAudioDevice. |
| Equal(TSdlAudioDevice, Cardinal) | Used to compare against 0. |
| Implicit | Used to set the value to 0. |
| NotEqual(TSdlAudioDevice, TSdlAudioDevice) | Used to compare against another TSdlAudioDevice. |
| NotEqual(TSdlAudioDevice, Cardinal) | Used to compare against 0. |
Methods
| Name | Description |
|---|---|
| Bind(TSdlAudioStream) | Bind a single audio stream to an audio device. |
| Bind(TArray<TSdlAudioStream>) | Bind a list of audio streams to an audio device. |
| Close | Close a previously-opened audio device. |
| GetFormat | Get audio format this device is currently using. |
| Open(TSdlAudioDevice) | Open a device from a previously opened device. This just creates another logical device on the same physical device. This may be useful for making logical groupings of audio streams. |
| Open(TSdlAudioDeviceID, TSdlAudioSpec) | Open a specific audio device. |
| Open(TSdlAudioDeviceID) | Open a specific audio device. |
| Pause | Pause audio playback on the device. |
| Resume | Use this method to unpause audio playback on a specified device. |
| SetPostmixCallback | Set a callback that fires when data is about to be fed to an audio device. |
| Unbind(TSdlAudioStream) | Unbind a single audio stream from its audio device. |
| Unbind(TArray<TSdlAudioStream>) | Unbind a list of audio streams from their audio devices. |
Property Descriptions
ChannelMap
The current channel map.
Channel maps are optional; most things do not need them, instead passing data in the order that SDL expects.
Audio devices usually have no remapping applied. This is represented by returning nil, and does not signify an error.
property ChannelMap: TArray<Integer> read GetChannelMap
Type: TArray<Integer>
See Also
Remarks
It is safe to use this property from any thread
Gain
The gain of the audio device.
The gain of a device is its volume; a larger gain means a louder output, with a gain of zero being silence.
Audio devices default to a gain of 1.0 (no change in output).
This is applied, along with any per-audiostream gain, during playback to the hardware, and can be continuously changed to create various effects. On recording devices, this will adjust the gain before passing the data into an audiostream; that recording audiostream can then adjust its gain further when outputting the data elsewhere, if it likes, but that second gain is not applied until the data leaves the audiostream again.
property Gain: Single read GetGain write SetGain
Type: Single
Exceptions
ESdlError: Raised on failure.
Remarks
It is safe to use this property from any thread
IsPaused
Whether the audio device is paused.
Unlike in SDL2, audio devices start in an unpaused state, since an app has to bind a stream before any audio will flow.
You can also set this property to pause/unpause the device.
property IsPaused: Boolean read GetIsPaused write SetIsPaused
Type: Boolean
Exceptions
ESdlError: Raised on failure.
See Also
Remarks
It is safe to use this property from any thread
IsPlaybackDevice
Whether this audio device is a playback device (instead of recording).
property IsPlaybackDevice: Boolean read GetIsPlaybackDevice
Type: Boolean
Remarks
It is safe to use this property from any thread
Operator Descriptions
Equal(TSdlAudioDevice, TSdlAudioDevice)
Used to compare against another TSdlAudioDevice.
class operator Equal(const ALeft, ARight: TSdlAudioDevice): Boolean; inline; static
Parameters
ALeft: TSdlAudioDevice
ARight: TSdlAudioDevice
Returns
Boolean
Equal(TSdlAudioDevice, Cardinal)
Used to compare against 0.
class operator Equal(const ALeft: TSdlAudioDevice; const ARight: Cardinal): Boolean; inline; static
Parameters
ALeft: TSdlAudioDevice
ARight: Cardinal
Returns
Boolean
Implicit(Cardinal)
Used to set the value to 0.
class operator Implicit(const AValue: Cardinal): TSdlAudioDevice; inline; static
Parameters
AValue: Cardinal
Returns
NotEqual(TSdlAudioDevice, TSdlAudioDevice)
Used to compare against another TSdlAudioDevice.
class operator NotEqual(const ALeft, ARight: TSdlAudioDevice): Boolean; inline; static
Parameters
ALeft: TSdlAudioDevice
ARight: TSdlAudioDevice
Returns
Boolean
NotEqual(TSdlAudioDevice, Cardinal)
Used to compare against 0.
class operator NotEqual(const ALeft: TSdlAudioDevice; const ARight: Cardinal): Boolean; inline; static
Parameters
ALeft: TSdlAudioDevice
ARight: Cardinal
Returns
Boolean
Method Descriptions
Bind(TSdlAudioStream)
Bind a single audio stream to an audio device.
This is a convenience method, equivalent to calling the other overload with an array containing 1 stream.
procedure Bind(const AStream: TSdlAudioStream); overload; inline
Exceptions
ESdlError: Raised on failure.
Parameters
AStream: TSdlAudioStream
: The audio stream to bind to a device.
See Also
Remarks
It is safe to call this method from any thread
Bind(TArray<TSdlAudioStream>)
Bind a list of audio streams to an audio device.
Audio data will flow through any bound streams. For a playback device, data for all bound streams will be mixed together and fed to the device. For a recording device, a copy of recorded data will be provided to each bound stream.
This operation is atomic--all streams bound in the same call will start processing at the same time, so they can stay in sync. Also: either all streams will be bound or none of them will be.
It is an error to bind an already-bound stream; it must be explicitly unbound first.
Binding a stream to a device will set its output format for playback devices, and its input format for recording devices, so they match the device's settings. The caller is welcome to change the other end of the stream's format at any time with TSdlAudioStream.Format.
procedure Bind(const AStreams: TArray<TSdlAudioStream>); overload; inline
Exceptions
ESdlError: Raised on failure.
Parameters
AStreams: TArray<TSdlAudioStream>
: The array of audio streams to bind.
See Also
Remarks
It is safe to call this method from any thread
Close
Close a previously-opened audio device.
The application should close open audio devices once they are no longer needed.
This function may block briefly while pending audio data is played by the hardware, so that applications don't drop the last buffer of data they supplied if terminating immediately afterwards.
procedure Close; inline
See Also
Remarks
It is safe to call this method from any thread
GetFormat(TSdlAudioSpec)
Get audio format this device is currently using.
You can also use this to request the current device buffer size. This is specified in sample frames and represents the amount of data SDL will feed to the physical hardware in each chunk. This can be converted to milliseconds of audio with the following equation:
ms = ((frames * 1000) / spec.freq);
Buffer size is only important if you need low-level control over the audio playback timing. Most apps do not need this.
function GetFormat(out ASpec: TSdlAudioSpec): Integer; inline
Exceptions
ESdlError: Raised on failure.
Parameters
ASpec: TSdlAudioSpec
: Will be filled with device details.
Returns
Integer: The device buffer size, in sample frames.
Remarks
It is safe to call this method from any thread
Open(TSdlAudioDevice)
Open a device from a previously opened device. This just creates another logical device on the same physical device. This may be useful for making logical groupings of audio streams.
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 TSdlAudioStream.Open instead of this method).
When done with an audio device, possibly at the end of the app's life, one should call Close.
class function Open(const ADevice: TSdlAudioDevice): TSdlAudioDevice; overload; inline; static
Exceptions
ESdlError: Raised on failure.
Parameters
ADevice: TSdlAudioDevice
: The previously opened device.
Returns
TSdlAudioDevice: The audio device.
See Also
Remarks
It is safe to call this method from any thread
Open(TSdlAudioDeviceID, TSdlAudioSpec)
Open a specific audio device.
You can open both playback and recording devices through this method. 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 TSdlAudioStream.Open instead of this method).
If you don't care about opening a specific device, pass a ADeviceID of either TSdlAudioDeviceID.DefaultPlaybackDevice or TSdlAudioDeviceID.DefaultRecordingDevice. 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. TSdlAudioDeviceID.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 audio device 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.
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 Close.
class function Open(const ADeviceID: TSdlAudioDeviceID; const ASpec: TSdlAudioSpec): TSdlAudioDevice; overload; inline; static
Exceptions
ESdlError: Raised on failure.
Parameters
ADeviceID: TSdlAudioDeviceID
: The device instance id to open, or TSdlAudioDeviceID.DefaultPlaybackDevice or TSdlAudioDeviceID.DefaultRecordingDevice for the most reasonable default device.
ASpec: TSdlAudioSpec
: The requested device configuration.
Returns
TSdlAudioDevice: The audio device.
See Also
Remarks
It is safe to call this method from any thread
Open(TSdlAudioDeviceID)
Open a specific audio device.
You can open both playback and recording devices through this method. 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 TSdlAudioStream.Open instead of this method).
If you don't care about opening a specific device, pass a ADeviceID of either TSdlAudioDeviceID.DefaultPlaybackDevice or TSdlAudioDeviceID.DefaultRecordingDevice. 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.
It's legal to open the same device ID more than once; each successful open will generate a new logical audio device 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.
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 Close.
class function Open(const ADeviceID: TSdlAudioDeviceID): TSdlAudioDevice; overload; inline; static
Exceptions
ESdlError: Raised on failure.
Parameters
ADeviceID: TSdlAudioDeviceID
: The device instance id to open, or TSdlAudioDeviceID.DefaultPlaybackDevice or TSdlAudioDeviceID.DefaultRecordingDevice for the most reasonable default device.
Returns
TSdlAudioDevice: The audio device.
See Also
Remarks
It is safe to call this method from any thread
Pause
Pause audio playback on the device.
This method pauses audio processing for the device. Any bound audio streams will not progress, and no audio will be generated. Pausing one device does not prevent other unpaused devices from running.
Unlike in SDL2, audio devices start in an unpaused state, since an app has to bind a stream before any audio will flow. Pausing a paused device is a legal no-op.
Pausing a device can be useful to halt all audio without unbinding all the audio streams. This might be useful while a game is paused, or a level is loading, etc.
procedure Pause; inline
Exceptions
ESdlError: Raised on failure.
See Also
Remarks
It is safe to call this method from any thread
Resume
Use this method to unpause audio playback on a specified device.
This function unpauses audio processing for a given device that has previously been paused with Pause. Once unpaused, any bound audio streams will begin to progress again, and audio can be generated.
Unlike in SDL2, audio devices start in an unpaused state, since an app has to bind a stream before any audio will flow. Unpausing an unpaused device is a legal no-op.
procedure Resume; inline
Exceptions
ESdlError: Raised on failure.
See Also
Remarks
It is safe to call this method from any thread
SetPostmixCallback(TSdlAudioPostmixCallback, Pointer)
Set a callback that fires when data is about to be fed to an audio device.
This is useful for accessing the final mix, perhaps for writing a visualizer or applying a final effect to the audio data before playback.
The buffer is the final mix of all bound audio streams on an opened device; this callback will fire regularly for any device that is both opened and unpaused. If there is no new data to mix, either because no streams are bound to the device or all the streams are empty, this callback will still fire with the entire buffer set to silence.
This callback is allowed to make changes to the data; the contents of the buffer after this call is what is ultimately passed along to the hardware.
The callback is always provided the data in float format (values from -1.0 to 1.0), but the number of channels or sample rate may be different than the format the app requested when opening the device; SDL might have had to manage a conversion behind the scenes, or the playback might have jumped to new physical hardware when a system default changed, etc. These details may change between calls. Accordingly, the size of the buffer might change between calls as well.
This callback can run at any time, and from any thread; if you need to serialize access to your app's data, you should provide and use a mutex or other synchronization device.
All of this to say: there are specific needs this callback can fulfill, but it is not the simplest interface. Apps should generally provide audio in their preferred format through an TSdlAudioStream and let SDL handle the difference.
This function is extremely time-sensitive; the callback should do the least amount of work possible and return as quickly as it can. The longer the callback runs, the higher the risk of audio dropouts or other problems.
This function will block until the audio device is in between iterations, so any existing callback that might be running will finish before this function sets the new callback and returns.
Setting a nil callback function disables any previously-set callback.
procedure SetPostmixCallback(const ACallback: TSdlAudioPostmixCallback; const AUserData: Pointer); inline
Exceptions
ESdlError: Raised on failure.
Parameters
ACallback: TSdlAudioPostmixCallback
: A callback function to be called. Can be nil.
AUserData: Pointer
: App-controlled pointer passed to callback. Can be nil.
Remarks
It is safe to call this method from any thread
Unbind(TSdlAudioStream)
Unbind a single audio stream from its audio device.
This is a convenience method, equivalent to calling the other overload with an array containing 1 stream.
class procedure Unbind(const AStream: TSdlAudioStream); overload; inline; static
Parameters
AStream: TSdlAudioStream
: The audio stream to unbind.
See Also
Remarks
It is safe to call this method from any thread
Unbind(TArray<TSdlAudioStream>)
Unbind a list of audio streams from their audio devices.
The streams being unbound do not all have to be on the same device. All streams on the same device will be unbound atomically (data will stop flowing through all unbound streams on the same device at the same time).
Unbinding a stream that isn't bound to a device is a legal no-op.
class procedure Unbind(const AStreams: TArray<TSdlAudioStream>); overload; inline; static
Parameters
AStreams: TArray<TSdlAudioStream>
: An array of audio streams to unbind.
See Also
Remarks
It is safe to call this method from any thread