paulscode.sound
Class Source

java.lang.Object
  extended by paulscode.sound.Source
Direct Known Subclasses:
SourceJavaSound, SourceJOAL, SourceLWJGLOpenAL

public class Source
extends java.lang.Object

The Source class is used to store information about a source. Source objects are stored in a map in the Library class. The information they contain is used to create library-specific sources. This is the template class which is extended for each specific library. This class is also used by the "No Sound" library to represent a mute source.

SoundSystem License:

You are free to use this library for any purpose, commercial or otherwise. You may modify this library or source code, and distribute it any way you like, provided the following conditions are met:
1) You may not falsely claim to be the author of this library or any unmodified portion of it.
2) You may not copyright this library or a modified version of it and then sue me for copyright infringement.
3) If you modify the source code, you must clearly document the changes made before redistributing the modified source code, so other users know it is not the original code.
4) You are not required to give me credit for this library in any derived work, but if you do, you must also mention my website: http://www.paulscode.com
5) I the author will not be responsible for any damages (physical, financial, or otherwise) caused by the use if this library or any part of it.
6) I the author do not guarantee, warrant, or make any representations, either expressed or implied, regarding the use of this library or any part of it.

Author: Paul Lamb
http://www.paulscode.com


Field Summary
 int attModel
          Attenuation model to use for this source.
 Channel channel
          Channel to play this source on.
protected  ICodec codec
          Codec used to read data for streaming sources.
 float distanceFromListener
          This source's distance from the listener.
 float distOrRoll
          Either fade distance or rolloff factor, depending on the value of attModel.
protected  float fadeInGain
          Specifies the gain factor used for the fade-in effect, or 1 when source is not currently fading in.
protected  long fadeInMilis
          Specifies the number of miliseconds it should take to fade in.
protected  float fadeOutGain
          Specifies the gain factor used for the fade-out effect, or -1 when source is not currently fading out.
protected  long fadeOutMilis
          Specifies the number of miliseconds it should take to fade out.
 FilenameURL filenameURL
          The audio file which this source should play.
 float gain
          This source's volume (a float between 0.0 - 1.0).
protected  long lastFadeCheck
          System time in miliseconds when the last fade in/out volume check occurred.
protected  java.lang.Class libraryType
          The library class associated with this type of channel.
protected  java.util.LinkedList<SoundBuffer> nextBuffers
          List of buffers to hold some initial data from the next sound in the queue.
protected  ICodec nextCodec
          Codec used to read in some initial data from the next sound in the queue.
protected  float pitch
          This value represents the source's pitch (float value between 0.5f - 2.0f).
 Vector3D position
          This source's position in 3D space.
 boolean preLoad
          Used by streaming sources to indicate whether or not the initial stream-buffers still need to be queued.
 boolean priority
          Determines whether or not this is a priority source.
 javax.sound.sampled.AudioFormat rawDataFormat
          Format the raw data will be in if this is a Raw Data Stream source.
 boolean rawDataStream
          True if this source is being directly fed with raw audio data.
 SoundBuffer soundBuffer
          Holds the data used by normal sources.
protected  java.lang.Object soundSequenceLock
          Ensures that only one thread accesses the soundSequenceQueue at a time.
protected  java.util.LinkedList<FilenameURL> soundSequenceQueue
          The list of files to stream when the current stream finishes.
 java.lang.String sourcename
          Unique name for this source.
 float sourceVolume
          This value should be used to manually increase or decrease source volume.
 boolean temporary
          Determines whether a source should be removed after it finishes playing.
 boolean toLoop
          Whether this source should loop or only play once.
 boolean toPlay
          Whether this source needs to be played (for example if it was playing and looping when it got culled).
 boolean toStream
          Whether or not this source should be streamed.
 Vector3D velocity
          Source's velocity in world-space, for use in Doppler effect.
 
Constructor Summary
Source(javax.sound.sampled.AudioFormat audioFormat, boolean priority, java.lang.String sourcename, float x, float y, float z, int attModel, float distOrRoll)
          Constructor: Creates a new streaming source that will be directly fed with raw audio data.
Source(boolean priority, boolean toStream, boolean toLoop, java.lang.String sourcename, FilenameURL filenameURL, SoundBuffer soundBuffer, float x, float y, float z, int attModel, float distOrRoll, boolean temporary)
          Constructor: Creates a new source using the specified parameters.
