paulscode.sound
Class Source

java.lang.Object
  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.