OSDL::Audio::Sound Class Reference

Sound is punctual audible content, as opposed to music. More...

#include <OSDLSound.h>

Inheritance diagram for OSDL::Audio::Sound:

[legend]

Collaboration diagram for OSDL::Audio::Sound:

[legend]

List of all members.

Public Member Functions
	Sound (const std::string &soundFile, bool preload=true)
	Creates a new sound instance from specified file.
virtual	~Sound () throw ()
	Virtual destructor.
virtual bool	load ()
	Loads the sound from file.
virtual bool	unload ()
	Unloads the sound that may be contained by this instance.
virtual Volume	getVolume () const
	Returns the volume associated to this sound instance.
virtual void	setVolume (Volume newVolume)
	Sets the volume associated to this sound instance.
virtual void	play (PlaybackCount playCount=1)
	Plays this sound instance at once on any appropriate channel number.
virtual ChannelNumber	playReturnChannel (PlaybackCount playCount=1)
	Plays this sound instance at once on any appropriate channel number, and returns that channel number.
virtual void	play (ChannelNumber mixingChannelNumber, PlaybackCount playCount=1)
	Plays this sound instance at once on specified mixing channel.
virtual void	playForAtMost (Ceylan::System::Millisecond maxDuration, PlaybackCount playCount=1)
	Plays this sound instance at once on any channel number within specified duration.
virtual ChannelNumber	playForAtMostReturnChannel (Ceylan::System::Millisecond maxDuration, PlaybackCount playCount=1)
	Plays this sound instance at once on any channel number within specified duration.
virtual void	playForAtMost (Ceylan::System::Millisecond maxDuration, ChannelNumber mixingChannelNumber, PlaybackCount playCount=1)
	Plays this sound instance at once on specified mixing channel within specified duration.
virtual void	playWithFadeIn (Ceylan::System::Millisecond fadeInMaxDuration, PlaybackCount playCount=1)
	Plays this sound instance at once on any appropriate channel number, beginning with a fade-in effect.
virtual ChannelNumber	playWithFadeInReturnChannel (Ceylan::System::Millisecond fadeInMaxDuration, PlaybackCount playCount=1)
	Plays this sound instance at once on any appropriate channel number, beginning with a fade-in effect.
virtual void	playWithFadeIn (Ceylan::System::Millisecond fadeInMaxDuration, ChannelNumber mixingChannelNumber, PlaybackCount playCount=1)
	Plays this sound instance at once on specified channel number, beginning with a fade-in effect.
virtual void	playWithFadeInForAtMost (Ceylan::System::Millisecond playbackMaxDuration, Ceylan::System::Millisecond fadeInMaxDuration, PlaybackCount playCount=1)
	Plays this sound instance at once on any appropriate channel number, beginning with a fade-in effect.
virtual ChannelNumber	playWithFadeInForAtMostReturnChannel (Ceylan::System::Millisecond playbackMaxDuration, Ceylan::System::Millisecond fadeInMaxDuration, PlaybackCount playCount=1)
	Plays this sound instance at once on any appropriate channel number, beginning with a fade-in effect.
virtual void	playWithFadeInForAtMost (Ceylan::System::Millisecond playbackMaxDuration, Ceylan::System::Millisecond fadeInMaxDuration, ChannelNumber mixingChannelNumber, PlaybackCount playCount=1)
	Plays this sound instance at once on specified channel number, beginning with a fade-in effect.
virtual const std::string	toString (Ceylan::VerbosityLevels level=Ceylan::high) const
	Returns an user-friendly description of the state of this object.
virtual bool	isConvertedToOutputFormat () const
	Tells whether the internal samples of this audible have already been converted to the sample format used for audio output.
Static Public Member Functions
static std::string	FindAudiblePath (const std::string &audibleFilename)
	Helper method to find the audible specified by its filename, using audio locators.
Static Protected Member Functions
static int	GetLoopsForPlayCount (PlaybackCount playCount)
	Helper method to factorize conversion of play counts into a number of loops.
Protected Attributes
OSDL::Utils::DataStream *	_dataStream
	The internal low level sound is defined through the template.
bool	_convertedToOutputFormat
	Tells whether the internal samples have been converted already to the sample format used for audio output.
Private Member Functions
	Sound (const Sound &source)
	Copy constructor made private to ensure that it will be never called.
Sound &	operator= (const Sound &source)
	Assignment operator made private to ensure that it will be never called.

Detailed Description

Sound is punctual audible content, as opposed to music.