Source(Source old, SoundBuffer soundBuffer)
          Constructor: Creates a new source matching the specified one.
 
Method Summary
 void activate()
          Allows a previously culled source to be played again.
 boolean active()
          Returns false if the source has been culled.
 void changeSource(boolean priority, boolean toStream, boolean toLoop, java.lang.String sourcename, FilenameURL filenameURL, SoundBuffer soundBuffer, float x, float y, float z, int attModel, float distOrRoll, boolean temporary)
          Changes the sources peripheral information to match the supplied parameters.
 boolean checkFadeOut()
          Resets this source's volume if it is fading out or in.
 void cleanup()
          Shuts the source down and removes references to all instantiated objects.
 void cull()
          Stops and flushes the source, and prevents it from being played again until the activate() is called.
 void dequeueSound(java.lang.String filename)
          Removes the first occurrence of the specified filename from the list of sounds to play when the previous stream ends.
protected  boolean errorCheck(boolean error, java.lang.String message)
          Prints the specified message if error is true.
protected  void errorMessage(java.lang.String message)
          Prints an error message.
 void fadeOut(FilenameURL filenameURL, long milis)
          Fades out the volume of whatever this source is currently playing, then begins playing the specified filename at the source's previously assigned volume level.
 void fadeOutIn(FilenameURL filenameURL, long milisOut, long milisIn)
          Fades out the volume of whatever this source is currently playing, then fades the volume back in playing the specified file.
 int feedRawAudioData(Channel c, byte[] buffer)
          Feeds raw data to the specified channel.
 void flush()
          Dequeues any previously queued data.
 java.lang.String getClassName()
          Returns the name of the class.
 float getDistanceFromListener()
          Returns the source's distance from the listener.
 float getPitch()
          Returns the pitch of the specified source.
 int getSoundSequenceQueueSize()
          Returns the size of the sound sequence queue (if this is a streaming source).
protected  void importantMessage(java.lang.String message)
          Prints an important message.
 boolean incrementSoundSequence()
          Removes the next filename/URL from the sound sequence queue and assigns it to this source.
 void listenerMoved()
          Called every time the listener's position or orientation changes.
protected  void message(java.lang.String message)
          Prints a message.
 float millisecondsPlayed()
          Returns the number of miliseconds since the source began playing.
 void pause()
          Pauses the source.
 boolean paused()
          Returns true if the source has been paused.
 void play(Channel c)
          Plays the source on the specified channel.
 boolean playing()
          Returns true if the source is playing.
 void positionChanged()
          Called every time the source changes position.
 boolean preLoad()
          Queues up the initial stream-buffers for the stream.
protected  void printStackTrace(java.lang.Exception e)
          Prints an exception's error message followed by the stack trace.
 void queueSound(FilenameURL filenameURL)
          If this is a streaming source, queues up the next sound to play when the previous stream ends.
 boolean readBuffersFromNextSoundInSequence()
          Reads in initial buffers of data from the next sound in the sound sequence queue, to reduce lag when the transition occurrs.
 boolean reverseByteOrder()
          Indicates whether or not this source's associated library requires some codecs to reverse-order the audio data they generate.
 void rewind()
          Rewinds the source.
 void setAttenuation(int model)
          Sets this source's attenuation model.
 void setDistOrRoll(float dr)
          Sets this source's fade distance or rolloff factor, depending on the attenuation model.
 void setLooping(boolean lp)
          Sets whether this source should loop or only play once.
 void setPitch(float value)
          Manually sets the specified source's pitch.
 void setPosition(float x, float y, float z)
          Moves the source to the specified position.
 void setPriority(boolean pri)
          Sets whether or not this source is a priority source.
 void setTemporary(boolean tmp)
          Sets whether or not this source should be removed when it finishes playing.
 void setVelocity(float x, float y, float z)
          Sets this source's velocity, for use in Doppler effect.
 void stop()
          Stops the source.
 boolean stopped()
          Returns true if the source has been stopped.
 boolean stream()
          Streams the source on its current channel
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

libraryType

protected java.lang.Class libraryType
The library class associated with this type of channel.


rawDataStream

public boolean rawDataStream
True if this source is being directly fed with raw audio data.


rawDataFormat

public javax.sound.sampled.AudioFormat rawDataFormat
Format the raw data will be in if this is a Raw Data Stream source.


