Package com.ardor3d.audio

Class Source

java.lang.Object
com.ardor3d.audio.Source
Direct Known Subclasses:
SourceJOAL
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
    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<? extends Library>
    libraryType
    The library class associated with this type of channel.
    protected 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).
    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 final 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.
    Vector3
    velocity
    Source's velocity in world-space, for use in Doppler effect.

  • Constructor Summary

    Constructors
    Constructor
    Description
    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(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(Source old, SoundBuffer soundBuffer)
    Constructor: Creates a new source matching the specified one.

  • Method Summary

    Modifier and Type
    Method
    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
    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 Details

    • libraryType

      protected Class<? extends Library> 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 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 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.

    • nextCodec

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

    • nextBuffers

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

    • 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 Details

    • 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 Details

    • 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.

    • 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, 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:
      c - Channel to stream on.
      buffer - Byte buffer containing raw audio data to stream.
      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.