Both are Audible instances.

They are also objects containing a low level sample (here a sound), which can be loaded, unloaded, reloaded from file at will. Therefore a Sound is (indirectly) a Loadable instance (mother class of the LoadableWithContent template).

Methods for playing sounds are non-blocking: they trigger the playing and return immediately, the execution continues while the playback goes on, unless specified otherwise.

See also:: Music

On the PC platform, sounds can be either WAV or OggVorbis.

In the embedded case (Nintendo DS platform), sounds can be either RAW with OSDL header, or MP3.

Sounds, as opposed to musics, are read once for all, as a whole, in memory, not streamed chunk after chunk from the media.

Definition at line 151 of file OSDLSound.h.

Constructor & Destructor Documentation

Sound::Sound	(	const std::string &	soundFile,
		bool	preload = `true`
	)			`[explicit]`

Creates a new sound instance from specified file.

Parameters:

soundFile

the file containing the targeted sound. On all PC-like platforms (including Windows and most UNIX), the supported formats are WAVE, AIFF, RIFF, OGG, and VOC. WAVE and OGG are recommended for sounds. On the Nintendo DS, only one format is supported, the .osdl.sound format.

See also:: trunk/tools/mediaraw2osdlsound.cc for a description.

Parameters:

preload

the sound will be loaded directly by this constructor iff true, otherwise only its path will be stored to allow for a later loading.

Exceptions:

SoundException

if the operation failed or is not supported.

Definition at line 130 of file OSDLSound.cc.

References OSDL::Audio::AudioModule::IsAudioInitialized(), and load().

Sound::~Sound ( ) throw () [virtual]

Virtual destructor.

Definition at line 162 of file OSDLSound.cc.

References unload().

OSDL::Audio::Sound::Sound ( const Sound & source ) [explicit, private]

Copy constructor made private to ensure that it will be never called.

The compiler should complain whenever this undefined constructor is called, implicitly or not.

Member Function Documentation

string Audible::FindAudiblePath ( const std::string & audibleFilename ) [static, inherited]

Helper method to find the audible specified by its filename, using audio locators.

Note:: Starts by searching the current directory, before using the locator paths.

Parameters:

audibleFilename

the filename of the file where the audible is stored.

Exceptions:

AudibleException

if the operation failed, including if the file could not be found despite audio path locator.

Definition at line 130 of file OSDLAudible.cc.

References OSDL::Audio::AudioModule::AudioFileLocator, OSDL::Audio::AudioModule::AudioPathEnvironmentVariable, and OSDL::Audio::Audible::toString().

int Audible::GetLoopsForPlayCount ( PlaybackCount playCount ) [static, protected, inherited]

Helper method to factorize conversion of play counts into a number of loops.

Exceptions:

AudibleException

if the play count is out of bounds (must be either -1 for infinite looping or strictly superior to zero).

Definition at line 186 of file OSDLAudible.cc.

References OSDL::Audio::Loop, and OSDL::Video::Pixels::toString().

Referenced by play(), OSDL::Audio::Music::play(), playForAtMost(), playForAtMostReturnChannel(), playReturnChannel(), playWithFadeIn(), OSDL::Audio::Music::playWithFadeIn(), playWithFadeInForAtMost(), playWithFadeInForAtMostReturnChannel(), OSDL::Audio::Music::playWithFadeInFromPosition(), and playWithFadeInReturnChannel().

Volume Sound::getVolume ( ) const [virtual]

Returns the volume associated to this sound instance.

Exceptions:

SoundException

if the operation failed, including if not supported or if no previously loaded sound is available.

Implements OSDL::Audio::Audible.

Definition at line 500 of file OSDLSound.cc.

Referenced by toString().

bool Audible::isConvertedToOutputFormat ( ) const [virtual, inherited]

Tells whether the internal samples of this audible have already been converted to the sample format used for audio output.

Returns:: true iff the samples are already converted.

Definition at line 105 of file OSDLAudible.cc.

References OSDL::Audio::Audible::_convertedToOutputFormat.

bool Sound::load ( ) [virtual]

Loads the sound from file.

Returns:: true iff the sound had to be actually loaded (otherwise it was already loaded and nothing was done).

Exceptions:

Ceylan::LoadableException

whenever the loading fails.

Definition at line 192 of file OSDLSound.cc.

