Inheritance diagram for SDL::AudioRef:

Collaboration diagram for SDL::AudioRef:

Public Member Functions
constexpr	AudioRef (AudioRaw resource) noexcept
	Constructs from raw Audio. More...

constexpr	AudioRef (const Audio &resource) noexcept
	Constructs from Audio. More...

constexpr	AudioRef (Audio &&resource) noexcept
	Constructs from Audio. More...

constexpr	AudioRef (const AudioRef &other) noexcept
	Copy constructor.

constexpr	AudioRef (AudioRef &&other) noexcept
	Move constructor.

	~AudioRef ()
	Destructor.

AudioRef &	operator= (const AudioRef &other) noexcept
	Assignment operator.

constexpr	operator AudioRaw () const noexcept
	Converts to AudioRaw.

constexpr	Audio (std::nullptr_t=nullptr) noexcept
	Default ctor.

constexpr	Audio (AudioRaw resource) noexcept
	Constructs from raw Audio. More...

constexpr	Audio (const Audio &other) noexcept=delete
	Copy constructor.

constexpr	Audio (Audio &&other) noexcept
	Move constructor.

constexpr	Audio (const AudioRef &other)=delete

constexpr	Audio (AudioRef &&other)=delete

	Audio (MixerRef mixer, IOStreamRef io, bool predecode, bool closeio=false)
	Load audio for playback from an IOStream. More...

	Audio (MixerRef mixer, StringParam path, bool predecode)
	Load audio for playback from a file. More...

	Audio (PropertiesRef props)
	Load audio for playback through a collection of properties. More...

	Audio (MixerRef mixer, IOStreamRef io, const AudioSpec &spec, bool closeio=false)
	Load raw PCM data from an IOStream. More...

	Audio (MixerRef mixer, SourceBytes data, const AudioSpec &spec)
	Load raw PCM data from a memory buffer. More...

Public Member Functions inherited from SDL::Audio
constexpr	Audio (std::nullptr_t=nullptr) noexcept
	Default ctor.

constexpr	Audio (AudioRaw resource) noexcept
	Constructs from raw Audio. More...

constexpr	Audio (const Audio &other) noexcept=delete
	Copy constructor.

constexpr	Audio (Audio &&other) noexcept
	Move constructor.

constexpr	Audio (const AudioRef &other)=delete

constexpr	Audio (AudioRef &&other)=delete

	Audio (MixerRef mixer, IOStreamRef io, bool predecode, bool closeio=false)
	Load audio for playback from an IOStream. More...

	Audio (MixerRef mixer, StringParam path, bool predecode)
	Load audio for playback from a file. More...

	Audio (PropertiesRef props)
	Load audio for playback through a collection of properties. More...

	Audio (MixerRef mixer, IOStreamRef io, const AudioSpec &spec, bool closeio=false)
	Load raw PCM data from an IOStream. More...

	Audio (MixerRef mixer, SourceBytes data, const AudioSpec &spec)
	Load raw PCM data from a memory buffer. More...

	~Audio ()
	Destructor.

constexpr Audio &	operator= (Audio &&other) noexcept
	Assignment operator.

Audio &	operator= (const Audio &other)=delete
	Assignment operator.

constexpr AudioRaw	get () const noexcept
	Retrieves underlying AudioRaw.

constexpr AudioRaw	release () noexcept
	Retrieves underlying AudioRaw and clear this.

constexpr auto	operator<=> (const Audio &other) const noexcept=default
	Comparison.

constexpr	operator bool () const noexcept
	Converts to bool.

void	Destroy ()
	Destroy the specified audio. More...

PropertiesRef	GetProperties ()
	Get the properties associated with a Audio. More...

Sint64	GetDuration ()
	Get the length of a Audio's playback in sample frames. More...

void	GetFormat (AudioSpec *spec)
	Query the initial audio format of a Audio. More...

Sint64	MSToFrames (Milliseconds ms)
	Convert milliseconds to sample frames for a Audio's format. More...

Milliseconds	FramesToMS (Sint64 frames)
	Convert sample frames for a Audio's format to milliseconds. More...

Detailed Description

This does not take ownership!

Constructor & Destructor Documentation

◆ AudioRef() [1/3]

constexpr SDL::AudioRef::AudioRef ( AudioRaw resource )

inlineconstexprnoexcept

Parameters

resource a AudioRaw.

This does not takes ownership!

◆ AudioRef() [2/3]

