You use Track to play and mix Sound objects. More...

#include <Track.hpp>

Inheritance diagram for Cori::Audio::Track:

Collaboration diagram for Cori::Audio::Track:

Public Member Functions
std::expected< void, Core::CoriError<> >	SetSound (const std::shared_ptr< Sound > &sound)
	Assigns the Sound asset to the Track.
std::expected< void, Core::CoriError<> >	Start (const PlayParams &params=PlayParams{})
	Starts the Track that has a preassigned Sound asset.
std::expected< void, Core::CoriError<> >	Play (const IsSoundWithParams auto &... sequence)
	Plays a single or a sequence of SoundWithParams objects.
std::expected< void, Core::CoriError<> >	Stop (const bool abruptStop, const int64_t fadeOutMS=0)
	Stops the Track.
std::expected< void, Core::CoriError<> >	Pause ()
	Pauses the Track.
std::expected< void, Core::CoriError<> >	Resume ()
	Resumes the Track.
bool	IsPaused () const
	Checks if the Track is paused.
bool	IsPlaying () const
	Checks if the Track is playing.
std::expected< void, Core::CoriError<> >	SetGain (const float gain)
	Sets the Track gain.
float	GetGain () const
	Returns the current Track gain. The default gain for a Track is 1.0f.
std::expected< void, Core::CoriError<> >	SetTag (const char *tag)
	Assigns the tag to the Track.
void	RemoveTag (const char *tag, const bool preserveCachedTag=false)
	Removes the tag from the Track.
std::string_view	GetTag () const
	Gets the active/cached Track tag.
bool	IsValid () const
	Check if the Track is valid.
TrackID	GetID () const
	Returns the TrackID associated with Track.
void	SetTrackStopCallback (TrackStopCallbackFn callback)
	Sets a callback to be run when the Track stops playing.
	~Track ()

Static Public Member Functions
static std::shared_ptr< Track >	Create (std::string name)
	Creates a Track object.
static void	TrackStopCallback (void userdata, MIX_Track track)
	For internal use only!

Public Attributes
const std::string	m_Name

Detailed Description

You use Track to play and mix Sound objects.

Definition at line 19 of file Track.hpp.

Constructor & Destructor Documentation

◆ ~Track()

Cori::Audio::Track::~Track ( )

Definition at line 158 of file Track.cpp.

Member Function Documentation

◆ Create()

std::shared_ptr< Track > Cori::Audio::Track::Create ( std::string name )

staticnodiscard

Creates a Track object.

Parameters

name	Name to be assigned to the Track.

Returns: Shared pointer to the created Track object.

Definition at line 154 of file Track.cpp.

◆ GetGain()

float Cori::Audio::Track::GetGain ( ) const

nodiscard

Returns the current Track gain. The default gain for a Track is 1.0f.

Returns: Current Track gain.

Definition at line 105 of file Track.cpp.

◆ GetID()

TrackID Cori::Audio::Track::GetID ( ) const

nodiscard

Returns the TrackID associated with Track.

Definition at line 146 of file Track.cpp.

◆ GetTag()

std::string_view Cori::Audio::Track::GetTag ( ) const

nodiscard

Gets the active/cached Track tag.

Returns: String View of the Tag cache.

Definition at line 134 of file Track.cpp.

◆ IsPaused()

bool Cori::Audio::Track::IsPaused ( ) const

nodiscard

Checks if the Track is paused.

Returns: Paused state.

Definition at line 80 of file Track.cpp.

◆ IsPlaying()

bool Cori::Audio::Track::IsPlaying ( ) const

nodiscard

Checks if the Track is playing.

Returns: Playing state.

Definition at line 88 of file Track.cpp.

◆ IsValid()

bool Cori::Audio::Track::IsValid ( ) const

nodiscard

Check if the Track is valid.

Returns: Validity state.

Note: Generally there is no need to explicitly check for sound validity, because Track already does so.

Definition at line 142 of file Track.cpp.

◆ Pause()

std::expected< void, Core::CoriError<> > Cori::Audio::Track::Pause ( )

Pauses the Track.

Note: Pausing a Track will not fire its stop callback.

Returns: Expected object with void on success or CoriError<> on failure.

Definition at line 62 of file Track.cpp.

◆ Play()

std::expected< void, Core::CoriError<> > Cori::Audio::Track::Play ( const IsSoundWithParams auto &... sequence )

inline

Plays a single or a sequence of SoundWithParams objects.

Parameters

sequence A sequence of objects of type SoundWithParams.

It creates a looped sequence of Sounds each with its own Mixer::PlayParams, in params there is a variable called LoopedInSequence, it defines the looping point of the sequence, the function will play all sequenced sounds once until it sees a LoopedInSequence=true in the sequence, object it belongs to becomes a looping point. Looping begins at the looping point and ends at the end if the sequence and then restarts, all LoopedInSequence variables in the SoundWithParams after the looping point has no affect on the looping behaviour. Looping will be indefinite, until the Stop method is called.
If only one SoundWithParams object was passed, if LoopedInSequence=true it will start an infinite loop, otherwise it will just play it once.

