The playback capability of a device. More...

Inheritance diagram for stmi::PlaybackCapability:

Classes
struct	SoundData
	Return data type. More...

Public Member Functions
virtual int32_t	preloadSound (const std::string &sFileName) noexcept=0
	Pre-load sound file. More...

virtual int32_t	preloadSound (uint8_t const *p0Buffer, int32_t nBufferSize) noexcept=0
	Pre-load sound buffer. More...

virtual SoundData	playSound (const std::string &sFileName, double fVolume, bool bLoop, bool bRelative, double fX, double fY, double fZ) noexcept=0
	Play sound file at a given position. More...

virtual SoundData	playSound (uint8_t const *p0Buffer, int32_t nBufferSize, double fVolume, bool bLoop, bool bRelative, double fX, double fY, double fZ) noexcept=0
	Play sound buffer at a given position. More...

virtual int32_t	playSound (int32_t nFileId, double fVolume, bool bLoop, bool bRelative, double fX, double fY, double fZ) noexcept=0
	Play previously played or pre-loaded file or buffer at a given position. More...

SoundData	playSound (const std::string &sFileName) noexcept
	Play sound file at current listener position. More...

SoundData	playSound (uint8_t *p0Buffer, int32_t nBufferSize) noexcept
	Play sound buffer at current listener position. More...

int32_t	playSound (int32_t nFileId) noexcept
	Play previously played or pre-loaded file or buffer at current listener position. More...

virtual bool	setSoundPos (int32_t nSoundId, bool bRelative, double fX, double fY, double fZ) noexcept=0
	Set position of a currently playing sound. More...

virtual bool	setSoundVol (int32_t nSoundId, double fVolume) noexcept=0
	Set volume of a currently playing sound. More...

virtual bool	setListenerPos (double fX, double fY, double fZ) noexcept=0
	Set listener position. More...

virtual bool	setListenerVol (double fVolume) noexcept=0
	Set listener volume. More...

virtual bool	pauseSound (int32_t nSoundId) noexcept=0
	Pause a sound. More...

virtual bool	resumeSound (int32_t nSoundId) noexcept=0
	Resume a sound. More...

virtual bool	stopSound (int32_t nSoundId) noexcept=0
	Stop a sound. More...

virtual bool	pauseDevice () noexcept=0
	Pause playback of device. More...

virtual bool	resumeDevice () noexcept=0
	Resume playback of device. More...

virtual void	stopAllSounds () noexcept=0
	Stops all sounds of device. More...

virtual bool	isDefaultDevice () noexcept=0
	Tells whether this is the capability of the default playback device. More...

Public Member Functions inherited from stmi::Capability
virtual	~Capability () noexcept=default

int32_t	getId () const noexcept
	The capability id. More...

virtual shared_ptr< Device >	getDevice () const noexcept=0
	Returns the device owning this capability, if any. More...

const Class &	getCapabilityClass () const noexcept
	Get the registered class of the capability instance. More...

Static Public Member Functions
static const Capability::Class &	getClass () noexcept

Static Public Member Functions inherited from stmi::Capability
static bool	isCapabilityClassIdRegistered (const std::string &sCapabilityClassId) noexcept
	Tells whether the given capability class id is registered. More...

static Class	getCapabilityClassIdClass (const std::string &sCapabilityClassId) noexcept
	Gets the class with given class id. More...

Static Public Attributes
static const char *const	s_sClassId

Protected Member Functions
	PlaybackCapability () noexcept

Protected Member Functions inherited from stmi::Capability
	Capability (const Class &oClass) noexcept
	Constructor to be called from subclasses. More...

Additional Inherited Members
Static Protected Member Functions inherited from stmi::Capability
static bool	isCapabilityTypeRegistered (const std::type_info &oCapabilityType) noexcept
	Tells whether a capability type was registered. More...

static const std::type_info &	getCapabilityClassIdType (const std::string &sCapabilityClassId, bool &bRegistered) noexcept
	Gets the type of the registered capability subclass associated with class id. More...

static std::string	getCapabilityTypeClassId (const std::type_info &oType) noexcept
	Gets the class id of the given type. More...

Detailed Description

The playback capability of a device.

Devices with this capability can generate "sound finished" events.

Note: the reference system is flipped by 180 degrees around the x axis compared with the coordinates of your typical screen. That is you should negate y and z coordinates when setting the position of listener and sounds.

This interface is very simple and limited compared to what OpenAL can do. The orientation of the listener cannot be changed, the direction of sounds and their sound cone cannot be set, etc.