References OSDL::Audio::Audible::_convertedToOutputFormat, _dataStream, OSDL::Utils::createDataStreamFrom(), OSDL::DescribeFileTag(), OSDL::Audio::AudioModule::IMAADPCMSampleFormat, OSDL::Audio::AudioModule::LittleSint16SampleFormat, LOG_DEBUG_AUDIO, OSDL::Audio::AudioModule::Mono, OSDL::Audio::AudioModule::Sint8SampleFormat, OSDL::SoundTag, OSDL::Audio::AudioModule::Stereo, and OSDL::Video::Pixels::toString().

Referenced by Sound().

Sound& OSDL::Audio::Sound::operator= ( const Sound & source ) [private]

Assignment operator made private to ensure that it will be never called.

The compiler should complain whenever this undefined operator is called, implicitly or not.

void Sound::play	(	ChannelNumber	mixingChannelNumber,
		PlaybackCount	playCount = `1`
	)			`[virtual]`

Plays this sound instance at once on specified mixing channel.

Parameters:

	mixingChannelNumber	number of the mixing channel this sound should be played on.
	playCount	the number of times this sound should be played, unless stopped by halt, fade out, expiration time or audio module stop. -1 means forever. Otherwise it must be strictly positive (exception thrown if zero or below -1).

Exceptions:

AudibleException

if the operation failed, including if not supported or if no free channel is available.

Definition at line 647 of file OSDLSound.cc.

References OSDL::Audio::Audible::GetLoopsForPlayCount().

void Sound::play ( PlaybackCount playCount = 1 ) [virtual]

Plays this sound instance at once on any appropriate channel number.

Parameters:

playCount

the number of times this sound should be played, unless stopped by halt, fade out, expiration time or audio module stop. -1 means forever. Otherwise it must be strictly positive (exception thrown if zero or below -1).

Exceptions:

AudibleException

if the operation failed, including if not supported or if no free channel is available.

See also:: playReturnChannel if the chosen channel needs to be known.

Implements OSDL::Audio::Audible.

Definition at line 578 of file OSDLSound.cc.

References playReturnChannel().

void Sound::playForAtMost	(	Ceylan::System::Millisecond	maxDuration,
		ChannelNumber	mixingChannelNumber,
		PlaybackCount	playCount = `1`
	)			`[virtual]`

Plays this sound instance at once on specified mixing channel within specified duration.

Parameters:

	maxDuration	the maximum duration during which this sound will be played, in milliseconds. It may stop earlier if: (sound duration).playCount < maxDuration
	mixingChannelNumber	number of the mixing channel this sound should be played on.
	playCount	the number of times this sound should be played, unless stopped by halt, fade out, expiration time or audio module stop. -1 means forever. Otherwise it must be strictly positive (exception thrown if zero or below -1).

Exceptions:

AudibleException

if the operation failed, including if not supported or if no free channel is available.

Definition at line 719 of file OSDLSound.cc.

References OSDL::Audio::Audible::GetLoopsForPlayCount().

void Sound::playForAtMost	(	Ceylan::System::Millisecond	maxDuration,
		PlaybackCount	playCount = `1`
	)			`[virtual]`

Plays this sound instance at once on any channel number within specified duration.

Parameters:

	maxDuration	the maximum duration during which this sound will be played, in milliseconds. It may stop earlier if: (sound duration).playCount < maxDuration
	playCount	the number of times this sound should be played, unless stopped by halt, fade out, expiration time or audio module stop. -1 means forever. Otherwise it must be strictly positive (exception thrown if zero or below -1).

Exceptions:

AudibleException

if the operation failed, including if not supported or if no free channel is available.

Definition at line 677 of file OSDLSound.cc.

References playForAtMostReturnChannel().

ChannelNumber Sound::playForAtMostReturnChannel	(	Ceylan::System::Millisecond	maxDuration,
		PlaybackCount	playCount = `1`
	)			`[virtual]`

Plays this sound instance at once on any channel number within specified duration.

Parameters:

	maxDuration	the maximum duration during which this sound will be played, in milliseconds. It may stop earlier if: (sound duration).playCount < maxDuration
	playCount	the number of times this sound should be played, unless stopped by halt, fade out, expiration time or audio module stop. -1 means forever. Otherwise it must be strictly positive (exception thrown if zero or below -1).

Returns:: the number of the channel number being used.

Exceptions:

AudibleException

if the operation failed, including if not supported or if no free channel is available.

Definition at line 688 of file OSDLSound.cc.

References OSDL::Audio::Audible::GetLoopsForPlayCount().

Referenced by playForAtMost().