Returns: Expected object with void on success or CoriError<> on failure.

Definition at line 49 of file Track.hpp.

Here is the call graph for this function:

◆ RemoveTag()

void Cori::Audio::Track::RemoveTag	(	const char *	tag,
		const bool	preserveCachedTag = false )

Removes the tag from the Track.

Parameters

tag	Tag to be removed.
preserveCachedTag	Whether to leave the removed cache tag.

With preserveCachedTag=true it will leave the tag cached, it will be still available via GetTag(), otherwise it will erase a tag from cache.

Definition at line 123 of file Track.cpp.

◆ Resume()

std::expected< void, Core::CoriError<> > Cori::Audio::Track::Resume ( )

Resumes the Track.

Returns: Expected object with void on success or CoriError<> on failure.

Definition at line 71 of file Track.cpp.

◆ SetGain()

std::expected< void, Core::CoriError<> > Cori::Audio::Track::SetGain ( const float gain )

Sets the Track gain.

Parameters

gain	Specified gain, negative values are illegal.

Gain of 0.0f will completely silence the Track, value of 1.0f will not change the Track volume, values higher than 1.0f will increase the volume. There is no gain limit specified.

Returns: Expected object with void on success or CoriError<> on failure.

Note: Because there is no limit, this can get very load very quickly, be carefully.

Definition at line 96 of file Track.cpp.

◆ SetSound()

std::expected< void, Core::CoriError<> > Cori::Audio::Track::SetSound ( const std::shared_ptr< Sound > & sound )

Assigns the Sound asset to the Track.

Parameters

sound Sound asset.

Note: You generally want to use Play, this is only used when you have a Track that will not change its Sound asset ofter and will be started/restarted very-very often.

Returns: Expected object with void on success or CoriError<> on failure.

Definition at line 6 of file Track.cpp.

◆ SetTag()

std::expected< void, Core::CoriError<> > Cori::Audio::Track::SetTag ( const char * tag )

Assigns the tag to the Track.

Parameters

tag	Tag to be assigned.

Returns: Expected object with void on success or CoriError<> on failure.

Definition at line 113 of file Track.cpp.

◆ SetTrackStopCallback()

void Cori::Audio::Track::SetTrackStopCallback ( TrackStopCallbackFn callback )

Sets a callback to be run when the Track stops playing.

Parameters

callback Lambda ot function bind.

Note: When a sequence is playing this callback will be called for every part of the sequence.

Definition at line 150 of file Track.cpp.

◆ Start()

std::expected< void, Core::CoriError<> > Cori::Audio::Track::Start ( const PlayParams & params = PlayParams{} )

Starts the Track that has a preassigned Sound asset.

Parameters

params A set of parameters to use when starting or restarting Tracks.

Note: You generally want to use Play, this is only used when you have a Track that will not change its Sound asset ofter and will be started/restarted very-very often.

Returns: Expected object with void on success or CoriError<> on failure.

Definition at line 29 of file Track.cpp.

◆ Stop()

std::expected< void, Core::CoriError<> > Cori::Audio::Track::Stop	(	const bool	abruptStop,
		const int64_t	fadeOutMS = 0 )

Stops the Track.

Parameters

abruptStop	Stopping mode.
fadeOutMS	Number of milliseconds to spend fading out to silence before stopping. Has no effect if abruptStop is false. Optional, 0 by default.

If abruptStop is false, the Track will stop any sequence its playing, but will let the already playing Sound asset to finish mixing. If abruptStop is true, the Track will stop any sequence its playing and stop mixing immediately.

Returns: Expected object with void on success or CoriError<> on failure.

Definition at line 42 of file Track.cpp.

◆ TrackStopCallback()

void Cori::Audio::Track::TrackStopCallback	(	void *	userdata,
		MIX_Track *	track )

static

For internal use only!

Definition at line 162 of file Track.cpp.

Member Data Documentation

◆ m_Name

const std::string Cori::Audio::Track::m_Name

Definition at line 258 of file Track.hpp.

The documentation for this class was generated from the following files:

Public Member Functions

Static Public Member Functions

Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ ~Track()

Member Function Documentation

◆ Create()

◆ GetGain()

◆ GetID()

◆ GetTag()

◆ IsPaused()

◆ IsPlaying()

◆ IsValid()

◆ Pause()

◆ Play()

◆ RemoveTag()

◆ Resume()

◆ SetGain()

◆ SetSound()

◆ SetTag()

◆ SetTrackStopCallback()

◆ Start()

◆ Stop()

◆ TrackStopCallback()

Member Data Documentation

◆ m_Name