Source (Etyl Commons 1.0.2 API)

java.lang.Object
- paulscode.sound.Source

Direct Known Subclasses:

SourceJavaSound
```
public class Source
extends 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

Fields
Modifier and Type	Field and Description
`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 Class`	`libraryType` The library class associated with this type of channel.
`protected float`	`pitch` This value represents the source's pitch (float value between 0.5f - 2.0f).
`com.badlogic.gdx.math.Vector3`	`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.
`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 Object`	`soundSequenceLock` Ensures that only one thread accesses the soundSequenceQueue at a time.
`protected LinkedList<FilenameURL>`	`soundSequenceQueue` The list of files to stream when the current stream finishes.
`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.
`com.badlogic.gdx.math.Vector3`	`velocity` Source's velocity in world-space, for use in Doppler effect.

Constructor Summary

Constructors
Constructor and Description
`Source(AudioFormat audioFormat, boolean priority, 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, 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

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`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, 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(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, String message)` Prints the specified message if error is true.
`protected void`	`errorMessage(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.
`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(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(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(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`	`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 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 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 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 com.badlogic.gdx.math.Vector3 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 com.badlogic.gdx.math.Vector3 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.
  - soundSequenceQueue
```
protected LinkedList<FilenameURL> soundSequenceQueue
```
    The list of files to stream when the current stream finishes.
  - soundSequenceLock
```
protected final 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,
              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(AudioFormat audioFormat,
              boolean priority,
              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(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.
  - 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,
                         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 String getClassName()
```
    Returns the name of the class.
    
    Returns:
    
    SoundLibraryXXXX.
  - message
```
protected void message(String message)
```
    Prints a message.
    
    Parameters:
    
    message - Message to print.
  - importantMessage
```
protected void importantMessage(String message)
```
    Prints an important message.
    
    Parameters:
    
    message - Message to print.
  - errorCheck
```
protected boolean errorCheck(boolean error,
                             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(String message)
```
    Prints an error message.
    
    Parameters:
    
    message - Message to print.
  - printStackTrace
```
protected void printStackTrace(Exception e)
```
    Prints an exception's error message followed by the stack trace.
    
    Parameters:
    
    e - Exception containing the information to print.

Class Source

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

libraryType

rawDataStream

rawDataFormat

temporary

priority

toStream

toLoop

toPlay

sourcename

filenameURL

position

attModel

distOrRoll

velocity

gain

sourceVolume

pitch

distanceFromListener

channel

soundBuffer

codec

soundSequenceQueue

soundSequenceLock

preLoad

fadeOutGain

fadeInGain

fadeOutMilis

fadeInMilis

lastFadeCheck

Constructor Detail

Source

Source

Source

Method Detail

cleanup

queueSound

dequeueSound

fadeOut

fadeOutIn

checkFadeOut

incrementSoundSequence

getSoundSequenceQueueSize

setTemporary

listenerMoved

setPosition

positionChanged

setPriority

setLooping

setAttenuation

setDistOrRoll

setVelocity

getDistanceFromListener

setPitch

getPitch

reverseByteOrder

changeSource

feedRawAudioData

play

stream

preLoad

pause

stop

rewind

flush

cull

activate

active

playing

stopped

paused

millisecondsPlayed

getClassName

message

importantMessage