temporary

public boolean temporary
Determines whether a source should be removed after it finishes playing.


priority

public boolean priority
Determines whether or not this is a priority source. Priority sources will not be overwritten by other sources when there are no available channels.


toStream

public boolean toStream
Whether or not this source should be streamed.


toLoop

public boolean toLoop
Whether this source should loop or only play once.


toPlay

public boolean toPlay
Whether this source needs to be played (for example if it was playing and looping when it got culled).


sourcename

public java.lang.String sourcename
Unique name for this source. More than one source can not have the same sourcename.


filenameURL

public FilenameURL filenameURL
The audio file which this source should play.


position

public Vector3D position
This source's position in 3D space.


attModel

public int attModel
Attenuation model to use for this source.


distOrRoll

public float distOrRoll
Either fade distance or rolloff factor, depending on the value of attModel.


velocity

public Vector3D velocity
Source's velocity in world-space, for use in Doppler effect.


gain

public float gain
This source's volume (a float between 0.0 - 1.0). This value is used internally for attenuation, and should not be used to manually change a source's volume.


sourceVolume

public float sourceVolume
This value should be used to manually increase or decrease source volume.


pitch

protected float pitch
This value represents the source's pitch (float value between 0.5f - 2.0f).


distanceFromListener

public float distanceFromListener
This source's distance from the listener.


channel

public Channel channel
Channel to play this source on.


soundBuffer

public SoundBuffer soundBuffer
Holds the data used by normal sources.


codec

protected ICodec codec
Codec used to read data for streaming sources.


nextCodec

protected ICodec nextCodec
Codec used to read in some initial data from the next sound in the queue.


nextBuffers

protected java.util.LinkedList<SoundBuffer> nextBuffers
List of buffers to hold some initial data from the next sound in the queue.


soundSequenceQueue

protected java.util.LinkedList<FilenameURL> soundSequenceQueue
The list of files to stream when the current stream finishes.


soundSequenceLock

protected final java.lang.Object soundSequenceLock
Ensures that only one thread accesses the soundSequenceQueue at a time.


preLoad

public boolean preLoad
Used by streaming sources to indicate whether or not the initial stream-buffers still need to be queued.


fadeOutGain

protected float fadeOutGain
Specifies the gain factor used for the fade-out effect, or -1 when source is not currently fading out.


fadeInGain

protected float fadeInGain
Specifies the gain factor used for the fade-in effect, or 1 when source is not currently fading in.


fadeOutMilis

protected long fadeOutMilis
Specifies the number of miliseconds it should take to fade out.


fadeInMilis

protected long fadeInMilis
Specifies the number of miliseconds it should take to fade in.


lastFadeCheck

protected long lastFadeCheck
System time in miliseconds when the last fade in/out volume check occurred.

Constructor Detail

Source

public Source(boolean priority,
              boolean toStream,
              boolean toLoop,
              java.lang.String sourcename,
              FilenameURL filenameURL,
              SoundBuffer soundBuffer,
              float x,
              float y,
              float z,
              int attModel,
              float distOrRoll,
              boolean temporary)
Constructor: Creates a new source using the specified parameters.

Parameters:
priority - Setting this to true will prevent other sounds from overriding this one.
toStream - Setting this to true will create a streaming source.
toLoop - Should this source loop, or play only once.
sourcename - A unique identifier for this source. Two sources may not use the same sourcename.
filenameURL - The filename/URL of the sound file to play at this source.
soundBuffer - Buffer containing audio data, or null if not loaded yet.
x - X position for this source.
y - Y position for this source.
z - Z position for this source.
attModel - Attenuation model to use.
distOrRoll - Either the fading distance or rolloff factor, depending on the value of 'att'.
temporary - Whether or not to remove this source after it finishes playing.

Source

public Source(Source old,
              SoundBuffer soundBuffer)
Constructor: Creates a new source matching the specified one.

Parameters:
old - Source to copy information from.
soundBuffer - Buffer containing audio data, or null if not loaded yet.

Source

public Source(javax.sound.sampled.AudioFormat audioFormat,
              boolean priority,
              java.lang.String sourcename,
              float x,
              float y,
              float z,
              int attModel,
              float distOrRoll)
Constructor: Creates a new streaming source that will be directly fed with raw audio data.

