Handle to an owned audioStream. More...

Inheritance diagram for SDL::AudioStream:

[legend]

Public Member Functions
void	Destroy ()
	Free an audio stream.

AudioStreamShared	share ()
	Move this audioStream into a AudioStreamShared.

constexpr	ResourceUnique (std::nullptr_t=nullptr)
	Default constructor.

constexpr	ResourceUnique (base::value_type value, DELETER deleter={})
	Constructs from raw type.

constexpr	ResourceUnique (ResourceUnique &&other)
	Move constructor.

	ResourceUnique (const ResourceUnique &other)=delete

Public Member Functions inherited from SDL::ResourceUnique< AudioStreamRef >
constexpr	ResourceUnique (std::nullptr_t=nullptr)
	Default constructor.

constexpr	ResourceUnique (base::value_type value, DefaultDeleter< AudioStreamRef > deleter={})
	Constructs from raw type.

constexpr	ResourceUnique (ResourceUnique &&other)
	Move constructor.

	ResourceUnique (const ResourceUnique &other)=delete

	~ResourceUnique ()
	Destructor.

constexpr ResourceUnique &	operator= (ResourceUnique other)
	Assignment operator.

void	reset ()
	Resets the value, destroying the resource if not nullptr.

Public Member Functions inherited from SDL::ResourceOwnerBase< RESOURCE, DELETER >
RESOURCE	release ()
	Returns reference and reset this.

Public Member Functions inherited from SDL::ResourcePtrBase< RESOURCE >
constexpr	operator bool () const
	Check if not null.

constexpr bool	operator== (const ResourcePtrBase &other) const
	Comparison.

constexpr bool	operator== (std::nullptr_t) const
	Comparison.

constexpr bool	operator== (std::nullopt_t) const
	Comparison.

constexpr reference	operator* () const
	Gets reference.

constexpr const reference *	operator-> () const
	Gets addressable reference.

constexpr reference *	operator-> ()
	Gets addressable reference.

reference	get () const
	Get reference.

Static Public Member Functions
static AudioStream	Create (OptionalRef< const AudioSpec > src_spec, OptionalRef< const AudioSpec > dst_spec)
	Create a new audio stream.

static AudioStream	OpenAudioDeviceStream (AudioDeviceRef devid, OptionalRef< const AudioSpec > spec, AudioStreamCB callback)
	Convenience function for straightforward audio init for the common case.

static AudioStream	OpenAudioDeviceStream (AudioDeviceRef devid, OptionalRef< const AudioSpec > spec=std::nullopt, AudioStreamCallback callback=nullptr, void *userdata=nullptr)
	Convenience function for straightforward audio init for the common case.

Additional Inherited Members
Public Types inherited from SDL::ResourceOwnerBase< RESOURCE, DELETER >
using	deleter = DELETER
	The deleter type.

Public Types inherited from SDL::ResourcePtrBase< RESOURCE >
using	reference = RESOURCE
	The reference resource type.

using	value_type = typename reference::value_type
	The raw resource type.

Protected Member Functions inherited from SDL::ResourceOwnerBase< RESOURCE, DELETER >
constexpr	ResourceOwnerBase (base::value_type value={}, DELETER deleter={})
	Constructs from raw type.

void	free ()
	Frees resource.

Protected Member Functions inherited from SDL::ResourcePtrBase< RESOURCE >
constexpr	ResourcePtrBase (value_type value={})
	Constructs from raw type.

reference &	get ()
	Get reference.

Detailed Description

Category:: Resource

See also: AudioStreamRef

Member Function Documentation

◆ Create()

static AudioStream SDL::AudioStream::Create	(	OptionalRef< const AudioSpec >	src_spec,
		OptionalRef< const AudioSpec >	dst_spec
	)

inlinestatic

Parameters

src_spec	the format details of the input audio.
dst_spec	the format details of the output audio.

Returns: a new audio stream on success.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: AudioStreamRef.PutData; AudioStreamRef.GetData; AudioStreamRef.GetAvailable; AudioStreamRef.Flush; AudioStreamRef.Clear; AudioStreamRef.SetFormat; AudioStream.Destroy

◆ Destroy()

void SDL::AudioStream::Destroy ( )

inline

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 AudioStream.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.

Since: This function is available since SDL 3.2.0.

See also: AudioStream.Create

◆ OpenAudioDeviceStream() [1/2]

static AudioStream SDL::AudioStream::OpenAudioDeviceStream	(	AudioDeviceRef	devid,
		OptionalRef< const AudioSpec >	spec,
		AudioStreamCB	callback
	)

inlinestatic

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 AudioStreamRef 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 AudioStreamRef.ResumeDevice(stream);

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 nullptr, the system will choose the format, and the app can use AudioStreamRef.GetFormat() to obtain this information later.

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

One can optionally provide a callback function; if nullptr, 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 AudioStream.Destroy will also close the audio device associated with this stream.

Parameters

devid	an audio device to open, or AUDIO_DEVICE_DEFAULT_PLAYBACK or AUDIO_DEVICE_DEFAULT_RECORDING.
spec	the audio stream's data format. Can be std::nullopt.
callback	a callback where the app will provide new data for playback, or receive new data for recording. Can be nullptr, in which case the app will need to call AudioStreamRef.PutData or AudioStreamRef.GetData as necessary.

Returns: an audio stream on success.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: AudioStreamRef.GetDevice; AudioStreamRef.ResumeDevice

◆ OpenAudioDeviceStream() [2/2]

static AudioStream SDL::AudioStream::OpenAudioDeviceStream	(	AudioDeviceRef	devid,
		OptionalRef< const AudioSpec >	spec = `std::nullopt`,
		AudioStreamCallback	callback = `nullptr`,
		void *	userdata = `nullptr`
	)

inlinestatic

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 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 AudioStreamRef.ResumeDevice(stream);

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 nullptr, the system will choose the format, and the app can use AudioStreamRef.GetFormat() to obtain this information later.

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

One can optionally provide a callback function; if nullptr, 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 AudioStream.Destroy will also close the audio device associated with this stream.

Parameters

devid	an audio device to open, or AUDIO_DEVICE_DEFAULT_PLAYBACK or AUDIO_DEVICE_DEFAULT_RECORDING.
spec	the audio stream's data format. Can be std::nullopt.
callback	a callback where the app will provide new data for playback, or receive new data for recording. Can be nullptr, in which case the app will need to call AudioStreamRef.PutData or AudioStreamRef.GetData as necessary.
userdata	app-controlled pointer passed to callback. Can be nullptr. Ignored if callback is nullptr.

Returns: an audio stream on success.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: AudioStreamRef.GetDevice; AudioStreamRef.ResumeDevice

The documentation for this struct was generated from the following file:

SDL3pp/SDL3pp_audio.h

Public Member Functions

Static Public Member Functions

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ Create()

◆ Destroy()

◆ OpenAudioDeviceStream() [1/2]

◆ OpenAudioDeviceStream() [2/2]