Typed constant for macro SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK.

Typed constant for macro SDL_AUDIO_DEVICE_DEFAULT_RECORDING.

Use this function to get the number of built-in audio drivers.

This function returns a hardcoded number. This never returns a negative value; if there are no drivers compiled into this build of SDL, this function returns zero. The presence of a driver in this list does not mean it will function, it just means SDL is capable of interacting with that interface. For example, a build of SDL might have esound support, but if there's no esound server available, SDL's esound driver would fail if used.

By default, SDL tries all drivers, in its preferred order, until one is found to be usable.

Returns

the number of built-in audio drivers.

Thread safety

It is safe to call this function from any thread.

See also

getAudioDriver

sdl3-bindgen-sys notes

Since: 3.2.0

Use this function to get the number of built-in audio drivers.

This function returns a hardcoded number. This never returns a negative value; if there are no drivers compiled into this build of SDL, this function returns zero. The presence of a driver in this list does not mean it will function, it just means SDL is capable of interacting with that interface. For example, a build of SDL might have esound support, but if there's no esound server available, SDL's esound driver would fail if used.

By default, SDL tries all drivers, in its preferred order, until one is found to be usable.

Returns

the number of built-in audio drivers.

Thread safety

It is safe to call this function from any thread.

See also

getAudioDriver

sdl3-bindgen-sys notes

Since: 3.2.0

Use this function to get the name of a built in audio driver.

The list of audio drivers is given in the order that they are normally initialized by default; the drivers that seem more reasonable to choose first (as far as the SDL developers believe) are earlier in the list.

The names of drivers are all simple, low-ASCII identifiers, like "alsa", "coreaudio" or "wasapi". These never have Unicode characters, and are not meant to be proper names.

Returns

the name of the audio driver at the requested index, or NULL if an invalid index was specified.

Thread safety

It is safe to call this function from any thread.

See also

getNumAudioDrivers

sdl3-bindgen-sys notes

Since: 3.2.0

Use this function to get the name of a built in audio driver.

The list of audio drivers is given in the order that they are normally initialized by default; the drivers that seem more reasonable to choose first (as far as the SDL developers believe) are earlier in the list.

The names of drivers are all simple, low-ASCII identifiers, like "alsa", "coreaudio" or "wasapi". These never have Unicode characters, and are not meant to be proper names.

Returns

the name of the audio driver at the requested index, or NULL if an invalid index was specified.

Thread safety

It is safe to call this function from any thread.

See also

getNumAudioDrivers

sdl3-bindgen-sys notes

Since: 3.2.0

Get the name of the current audio driver.

The names of drivers are all simple, low-ASCII identifiers, like "alsa", "coreaudio" or "wasapi". These never have Unicode characters, and are not meant to be proper names.

Returns

the name of the current audio driver or NULL if no driver has been initialized.

Thread safety

It is safe to call this function from any thread.

sdl3-bindgen-sys notes

Since: 3.2.0

Get the name of the current audio driver.

The names of drivers are all simple, low-ASCII identifiers, like "alsa", "coreaudio" or "wasapi". These never have Unicode characters, and are not meant to be proper names.

Returns

the name of the current audio driver or NULL if no driver has been initialized.

Thread safety

It is safe to call this function from any thread.

sdl3-bindgen-sys notes

Since: 3.2.0

Get a list of currently-connected audio playback devices.

This returns of list of available devices that play sound, perhaps to speakers or headphones ("playback" devices). If you want devices that record audio, like a microphone ("recording" devices), use getAudioRecordingDevices instead.

This only returns a list of physical devices; it will not have any device IDs returned by openAudioDevice.

If this function returns NULL, to signify an error, *count will be set to zero.

Returns

a 0 terminated array of device instance IDs or NULL on error; call getError for more information. This should be freed with free when it is no longer needed.

Thread safety

It is safe to call this function from any thread.

See also

openAudioDevice, getAudioRecordingDevices

sdl3-bindgen-sys notes

Since: 3.2.0

Get a list of currently-connected audio playback devices.

This returns of list of available devices that play sound, perhaps to speakers or headphones ("playback" devices). If you want devices that record audio, like a microphone ("recording" devices), use getAudioRecordingDevices instead.

This only returns a list of physical devices; it will not have any device IDs returned by openAudioDevice.

If this function returns NULL, to signify an error, *count will be set to zero.

Returns

a 0 terminated array of device instance IDs or NULL on error; call getError for more information. This should be freed with free when it is no longer needed.

Thread safety

It is safe to call this function from any thread.

See also

openAudioDevice, getAudioRecordingDevices

sdl3-bindgen-sys notes

Since: 3.2.0

Get a list of currently-connected audio recording devices.

This returns of list of available devices that record audio, like a microphone ("recording" devices). If you want devices that play sound, perhaps to speakers or headphones ("playback" devices), use getAudioPlaybackDevices instead.

This only returns a list of physical devices; it will not have any device IDs returned by openAudioDevice.

If this function returns NULL, to signify an error, *count will be set to zero.

Returns

a 0 terminated array of device instance IDs, or NULL on failure; call getError for more information. This should be freed with free when it is no longer needed.

Thread safety

It is safe to call this function from any thread.

See also

openAudioDevice, getAudioPlaybackDevices

sdl3-bindgen-sys notes

Since: 3.2.0

Get a list of currently-connected audio recording devices.

This returns of list of available devices that record audio, like a microphone ("recording" devices). If you want devices that play sound, perhaps to speakers or headphones ("playback" devices), use getAudioPlaybackDevices instead.

This only returns a list of physical devices; it will not have any device IDs returned by openAudioDevice.

If this function returns NULL, to signify an error, *count will be set to zero.

Returns

a 0 terminated array of device instance IDs, or NULL on failure; call getError for more information. This should be freed with free when it is no longer needed.

Thread safety

It is safe to call this function from any thread.

See also

openAudioDevice, getAudioPlaybackDevices

sdl3-bindgen-sys notes

Since: 3.2.0

Get the human-readable name of a specific audio device.

WARNING: this function will work with SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK and SDL_AUDIO_DEVICE_DEFAULT_RECORDING, returning the current default physical devices' names. However, as the default device may change at any time, it is likely better to show a generic name to the user, like "System default audio device" or perhaps "default [currently %s]". Do not store this name to disk to reidentify the device in a later run of the program, as the default might change in general, and the string will be the name of a specific device and not the abstract system default.

Returns

the name of the audio device, or NULL on failure; call getError for more information.

Thread safety

It is safe to call this function from any thread.

See also

getAudioPlaybackDevices, getAudioRecordingDevices

sdl3-bindgen-sys notes

Since: 3.2.0

Get the human-readable name of a specific audio device.

WARNING: this function will work with SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK and SDL_AUDIO_DEVICE_DEFAULT_RECORDING, returning the current default physical devices' names. However, as the default device may change at any time, it is likely better to show a generic name to the user, like "System default audio device" or perhaps "default [currently %s]". Do not store this name to disk to reidentify the device in a later run of the program, as the default might change in general, and the string will be the name of a specific device and not the abstract system default.

Returns

the name of the audio device, or NULL on failure; call getError for more information.

Thread safety

It is safe to call this function from any thread.

See also

getAudioPlaybackDevices, getAudioRecordingDevices

sdl3-bindgen-sys notes

Since: 3.2.0

Get the current audio format of a specific audio device.