ChannelNumber Sound::playReturnChannel ( PlaybackCount playCount = 1 ) [virtual]

Plays this sound instance at once on any appropriate channel number, and returns that channel number.

Parameters:

playCount

the number of times this sound should be played, unless stopped by halt, fade out, expiration time or audio module stop. -1 means forever. Otherwise it must be strictly positive (exception thrown if zero or below -1).

Returns:: the number of the channel number being used.

Exceptions:

AudibleException

if the operation failed, including if not supported or if no free channel is available.

Note:: Cannot be inherited from Audible as they have no concept of a channel.

Definition at line 617 of file OSDLSound.cc.

References OSDL::Audio::Audible::GetLoopsForPlayCount().

Referenced by play().

void Sound::playWithFadeIn	(	Ceylan::System::Millisecond	fadeInMaxDuration,
		ChannelNumber	mixingChannelNumber,
		PlaybackCount	playCount = `1`
	)			`[virtual]`

Plays this sound instance at once on specified channel number, beginning with a fade-in effect.

Parameters:

	fadeInMaxDuration	duration in milliseconds during which the fade-in effect should take to go from silence to full volume.
	mixingChannelNumber	number of the mixing channel this sound should be played on.
	playCount	the number of times this sound should be played, unless stopped by halt, fade out, expiration time or audio module stop. -1 means forever. Otherwise it must be strictly positive (exception thrown if zero or below -1).

Exceptions:

AudibleException

if the operation failed, including if not supported or if no free channel is available.

See also:: playWithFadeInReturnChannel if the chosen channel needs to be known.

Definition at line 793 of file OSDLSound.cc.

References OSDL::Audio::Audible::GetLoopsForPlayCount().

void Sound::playWithFadeIn	(	Ceylan::System::Millisecond	fadeInMaxDuration,
		PlaybackCount	playCount = `1`
	)			`[virtual]`

Plays this sound instance at once on any appropriate channel number, beginning with a fade-in effect.

Parameters:

	fadeInMaxDuration	duration in milliseconds during which the fade-in effect should take to go from silence to full volume.
	playCount	the number of times this sound should be played, unless stopped by halt, fade out, expiration time or audio module stop. -1 means forever. Otherwise it must be strictly positive (exception thrown if zero or below -1).

Exceptions:

AudibleException

if the operation failed, including if not supported or if no free channel is available.

See also:: playWithFadeInReturnChannel if the chosen channel needs to be known.

Implements OSDL::Audio::Audible.

Definition at line 750 of file OSDLSound.cc.

References playWithFadeInReturnChannel().

void Sound::playWithFadeInForAtMost	(	Ceylan::System::Millisecond	playbackMaxDuration,
		Ceylan::System::Millisecond	fadeInMaxDuration,
		ChannelNumber	mixingChannelNumber,
		PlaybackCount	playCount = `1`
	)			`[virtual]`

Plays this sound instance at once on specified channel number, beginning with a fade-in effect.

Parameters:

	playbackMaxDuration	the maximum duration during which this sound will be played, in milliseconds.
	fadeInMaxDuration	duration in milliseconds during which the fade-in effect should take to go from silence to full volume.
	mixingChannelNumber	number of the mixing channel this sound should be played on.
	playCount	the number of times this sound should be played, unless stopped by halt, fade out, expiration time or audio module stop. -1 means forever. Otherwise it must be strictly positive (exception thrown if zero or below -1).

Exceptions:

AudibleException

if the operation failed, including if not supported or if no free channel is available.

See also:: playWithFadeInReturnChannel if the chosen channel needs to be known.

Definition at line 874 of file OSDLSound.cc.

References OSDL::Audio::Audible::GetLoopsForPlayCount().

void Sound::playWithFadeInForAtMost	(	Ceylan::System::Millisecond	playbackMaxDuration,
		Ceylan::System::Millisecond	fadeInMaxDuration,
		PlaybackCount	playCount = `1`
	)			`[virtual]`

Plays this sound instance at once on any appropriate channel number, beginning with a fade-in effect.

Parameters:

	playbackMaxDuration	the maximum duration during which this sound will be played, in milliseconds.
	fadeInMaxDuration	duration in milliseconds during which the fade-in effect should take to go from silence to full volume.
	playCount	the number of times this sound should be played, unless stopped by halt, fade out, expiration time or audio module stop. -1 means forever. Otherwise it must be strictly positive (exception thrown if zero or below -1).

Exceptions:

AudibleException

if the operation failed, including if not supported or if no free channel is available.