If the listener is at position (0,0,0), the up direction is (0,1,0), the left direction is (-1,0,0), the behind direction is (0,0,1).

The user of this interface can assume that the listener's initial position is (0,0,0) and the listener volume is 1.

When one of the playSound methods is called, an event listener (added to the device manager managing the device implementing this capability) can expect to receive a SndFinishedEvent when the sound has finished playing or the device was removed. A listeners being removed will receive the SndFinishedEvent only if it was added with the finalization flag.

Constructor & Destructor Documentation

◆ PlaybackCapability()

stmi::PlaybackCapability::PlaybackCapability ( )

inlineprotectednoexcept

Member Function Documentation

◆ getClass()

static const Capability::Class& stmi::PlaybackCapability::getClass ( )

inlinestaticnoexcept

◆ isDefaultDevice()

virtual bool stmi::PlaybackCapability::isDefaultDevice ( )

pure virtualnoexcept

Tells whether this is the capability of the default playback device.

Only one of the playback devices of a device manager should be default.

Returns: Whether default.

◆ pauseDevice()

virtual bool stmi::PlaybackCapability::pauseDevice ( )

pure virtualnoexcept

Pause playback of device.

Subsequent resumeSound on already paused sounds have effect as soon as resumeAllSounds is called.

Returns: If playback was already paused false, true otherwise.

◆ pauseSound()

virtual bool stmi::PlaybackCapability::pauseSound ( int32_t nSoundId )

pure virtualnoexcept

Pause a sound.

If called when the device is paused with pauseDevice(), the sound will not resume if resumeAllSounds() is called.

Parameters

nSoundId The sound id to pause.

Returns: Whether the sound was not paused (independent from device pausing).

◆ playSound() [1/6]

virtual SoundData stmi::PlaybackCapability::playSound	(	const std::string &	sFileName,
		double	fVolume,
		bool	bLoop,
		bool	bRelative,
		double	fX,
		double	fY,
		double	fZ
	)

pure virtualnoexcept

Play sound file at a given position.

Parameters

sFileName	The absolute path of the sound file. Cannot be empty.
bRelative	Whether the position is relative to the listener.
fVolume	The volume (0.0 inaudible, 1.0 maximum).
bLoop	Whether to loop.
fX	The x coord.
fY	The y coord.
fZ	The z coord.

Returns: The sound data.

◆ playSound() [2/6]

virtual SoundData stmi::PlaybackCapability::playSound	(	uint8_t const *	p0Buffer,
		int32_t	nBufferSize,
		double	fVolume,
		bool	bLoop,
		bool	bRelative,
		double	fX,
		double	fY,
		double	fZ
	)

pure virtualnoexcept

Play sound buffer at a given position.

Parameters

p0Buffer	The pointer to a buffer. Cannot be null.
nBufferSize	The size of the buffer. Cannot be negative.
fVolume	The volume (0.0 inaudible, 1.0 maximum).
bLoop	Whether to loop.
bRelative	Whether the position is relative to the listener.
fX	The x coord.
fY	The y coord.
fZ	The z coord.

Returns: The sound data.

◆ playSound() [3/6]

virtual int32_t stmi::PlaybackCapability::playSound	(	int32_t	nFileId,
		double	fVolume,
		bool	bLoop,
		bool	bRelative,
		double	fX,
		double	fY,
		double	fZ
	)

pure virtualnoexcept

Play previously played or pre-loaded file or buffer at a given position.

The nFileId is only valid within the instance that created it.

Parameters

nFileId	The id of the previously played file or buffer to play as a new sound.
fVolume	The volume (0.0 inaudible, 1.0 maximum).
bLoop	Whether to loop.
bRelative	Whether the position is relative to the listener.
fX	The x coord.
fY	The y coord.
fZ	The z coord.

Returns: The sound id or negative if error.

◆ playSound() [4/6]

SoundData stmi::PlaybackCapability::playSound ( const std::string & sFileName )

noexcept

Play sound file at current listener position.

The sound is played at maximum volume.

Parameters

sFileName The absolute path of the sound file. Cannot be empty.

Returns: The sound data.

◆ playSound() [5/6]

SoundData stmi::PlaybackCapability::playSound	(	uint8_t *	p0Buffer,
		int32_t	nBufferSize
	)

noexcept

Play sound buffer at current listener position.

The sound is played at maximum volume.

Parameters

p0Buffer	The pointer to a buffer. Cannot be null.
nBufferSize	The size of the buffer. Cannot be negative.

Returns: The sound data.

◆ playSound() [6/6]