For an opened device, this will report the format the device is currently using. If the device isn't yet opened, this will report the device's preferred format (or a reasonable default if this can't be determined).

You may also specify SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK or SDL_AUDIO_DEVICE_DEFAULT_RECORDING here, which is useful for getting a reasonable recommendation before opening the system-recommended default device.

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 = (int) ((((Sint64) 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.

Returns

true on success or false on failure; call getError for more information.

Thread safety

It is safe to call this function from any thread.

sdl3-bindgen-sys notes

Since: 3.2.0

Get the current audio format of a specific audio device.

For an opened device, this will report the format the device is currently using. If the device isn't yet opened, this will report the device's preferred format (or a reasonable default if this can't be determined).

You may also specify SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK or SDL_AUDIO_DEVICE_DEFAULT_RECORDING here, which is useful for getting a reasonable recommendation before opening the system-recommended default device.

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 = (int) ((((Sint64) 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.

Returns

true on success or false on failure; call getError for more information.

Thread safety

It is safe to call this function from any thread.

sdl3-bindgen-sys notes

Since: 3.2.0

Get the current channel map of an audio device.

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 NULL, and does not signify an error.

Returns

an array of the current channel mapping, with as many elements as the current output spec's channels, or NULL if default. This should be freed with free when it is no longer needed.

Thread safety

It is safe to call this function from any thread.

See also

setAudioStreamInputChannelMap

sdl3-bindgen-sys notes

Since: 3.2.0

Get the current channel map of an audio device.

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 NULL, and does not signify an error.

Returns

an array of the current channel mapping, with as many elements as the current output spec's channels, or NULL if default. This should be freed with free when it is no longer needed.

Thread safety

It is safe to call this function from any thread.

See also

setAudioStreamInputChannelMap

sdl3-bindgen-sys notes

Since: 3.2.0

Open a specific audio device.

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 openAudioDeviceStream instead of this function).

If you don't care about opening a specific device, pass a devid of either SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK or SDL_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. getAudioDeviceFormat 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 SDL_AudioDeviceID 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 SDL_AudioDeviceID 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 closeAudioDevice on the returned device id.

Returns

the device ID on success or 0 on failure; call getError for more information.

Thread safety

It is safe to call this function from any thread.

See also

closeAudioDevice, getAudioDeviceFormat

sdl3-bindgen-sys notes

Since: 3.2.0

Open a specific audio device.

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 openAudioDeviceStream instead of this function).

If you don't care about opening a specific device, pass a devid of either SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK or SDL_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. getAudioDeviceFormat 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 SDL_AudioDeviceID 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 SDL_AudioDeviceID 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 closeAudioDevice on the returned device id.

Returns

the device ID on success or 0 on failure; call getError for more information.

Thread safety

It is safe to call this function from any thread.

See also

closeAudioDevice, getAudioDeviceFormat

sdl3-bindgen-sys notes

Since: 3.2.0

Determine if an audio device is physical (instead of logical).

An SDL_AudioDeviceID that represents physical hardware is a physical device; there is one for each piece of hardware that SDL can see. Logical devices are created by calling openAudioDevice or openAudioDeviceStream, and while each is associated with a physical device, there can be any number of logical devices on one physical device.

For the most part, logical and physical IDs are interchangeable if you try to open a logical device, SDL understands to assign that effort to the underlying physical device, etc. However, it might be useful to know if an arbitrary device ID is physical or logical. This function reports which.

This function may return either true or false for invalid device IDs.

Returns

true if devid is a physical device, false if it is logical.

Thread safety

It is safe to call this function from any thread.

sdl3-bindgen-sys notes

Since: 3.2.0

Determine if an audio device is physical (instead of logical).

An SDL_AudioDeviceID that represents physical hardware is a physical device; there is one for each piece of hardware that SDL can see. Logical devices are created by calling openAudioDevice or openAudioDeviceStream, and while each is associated with a physical device, there can be any number of logical devices on one physical device.

For the most part, logical and physical IDs are interchangeable if you try to open a logical device, SDL understands to assign that effort to the underlying physical device, etc. However, it might be useful to know if an arbitrary device ID is physical or logical. This function reports which.

This function may return either true or false for invalid device IDs.

Returns

true if devid is a physical device, false if it is logical.

Thread safety

It is safe to call this function from any thread.

sdl3-bindgen-sys notes

Since: 3.2.0

Determine if an audio device is a playback device (instead of recording).

This function may return either true or false for invalid device IDs.

Returns

true if devid is a playback device, false if it is recording.

Thread safety

It is safe to call this function from any thread.

sdl3-bindgen-sys notes

Since: 3.2.0

Determine if an audio device is a playback device (instead of recording).

This function may return either true or false for invalid device IDs.

Returns

true if devid is a playback device, false if it is recording.

Thread safety

It is safe to call this function from any thread.

sdl3-bindgen-sys notes

Since: 3.2.0

Use this function to pause audio playback on a specified device.

This function pauses audio processing for a given 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.

Physical devices can not be paused or unpaused, only logical devices created through openAudioDevice can be.

Returns

true on success or false on failure; call getError for more information.

Thread safety

It is safe to call this function from any thread.

See also

resumeAudioDevice, audioDevicePaused

sdl3-bindgen-sys notes

Since: 3.2.0

Use this function to pause audio playback on a specified device.

This function pauses audio processing for a given 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.

Physical devices can not be paused or unpaused, only logical devices created through openAudioDevice can be.

Returns

true on success or false on failure; call getError for more information.

Thread safety

It is safe to call this function from any thread.

See also

resumeAudioDevice, audioDevicePaused

sdl3-bindgen-sys notes

Since: 3.2.0

Use this function to unpause audio playback on a specified device.

This function unpauses audio processing for a given device that has previously been paused with pauseAudioDevice. 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.

Physical devices can not be paused or unpaused, only logical devices created through openAudioDevice can be.

Returns

true on success or false on failure; call getError for more information.

Thread safety

It is safe to call this function from any thread.

See also

audioDevicePaused, pauseAudioDevice

sdl3-bindgen-sys notes

Since: 3.2.0

Use this function to unpause audio playback on a specified device.

This function unpauses audio processing for a given device that has previously been paused with pauseAudioDevice. 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.

Physical devices can not be paused or unpaused, only logical devices created through openAudioDevice can be.

Returns

true on success or false on failure; call getError for more information.

Thread safety

It is safe to call this function from any thread.

See also

audioDevicePaused, pauseAudioDevice

sdl3-bindgen-sys notes

Since: 3.2.0

Use this function to query if an 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.

Physical devices can not be paused or unpaused, only logical devices created through openAudioDevice can be. Physical and invalid device IDs will report themselves as unpaused here.

Returns

true if device is valid and paused, false otherwise.

Thread safety

It is safe to call this function from any thread.

See also

pauseAudioDevice, resumeAudioDevice

sdl3-bindgen-sys notes

Since: 3.2.0

Use this function to query if an 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.

Physical devices can not be paused or unpaused, only logical devices created through openAudioDevice can be. Physical and invalid device IDs will report themselves as unpaused here.

Returns

true if device is valid and paused, false otherwise.

Thread safety

It is safe to call this function from any thread.

See also

pauseAudioDevice, resumeAudioDevice

sdl3-bindgen-sys notes

Since: 3.2.0

Get the gain of an 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.0f (no change in output).

Physical devices may not have their gain changed, only logical devices, and this function will always return -1.0f when used on physical devices.

Returns

the gain of the device or -1.0f on failure; call getError for more information.

Thread safety

It is safe to call this function from any thread.

See also

setAudioDeviceGain

sdl3-bindgen-sys notes

Since: 3.2.0

Get the gain of an 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.0f (no change in output).

Physical devices may not have their gain changed, only logical devices, and this function will always return -1.0f when used on physical devices.

Returns

the gain of the device or -1.0f on failure; call getError for more information.

Thread safety

It is safe to call this function from any thread.

See also

setAudioDeviceGain

sdl3-bindgen-sys notes

Since: 3.2.0

Change the gain of an 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.0f (no change in output).

Physical devices may not have their gain changed, only logical devices, and this function will always return false when used on physical devices. While it might seem attractive to adjust several logical devices at once in this way, it would allow an app or library to interfere with another portion of the program's otherwise-isolated devices.

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.

Returns

true on success or false on failure; call getError for more information.

Thread safety

It is safe to call this function from any thread, as it holds a stream-specific mutex while running.

See also

getAudioDeviceGain

sdl3-bindgen-sys notes

Since: 3.2.0

Change the gain of an 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.0f (no change in output).

Physical devices may not have their gain changed, only logical devices, and this function will always return false when used on physical devices. While it might seem attractive to adjust several logical devices at once in this way, it would allow an app or library to interfere with another portion of the program's otherwise-isolated devices.

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.

Returns

true on success or false on failure; call getError for more information.

Thread safety

It is safe to call this function from any thread, as it holds a stream-specific mutex while running.

See also

getAudioDeviceGain

sdl3-bindgen-sys notes

Since: 3.2.0

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.

Thread safety

It is safe to call this function from any thread.

See also

openAudioDevice

sdl3-bindgen-sys notes

Since: 3.2.0

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.

Thread safety

It is safe to call this function from any thread.

See also

openAudioDevice

sdl3-bindgen-sys notes

Since: 3.2.0

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.

Audio streams can only be bound to an open device. 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 setAudioStreamFormat. If the other end of the stream's format has never been set (the audio stream was created with a NULL audio spec), this function will set it to match the device end's format.

Returns

true on success or false on failure; call getError for more information.

Thread safety

It is safe to call this function from any thread.

See also

bindAudioStreams, unbindAudioStream, getAudioStreamDevice

sdl3-bindgen-sys notes

Since: 3.2.0

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.

Audio streams can only be bound to an open device. 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 setAudioStreamFormat. If the other end of the stream's format has never been set (the audio stream was created with a NULL audio spec), this function will set it to match the device end's format.

Returns

true on success or false on failure; call getError for more information.

Thread safety

It is safe to call this function from any thread.

See also

bindAudioStreams, unbindAudioStream, getAudioStreamDevice

sdl3-bindgen-sys notes

Since: 3.2.0

Bind a single audio stream to an audio device.

This is a convenience function, equivalent to calling bindAudioStreams (devid, &stream, 1).

Returns

true on success or false on failure; call getError for more information.

Thread safety

It is safe to call this function from any thread.

See also

bindAudioStreams, unbindAudioStream, getAudioStreamDevice

sdl3-bindgen-sys notes

Since: 3.2.0

Bind a single audio stream to an audio device.

This is a convenience function, equivalent to calling bindAudioStreams (devid, &stream, 1).

Returns

true on success or false on failure; call getError for more information.

Thread safety

It is safe to call this function from any thread.

See also

bindAudioStreams, unbindAudioStream, getAudioStreamDevice

sdl3-bindgen-sys notes

Since: 3.2.0

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.

Thread safety

It is safe to call this function from any thread.

See also

bindAudioStreams

sdl3-bindgen-sys notes

Since: 3.2.0

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.

Thread safety

It is safe to call this function from any thread.

See also

bindAudioStreams

sdl3-bindgen-sys notes

Since: 3.2.0

Unbind a single audio stream from its audio device.

This is a convenience function, equivalent to calling unbindAudioStreams (&stream, 1).

Thread safety

It is safe to call this function from any thread.

See also

bindAudioStream

sdl3-bindgen-sys notes

Since: 3.2.0

Unbind a single audio stream from its audio device.

This is a convenience function, equivalent to calling unbindAudioStreams (&stream, 1).

Thread safety

It is safe to call this function from any thread.

See also

bindAudioStream

sdl3-bindgen-sys notes

Since: 3.2.0

Query an audio stream for its currently-bound device.

This reports the logical audio device that an audio stream is currently bound to.

If not bound, or invalid, this returns zero, which is not a valid device ID.

Returns

the bound audio device, or 0 if not bound or invalid.

Thread safety

It is safe to call this function from any thread.

See also

bindAudioStream, bindAudioStreams

sdl3-bindgen-sys notes

Since: 3.2.0

Query an audio stream for its currently-bound device.

This reports the logical audio device that an audio stream is currently bound to.

If not bound, or invalid, this returns zero, which is not a valid device ID.

Returns

the bound audio device, or 0 if not bound or invalid.

Thread safety

It is safe to call this function from any thread.

See also

bindAudioStream, bindAudioStreams

sdl3-bindgen-sys notes

Since: 3.2.0

Create a new audio stream.

Note that src_spec or dst_spec may be NULL, but any attempts to put or get data from an audio stream will fail until it has valid specs assigned to both ends of the stream. Specs can be assigned later through setAudioStreamFormat, or binding the stream to an audio device (which will set the format of only the input or output, depending on what kind of device the stream was bound to).

Returns

a new audio stream on success or NULL on failure; call getError for more information.

Thread safety

It is safe to call this function from any thread.

See also

putAudioStreamData, getAudioStreamData, getAudioStreamAvailable, flushAudioStream, clearAudioStream, setAudioStreamFormat, destroyAudioStream

sdl3-bindgen-sys notes

Since: 3.2.0

Create a new audio stream.

Note that src_spec or dst_spec may be NULL, but any attempts to put or get data from an audio stream will fail until it has valid specs assigned to both ends of the stream. Specs can be assigned later through setAudioStreamFormat, or binding the stream to an audio device (which will set the format of only the input or output, depending on what kind of device the stream was bound to).

Returns

a new audio stream on success or NULL on failure; call getError for more information.

Thread safety

It is safe to call this function from any thread.

See also

putAudioStreamData, getAudioStreamData, getAudioStreamAvailable, flushAudioStream, clearAudioStream, setAudioStreamFormat, destroyAudioStream

sdl3-bindgen-sys notes

Since: 3.2.0

Get the properties associated with an audio stream.

The application can hang any data it wants here, but the following properties are understood by SDL:

• sDL_PROP_AUDIOSTREAM_AUTO_CLEANUP_BOOLEAN: if true (the default), the stream be automatically cleaned up when the audio subsystem quits. If set to false, the streams will persist beyond that. This property is ignored for streams created through openAudioDeviceStream, and will always be cleaned up. Streams that are not cleaned up will still be unbound from devices when the audio subsystem quits. This property was added in SDL 3.4.0.

Returns

a valid property ID on success or 0 on failure; call getError for more information.

Thread safety

It is safe to call this function from any thread.

sdl3-bindgen-sys notes

Since: 3.2.0

Get the properties associated with an audio stream.

The application can hang any data it wants here, but the following properties are understood by SDL:

• sDL_PROP_AUDIOSTREAM_AUTO_CLEANUP_BOOLEAN: if true (the default), the stream be automatically cleaned up when the audio subsystem quits. If set to false, the streams will persist beyond that. This property is ignored for streams created through openAudioDeviceStream, and will always be cleaned up. Streams that are not cleaned up will still be unbound from devices when the audio subsystem quits. This property was added in SDL 3.4.0.

Returns

a valid property ID on success or 0 on failure; call getError for more information.

Thread safety

It is safe to call this function from any thread.

sdl3-bindgen-sys notes

Since: 3.2.0

Query the current format of an audio stream.

Returns

true on success or false on failure; call getError for more information.

Thread safety

It is safe to call this function from any thread, as it holds a stream-specific mutex while running.

See also

setAudioStreamFormat

sdl3-bindgen-sys notes

Since: 3.2.0

Query the current format of an audio stream.

Returns

true on success or false on failure; call getError for more information.

Thread safety

It is safe to call this function from any thread, as it holds a stream-specific mutex while running.

See also

setAudioStreamFormat

sdl3-bindgen-sys notes

Since: 3.2.0

Change the input and output formats of an audio stream.

Future calls to and getAudioStreamAvailable and getAudioStreamData will reflect the new format, and future calls to putAudioStreamData must provide data in the new input formats.

Data that was previously queued in the stream will still be operated on in the format that was current when it was added, which is to say you can put the end of a sound file in one format to a stream, change formats for the next sound file, and start putting that new data while the previous sound file is still queued, and everything will still play back correctly.

If a stream is bound to a device, then the format of the side of the stream bound to a device cannot be changed (src_spec for recording devices, dst_spec for playback devices). Attempts to make a change to this side will be ignored, but this will not report an error. The other side's format can be changed.

src_spec and dst_spec may each be NULL; a NULL spec signals not to change the current format for that side of the stream.

Returns

true on success or false on failure; call getError for more information.

Thread safety

It is safe to call this function from any thread, as it holds a stream-specific mutex while running.

See also

getAudioStreamFormat, setAudioStreamFrequencyRatio

sdl3-bindgen-sys notes

Since: 3.2.0

Change the input and output formats of an audio stream.

Future calls to and getAudioStreamAvailable and getAudioStreamData will reflect the new format, and future calls to putAudioStreamData must provide data in the new input formats.

Data that was previously queued in the stream will still be operated on in the format that was current when it was added, which is to say you can put the end of a sound file in one format to a stream, change formats for the next sound file, and start putting that new data while the previous sound file is still queued, and everything will still play back correctly.

If a stream is bound to a device, then the format of the side of the stream bound to a device cannot be changed (src_spec for recording devices, dst_spec for playback devices). Attempts to make a change to this side will be ignored, but this will not report an error. The other side's format can be changed.

src_spec and dst_spec may each be NULL; a NULL spec signals not to change the current format for that side of the stream.

Returns

true on success or false on failure; call getError for more information.

Thread safety

It is safe to call this function from any thread, as it holds a stream-specific mutex while running.

See also

getAudioStreamFormat, setAudioStreamFrequencyRatio

sdl3-bindgen-sys notes

Since: 3.2.0

Get the frequency ratio of an audio stream.

Returns

the frequency ratio of the stream or 0.0 on failure; call getError for more information.

Thread safety

It is safe to call this function from any thread, as it holds a stream-specific mutex while running.

See also

setAudioStreamFrequencyRatio

sdl3-bindgen-sys notes

Since: 3.2.0

Get the frequency ratio of an audio stream.

Returns

the frequency ratio of the stream or 0.0 on failure; call getError for more information.

Thread safety

It is safe to call this function from any thread, as it holds a stream-specific mutex while running.

See also

setAudioStreamFrequencyRatio

sdl3-bindgen-sys notes

Since: 3.2.0

Change the frequency ratio of an audio stream.

The frequency ratio is used to adjust the rate at which input data is consumed. Changing this effectively modifies the speed and pitch of the audio. A value greater than 1.0f will play the audio faster, and at a higher pitch. A value less than 1.0f will play the audio slower, and at a lower pitch. 1.0f means play at normal speed.

This is applied during getAudioStreamData, and can be continuously changed to create various effects.

Returns

true on success or false on failure; call getError for more information.

Thread safety

It is safe to call this function from any thread, as it holds a stream-specific mutex while running.

See also

getAudioStreamFrequencyRatio, setAudioStreamFormat

sdl3-bindgen-sys notes

Since: 3.2.0

Change the frequency ratio of an audio stream.

The frequency ratio is used to adjust the rate at which input data is consumed. Changing this effectively modifies the speed and pitch of the audio. A value greater than 1.0f will play the audio faster, and at a higher pitch. A value less than 1.0f will play the audio slower, and at a lower pitch. 1.0f means play at normal speed.

This is applied during getAudioStreamData, and can be continuously changed to create various effects.

Returns

true on success or false on failure; call getError for more information.

Thread safety

It is safe to call this function from any thread, as it holds a stream-specific mutex while running.

See also

getAudioStreamFrequencyRatio, setAudioStreamFormat

sdl3-bindgen-sys notes

Since: 3.2.0

Get the gain of an audio stream.

The gain of a stream is its volume; a larger gain means a louder output, with a gain of zero being silence.

Audio streams default to a gain of 1.0f (no change in output).

Returns

the gain of the stream or -1.0f on failure; call getError for more information.

Thread safety

It is safe to call this function from any thread, as it holds a stream-specific mutex while running.

See also

setAudioStreamGain

sdl3-bindgen-sys notes

Since: 3.2.0

Get the gain of an audio stream.

The gain of a stream is its volume; a larger gain means a louder output, with a gain of zero being silence.

Audio streams default to a gain of 1.0f (no change in output).

Returns

the gain of the stream or -1.0f on failure; call getError for more information.

Thread safety

It is safe to call this function from any thread, as it holds a stream-specific mutex while running.

See also

setAudioStreamGain

sdl3-bindgen-sys notes

Since: 3.2.0

Change the gain of an audio stream.

The gain of a stream is its volume; a larger gain means a louder output, with a gain of zero being silence.

Audio streams default to a gain of 1.0f (no change in output).

This is applied during getAudioStreamData, and can be continuously changed to create various effects.

Returns

true on success or false on failure; call getError for more information.

Thread safety

It is safe to call this function from any thread, as it holds a stream-specific mutex while running.

See also

getAudioStreamGain

sdl3-bindgen-sys notes

Since: 3.2.0

Change the gain of an audio stream.

The gain of a stream is its volume; a larger gain means a louder output, with a gain of zero being silence.

Audio streams default to a gain of 1.0f (no change in output).

This is applied during getAudioStreamData, and can be continuously changed to create various effects.

Returns

true on success or false on failure; call getError for more information.

Thread safety

It is safe to call this function from any thread, as it holds a stream-specific mutex while running.

See also

getAudioStreamGain

sdl3-bindgen-sys notes

Since: 3.2.0

Get the current input channel map of an audio stream.

Channel maps are optional; most things do not need them, instead passing data in the order that SDL expects.

Audio streams default to no remapping applied. This is represented by returning NULL, and does not signify an error.

Returns

an array of the current channel mapping, with as many elements as the current output spec's channels, or NULL if default. This should be freed with free when it is no longer needed.

Thread safety

It is safe to call this function from any thread, as it holds a stream-specific mutex while running.

See also

setAudioStreamInputChannelMap

sdl3-bindgen-sys notes

Since: 3.2.0

Get the current input channel map of an audio stream.

Channel maps are optional; most things do not need them, instead passing data in the order that SDL expects.

Audio streams default to no remapping applied. This is represented by returning NULL, and does not signify an error.

Returns

an array of the current channel mapping, with as many elements as the current output spec's channels, or NULL if default. This should be freed with free when it is no longer needed.

Thread safety

It is safe to call this function from any thread, as it holds a stream-specific mutex while running.

See also

setAudioStreamInputChannelMap

sdl3-bindgen-sys notes

Since: 3.2.0

Get the current output channel map of an audio stream.

Channel maps are optional; most things do not need them, instead passing data in the order that SDL expects.

Audio streams default to no remapping applied. This is represented by returning NULL, and does not signify an error.

Returns

an array of the current channel mapping, with as many elements as the current output spec's channels, or NULL if default. This should be freed with free when it is no longer needed.

Thread safety

It is safe to call this function from any thread, as it holds a stream-specific mutex while running.

See also

setAudioStreamInputChannelMap

sdl3-bindgen-sys notes

Since: 3.2.0

Get the current output channel map of an audio stream.

Channel maps are optional; most things do not need them, instead passing data in the order that SDL expects.

Audio streams default to no remapping applied. This is represented by returning NULL, and does not signify an error.

Returns

an array of the current channel mapping, with as many elements as the current output spec's channels, or NULL if default. This should be freed with free when it is no longer needed.

Thread safety

It is safe to call this function from any thread, as it holds a stream-specific mutex while running.

See also

setAudioStreamInputChannelMap

sdl3-bindgen-sys notes

Since: 3.2.0

Set the current input channel map of an audio stream.

Channel maps are optional; most things do not need them, instead passing data in the order that SDL expects.

The input channel map reorders data that is added to a stream via putAudioStreamData. Future calls to putAudioStreamData must provide data in the new channel order.

Each item in the array represents an input channel, and its value is the channel that it should be remapped to. To reverse a stereo signal's left and right values, you'd have an array of { 1, 0 }. It is legal to remap multiple channels to the same thing, so { 1, 1 } would duplicate the right channel to both channels of a stereo signal. An element in the channel map set to -1 instead of a valid channel will mute that channel, setting it to a silence value.

You cannot change the number of channels through a channel map, just reorder/mute them.

Data that was previously queued in the stream will still be operated on in the order that was current when it was added, which is to say you can put the end of a sound file in one order to a stream, change orders for the next sound file, and start putting that new data while the previous sound file is still queued, and everything will still play back correctly.

Audio streams default to no remapping applied. Passing a NULL channel map is legal, and turns off remapping.

SDL will copy the channel map; the caller does not have to save this array after this call.

If count is not equal to the current number of channels in the audio stream's format, this will fail. This is a safety measure to make sure a race condition hasn't changed the format while this call is setting the channel map.

Unlike attempting to change the stream's format, the input channel map on a stream bound to a recording device is permitted to change at any time; any data added to the stream from the device after this call will have the new mapping, but previously-added data will still have the prior mapping.

Returns

true on success or false on failure; call getError for more information.

Thread safety

It is safe to call this function from any thread, as it holds a stream-specific mutex while running. Don't change the stream's format to have a different number of channels from a different thread at the same time, though!

See also

setAudioStreamOutputChannelMap

sdl3-bindgen-sys notes

Since: 3.2.0

Set the current input channel map of an audio stream.

Channel maps are optional; most things do not need them, instead passing data in the order that SDL expects.

The input channel map reorders data that is added to a stream via putAudioStreamData. Future calls to putAudioStreamData must provide data in the new channel order.

Each item in the array represents an input channel, and its value is the channel that it should be remapped to. To reverse a stereo signal's left and right values, you'd have an array of { 1, 0 }. It is legal to remap multiple channels to the same thing, so { 1, 1 } would duplicate the right channel to both channels of a stereo signal. An element in the channel map set to -1 instead of a valid channel will mute that channel, setting it to a silence value.

You cannot change the number of channels through a channel map, just reorder/mute them.

Data that was previously queued in the stream will still be operated on in the order that was current when it was added, which is to say you can put the end of a sound file in one order to a stream, change orders for the next sound file, and start putting that new data while the previous sound file is still queued, and everything will still play back correctly.

Audio streams default to no remapping applied. Passing a NULL channel map is legal, and turns off remapping.

SDL will copy the channel map; the caller does not have to save this array after this call.

If count is not equal to the current number of channels in the audio stream's format, this will fail. This is a safety measure to make sure a race condition hasn't changed the format while this call is setting the channel map.

Unlike attempting to change the stream's format, the input channel map on a stream bound to a recording device is permitted to change at any time; any data added to the stream from the device after this call will have the new mapping, but previously-added data will still have the prior mapping.

Returns

true on success or false on failure; call getError for more information.

Thread safety

It is safe to call this function from any thread, as it holds a stream-specific mutex while running. Don't change the stream's format to have a different number of channels from a different thread at the same time, though!

See also

setAudioStreamOutputChannelMap

sdl3-bindgen-sys notes

Since: 3.2.0

Set the current output channel map of an audio stream.

Channel maps are optional; most things do not need them, instead passing data in the order that SDL expects.

The output channel map reorders data that is leaving a stream via getAudioStreamData.

Each item in the array represents an input channel, and its value is the channel that it should be remapped to. To reverse a stereo signal's left and right values, you'd have an array of { 1, 0 }. It is legal to remap multiple channels to the same thing, so { 1, 1 } would duplicate the right channel to both channels of a stereo signal. An element in the channel map set to -1 instead of a valid channel will mute that channel, setting it to a silence value.

You cannot change the number of channels through a channel map, just reorder/mute them.

The output channel map can be changed at any time, as output remapping is applied during getAudioStreamData.

Audio streams default to no remapping applied. Passing a NULL channel map is legal, and turns off remapping.

SDL will copy the channel map; the caller does not have to save this array after this call.

If count is not equal to the current number of channels in the audio stream's format, this will fail. This is a safety measure to make sure a race condition hasn't changed the format while this call is setting the channel map.

Unlike attempting to change the stream's format, the output channel map on a stream bound to a recording device is permitted to change at any time; any data added to the stream after this call will have the new mapping, but previously-added data will still have the prior mapping. When the channel map doesn't match the hardware's channel layout, SDL will convert the data before feeding it to the device for playback.

Returns

true on success or false on failure; call getError for more information.

Thread safety

It is safe to call this function from any thread, as it holds a stream-specific mutex while running. Don't change the stream's format to have a different number of channels from a a different thread at the same time, though!

See also

setAudioStreamInputChannelMap

sdl3-bindgen-sys notes

Since: 3.2.0

Set the current output channel map of an audio stream.

Channel maps are optional; most things do not need them, instead passing data in the order that SDL expects.

The output channel map reorders data that is leaving a stream via getAudioStreamData.

Each item in the array represents an input channel, and its value is the channel that it should be remapped to. To reverse a stereo signal's left and right values, you'd have an array of { 1, 0 }. It is legal to remap multiple channels to the same thing, so { 1, 1 } would duplicate the right channel to both channels of a stereo signal. An element in the channel map set to -1 instead of a valid channel will mute that channel, setting it to a silence value.

You cannot change the number of channels through a channel map, just reorder/mute them.

The output channel map can be changed at any time, as output remapping is applied during getAudioStreamData.

Audio streams default to no remapping applied. Passing a NULL channel map is legal, and turns off remapping.

SDL will copy the channel map; the caller does not have to save this array after this call.

If count is not equal to the current number of channels in the audio stream's format, this will fail. This is a safety measure to make sure a race condition hasn't changed the format while this call is setting the channel map.

Unlike attempting to change the stream's format, the output channel map on a stream bound to a recording device is permitted to change at any time; any data added to the stream after this call will have the new mapping, but previously-added data will still have the prior mapping. When the channel map doesn't match the hardware's channel layout, SDL will convert the data before feeding it to the device for playback.

Returns

true on success or false on failure; call getError for more information.

Thread safety

It is safe to call this function from any thread, as it holds a stream-specific mutex while running. Don't change the stream's format to have a different number of channels from a a different thread at the same time, though!

See also

setAudioStreamInputChannelMap

sdl3-bindgen-sys notes

Since: 3.2.0

Add data to the stream.

This data must match the format/channels/samplerate specified in the latest call to setAudioStreamFormat, or the format specified when creating the stream if it hasn't been changed.

Note that this call simply copies the unconverted data for later. This is different than SDL2, where data was converted during the Put call and the Get call would just dequeue the previously-converted data.

Returns

true on success or false on failure; call getError for more information.

Thread safety

It is safe to call this function from any thread, but if the stream has a callback set, the caller might need to manage extra locking.

See also

clearAudioStream, flushAudioStream, getAudioStreamData, getAudioStreamQueued

sdl3-bindgen-sys notes

Since: 3.2.0

Add data to the stream.

This data must match the format/channels/samplerate specified in the latest call to setAudioStreamFormat, or the format specified when creating the stream if it hasn't been changed.

Note that this call simply copies the unconverted data for later. This is different than SDL2, where data was converted during the Put call and the Get call would just dequeue the previously-converted data.

Returns

true on success or false on failure; call getError for more information.

Thread safety

It is safe to call this function from any thread, but if the stream has a callback set, the caller might need to manage extra locking.

See also

clearAudioStream, flushAudioStream, getAudioStreamData, getAudioStreamQueued

sdl3-bindgen-sys notes

Since: 3.2.0

Add external data to an audio stream without copying it.

Unlike putAudioStreamData, this function does not make a copy of the provided data, instead storing the provided pointer. This means that the put operation does not need to allocate and copy the data, but the original data must remain available until the stream is done with it, either by being read from the stream in its entirety, or a call to clearAudioStream or destroyAudioStream.

The data must match the format/channels/samplerate specified in the latest call to setAudioStreamFormat, or the format specified when creating the stream if it hasn't been changed.

An optional callback may be provided, which is called when the stream no longer needs the data. Once this callback fires, the stream will not access the data again. This callback will fire for any reason the data is no longer needed, including clearing or destroying the stream.

Note that there is still an allocation to store tracking information, so this function is more efficient for larger blocks of data. If you're planning to put a few samples at a time, it will be more efficient to use putAudioStreamData, which allocates and buffers in blocks.

Returns

true on success or false on failure; call getError for more information.

Thread safety

It is safe to call this function from any thread, but if the stream has a callback set, the caller might need to manage extra locking.

See also

clearAudioStream, flushAudioStream, getAudioStreamData, getAudioStreamQueued

sdl3-bindgen-sys notes

Since: 3.4.0

Add external data to an audio stream without copying it.

Unlike putAudioStreamData, this function does not make a copy of the provided data, instead storing the provided pointer. This means that the put operation does not need to allocate and copy the data, but the original data must remain available until the stream is done with it, either by being read from the stream in its entirety, or a call to clearAudioStream or destroyAudioStream.

The data must match the format/channels/samplerate specified in the latest call to setAudioStreamFormat, or the format specified when creating the stream if it hasn't been changed.

An optional callback may be provided, which is called when the stream no longer needs the data. Once this callback fires, the stream will not access the data again. This callback will fire for any reason the data is no longer needed, including clearing or destroying the stream.

Note that there is still an allocation to store tracking information, so this function is more efficient for larger blocks of data. If you're planning to put a few samples at a time, it will be more efficient to use putAudioStreamData, which allocates and buffers in blocks.

Returns

true on success or false on failure; call getError for more information.

Thread safety

It is safe to call this function from any thread, but if the stream has a callback set, the caller might need to manage extra locking.

See also

clearAudioStream, flushAudioStream, getAudioStreamData, getAudioStreamQueued

sdl3-bindgen-sys notes

Since: 3.4.0

Add data to the stream with each channel in a separate array.

This data must match the format/channels/samplerate specified in the latest call to setAudioStreamFormat, or the format specified when creating the stream if it hasn't been changed.

The data will be interleaved and queued. Note that SDL_AudioStream only operates on interleaved data, so this is simply a convenience function for easily queueing data from sources that provide separate arrays. There is no equivalent function to retrieve planar data.

The arrays in channel_buffers are ordered as they are to be interleaved; the first array will be the first sample in the interleaved data. Any individual array may be NULL; in this case, silence will be interleaved for that channel.

num_channels specifies how many arrays are in channel_buffers. This can be used as a safety to prevent overflow, in case the stream format has changed elsewhere. If more channels are specified than the current input spec, they are ignored. If less channels are specified, the missing arrays are treated as if they are NULL (silence is written to those channels). If the count is -1, SDL will assume the array count matches the current input spec.

Note that num_samples is the number of samples per array. This can also be thought of as the number of sample frames to be queued. A value of 1 with stereo arrays will queue two samples to the stream. This is different than putAudioStreamData, which wants the size of a single array in bytes.

Returns

true on success or false on failure; call getError for more information.

Thread safety

It is safe to call this function from any thread, but if the stream has a callback set, the caller might need to manage extra locking.

See also

clearAudioStream, flushAudioStream, getAudioStreamData, getAudioStreamQueued

sdl3-bindgen-sys notes

Since: 3.4.0

Add data to the stream with each channel in a separate array.

This data must match the format/channels/samplerate specified in the latest call to setAudioStreamFormat, or the format specified when creating the stream if it hasn't been changed.

The data will be interleaved and queued. Note that SDL_AudioStream only operates on interleaved data, so this is simply a convenience function for easily queueing data from sources that provide separate arrays. There is no equivalent function to retrieve planar data.

The arrays in channel_buffers are ordered as they are to be interleaved; the first array will be the first sample in the interleaved data. Any individual array may be NULL; in this case, silence will be interleaved for that channel.

num_channels specifies how many arrays are in channel_buffers. This can be used as a safety to prevent overflow, in case the stream format has changed elsewhere. If more channels are specified than the current input spec, they are ignored. If less channels are specified, the missing arrays are treated as if they are NULL (silence is written to those channels). If the count is -1, SDL will assume the array count matches the current input spec.

Note that num_samples is the number of samples per array. This can also be thought of as the number of sample frames to be queued. A value of 1 with stereo arrays will queue two samples to the stream. This is different than putAudioStreamData, which wants the size of a single array in bytes.

Returns

true on success or false on failure; call getError for more information.

Thread safety

It is safe to call this function from any thread, but if the stream has a callback set, the caller might need to manage extra locking.

See also

clearAudioStream, flushAudioStream, getAudioStreamData, getAudioStreamQueued

sdl3-bindgen-sys notes

Since: 3.4.0

Get converted/resampled data from the stream.

The input/output data format/channels/samplerate is specified when creating the stream, and can be changed after creation by calling setAudioStreamFormat.

Note that any conversion and resampling necessary is done during this call, and putAudioStreamData simply queues unconverted data for later. This is different than SDL2, where that work was done while inputting new data to the stream and requesting the output just copied the converted data.

Returns

the number of bytes read from the stream or -1 on failure; call getError for more information.

Thread safety

It is safe to call this function from any thread, but if the stream has a callback set, the caller might need to manage extra locking.

See also

clearAudioStream, getAudioStreamAvailable, putAudioStreamData

sdl3-bindgen-sys notes

Since: 3.2.0

Get converted/resampled data from the stream.

The input/output data format/channels/samplerate is specified when creating the stream, and can be changed after creation by calling setAudioStreamFormat.

Note that any conversion and resampling necessary is done during this call, and putAudioStreamData simply queues unconverted data for later. This is different than SDL2, where that work was done while inputting new data to the stream and requesting the output just copied the converted data.

Returns

the number of bytes read from the stream or -1 on failure; call getError for more information.

Thread safety

It is safe to call this function from any thread, but if the stream has a callback set, the caller might need to manage extra locking.

See also

clearAudioStream, getAudioStreamAvailable, putAudioStreamData

sdl3-bindgen-sys notes

Since: 3.2.0

Get the number of converted/resampled bytes available.

The stream may be buffering data behind the scenes until it has enough to resample correctly, so this number might be lower than what you expect, or even be zero. Add more data or flush the stream if you need the data now.

If the stream has so much data that it would overflow an int, the return value is clamped to a maximum value, but no queued data is lost; if there are gigabytes of data queued, the app might need to read some of it with getAudioStreamData before this function's return value is no longer clamped.

Returns

the number of converted/resampled bytes available or -1 on failure; call getError for more information.

Thread safety

It is safe to call this function from any thread.

See also

getAudioStreamData, putAudioStreamData

sdl3-bindgen-sys notes

Since: 3.2.0

Get the number of converted/resampled bytes available.

The stream may be buffering data behind the scenes until it has enough to resample correctly, so this number might be lower than what you expect, or even be zero. Add more data or flush the stream if you need the data now.

If the stream has so much data that it would overflow an int, the return value is clamped to a maximum value, but no queued data is lost; if there are gigabytes of data queued, the app might need to read some of it with getAudioStreamData before this function's return value is no longer clamped.

Returns

the number of converted/resampled bytes available or -1 on failure; call getError for more information.

Thread safety

It is safe to call this function from any thread.

See also

getAudioStreamData, putAudioStreamData

sdl3-bindgen-sys notes

Since: 3.2.0

Get the number of bytes currently queued.

This is the number of bytes put into a stream as input, not the number that can be retrieved as output. Because of several details, it's not possible to calculate one number directly from the other. If you need to know how much usable data can be retrieved right now, you should use getAudioStreamAvailable and not this function.

Note that audio streams can change their input format at any time, even if there is still data queued in a different format, so the returned byte count will not necessarily match the number of sample frames available. Users of this API should be aware of format changes they make when feeding a stream and plan accordingly.

Queued data is not converted until it is consumed by getAudioStreamData, so this value should be representative of the exact data that was put into the stream.

If the stream has so much data that it would overflow an int, the return value is clamped to a maximum value, but no queued data is lost; if there are gigabytes of data queued, the app might need to read some of it with getAudioStreamData before this function's return value is no longer clamped.

Returns

the number of bytes queued or -1 on failure; call getError for more information.

Thread safety

It is safe to call this function from any thread.

See also

putAudioStreamData, clearAudioStream

sdl3-bindgen-sys notes

Since: 3.2.0

Get the number of bytes currently queued.

This is the number of bytes put into a stream as input, not the number that can be retrieved as output. Because of several details, it's not possible to calculate one number directly from the other. If you need to know how much usable data can be retrieved right now, you should use getAudioStreamAvailable and not this function.

Note that audio streams can change their input format at any time, even if there is still data queued in a different format, so the returned byte count will not necessarily match the number of sample frames available. Users of this API should be aware of format changes they make when feeding a stream and plan accordingly.

Queued data is not converted until it is consumed by getAudioStreamData, so this value should be representative of the exact data that was put into the stream.

If the stream has so much data that it would overflow an int, the return value is clamped to a maximum value, but no queued data is lost; if there are gigabytes of data queued, the app might need to read some of it with getAudioStreamData before this function's return value is no longer clamped.

Returns

the number of bytes queued or -1 on failure; call getError for more information.

Thread safety

It is safe to call this function from any thread.

See also

putAudioStreamData, clearAudioStream

sdl3-bindgen-sys notes

Since: 3.2.0

Tell the stream that you're done sending data, and anything being buffered should be converted/resampled and made available immediately.

It is legal to add more data to a stream after flushing, but there may be audio gaps in the output. Generally this is intended to signal the end of input, so the complete output becomes available.

Returns

true on success or false on failure; call getError for more information.

Thread safety

It is safe to call this function from any thread.

See also

putAudioStreamData

sdl3-bindgen-sys notes

Since: 3.2.0

Tell the stream that you're done sending data, and anything being buffered should be converted/resampled and made available immediately.

It is legal to add more data to a stream after flushing, but there may be audio gaps in the output. Generally this is intended to signal the end of input, so the complete output becomes available.

Returns

true on success or false on failure; call getError for more information.

Thread safety

It is safe to call this function from any thread.

See also

putAudioStreamData

sdl3-bindgen-sys notes

Since: 3.2.0

Clear any pending data in the stream.

This drops any queued data, so there will be nothing to read from the stream until more is added.

Returns

true on success or false on failure; call getError for more information.

Thread safety

It is safe to call this function from any thread.

See also

getAudioStreamAvailable, getAudioStreamData, getAudioStreamQueued, putAudioStreamData

sdl3-bindgen-sys notes

Since: 3.2.0

Clear any pending data in the stream.

This drops any queued data, so there will be nothing to read from the stream until more is added.

Returns

true on success or false on failure; call getError for more information.

Thread safety

It is safe to call this function from any thread.

See also

getAudioStreamAvailable, getAudioStreamData, getAudioStreamQueued, putAudioStreamData

sdl3-bindgen-sys notes

Since: 3.2.0

Use this function to pause audio playback on the audio device associated with an audio stream.

This function pauses audio processing for a given 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.

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.

Returns

true on success or false on failure; call getError for more information.

Thread safety

It is safe to call this function from any thread.

See also

resumeAudioStreamDevice

sdl3-bindgen-sys notes

Since: 3.2.0

Use this function to pause audio playback on the audio device associated with an audio stream.

This function pauses audio processing for a given 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.

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.

Returns

true on success or false on failure; call getError for more information.

Thread safety

It is safe to call this function from any thread.

See also

resumeAudioStreamDevice

sdl3-bindgen-sys notes

Since: 3.2.0

Use this function to unpause audio playback on the audio device associated with an audio stream.

This function unpauses audio processing for a given device that has previously been paused. Once unpaused, any bound audio streams will begin to progress again, and audio can be generated.

openAudioDeviceStream opens audio devices in a paused state, so this function call is required for audio playback to begin on such devices.

Returns

true on success or false on failure; call getError for more information.

Thread safety

It is safe to call this function from any thread.

See also

pauseAudioStreamDevice

sdl3-bindgen-sys notes

Since: 3.2.0

Use this function to unpause audio playback on the audio device associated with an audio stream.

This function unpauses audio processing for a given device that has previously been paused. Once unpaused, any bound audio streams will begin to progress again, and audio can be generated.

openAudioDeviceStream opens audio devices in a paused state, so this function call is required for audio playback to begin on such devices.

Returns

true on success or false on failure; call getError for more information.

Thread safety

It is safe to call this function from any thread.

See also

pauseAudioStreamDevice

sdl3-bindgen-sys notes

Since: 3.2.0

Use this function to query if an audio device associated with a stream 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.

Returns

true if device is valid and paused, false otherwise.

Thread safety

It is safe to call this function from any thread.

See also

pauseAudioStreamDevice, resumeAudioStreamDevice

sdl3-bindgen-sys notes

Since: 3.2.0

Use this function to query if an audio device associated with a stream 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.

Returns

true if device is valid and paused, false otherwise.

Thread safety

It is safe to call this function from any thread.

See also

pauseAudioStreamDevice, resumeAudioStreamDevice

sdl3-bindgen-sys notes

Since: 3.2.0

Lock an audio stream for serialized access.

Each SDL_AudioStream has an internal mutex it uses to protect its data structures from threading conflicts. This function allows an app to lock that mutex, which could be useful if registering callbacks on this stream.

One does not need to lock a stream to use in it most cases, as the stream manages this lock internally. However, this lock is held during callbacks, which may run from arbitrary threads at any time, so if an app needs to protect shared data during those callbacks, locking the stream guarantees that the callback is not running while the lock is held.

As this is just a wrapper over lockMutex for an internal lock; it has all the same attributes (recursive locks are allowed, etc).

Returns

true on success or false on failure; call getError for more information.

Thread safety

It is safe to call this function from any thread.

See also

unlockAudioStream

sdl3-bindgen-sys notes

Since: 3.2.0

Lock an audio stream for serialized access.

Each SDL_AudioStream has an internal mutex it uses to protect its data structures from threading conflicts. This function allows an app to lock that mutex, which could be useful if registering callbacks on this stream.

One does not need to lock a stream to use in it most cases, as the stream manages this lock internally. However, this lock is held during callbacks, which may run from arbitrary threads at any time, so if an app needs to protect shared data during those callbacks, locking the stream guarantees that the callback is not running while the lock is held.

As this is just a wrapper over lockMutex for an internal lock; it has all the same attributes (recursive locks are allowed, etc).

Returns

true on success or false on failure; call getError for more information.

Thread safety

It is safe to call this function from any thread.

See also

unlockAudioStream

sdl3-bindgen-sys notes

Since: 3.2.0

Unlock an audio stream for serialized access.

This unlocks an audio stream after a call to lockAudioStream.

Returns

true on success or false on failure; call getError for more information.

Thread safety

You should only call this from the same thread that previously called lockAudioStream.

See also

lockAudioStream

sdl3-bindgen-sys notes

Since: 3.2.0

Unlock an audio stream for serialized access.

This unlocks an audio stream after a call to lockAudioStream.

Returns

true on success or false on failure; call getError for more information.

Thread safety

You should only call this from the same thread that previously called lockAudioStream.

See also

lockAudioStream

sdl3-bindgen-sys notes

Since: 3.2.0

Set a callback that runs when data is requested from an audio stream.

This callback is called before data is obtained from the stream, giving the callback the chance to add more on-demand.

The callback can (optionally) call putAudioStreamData to add more audio to the stream during this call; if needed, the request that triggered this callback will obtain the new data immediately.

The callback's additional_amount argument is roughly how many bytes of unconverted data (in the stream's input format) is needed by the caller, although this may overestimate a little for safety. This takes into account how much is already in the stream and only asks for any extra necessary to resolve the request, which means the callback may be asked for zero bytes, and a different amount on each call.

The callback is not required to supply exact amounts; it is allowed to supply too much or too little or none at all. The caller will get what's available, up to the amount they requested, regardless of this callback's outcome.

Clearing or flushing an audio stream does not call this callback.

This function obtains the stream's lock, which means any existing callback (get or put) in progress will finish running before setting the new callback.

Setting a NULL function turns off the callback.

Returns

true on success or false on failure; call getError for more information. This only fails if stream is NULL.

Thread safety

It is safe to call this function from any thread.

See also

setAudioStreamPutCallback

sdl3-bindgen-sys notes

Since: 3.2.0

Set a callback that runs when data is requested from an audio stream.

This callback is called before data is obtained from the stream, giving the callback the chance to add more on-demand.

The callback can (optionally) call putAudioStreamData to add more audio to the stream during this call; if needed, the request that triggered this callback will obtain the new data immediately.

The callback's additional_amount argument is roughly how many bytes of unconverted data (in the stream's input format) is needed by the caller, although this may overestimate a little for safety. This takes into account how much is already in the stream and only asks for any extra necessary to resolve the request, which means the callback may be asked for zero bytes, and a different amount on each call.

The callback is not required to supply exact amounts; it is allowed to supply too much or too little or none at all. The caller will get what's available, up to the amount they requested, regardless of this callback's outcome.

Clearing or flushing an audio stream does not call this callback.

This function obtains the stream's lock, which means any existing callback (get or put) in progress will finish running before setting the new callback.

Setting a NULL function turns off the callback.

Returns

true on success or false on failure; call getError for more information. This only fails if stream is NULL.

Thread safety

It is safe to call this function from any thread.

See also

setAudioStreamPutCallback

sdl3-bindgen-sys notes

Since: 3.2.0

Set a callback that runs when data is added to an audio stream.

This callback is called after the data is added to the stream, giving the callback the chance to obtain it immediately.

The callback can (optionally) call getAudioStreamData to obtain audio from the stream during this call.

The callback's additional_amount argument is how many bytes of converted data (in the stream's output format) was provided by the caller, although this may underestimate a little for safety. This value might be less than what is currently available in the stream, if data was already there, and might be less than the caller provided if the stream needs to keep a buffer to aid in resampling. Which means the callback may be provided with zero bytes, and a different amount on each call.

The callback may call getAudioStreamAvailable to see the total amount currently available to read from the stream, instead of the total provided by the current call.

The callback is not required to obtain all data. It is allowed to read less or none at all. Anything not read now simply remains in the stream for later access.

Clearing or flushing an audio stream does not call this callback.

This function obtains the stream's lock, which means any existing callback (get or put) in progress will finish running before setting the new callback.

Setting a NULL function turns off the callback.

Returns

true on success or false on failure; call getError for more information. This only fails if stream is NULL.

Thread safety

It is safe to call this function from any thread.

See also

setAudioStreamGetCallback

sdl3-bindgen-sys notes

Since: 3.2.0

Set a callback that runs when data is added to an audio stream.

This callback is called after the data is added to the stream, giving the callback the chance to obtain it immediately.

The callback can (optionally) call getAudioStreamData to obtain audio from the stream during this call.

The callback's additional_amount argument is how many bytes of converted data (in the stream's output format) was provided by the caller, although this may underestimate a little for safety. This value might be less than what is currently available in the stream, if data was already there, and might be less than the caller provided if the stream needs to keep a buffer to aid in resampling. Which means the callback may be provided with zero bytes, and a different amount on each call.

The callback may call getAudioStreamAvailable to see the total amount currently available to read from the stream, instead of the total provided by the current call.

The callback is not required to obtain all data. It is allowed to read less or none at all. Anything not read now simply remains in the stream for later access.

Clearing or flushing an audio stream does not call this callback.

This function obtains the stream's lock, which means any existing callback (get or put) in progress will finish running before setting the new callback.

Setting a NULL function turns off the callback.

Returns

true on success or false on failure; call getError for more information. This only fails if stream is NULL.

Thread safety

It is safe to call this function from any thread.

See also

setAudioStreamGetCallback

sdl3-bindgen-sys notes

Since: 3.2.0

Free an audio stream.

This will release all allocated data, including any audio that is still queued. You do not need to manually clear the stream first.

If this stream was bound to an audio device, it is unbound during this call. If this stream was created with openAudioDeviceStream, the audio device that was opened alongside this stream's creation will be closed, too.

Thread safety

It is safe to call this function from any thread.

See also

createAudioStream

sdl3-bindgen-sys notes

Since: 3.2.0

Free an audio stream.

This will release all allocated data, including any audio that is still queued. You do not need to manually clear the stream first.

If this stream was bound to an audio device, it is unbound during this call. If this stream was created with openAudioDeviceStream, the audio device that was opened alongside this stream's creation will be closed, too.

Thread safety

It is safe to call this function from any thread.

See also

createAudioStream

sdl3-bindgen-sys notes

Since: 3.2.0

Convenience function for straightforward audio init for the common case.

If all your app intends to do is provide a single source of PCM audio, this function allows you to do all your audio setup in a single call.

This is also intended to be a clean means to migrate apps from SDL2.

This function will open an audio device, create a stream and bind it. Unlike other methods of setup, the audio device will be closed when this stream is destroyed, so the app can treat the returned SDL_AudioStream as the only object needed to manage audio playback.

Also unlike other functions, the audio device begins paused. This is to map more closely to SDL2-style behavior, since there is no extra step here to bind a stream to begin audio flowing. The audio device should be resumed with resumeAudioStreamDevice.

This function works with both playback and recording devices.

The spec parameter represents the app's side of the audio stream. That is, for recording audio, this will be the output format, and for playing audio, this will be the input format. If spec is NULL, the system will choose the format, and the app can use getAudioStreamFormat to obtain this information later.

If you don't care about opening a specific audio device, you can (and probably should), use SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK for playback and SDL_AUDIO_DEVICE_DEFAULT_RECORDING for recording.

One can optionally provide a callback function; if NULL, the app is expected to queue audio data for playback (or unqueue audio data if capturing). Otherwise, the callback will begin to fire once the device is unpaused.

Destroying the returned stream with destroyAudioStream will also close the audio device associated with this stream.

Returns

an audio stream on success, ready to use, or NULL on failure; call getError for more information. When done with this stream, call destroyAudioStream to free resources and close the device.

Thread safety

It is safe to call this function from any thread.

See also

getAudioStreamDevice, resumeAudioStreamDevice

sdl3-bindgen-sys notes

Since: 3.2.0

Convenience function for straightforward audio init for the common case.

If all your app intends to do is provide a single source of PCM audio, this function allows you to do all your audio setup in a single call.

This is also intended to be a clean means to migrate apps from SDL2.

This function will open an audio device, create a stream and bind it. Unlike other methods of setup, the audio device will be closed when this stream is destroyed, so the app can treat the returned SDL_AudioStream as the only object needed to manage audio playback.

Also unlike other functions, the audio device begins paused. This is to map more closely to SDL2-style behavior, since there is no extra step here to bind a stream to begin audio flowing. The audio device should be resumed with resumeAudioStreamDevice.

This function works with both playback and recording devices.

The spec parameter represents the app's side of the audio stream. That is, for recording audio, this will be the output format, and for playing audio, this will be the input format. If spec is NULL, the system will choose the format, and the app can use getAudioStreamFormat to obtain this information later.

If you don't care about opening a specific audio device, you can (and probably should), use SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK for playback and SDL_AUDIO_DEVICE_DEFAULT_RECORDING for recording.

One can optionally provide a callback function; if NULL, the app is expected to queue audio data for playback (or unqueue audio data if capturing). Otherwise, the callback will begin to fire once the device is unpaused.

Destroying the returned stream with destroyAudioStream will also close the audio device associated with this stream.

Returns

an audio stream on success, ready to use, or NULL on failure; call getError for more information. When done with this stream, call destroyAudioStream to free resources and close the device.

Thread safety

It is safe to call this function from any thread.

See also

getAudioStreamDevice, resumeAudioStreamDevice

sdl3-bindgen-sys notes

Since: 3.2.0