Parameters:
audioFormat - Format that the data will be in.
priority - Setting this to true will prevent other sounds from overriding this one.
sourcename - A unique identifier for this source. Two sources may not use the same sourcename.
x - X position for this source.
y - Y position for this source.
z - Z position for this source.
attModel - Attenuation model to use.
distOrRoll - Either the fading distance or rolloff factor, depending on the value of 'att'.
Method Detail

cleanup

public void cleanup()
Shuts the source down and removes references to all instantiated objects.


queueSound

public void queueSound(FilenameURL filenameURL)
If this is a streaming source, queues up the next sound to play when the previous stream ends. This method has no effect on non-streaming sources.

Parameters:
filenameURL - The filename/URL of the sound file to stream next.

dequeueSound

public void dequeueSound(java.lang.String filename)
Removes the first occurrence of the specified filename from the list of sounds to play when the previous stream ends. This method has no effect on non-streaming sources.

Parameters:
filename - Filename/identifier of a sound file to remove from the queue.

fadeOut

public void fadeOut(FilenameURL filenameURL,
                    long milis)
Fades out the volume of whatever this source is currently playing, then begins playing the specified filename at the source's previously assigned volume level. If the filename parameter is null or empty, the source will simply fade out and stop. The miliseconds parameter must be non-negative or zero. This method will remove anything that is currently in the list of queued sounds that would have played next when the current sound finished playing. This method has no effect on non-streaming sources.

Parameters:
filenameURL - Filename/URL of the sound file to play next, or null for none.
milis - Number of miliseconds the fadeout should take.

fadeOutIn

public void fadeOutIn(FilenameURL filenameURL,
                      long milisOut,
                      long milisIn)
Fades out the volume of whatever this source is currently playing, then fades the volume back in playing the specified file. Final volume after fade-in completes will be equal to the source's previously assigned volume level. The filenameURL parameter may not be null or empty. The miliseconds parameters must be non-negative or zero. This method will remove anything that is currently in the list of queued sounds that would have played next when the current sound finished playing. This method has no effect on non-streaming sources.

Parameters:
filenameURL - Filename/URL of the sound file to play next, or null for none.
milisOut - Number of miliseconds the fadeout should take.
milisIn - Number of miliseconds the fadein should take.

checkFadeOut

public boolean checkFadeOut()
Resets this source's volume if it is fading out or in. Returns true if this source is currently in the process of fading out. When fade-out completes, this method transitions the source to the next sound in the sound sequence queue if there is one. This method has no effect on non-streaming sources.

Returns:
True if this source is in the process of fading out.

incrementSoundSequence

public boolean incrementSoundSequence()
Removes the next filename/URL from the sound sequence queue and assigns it to this source. This method has no effect on non-streaming sources. This method is used internally by SoundSystem, and it is unlikely that the user will ever need to use it.

Returns:
True if there was something in the queue.

readBuffersFromNextSoundInSequence

public boolean readBuffersFromNextSoundInSequence()
Reads in initial buffers of data from the next sound in the sound sequence queue, to reduce lag when the transition occurrs. This method has no effect on non-streaming sources. This method is used internally by SoundSystem, and it is unlikely that the user will ever need to use it.

Returns:
False if there is nothing in the queue to read from.

getSoundSequenceQueueSize

public int getSoundSequenceQueueSize()
Returns the size of the sound sequence queue (if this is a streaming source).

Returns:
Number of sounds left in the queue, or zero if none.

setTemporary

public void setTemporary(boolean tmp)
Sets whether or not this source should be removed when it finishes playing.

Parameters:
tmp - True or false.

listenerMoved

public void listenerMoved()
Called every time the listener's position or orientation changes.


setPosition

public void setPosition(float x,
                        float y,
                        float z)
Moves the source to the specified position.

Parameters:
x - X coordinate to move to.
y - Y coordinate to move to.
z - Z coordinate to move to.

positionChanged

public void positionChanged()
Called every time the source changes position.


setPriority

public void setPriority(boolean pri)
Sets whether or not this source is a priority source. A priority source will not be overritten by another source if there are no channels available to play on.

Parameters:
pri - True or false.

setLooping

public void setLooping(boolean lp)
Sets whether this source should loop or only play once.

Parameters:
lp - True or false.

setAttenuation

public void setAttenuation(int model)
Sets this source's attenuation model.

Parameters:
model - Attenuation model to use.

setDistOrRoll