constexpr SDL::AudioRef::AudioRef ( const Audio & resource )

inlineconstexprnoexcept

Parameters

resource a Audio.

This does not takes ownership!

◆ AudioRef() [3/3]

constexpr SDL::AudioRef::AudioRef ( Audio && resource )

inlineconstexprnoexcept

Parameters

resource a Audio.

This will release the ownership from resource!

Member Function Documentation

◆ Audio() [1/6]

constexpr SDL::Audio::Audio ( AudioRaw resource )

inlineexplicitconstexprnoexcept

Parameters

resource a AudioRaw to be wrapped.

This assumes the ownership, call release() if you need to take back.

◆ Audio() [2/6]

SDL::Audio::Audio	(	MixerRef	mixer,
		IOStreamRef	io,
		bool	predecode,
		bool	closeio = `false`
	)

inline

In normal usage, apps should load audio once, maybe at startup, then play it multiple times.

When loading audio, it will be cached fully in RAM in its original data format. Each time it plays, the data will be decoded. For example, an MP3 will be stored in memory in MP3 format and be decompressed on the fly during playback. This is a tradeoff between i/o overhead and memory usage.

If predecode is true, the data will be decompressed during load and stored as raw PCM data. This might dramatically increase loading time and memory usage, but there will be no need to decompress data during playback.

