Represents a sound which is currently played. More...

#include <ik_ISound.h>

Inheritance diagram for irrklang::ISound:

Public Member Functions
virtual ISoundSource *	getSoundSource ()=0
	returns source of the sound which stores the filename and other informations about that sound More...

virtual void	setIsPaused (bool paused=true)=0
	returns if the sound is paused More...

virtual bool	getIsPaused ()=0
	returns if the sound is paused More...

virtual void	stop ()=0
	Will stop the sound and free its resources. More...

virtual ik_f32	getVolume ()=0
	returns volume of the sound, a value between 0 (mute) and 1 (full volume). More...

virtual void	setVolume (ik_f32 volume)=0
	sets the volume of the sound, a value between 0 (mute) and 1 (full volume). More...

virtual void	setPan (ik_f32 pan)=0
	sets the pan of the sound. Takes a value between -1 and 1, 0 is center. More...

virtual ik_f32	getPan ()=0
	returns the pan of the sound. Takes a value between -1 and 1, 0 is center. More...

virtual bool	isLooped ()=0
	returns if the sound has been started to play looped More...

virtual void	setIsLooped (bool looped)=0
	changes the loop mode of the sound. More...

virtual bool	isFinished ()=0
	returns if the sound has finished playing. More...

virtual void	setMinDistance (ik_f32 min)=0
	Sets the minimal distance if this is a 3D sound. More...

virtual ik_f32	getMinDistance ()=0
	Returns the minimal distance if this is a 3D sound. More...

virtual void	setMaxDistance (ik_f32 max)=0
	Sets the maximal distance if this is a 3D sound. More...

virtual ik_f32	getMaxDistance ()=0
	Returns the maximal distance if this is a 3D sound. More...

virtual void	setPosition (vec3df position)=0
	sets the position of the sound in 3d space More...

virtual vec3df	getPosition ()=0
	returns the position of the sound in 3d space More...

virtual void	setVelocity (vec3df vel)=0
	sets the position of the sound in 3d space, needed for Doppler effects. More...

virtual vec3df	getVelocity ()=0
	returns the velocity of the sound in 3d space, needed for Doppler effects. More...

virtual ik_u32	getPlayPosition ()=0
	returns the current play position of the sound in milliseconds. More...

virtual bool	setPlayPosition (ik_u32 pos)=0
	sets the current play position of the sound in milliseconds. More...

virtual bool	setPlaybackSpeed (ik_f32 speed=1.0f)=0
	Sets the playback speed (frequency) of the sound. More...

virtual ik_f32	getPlaybackSpeed ()=0
	Returns the playback speed set by setPlaybackSpeed(). Default: 1.0f. More...

virtual ik_u32	getPlayLength ()=0
	returns the play length of the sound in milliseconds. More...

virtual ISoundEffectControl *	getSoundEffectControl ()=0
	Returns the sound effect control interface for this sound. More...

virtual void	setSoundStopEventReceiver (ISoundStopEventReceiver reciever, void userData=0)=0
	Sets the sound stop event receiver, an interface which gets called if a sound has finished playing. More...

Public Member Functions inherited from irrklang::IVirtualRefCounted
virtual	~IVirtualRefCounted ()
	Destructor. More...

virtual void	grab ()=0
	Grabs the object. Increments the reference counter by one. More...

virtual bool	drop ()=0
	Drops the object. Decrements the reference counter by one. More...

Detailed Description

Represents a sound which is currently played.

The sound can be stopped, its volume or pan changed, effects added/removed and similar using this interface. Creating sounds is done using ISoundEngine::play2D() or ISoundEngine::play3D(). More informations about the source of a sound can be obtained from the ISoundSource interface.

Definition at line 24 of file ik_ISound.h.

Member Function Documentation

virtual bool irrklang::ISound::getIsPaused ( )

pure virtual

returns if the sound is paused

virtual ik_f32 irrklang::ISound::getMaxDistance ( )

pure virtual

Returns the maximal distance if this is a 3D sound.

See setMaxDistance() for details.

virtual ik_f32 irrklang::ISound::getMinDistance ( )

pure virtual

Returns the minimal distance if this is a 3D sound.

See setMinDistance() for details.

virtual ik_f32 irrklang::ISound::getPan ( )

pure virtual

returns the pan of the sound. Takes a value between -1 and 1, 0 is center.

virtual ik_f32 irrklang::ISound::getPlaybackSpeed ( )

pure virtual

Returns the playback speed set by setPlaybackSpeed(). Default: 1.0f.

See setPlaybackSpeed() for details

virtual ik_u32 irrklang::ISound::getPlayLength ( )

pure virtual

returns the play length of the sound in milliseconds.

Returns -1 if not known for this sound for example because its decoder does not support length reporting or it is a file stream of unknown size. Note: You can also use ISoundSource::getPlayLength() to get the length of a sound without actually needing to play it.

virtual ik_u32 irrklang::ISound::getPlayPosition ( )

pure virtual

returns the current play position of the sound in milliseconds.

Returns: Returns -1 if not implemented or possible for this sound for example because it already has been stopped and freed internally or similar.

virtual vec3df irrklang::ISound::getPosition ( )

pure virtual

returns the position of the sound in 3d space

virtual ISoundEffectControl* irrklang::ISound::getSoundEffectControl ( )

pure virtual

Returns the sound effect control interface for this sound.

Sound effects such as Chorus, Distorsions, Echo, Reverb and similar can be controlled using this. The interface pointer is only valid as long as the ISound pointer is valid. If the ISound pointer gets dropped (IVirtualRefCounted::drop()), the ISoundEffects may not be used any more.

Returns: Returns a pointer to the sound effects interface if available. The sound has to be started via ISoundEngine::play2D() or ISoundEngine::play3D(), with the flag enableSoundEffects=true, otherwise 0 will be returned. Note that if the output driver does not support sound effects, 0 will be returned as well.

virtual ISoundSource* irrklang::ISound::getSoundSource ( )

pure virtual

returns source of the sound which stores the filename and other informations about that sound

Returns: Returns the sound source poitner of this sound. May return 0 if the sound source has been removed.

virtual vec3df irrklang::ISound::getVelocity ( )

pure virtual

returns the velocity of the sound in 3d space, needed for Doppler effects.

To use doppler effects use ISound::setVelocity to set a sounds velocity, ISoundEngine::setListenerPosition() to set the listeners velocity and ISoundEngine::setDopplerEffectParameters() to adjust two parameters influencing the doppler effects intensity.

virtual ik_f32 irrklang::ISound::getVolume ( )

pure virtual

returns volume of the sound, a value between 0 (mute) and 1 (full volume).

(this volume gets multiplied with the master volume of the sound engine and other parameters like distance to listener when played as 3d sound)

virtual bool irrklang::ISound::isFinished ( )

pure virtual

returns if the sound has finished playing.

Don't mix this up with isPaused(). isFinished() returns if the sound has been finished playing. If it has, is maybe already have been removed from the playing list of the sound engine and calls to any other of the methods of ISound will not have any result. If you call stop() to a playing sound will result that this function will return true when invoked.

virtual bool irrklang::ISound::isLooped ( )

pure virtual

returns if the sound has been started to play looped

virtual void irrklang::ISound::setIsLooped ( bool looped )

pure virtual

changes the loop mode of the sound.

If the sound is playing looped and it is changed to not-looped, then it will stop playing after the loop has finished. If it is not looped and changed to looped, the sound will start repeating to be played when it reaches its end. Invoking this method will not have an effect when the sound already has stopped.

virtual void irrklang::ISound::setIsPaused ( bool paused = true )

pure virtual

returns if the sound is paused

virtual void irrklang::ISound::setMaxDistance ( ik_f32 max )

pure virtual

Sets the maximal distance if this is a 3D sound.

Changing this value is usually not necessary. Use setMinDistance() instead. Don't change this value if you don't know what you are doing: This value causes the sound to stop attenuating after it reaches the max distance. Most people think that this sets the volume of the sound to 0 after this distance, but this is not true. Only change the minimal distance (using for example setMinDistance()) to influence this. The maximum distance for a sound source is the distance beyond which the sound does not get any quieter. The default minimum distance is 1, the default max distance is a huge number like 1000000000.0f.

virtual void irrklang::ISound::setMinDistance ( ik_f32 min )

pure virtual

Sets the minimal distance if this is a 3D sound.

Changes the distance at which the 3D sound stops getting louder. This works like this: As a listener approaches a 3D sound source, the sound gets louder. Past a certain point, it is not reasonable for the volume to continue to increase. Either the maximum (zero) has been reached, or the nature of the sound source imposes a logical limit. This is the minimum distance for the sound source. Similarly, the maximum distance for a sound source is the distance beyond which the sound does not get any quieter. The default minimum distance is 1, the default max distance is a huge number like 1000000000.0f.

virtual void irrklang::ISound::setPan ( ik_f32 pan )

pure virtual

sets the pan of the sound. Takes a value between -1 and 1, 0 is center.

virtual bool irrklang::ISound::setPlaybackSpeed ( ik_f32 speed = 1.0f )

pure virtual

Sets the playback speed (frequency) of the sound.

Plays the sound at a higher or lower speed, increasing or decreasing its frequency which makes it sound lower or higher. Note that this feature is not available on all sound output drivers (it is on the DirectSound drivers at least), and it does not work together with the 'enableSoundEffects' parameter of ISoundEngine::play2D and ISoundEngine::play3D when using DirectSound.

Parameters

speed Factor of the speed increase or decrease. 2 is twice as fast, 0.5 is only half as fast. The default is 1.0.

Returns: Returns true if sucessful, false if not. The current sound driver might not support changing the playBack speed, or the sound was started with the 'enableSoundEffects' parameter.

virtual bool irrklang::ISound::setPlayPosition ( ik_u32 pos )

pure virtual

sets the current play position of the sound in milliseconds.

Parameters

pos	Position in milliseconds. Must be between 0 and the value returned by getPlayPosition().

Returns: Returns true successful. False is returned for example if the sound already finished playing and is stopped or the audio source is not seekable, for example if it is an internet stream or a a file format not supporting seeking (a .MOD file for example). A file can be tested if it can bee seeking using ISoundSource::getIsSeekingSupported().

virtual void irrklang::ISound::setPosition ( vec3df position )

pure virtual

sets the position of the sound in 3d space

virtual void irrklang::ISound::setSoundStopEventReceiver	(	ISoundStopEventReceiver *	reciever,
		void *	userData = `0`
	)

pure virtual

Sets the sound stop event receiver, an interface which gets called if a sound has finished playing.

This event is guaranteed to be called when the sound or sound stream is finished, either because the sound reached its playback end, its sound source was removed, ISoundEngine::stopAllSounds() has been called or the whole engine was deleted. There is an example on how to use events in irrklang at Using Sound Events .

Parameters

receiver	Interface to a user implementation of the sound receiver. This interface should be as long valid as the sound exists or another stop event receiver is set. Set this to null to set no sound stop event receiver.
userData	A iser data pointer, can be null.

virtual void irrklang::ISound::setVelocity ( vec3df vel )

pure virtual

sets the position of the sound in 3d space, needed for Doppler effects.

To use doppler effects use ISound::setVelocity to set a sounds velocity, ISoundEngine::setListenerPosition() to set the listeners velocity and ISoundEngine::setDopplerEffectParameters() to adjust two parameters influencing the doppler effects intensity.

virtual void irrklang::ISound::setVolume ( ik_f32 volume )

pure virtual

sets the volume of the sound, a value between 0 (mute) and 1 (full volume).

This volume gets multiplied with the master volume of the sound engine and other parameters like distance to listener when played as 3d sound.

virtual void irrklang::ISound::stop ( )

pure virtual

Will stop the sound and free its resources.

If you just want to pause the sound, use setIsPaused(). After calling stop(), isFinished() will usually return true. Be sure to also call ->drop() once you are done.

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

g:/rioengine/libs/include/irrklang/ik_ISound.h

Public Member Functions

Detailed Description

Member Function Documentation