public void setDistOrRoll(float dr)
Sets this source's fade distance or rolloff factor, depending on the attenuation model.

Parameters:
dr - New value for fade distance or rolloff factor.

setVelocity

public void setVelocity(float x,
                        float y,
                        float z)
Sets this source's velocity, for use in Doppler effect.

Parameters:
x - Velocity along world x-axis.
y - Velocity along world y-axis.
z - Velocity along world z-axis.

getDistanceFromListener

public float getDistanceFromListener()
Returns the source's distance from the listener.

Returns:
How far away the source is.

setPitch

public void setPitch(float value)
Manually sets the specified source's pitch.

Parameters:
value - A float value ( 0.5f - 2.0f ).

getPitch

public float getPitch()
Returns the pitch of the specified source.

Returns:
Float value representing the source pitch (0.5f - 2.0f).

reverseByteOrder

public boolean reverseByteOrder()
Indicates whether or not this source's associated library requires some codecs to reverse-order the audio data they generate.

Returns:
True if audio data should be reverse-ordered.

changeSource

public void changeSource(boolean priority,
                         boolean toStream,
                         boolean toLoop,
                         java.lang.String sourcename,
                         FilenameURL filenameURL,
                         SoundBuffer soundBuffer,
                         float x,
                         float y,
                         float z,
                         int attModel,
                         float distOrRoll,
                         boolean temporary)
Changes the sources peripheral information to match the supplied parameters.

Parameters:
priority - Setting this to true will prevent other sounds from overriding this one.
toStream - Setting this to true will create a streaming source.
toLoop - Should this source loop, or play only once.
sourcename - A unique identifier for this source. Two sources may not use the same sourcename.
filenameURL - Filename/URL of the sound file to play at this source.
x - X position for this source.
y - Y position for this source.
z - Z position for this source.
attModel - Attenuation model to use.
distOrRoll - Either the fading distance or rolloff factor, depending on the value of 'att'.
temporary - Whether or not to remove this source after it finishes playing.

feedRawAudioData

public int feedRawAudioData(Channel c,
                            byte[] buffer)
Feeds raw data to the specified channel.

Parameters:
buffer - Byte buffer containing raw audio data to stream.
c - Channel to stream on.
Returns:
Number of prior buffers that have been processed, or -1 if unable to queue the buffer (if the source was culled, for example).

play

public void play(Channel c)
Plays the source on the specified channel.

Parameters:
c - Channel to play on.

stream

public boolean stream()
Streams the source on its current channel

Returns:
False when stream has finished playing.

preLoad

public boolean preLoad()
Queues up the initial stream-buffers for the stream.

Returns:
False if the end of the stream was reached.

pause

public void pause()
Pauses the source.


stop

public void stop()
Stops the source.


rewind

public void rewind()
Rewinds the source. If the source was paused, then it is stopped.


flush

public void flush()
Dequeues any previously queued data.


cull

public void cull()
Stops and flushes the source, and prevents it from being played again until the activate() is called.


activate

public void activate()
Allows a previously culled source to be played again.


active

public boolean active()
Returns false if the source has been culled.

Returns:
True or False

playing

public boolean playing()
Returns true if the source is playing.

Returns:
True or False

stopped

public boolean stopped()
Returns true if the source has been stopped.

Returns:
True or False

paused

public boolean paused()
Returns true if the source has been paused.

Returns:
True or False

millisecondsPlayed

public float millisecondsPlayed()
Returns the number of miliseconds since the source began playing.

Returns:
miliseconds, or -1 if not playing or unable to calculate

getClassName

public java.lang.String getClassName()
Returns the name of the class.

Returns:
SoundLibraryXXXX.

message

protected void message(java.lang.String message)
Prints a message.

Parameters:
message - Message to print.

importantMessage

protected void importantMessage(java.lang.String message)
Prints an important message.

Parameters:
message - Message to print.

errorCheck

protected boolean errorCheck(boolean error,
                             java.lang.String message)
Prints the specified message if error is true.

Parameters:
error - True or False.
message - Message to print if error is true.
Returns:
True if error is true.

errorMessage

protected void errorMessage(java.lang.String message)
Prints an error message.

Parameters:
message - Message to print.

printStackTrace

protected void printStackTrace(java.lang.Exception e)
Prints an exception's error message followed by the stack trace.

Parameters:
e - Exception containing the information to print.