int32_t stmi::PlaybackCapability::playSound ( int32_t nFileId )

noexcept

Play previously played or pre-loaded file or buffer at current listener position.

The sound is played at maximum volume.

The nFileId is only valid within the instance that created it.

Parameters

nFileId The id of the previously played file or buffer to play as a new sound.

Returns: The sound id or negative if error.

◆ preloadSound() [1/2]

virtual int32_t stmi::PlaybackCapability::preloadSound ( const std::string & sFileName )

pure virtualnoexcept

Pre-load sound file.

The returned file id can be used with the playSound method.

Parameters

sFileName The absolute path of the sound file. Cannot be empty.

Returns: The file id or negative if error (ex. device removed).

◆ preloadSound() [2/2]

virtual int32_t stmi::PlaybackCapability::preloadSound	(	uint8_t const *	p0Buffer,
		int32_t	nBufferSize
	)

pure virtualnoexcept

Pre-load sound buffer.

The returned file id can be used with the playSound method.

Parameters

p0Buffer	The pointer to a buffer. Cannot be null.
nBufferSize	The size of the buffer. Cannot be negative.

Returns: The file id or negative if error (ex. device removed).

◆ resumeDevice()

virtual bool stmi::PlaybackCapability::resumeDevice ( )

pure virtualnoexcept

Resume playback of device.

Returns: If playback was not paused false, true otherwise.

◆ resumeSound()

virtual bool stmi::PlaybackCapability::resumeSound ( int32_t nSoundId )

pure virtualnoexcept

Resume a sound.

If called when the device is paused with pauseDevice(), the sound will resume only when resumeAllSounds() is called.

Parameters

nSoundId The sound id to resume.

Returns: Whether the sound was paused (independent from device pausing).

◆ setListenerPos()

virtual bool stmi::PlaybackCapability::setListenerPos	(	double	fX,
		double	fY,
		double	fZ
	)

pure virtualnoexcept

Set listener position.

Parameters

fX	The x coord.
fY	The y coord.
fZ	The z coord.

Returns: Whether could set the position.

◆ setListenerVol()

virtual bool stmi::PlaybackCapability::setListenerVol ( double fVolume )

pure virtualnoexcept

Set listener volume.

Values outside the 0.0 to 1.0 range are clamped.

Parameters

fVolume The volume. A number from 0.0 (inaudible) to 1.0 (maximum).

Returns: Whether could set the volume.

◆ setSoundPos()

virtual bool stmi::PlaybackCapability::setSoundPos	(	int32_t	nSoundId,
		bool	bRelative,
		double	fX,
		double	fY,
		double	fZ
	)

pure virtualnoexcept

Set position of a currently playing sound.

Parameters

nSoundId	The sound id.
bRelative	Whether the position is relative to the listener.
fX	The x coord.
fY	The y coord.
fZ	The z coord.

Returns: Whether could set the position.

◆ setSoundVol()

virtual bool stmi::PlaybackCapability::setSoundVol	(	int32_t	nSoundId,
		double	fVolume
	)

pure virtualnoexcept

Set volume of a currently playing sound.

Parameters

nSoundId	The sound id.
fVolume	The volume (0.0 inaudible, 1.0 maximum).

Returns: Whether could set the volume.

◆ stopAllSounds()

virtual void stmi::PlaybackCapability::stopAllSounds ( )

pure virtualnoexcept

Stops all sounds of device.

Note: no SndFinishedEvent is sent to listeners.

◆ stopSound()

virtual bool stmi::PlaybackCapability::stopSound ( int32_t nSoundId )

pure virtualnoexcept

Stop a sound.

Note: no SndFinishedEvent is sent to listeners.

Parameters

nSoundId The sound id to stop.

Returns: Whether the sound existed.

Member Data Documentation

◆ s_sClassId

const char* const stmi::PlaybackCapability::s_sClassId

static

Classes

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ PlaybackCapability()

Member Function Documentation

◆ getClass()

◆ isDefaultDevice()

◆ pauseDevice()

◆ pauseSound()

◆ playSound() [1/6]

◆ playSound() [2/6]

◆ playSound() [3/6]

◆ playSound() [4/6]

◆ playSound() [5/6]

◆ playSound() [6/6]

◆ preloadSound() [1/2]

◆ preloadSound() [2/2]

◆ resumeDevice()

◆ resumeSound()

◆ setListenerPos()

◆ setListenerVol()

◆ setSoundPos()

◆ setSoundVol()

◆ stopAllSounds()

◆ stopSound()

Member Data Documentation

◆ s_sClassId