(One could also use Track.SetIOStream() to bypass loading the data into RAM upfront at all, but this offers still different tradeoffs. The correct approach depends on the app's needs and employing different approaches in different situations can make sense.)

Audio objects can be shared between mixers. This function takes a Mixer, to imply this is the most likely place it will be used and loading should try to match its audio format, but the resulting audio can be used elsewhere. If mixer is nullptr, SDL_mixer will set reasonable defaults.

Once a Audio is created, it can be assigned to a Track with Track.SetAudio(), or played without any management with Mixer.PlayAudio().

When done with a Audio, it can be freed with Audio.Destroy().

This function loads data from an IOStream. There is also a version that loads from a path on the filesystem (Mixer.LoadAudio()), and one that accepts properties for ultimate control (LoadAudioWithProperties()).

The IOStream provided must be able to seek, or loading will fail. If the stream can't seek (data is coming from an HTTP connection, etc), consider caching the data to memory or disk first and creating a new stream to read from there.

Parameters

mixer	a mixer this audio is intended to be used with. May be nullptr.
io	the IOStream to load data from.
predecode	if true, data will be fully uncompressed before returning.
closeio	true if SDL_mixer should close `io` before returning (success or failure).

Postcondition: an audio object that can be used to make sound on a mixer, or nullptr on failure; call GetError() for more information.

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

Since: This function is available since SDL_mixer 3.0.0.

See also: Audio.Destroy; Track.SetAudio; Mixer.LoadAudio; LoadAudioWithProperties

◆ Audio() [3/6]

SDL::Audio::Audio	(	MixerRef	mixer,
		IOStreamRef	io,
		const AudioSpec &	spec,
		bool	closeio = `false`
	)

inline

There are other options for streaming raw PCM: an AudioStream can be connected to a track, as can an IOStream, and will read from those sources on-demand when it is time to mix the audio. This function is useful for loading static audio data that is meant to be played multiple times.

This function will load the raw data in its entirety and cache it in RAM.

Audio objects can be shared between multiple mixers. The mixer parameter just suggests the most likely mixer to use this audio, in case some optimization might be applied, but this is not required, and a nullptr mixer may be specified.

Parameters

mixer	a mixer this audio is intended to be used with. May be nullptr.
io	the IOStream to load data from.
spec	what format the raw data is in.
closeio	true if SDL_mixer should close `io` before returning (success or failure).

Postcondition: an audio object that can be used to make sound on a mixer 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_mixer 3.0.0.

See also: Audio.Destroy; Track.SetAudio; Mixer.LoadRawAudio; Mixer.LoadRawAudioNoCopy; Mixer.LoadAudio_IO

◆ Audio() [4/6]

SDL::Audio::Audio	(	MixerRef	mixer,
		SourceBytes	data,
		const AudioSpec &	spec
	)

inline

There are other options for streaming raw PCM: an AudioStream can be connected to a track, as can an IOStream, and will read from those sources on-demand when it is time to mix the audio. This function is useful for loading static audio data that is meant to be played multiple times.

This function will load the raw data in its entirety and cache it in RAM, allocating a copy. If the original data will outlive the created Audio, you can use Mixer.LoadRawAudioNoCopy() to avoid extra allocations and copies.

Audio objects can be shared between multiple mixers. The mixer parameter just suggests the most likely mixer to use this audio, in case some optimization might be applied, but this is not required, and a nullptr mixer may be specified.

Parameters

mixer	a mixer this audio is intended to be used with. May be nullptr.
data	the raw PCM data to load.
spec	what format the raw data is in.

Postcondition: an audio object that can be used to make sound on a mixer 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_mixer 3.0.0.

See also: Audio.Destroy; Track.SetAudio; Mixer.LoadRawAudio_IO; Mixer.LoadRawAudioNoCopy; Mixer.LoadAudio_IO

◆ Audio() [5/6]

SDL::Audio::Audio	(	MixerRef	mixer,
		StringParam	path,
		bool	predecode
	)

inline

This is equivalent to calling:

Mixer.LoadAudio_IO(mixer, IOStream.FromFile(path, "rb"), predecode, true);

SDL::IOStream

The read/write operation structure.

Definition: SDL3pp_iostream.h:104

SDL::Mixer

An opaque object that represents a mixer.

Definition: SDL3pp_mixer.h:249

SDL::IOStream::FromFile

static IOStream FromFile(StringParam file, StringParam mode)

Use this function to create a new IOStream structure for reading from and/or writing to a named file.

Definition: SDL3pp_iostream.h:1780

SDL::Mixer::LoadAudio_IO

Audio LoadAudio_IO(IOStreamRef io, bool predecode, bool closeio=false)

Load audio for playback from an IOStream.

Definition: SDL3pp_mixer.h:4529

This function loads data from a path on the filesystem. There is also a version that loads from an IOStream (Mixer.LoadAudio_IO()), and one that accepts properties for ultimate control (LoadAudioWithProperties()).

Parameters

mixer	a mixer this audio is intended to be used with. May be nullptr.
path	the path on the filesystem to load data from.
predecode	if true, data will be fully uncompressed before returning.

Postcondition: an audio object that can be used to make sound on a mixer, or nullptr on failure; call GetError() for more information.

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

Since: This function is available since SDL_mixer 3.0.0.

See also: Audio.Destroy; Track.SetAudio; Mixer.LoadAudio_IO; LoadAudioWithProperties

◆ Audio() [6/6]

SDL::Audio::Audio ( PropertiesRef props )

inline

Please see Mixer.LoadAudio_IO() for a description of what the various LoadAudio functions do. This function uses properties to dictate how it operates, and exposes functionality the other functions don't provide.

Properties are discussed in SDL's documentation .

These are the supported properties:

prop::Audio.LOAD_IOSTREAM_POINTER: a pointer to an IOStream to be used to load audio data. Required. This stream must be able to seek!
prop::Audio.LOAD_CLOSEIO_BOOLEAN: true if SDL_mixer should close the IOStream before returning (success or failure).
prop::Audio.LOAD_PREDECODE_BOOLEAN: true if SDL_mixer should fully decode and decompress the data before returning. Otherwise it will be stored in its original state and decompressed on demand.
prop::Audio.LOAD_PREFERRED_MIXER_POINTER: a pointer to a Mixer, in case steps can be made to match its format when decoding. Optional.
prop::Audio.LOAD_SKIP_METADATA_TAGS_BOOLEAN: true to skip parsing metadata tags, like ID3 and APE tags. This can be used to speed up loading if the data definitely doesn't have these tags. Some decoders will fail if these tags are present when this property is true.
prop::Audio.DECODER_STRING: the name of the decoder to use for this data. Optional. If not specified, SDL_mixer will examine the data and choose the best decoder. These names are the same returned from GetAudioDecoder().

Specific decoders might accept additional custom properties, such as where to find soundfonts for MIDI playback, etc.

Parameters

props a set of properties on how to load audio.

Postcondition: an audio object that can be used to make sound on a mixer 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_mixer 3.0.0.

See also: Audio.Destroy; Track.SetAudio; Mixer.LoadAudio; Mixer.LoadAudio_IO

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

SDL3pp/SDL3pp_mixer.h

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ AudioRef() [1/3]

◆ AudioRef() [2/3]

◆ AudioRef() [3/3]

Member Function Documentation

◆ Audio() [1/6]

◆ Audio() [2/6]

◆ Audio() [3/6]

◆ Audio() [4/6]

◆ Audio() [5/6]

◆ Audio() [6/6]