See also:: playWithFadeInForAtMostReturnChannel if the chosen channel needs to be known.

Definition at line 824 of file OSDLSound.cc.

References playWithFadeInForAtMostReturnChannel().

ChannelNumber Sound::playWithFadeInForAtMostReturnChannel	(	Ceylan::System::Millisecond	playbackMaxDuration,
		Ceylan::System::Millisecond	fadeInMaxDuration,
		PlaybackCount	playCount = `1`
	)			`[virtual]`

Plays this sound instance at once on any appropriate channel number, beginning with a fade-in effect.

Parameters:

	playbackMaxDuration	the maximum duration during which this sound will be played, in milliseconds.
	fadeInMaxDuration	duration in milliseconds during which the fade-in effect should take to go from silence to full volume.
	playCount	the number of times this sound should be played, unless stopped by halt, fade out, expiration time or audio module stop. -1 means forever. Otherwise it must be strictly positive (exception thrown if zero or below -1).

Returns:: the channel number on which this sound is played.

Exceptions:

AudibleException

if the operation failed, including if not supported or if no free channel is available.

Note:: Cannot be inherited from Audible as they have no concept of a channel.

Definition at line 838 of file OSDLSound.cc.

References OSDL::Audio::Audible::GetLoopsForPlayCount().

Referenced by playWithFadeInForAtMost().

ChannelNumber Sound::playWithFadeInReturnChannel	(	Ceylan::System::Millisecond	fadeInMaxDuration,
		PlaybackCount	playCount = `1`
	)			`[virtual]`

Plays this sound instance at once on any appropriate channel number, beginning with a fade-in effect.

Parameters:

	fadeInMaxDuration	duration in milliseconds during which the fade-in effect should take to go from silence to full volume.
	playCount	the number of times this sound should be played, unless stopped by halt, fade out, expiration time or audio module stop. -1 means forever. Otherwise it must be strictly positive (exception thrown if zero or below -1).

Returns:: the channel number on which this sound is played.

Exceptions:

AudibleException

if the operation failed, including if not supported or if no free channel is available.

Note:: Cannot be inherited from Audible as they have no concept of a channel.

Definition at line 762 of file OSDLSound.cc.

References OSDL::Audio::Audible::GetLoopsForPlayCount().

Referenced by playWithFadeIn().

void Sound::setVolume ( Volume newVolume ) [virtual]

Sets the volume associated to this sound instance.

The volume setting will take effect when this sound will be used on a channel, being mixed into the output.

Parameters:

newVolume

the new volume to be set.

Exceptions:

SoundException

if the operation failed, including if not supported or if no previously loaded sound is available.

Implements OSDL::Audio::Audible.

Definition at line 534 of file OSDLSound.cc.

const string Sound::toString ( Ceylan::VerbosityLevels level = Ceylan::high ) const [virtual]

Returns an user-friendly description of the state of this object.

Parameters:

level

the requested verbosity level.

Note:: Text output format is determined from overall settings.

See also:: Ceylan::TextDisplayable

Reimplemented from OSDL::Audio::Audible.

Definition at line 904 of file OSDLSound.cc.

References getVolume(), OSDL::Audio::AudioModule::MaxVolume, and OSDL::Audio::AudioModule::MinVolume.

bool Sound::unload ( ) [virtual]

Unloads the sound that may be contained by this instance.

Returns:: true iff the sound had to be actually unloaded (otherwise it was not already available and nothing was done).

Note:: One has to ensure the sound is not playing before calling this method.

Exceptions:

Ceylan::LoadableException

whenever the unloading fails.

Definition at line 422 of file OSDLSound.cc.

References _dataStream.

Referenced by ~Sound().

Member Data Documentation

bool OSDL::Audio::Audible::_convertedToOutputFormat [protected, inherited]

Tells whether the internal samples have been converted already to the sample format used for audio output.

Definition at line 257 of file OSDLAudible.h.

Referenced by OSDL::Audio::Audible::isConvertedToOutputFormat(), load(), OSDL::Audio::Music::load(), and OSDL::Audio::Audible::toString().

OSDL::Utils::DataStream* OSDL::Audio::Sound::_dataStream [protected]

The internal low level sound is defined through the template.

The datastream corresponding to this sound.

Definition at line 653 of file OSDLSound.h.

Referenced by load(), and unload().

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

OSDL::Audio::Sound Class Reference

Public Member Functions

Static Public Member Functions

Static Protected Member Functions

Protected Attributes

Private Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation