espresso3d.engine.sound
Class E3DSoundHandler

java.lang.Object
  espresso3d.engine.base.E3DEngineItem
      espresso3d.engine.sound.E3DSoundHandler

public class E3DSoundHandler

extends E3DEngineItem

Author:

Curt TODO To change the template for this generated type comment go to Window - Preferences - Java - Code Style - Code Templates

Constructor Summary

E3DSoundHandler(E3DEngine engine)

Method Summary

void	addSound(E3DSound sound) Adds a sound to the preloaded sound list.
void	discardOldSounds() This is called by the engine to iterate through all playing sounds that have been set to play and ensure they are still playing.
E3DSound	getSound(java.lang.String soundName)
boolean	isSoundPaused(E3DSound sound) Checks if a sound is paused or not using the AL state of the sound.
boolean	isSoundPlaying(E3DSound sound) Checks if a sound is playing or not.
boolean	isSoundStopped(E3DSound sound) Checks if a sound is stopped or not.
void	loadSoundSet(java.lang.String soundSetFileName, boolean fromJar) Loads the soundSet into memory.
E3DSound2D	loop2DSound(java.lang.String soundName, double pitch, double volume) Loops a 2D sound, or a sound that has no position, until it is manually stopped.
E3DSound3D	loop3DSound(java.lang.String soundName, E3DActor sourceActor, double pitch, double volume, double referenceDistance, double maxDistance, double falloffFactor) Loops the specified until manually stoppped and binds it to the sourceActor so as the sourceActor moves, the sound will also move.
void	pauseSound(E3DSound sound) Pauses a sound.
E3DSound2D	play2DSound(java.lang.String soundName, double pitch, double volume) Plays a 2D sound, or a sound that has no position, 1 time.
E3DSound3D	play3DSound(java.lang.String soundName, E3DActor sourceActor, double pitch, double volume, double referenceDistance, double maxDistance, double falloffFactor) Plays the specified sound 1 time and binds it to the sourceActor so as the sourceActor moves, the sound will also move.
void	removeAllSounds()
void	removeSound(E3DSound sound)
void	removeSound(java.lang.String soundName)
void	rewindSound(E3DSound sound) Rewinds a sound to the beginning.
void	setListener(E3DActor listenerActor) Usually automatically called by the engine to be the current viewports camera actor
void	stopSound(E3DSound sound) This can be used to stop any sound, 2D or 3D by passing the sound object returned when the sound was set to play or loop.
void	unpauseSound(E3DSound sound) Unpauses a paused sound.
void	update3DSoundOrientation(E3DSound3D sound3D, E3DVector3F velocity) Updates the sounds position and velocity to be that of its source actor.

Methods inherited from class espresso3d.engine.base.E3DEngineItem

getEngine, setEngine

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

E3DSoundHandler

public E3DSoundHandler(E3DEngine engine)
                throws org.lwjgl.LWJGLException

Method Detail

getSound

public E3DSound getSound(java.lang.String soundName)

addSound

public void addSound(E3DSound sound)

Adds a sound to the preloaded sound list. If the sound is already loaded, the existing sound will be unloaded from memory and this new sound will be loaded in its place.

Parameters:

sound -

removeSound

public void removeSound(java.lang.String soundName)

removeSound

public void removeSound(E3DSound sound)

removeAllSounds

public void removeAllSounds()

loadSoundSet

public void loadSoundSet(java.lang.String soundSetFileName,
                         boolean fromJar)
                  throws E3DMissingEngineException,
                         E3DInvalidFileFormatException,
                         E3DInvalidSoundFormatException,
                         java.io.IOException

Loads the soundSet into memory. Current sounds are not removed.

Parameters:

fromJar -

Throws:

E3DMissingEngineException

E3DInvalidFileFormatException

E3DInvalidSoundFormatException

java.io.IOException

play3DSound

public E3DSound3D play3DSound(java.lang.String soundName,
                              E3DActor sourceActor,
                              double pitch,
                              double volume,
                              double referenceDistance,
                              double maxDistance,
                              double falloffFactor)
                       throws E3DSoundOutOfSourcesException

Plays the specified sound 1 time and binds it to the sourceActor so as the sourceActor moves, the sound will also move.

Parameters:

soundName - The name given to the sound that was loaded from the soundset (or manually)

sourceActor - The actor this sound will be bound to (so when the actor moves, this sound moves with it)

pitch - The pitch of the sound when it is played

volume - The volume of the sound when it is played

referenceDistance - This is the distance away you can be from the object and hear the sound at full volume (volume variable)

maxDistance - The maximum distance away you can hear the sound

falloffFactor - A falloff scalar. The higher this is, the faster the sound will falloff. Usually use 1

Returns:

Returns null if the sound is not found or a unique E3DSound3D object representing this sound or if the sound handler is out of free sources (sources are pooled and free up as other sounds end). This will be used for checking if the sound is playing and stopping the sound. The sound will be removed from the system after the sound has stopped (either the end of the sound or manual intervention).

Throws:

E3DSoundOutOfSourcesException - - This is a completely recoverable exception and is used to indicate that the engine is temporarily out of sources for sounds (ie: too many playing at one time). As a sound stops, the engine will free up that source for later use so sources will free up (unless they are all looping and never stop, in which case if you really need a sound you should handle this and stop one to free it up)

loop3DSound

public E3DSound3D loop3DSound(java.lang.String soundName,
                              E3DActor sourceActor,
                              double pitch,
                              double volume,
                              double referenceDistance,
                              double maxDistance,
                              double falloffFactor)
                       throws E3DSoundOutOfSourcesException

Loops the specified until manually stoppped and binds it to the sourceActor so as the sourceActor moves, the sound will also move.

Parameters:

soundName - The name given to the sound that was loaded from the soundset (or manually)

sourceActor - The actor this sound will be bound to (so when the actor moves, this sound moves with it)

pitch - The pitch of the sound when it is played

volume - The volume of the sound when it is played

referenceDistance - This is the distance away you can be from the object and hear the sound at full volume (volume variable)

maxDistance - The maximum distance away you can hear the sound

falloffFactor - A falloff scalar. The higher this is, the faster the sound will falloff. Usually use 1

Returns:

Returns null if the sound is not found or a unique E3DSound3D object representing this sound. This will be used for checking if the sound is playing and stopping the sound. The sound will be removed from the system after the sound has stopped (either the end of the sound or manual intervention).

Throws:

E3DSoundOutOfSourcesException - - This is a completely recoverable exception and is used to indicate that the engine is temporarily out of sources for sounds (ie: too many playing at one time). As a sound stops, the engine will free up that source for later use so sources will free up (unless they are all looping and never stop, in which case if you really need a sound you should handle this and stop one to free it up)

play2DSound

public E3DSound2D play2DSound(java.lang.String soundName,
                              double pitch,
                              double volume)
                       throws E3DSoundOutOfSourcesException

Plays a 2D sound, or a sound that has no position, 1 time.

Parameters:

soundName - The name given to the sound that was loaded from the soundset (or manually)

pitch - The pitch of the sound when it is played

volume - The volume of the sound when it is played

Returns:

Returns null if the sound is not found or a unique E3DSound2D object representing this sound. This will be used for checking if the sound is playing and stopping the sound. The sound will be removed from the system after the sound has stopped (either the end of the sound or manual intervention). When the sound has been removed, the discarded flag will be set to true in the sound.

Throws:

E3DSoundOutOfSourcesException - - This is a completely recoverable exception and is used to indicate that the engine is temporarily out of sources for sounds (ie: too many playing at one time). As a sound stops, the engine will free up that source for later use so sources will free up (unless they are all looping and never stop, in which case if you really need a sound you should handle this and stop one to free it up)

loop2DSound

public E3DSound2D loop2DSound(java.lang.String soundName,
                              double pitch,
                              double volume)
                       throws E3DSoundOutOfSourcesException

Loops a 2D sound, or a sound that has no position, until it is manually stopped.

Parameters:

soundName - The name given to the sound that was loaded from the soundset (or manually)

pitch - The pitch of the sound when it is played

volume - The volume of the sound when it is played

Returns:

Returns null if the sound is not found or a unique E3DSound2D object representing this sound. This will be used for checking if the sound is playing and stopping the sound. The sound will be removed from the system after the sound has stopped (either the end of the sound or manual intervention). When the sound has been removed, the discarded flag will be set to true in the sound.

Throws:

E3DSoundOutOfSourcesException - - This is a completely recoverable exception and is used to indicate that the engine is temporarily out of sources for sounds (ie: too many playing at one time). As a sound stops, the engine will free up that source for later use so sources will free up (unless they are all looping and never stop, in which case if you really need a sound you should handle this and stop one to free it up)

discardOldSounds

public void discardOldSounds()

This is called by the engine to iterate through all playing sounds that have been set to play and ensure they are still playing. If they have stopped, their al source is discarded.

stopSound

public void stopSound(E3DSound sound)

This can be used to stop any sound, 2D or 3D by passing the sound object returned when the sound was set to play or loop. After the sound is stopped, its alsourceid is freed and its discarded flag is set to true.

Parameters:

sound - An instance of a sound - not a preloaded sound.

pauseSound

public void pauseSound(E3DSound sound)

Pauses a sound. To resume its play, unpauseSound must be called. When paused, the sounds paused flag is set to true

Parameters:

sound -

unpauseSound

public void unpauseSound(E3DSound sound)

Unpauses a paused sound. This will do nothing if the sound hasn't already been paused

Parameters:

sound - An instance of a sound - not a preloaded sound.

rewindSound

public void rewindSound(E3DSound sound)

Rewinds a sound to the beginning. The sound keeps playing if it is playing, or stays paused if it is paused.

Parameters:

sound - An instance of a sound - not a preloaded sound.

isSoundPlaying

public boolean isSoundPlaying(E3DSound sound)

Checks if a sound is playing or not. Paused does not count as playing

Parameters:

sound - The sound to check

Returns:

Returns true if it is currently playing, otherwise false. After a sound has been stopped, it will quickly be discarded so you may also want to check the sound's discarded flag.

isSoundPaused

public boolean isSoundPaused(E3DSound sound)

Checks if a sound is paused or not using the AL state of the sound. This should normally be the same value that is retrieved from teh sounds paused flag (and it would be much faster to check that).

Parameters:

sound -

Returns:

isSoundStopped

public boolean isSoundStopped(E3DSound sound)

Checks if a sound is stopped or not. After a sound is stopped, its source will quickly be discarded by the engine and its flag will be set to discarded meaning play must be called again.

Parameters:

sound -

Returns:

update3DSoundOrientation

public void update3DSoundOrientation(E3DSound3D sound3D,
                                     E3DVector3F velocity)

Updates the sounds position and velocity to be that of its source actor. Velocity can be null if the actor isn't moving (just rotating)

Parameters:

velocity -

setListener

public void setListener(E3DActor listenerActor)

Usually automatically called by the engine to be the current viewports camera actor