Package jmri.jmrit.audio

Class AbstractAudioSource

  • All Implemented Interfaces:
    java.lang.Comparable<NamedBean>, Audio, PropertyChangeProvider, AudioSource, NamedBean
    Direct Known Subclasses:
    JavaSoundAudioSource, JoalAudioSource, NullAudioSource
    public abstract class AbstractAudioSource
extends AbstractAudio
implements AudioSource
    Base implementation of the AudioSource class.

    Specific implementations will extend this base class.

    This file is part of JMRI.

    JMRI is free software; you can redistribute it and/or modify it under the terms of version 2 of the GNU General Public License as published by the Free Software Foundation. See the "COPYING" file for a copy of this license.

    JMRI is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

    • Constructor Detail

      • AbstractAudioSource

        public AbstractAudioSource​(java.lang.String systemName)
        Abstract constructor for new AudioSource with system name
        Parameters:
        systemName - AudioSource object system name (e.g. IAS1)

      • AbstractAudioSource

        public AbstractAudioSource​(java.lang.String systemName,
                           java.lang.String userName)
        Abstract constructor for new AudioSource with system name and user name
        Parameters:
        systemName - AudioSource object system name (e.g. IAS1)
        userName - AudioSource object user name

    • Method Detail

      • getSubType

        public char getSubType()
        Description copied from interface: Audio
        An Audio object can represent one of a number of subtypes of object.

        This method enables us to determine which of those subtypes this particular instance is and be able to process accordingly.

        Current supported subtypes are:

        • B = Buffer
        • L = Listener
        • S = Source
        Specified by:
        getSubType in interface Audio
        Returns:
        subType char

      • queueBuffers

        public boolean queueBuffers​(java.util.Queue<AudioBuffer> audioBuffers)
        Description copied from interface: AudioSource
        Queues the linked AudioBuffer object to this Source's buffer queue

        Applies only to sub-types:

        • Source
        Specified by:
        queueBuffers in interface AudioSource
        Parameters:
        audioBuffers - the AudioBuffer object to enqueue to this AudioSource
        Returns:
        true if successfully queued audioBuffers; false otherwise

      • setAssignedBuffer

        public void setAssignedBuffer​(java.lang.String bufferSystemName)
        Description copied from interface: AudioSource
        Sets the system name of the linked AudioBuffer object

        Applies only to sub-types:

        • Source
        Specified by:
        setAssignedBuffer in interface AudioSource
        Parameters:
        bufferSystemName - the SystemName of the AudioBuffer (i.e. IAB1) to bind to this AudioSource

      • getAssignedBufferName

        public java.lang.String getAssignedBufferName()
        Description copied from interface: AudioSource
        Return system name of linked AudioBuffer object

        Applies only to sub-types:

        • Source
        Specified by:
        getAssignedBufferName in interface AudioSource
        Returns:
        sysName the SystemName of the AudioBuffer bound to this AudioSource

      • setPosition

        public void setPosition​(javax.vecmath.Vector3f pos)
        Description copied from interface: AudioSource
        Sets the position of this AudioSource object

        Applies only to sub-types:

        • Listener
        • Source
        Specified by:
        setPosition in interface AudioSource
        Parameters:
        pos - 3d position vector

      • setPosition

        public void setPosition​(float x,
                        float y,
                        float z)
        Description copied from interface: AudioSource
        Sets the position of this AudioSource object in x, y and z planes

        Applies only to sub-types:

        • Listener
        • Source
        Specified by:
        setPosition in interface AudioSource
        Parameters:
        x - x-coordinate
        y - y-coordinate
        z - z-coordinate

      • setPosition

        public void setPosition​(float x,
                        float y)
        Description copied from interface: AudioSource
        Sets the position of this AudioSource object in x and y planes with z plane position fixed at zero

        Equivalent to setPosition(x, y, 0.0f)

        Applies only to sub-types:

        • Listener
        • Source
        Specified by:
        setPosition in interface AudioSource
        Parameters:
        x - x-coordinate
        y - y-coordinate

      • getPosition

        public javax.vecmath.Vector3f getPosition()
        Description copied from interface: AudioSource
        Returns the position of this AudioSource object as a 3-dimensional vector.

        Applies only to sub-types:

        • Listener
        • Source
        Specified by:
        getPosition in interface AudioSource
        Returns:
        3d position vector

      • getCurrentPosition

        public javax.vecmath.Vector3f getCurrentPosition()
        Description copied from interface: AudioSource
        Returns the current position of this AudioSource object as a 3-dimensional vector.

        Applies only to sub-types:

        • Listener
        • Source
        Specified by:
        getCurrentPosition in interface AudioSource
        Returns:
        3d position vector

      • setPositionRelative

        public void setPositionRelative​(boolean relative)
        Description copied from interface: AudioSource
        Sets the position of this AudioSource object to be relative to the position of the AudioListener object or absolute.

        Applies only to sub-types:

        • Source
        Specified by:
        setPositionRelative in interface AudioSource
        Parameters:
        relative - position relative or absolute

      • isPositionRelative

        public boolean isPositionRelative()
        Description copied from interface: AudioSource
        Returns a boolean value that determines if the position of this AudioSource object is relative to the position of the AudioListener object or absolute.

        Applies only to sub-types:

        • Source
        Specified by:
        isPositionRelative in interface AudioSource
        Returns:
        boolean position relative

      • setVelocity

        public void setVelocity​(javax.vecmath.Vector3f vel)
        Description copied from interface: AudioSource
        Sets the velocity of this AudioSource object

        Applies only to sub-types:

        • Listener
        • Source
        Specified by:
        setVelocity in interface AudioSource
        Parameters:
        vel - 3d velocity vector

      • getVelocity

        public javax.vecmath.Vector3f getVelocity()
        Description copied from interface: AudioSource
        Returns the velocity of this AudioSource object

        Applies only to sub-types:

        • Listener
        • Source
        Specified by:
        getVelocity in interface AudioSource
        Returns:
        3d velocity vector

      • resetCurrentPosition

        public void resetCurrentPosition()
        Description copied from interface: AudioSource
        Method to reset the current position of this AudioSource object to the initial position as defined by setPosition.

        Applies only to sub-types:

        • Listener
        • Source
        Specified by:
        resetCurrentPosition in interface AudioSource

      • changePosition

        protected abstract void changePosition​(javax.vecmath.Vector3f pos)
        Change the current position of this source.
        Parameters:
        pos - new position

      • setGain

        public void setGain​(float gain)
        Description copied from interface: AudioSource
        Set the gain of this AudioSource object

        Default value = 1.0f

        Applies only to sub-types:

        • Listener
        • Source
        Specified by:
        setGain in interface AudioSource
        Parameters:
        gain - the gain of this AudioSource

      • getGain

        public float getGain()
        Description copied from interface: AudioSource
        Return the currently stored gain setting

        Default value = 1.0f

        Applies only to sub-types:

        • Listener
        • Source
        Specified by:
        getGain in interface AudioSource
        Returns:
        gain setting of this AudioSource

      • calculateGain

        protected abstract void calculateGain()
        Calculate the gain of this AudioSource based on distance from listener and fade levels.

      • setPitch

        public void setPitch​(float pitch)
        Description copied from interface: AudioSource
        Set the pitch of this AudioSource object

        Values are restricted from 0.5f to 2.0f, i.e. half to double

        Default value = 1.0f

        Applies only to sub-types:

        • Source
        Specified by:
        setPitch in interface AudioSource
        Parameters:
        pitch - the pitch of this AudioSource

      • getPitch

        public float getPitch()
        Description copied from interface: AudioSource
        Return the current pitch setting

        Values are restricted from 0.5f to 2.0f, i.e. half to double

        Default value = 1.0f

        Applies only to sub-types:

        • Source
        Specified by:
        getPitch in interface AudioSource
        Returns:
        pitch of this AudioSource

      • setReferenceDistance

        public void setReferenceDistance​(float referenceDistance)
        Description copied from interface: AudioSource
        Set the reference distance of this AudioSource object.

        Default value = 1.0f

        The Reference Distance is one of the main parameters you have for controlling the way that sounds attenuate with distance. A Source with Reference Distance set to 5 (meters) will be at maximum volume while it is within 5 metere of the listener, and start to fade out as it moves further away. At 10 meters it will be at half volume, and at 20 meters at a quarter volume, etc ...

        Applies only to sub-types:

        • Source
        Specified by:
        setReferenceDistance in interface AudioSource
        Parameters:
        referenceDistance - the Reference Distance for this AudioSource

      • getReferenceDistance

        public float getReferenceDistance()
        Description copied from interface: AudioSource
        Return the current reference distance setting

        Default value = 1.0f

        Applies only to sub-types:

        • Source
        Specified by:
        getReferenceDistance in interface AudioSource
        Returns:
        Reference Distance of this AudioSource

      • setOffset

        public void setOffset​(long offset)
        Description copied from interface: AudioSource
        Set the offset in which to start playback of this AudioSource.

        Default value = 0

        Value is clamped between 0 and length of attached AudioBuffer

        Applies only to sub-types:

        • Source
        Specified by:
        setOffset in interface AudioSource
        Parameters:
        offset - the offset in samples marking the point to commence playback

      • getOffset

        public long getOffset()
        Description copied from interface: AudioSource
        Return the offset in which to start playback of this AudioSource.

        Default value = 0

        Applies only to sub-types:

        • Source
        Specified by:
        getOffset in interface AudioSource
        Returns:
        the offset in samples marking the point to commence playback

      • setMaximumDistance

        public void setMaximumDistance​(float maximumDistance)
        Description copied from interface: AudioSource
        Set the current maximum distance setting.

        Default value = Audio.MAX_DISTANCE

        The maximum distance is that where the volume of the sound would normally be zero.

        Applies only to sub-types:

        • Source
        Specified by:
        setMaximumDistance in interface AudioSource
        Parameters:
        maximumDistance - maximum distance of this source

      • getMaximumDistance

        public float getMaximumDistance()
        Description copied from interface: AudioSource
        Return the current maximum distance setting.

        Default value = Audio.MAX_DISTANCE

        The maximum distance is that where the volume of the sound would normally be zero.

        Applies only to sub-types:

        • Source
        Specified by:
        getMaximumDistance in interface AudioSource
        Returns:
        the maximum distance

      • setRollOffFactor

        public void setRollOffFactor​(float rollOffFactor)
        Description copied from interface: AudioSource
        Set the roll-off factor of this AudioSource object.

        Default value = 1.0f

        Applies only to sub-types:

        • Source
        Specified by:
        setRollOffFactor in interface AudioSource
        Parameters:
        rollOffFactor - roll-off factor

      • getRollOffFactor

        public float getRollOffFactor()
        Description copied from interface: AudioSource
        Get the roll-off factor of this AudioSource object.

        Default value = 1.0f

        Applies only to sub-types:

        • Source
        Specified by:
        getRollOffFactor in interface AudioSource
        Returns:
        the roll-off factor

      • setLooped

        public void setLooped​(boolean loop)
        Description copied from interface: AudioSource
        Sets this AudioSource object to loop infinitely or not.

        When loop == false, sets the min and max number of loops to zero.

        Applies only to sub-types:

        • Source
        Specified by:
        setLooped in interface AudioSource
        Parameters:
        loop - infinite loop setting

      • isLooped

        public boolean isLooped()
        Description copied from interface: AudioSource
        Check if this AudioSource object will loop or not.

        Applies only to sub-types:

        • Source
        Specified by:
        isLooped in interface AudioSource
        Returns:
        boolean loop

      • setMinLoops

        public void setMinLoops​(int loops)
        Description copied from interface: AudioSource
        The minimum number of times that this AudioSource should loop.

        When set to 1, the sound will loop once (i.e. play through twice).

        When set to LOOP_CONTINUOUS, determines that this AudioSource object should loop indefinitely until explicitly stopped.

        Default value = 0

        Applies only to sub-types:

        • Source
        Specified by:
        setMinLoops in interface AudioSource
        Parameters:
        loops - minimum number of loops

      • getMinLoops

        public int getMinLoops()
        Description copied from interface: AudioSource
        Returns the minimum number of times that this AudioSource will loop, or LOOP_CONTINUOUS for infinite looping.

        Default value = 0

        Applies only to sub-types:

        • Source
        Specified by:
        getMinLoops in interface AudioSource
        Returns:
        number of loops

      • setMaxLoops

        public void setMaxLoops​(int loops)
        Description copied from interface: AudioSource
        The maximum number of times that this AudioSource should loop.

        When set to 1, the sound will loop once (i.e. play through twice).

        When set to LOOP_CONTINUOUS, determines that this AudioSource object should loop indefinitely until explicitly stopped.

        Default value = 0

        Applies only to sub-types:

        • Source
        Specified by:
        setMaxLoops in interface AudioSource
        Parameters:
        loops - maximum number of loops

      • calculateLoops

        protected void calculateLoops()
        Calculate the number of times to loop playback of this sound.

      • getMaxLoops

        public int getMaxLoops()
        Description copied from interface: AudioSource
        Returns the maximum number of times that this AudioSource will loop, or LOOP_CONTINUOUS for infinite looping.

        Default value = 0

        Applies only to sub-types:

        • Source
        Specified by:
        getMaxLoops in interface AudioSource
        Returns:
        maximum number of loops

      • getNumLoops

        public int getNumLoops()
        Description copied from interface: AudioSource
        The number of times that this AudioSource should loop, or LOOP_CONTINUOUS for infinite looping.

        When the minimum and maximum number of loops are different, each call to this method will return a different random number that lies between the two settings: 

         minimum <= number of loops <= maximum
        Default value = 0

        Applies only to sub-types:

        • Source
        Specified by:
        getNumLoops in interface AudioSource
        Returns:
        number of loops

      • setFadeIn

        public void setFadeIn​(int fadeInTime)
        Description copied from interface: AudioSource
        Set the length of time in milliseconds to fade this source in

        Default value = 1000

        Applies only to sub-types:

        • Source
        Specified by:
        setFadeIn in interface AudioSource
        Parameters:
        fadeInTime - fade-in time in milliseconds

      • getFadeIn

        public int getFadeIn()
        Description copied from interface: AudioSource
        Retrieve the length of time in milliseconds to fade this source in

        Default value = 1000

        Applies only to sub-types:

        • Source
        Specified by:
        getFadeIn in interface AudioSource
        Returns:
        fade-in time in milliseconds

      • setFadeOut

        public void setFadeOut​(int fadeOutTime)
        Description copied from interface: AudioSource
        Set the length of time in milliseconds to fade this source in

        Default value = 1000

        Applies only to sub-types:

        • Source
        Specified by:
        setFadeOut in interface AudioSource
        Parameters:
        fadeOutTime - fade-out time in milliseconds

      • getFadeOut

        public int getFadeOut()
        Description copied from interface: AudioSource
        Retrieve the length of time in milliseconds to fade this source in

        Default value = 1000

        Applies only to sub-types:

        • Source
        Specified by:
        getFadeOut in interface AudioSource
        Returns:
        fade-in time in milliseconds

      • getFadeGain

        protected float getFadeGain()
        Used to return the current calculated fade gain for this AudioSource.
        Returns:
        current fade gain

      • calculateFades

        protected void calculateFades()
        Calculate the fade gains.

      • bindAudioBuffer

        abstract boolean bindAudioBuffer​(AudioBuffer buffer)
        Binds this AudioSource with the specified AudioBuffer.

        Applies only to sub-types:

        • Source
        Parameters:
        buffer - The AudioBuffer to bind to this AudioSource
        Returns:
        true if successful

      • setBound

        protected void setBound​(boolean bound)
        Method to define if this AudioSource has been bound to an AudioBuffer.
        Parameters:
        bound - True if bound to an AudioBufferr

      • setQueued

        protected void setQueued​(boolean queued)

      • isBound

        public boolean isBound()
        Description copied from interface: AudioSource
        Method to return if this AudioSource has been bound to an AudioBuffer

        Applies only to sub-types:

        • Source
        Specified by:
        isBound in interface AudioSource
        Returns:
        True if bound to an AudioBuffer

      • isQueued

        public boolean isQueued()
        Description copied from interface: AudioSource
        Method to return if this AudioSource has AudioBuffers queued to it

        Applies only to sub-types:

        • Source
        Specified by:
        isQueued in interface AudioSource
        Returns:
        True if AudioBuffers are queued.

      • stateChanged

        public void stateChanged​(int oldState)
        Description copied from interface: Audio
        Method used to update the current state of the Audio object
        Specified by:
        stateChanged in interface Audio
        Parameters:
        oldState - the former state

      • play

        public void play()
        Description copied from interface: AudioSource
        Method to start playing this AudioSource Object

        If this AudioSource is already playing, this command is ignored.

        Applies only to sub-types:

        • Source
        Specified by:
        play in interface AudioSource

      • doPlay

        protected abstract void doPlay()
        Play the clip from the beginning. If looped, start looping.

      • stop

        public void stop()
        Description copied from interface: AudioSource
        Method to stop playing this AudioSource Object

        Applies only to sub-types:

        • Source
        Specified by:
        stop in interface AudioSource

      • doStop

        protected abstract void doStop()
        Stop playing the clip and rewind to the beginning.

      • togglePlay

        public void togglePlay()
        Description copied from interface: AudioSource
        Method to toggle playback of this AudioSource Object reseting position

        Applies only to sub-types:

        • Source
        Specified by:
        togglePlay in interface AudioSource

      • doTogglePlay

        protected void doTogglePlay()
        Toggle the current playing status. Will always start at/return to the beginning of the sample.

      • pause

        public void pause()
        Description copied from interface: AudioSource
        Method to pause playing this AudioSource Object

        Applies only to sub-types:

        • Source
        Specified by:
        pause in interface AudioSource

      • doPause

        protected abstract void doPause()
        Stop playing the clip but retain the current position.

      • resume

        public void resume()
        Description copied from interface: AudioSource
        Method to resume playing this AudioSource Object

        Applies only to sub-types:

        • Source
        Specified by:
        resume in interface AudioSource

      • doResume

        protected abstract void doResume()
        Play the clip from the current position.

      • togglePause

        public void togglePause()
        Description copied from interface: AudioSource
        Method to toggle playback of this AudioSource Object retaining postition

        Applies only to sub-types:

        • Source
        Specified by:
        togglePause in interface AudioSource

      • doTogglePause

        protected void doTogglePause()
        Toggle the current playing status. Will retain the playback position of the sample.

      • rewind

        public void rewind()
        Description copied from interface: AudioSource
        Method to rewind this AudioSource Object

        Applies only to sub-types:

        • Source
        Specified by:
        rewind in interface AudioSource

      • doRewind

        protected abstract void doRewind()
        Rewind clip to the beginning.

      • fadeIn

        public void fadeIn()
        Description copied from interface: AudioSource
        Method to fade in and then play this AudioSource Object

        Applies only to sub-types:

        • Source
        Specified by:
        fadeIn in interface AudioSource

      • doFadeIn

        protected abstract void doFadeIn()
        Fade in then play this AudioSource.

      • fadeOut

        public void fadeOut()
        Description copied from interface: AudioSource
        Method to fade out and then stop this AudioSource Object only when it is already playing.

        If not playing, command is ignored.

        Applies only to sub-types:

        • Source
        Specified by:
        fadeOut in interface AudioSource

      • doFadeOut

        protected abstract void doFadeOut()
        Fade out then stop this AudioSource.

      • getFading

        protected int getFading()
        Get the current fading status.
        Returns:
        fading status

      • getDebugString

        @Nonnull
public java.lang.String getDebugString()
        Description copied from interface: AudioSource
        Get debug info about this audio source. AbstractAudioSource overrides this to get more debug info. It was previously the method toString().
        Specified by:
        getDebugString in interface AudioSource
        Returns:
        a string with debug info or the result of the method toString()