Class SoundSource

java.lang.Object
de.pottgames.tuningfork.SoundSource
Direct Known Subclasses:
PcmSoundSource, SongSource
public abstract class SoundSource extends Object
A sound source is used to represent the position, speed and other attributes of a sound in the virtual audio world . It enables you to play, pause, stop, position sounds and let's you set different effects on it.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected final int
    sourceId
     

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    SoundSource()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    SoundEffect
    attachEffect(SoundEffect effect)
    Attaches a sound effect to this sound source.
    SoundEffect
    attachEffect(SoundEffect effect, float lowFreqVolume, float highFreqVolume)
    Attaches a sound effect to this sound source.
    void
    detachAllEffects()
    Detaches all currently attached sound effects from this sound source.
    boolean
    detachEffect(SoundEffect effect)
    Detaches the given SoundEffect from this sound source.
    void
    disableAttenuation()
    Disables the distance attenuation of this sound source.
    protected void
    dispose()
     
    void
    enableAttenuation()
    Enables the distance attenuation of this sound source.
    float
    getAttenuationFactor()
    Returns the attenuation factor of this source.
    float
    getAttenuationMaxDistance()
    Returns the distance at which the attenuation will stop.
    float
    getAttenuationMinDistance()
    Returns the minimum distance for the attenuation to start.
    float
    getPitch()
    Returns the pitch of this sound source.
    com.badlogic.gdx.math.Vector3
    getPosition(com.badlogic.gdx.math.Vector3 saveTo)
    Retrieves the position of this sound source.
    float
    getRadius()
    Returns the radius of the source.
    String
    getResampler()
    Returns the name of the resampler currently in use.
    AudioConfig.Spatialization
    getSpatialization()
    Retrieves the spatialization mode.
    AudioConfig.Virtualization
    getVirtualization()
    Retrieves the virtualization mode.
    float
    getVolume()
    Returns the base volume of this sound source.
    boolean
    hasFilter()
    Returns true if a direct filter is active on this sound source.
    boolean
    isDirectional()
    Returns true if this sound source is directional.
    boolean
    isPaused()
    Returns whether this sound source is paused.
    boolean
    isPlaying()
    Returns whether this sound source is currently playing.
    boolean
    isRelative()
    Returns whether this sound source handles the position attribute as relative to the listeners position.
    void
    makeDirectional(com.badlogic.gdx.math.Vector3 direction, float coneInnerAngle, float coneOuterAngle, float outOfConeVolume)
    Makes this sound source emit sound in a cone shape facing a direction.
    void
    makeOmniDirectional()
    Makes this sound source omni-directional.
    void
    pause()
    Pauses the sound playback.
    void
    play()
    Starts the playback of this sound source.
    void
    setAttenuationFactor(float rolloff)
    This factor determines how slowly or how quickly the sound source loses volume as the listener moves away from the source.
    void
    setAttenuationMaxDistance(float maxDistance)
    Sets the distance the listener must be from the sound source at which the attenuation should stop.
    void
    setAttenuationMinDistance(float minDistance)
    Sets the distance the listener must be from the sound source at which the attenuation should begin.
    void
    setDirection(com.badlogic.gdx.math.Vector3 direction)
    Sets the direction of this sound source.
    void
    setFilter(float lowFreqVolume, float highFreqVolume)
    Enables the given filter as direct filter (dry signal) on this sound source.
    void
    setLooping(boolean looping)
    Sets wether this sound source should loop.
    void
    setPitch(float pitch)
    Sets the pitch of this sound source.
    void
    setPosition(float x, float y, float z)
    Sets the positions of this sound source in the virtual world.
    void
    setPosition(com.badlogic.gdx.math.Vector3 position)
    Sets the positions of this sound source in the virtual world.
    void
    setRadius(float radius)
    Changes the source to a "large" source with a radius.
    void
    setRelative(boolean relative)
    Sets whether the position attribute of this sound source should be handled as relative or absolute values to the listener's position.
    If set to false, the position is the absolute position in the 3D world.
    If set to true, the position is relative to the listener's position, meaning a position of x=0,y=0,z=0 is always identical to the listener's position.
    boolean
    setResampler(String resampler)
    Sets the resampler for this sound source.

    Check AudioDevice.getAvailableResamplers() for a list of available resamplers.
    protected void
    setResamplerByIndex(int index)
     
    void
    setSpatialization(AudioConfig.Spatialization spatialization)
    Sets the spatialization mode for this sound source.
    void
    setSpeed(float x, float y, float z)
    Sets the speed of this sound source.
    void
    setSpeed(com.badlogic.gdx.math.Vector3 speed)
    Sets the speed of this sound source.
    void
    setVirtualization(AudioConfig.Virtualization virtualization)
    Sets the virtualization enabled state for this sound source.
    OpenAL requires input channels to be down-mixed to the output channel configuration, possibly using HRTF or other virtualization techniques to give a sense of speakers that may not be physically present.
    void
    setVolume(float volume)
    Sets the base volume of this sound source.
    void
    stop()
    Stops the sound playback and rewinds it.

    Methods inherited from class Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • sourceId

      protected final int sourceId

  • Constructor Details

    • SoundSource

      protected SoundSource()

  • Method Details

    • setVolume

      public void setVolume(float volume)
      Sets the base volume of this sound source. The final output volume might differ depending on the source's position, listener position etc.
      Parameters:
      volume - in the range of 0.0 - 1.0 with 0 being silent and 1 being the maximum volume. (default 1)

    • getVolume

      public float getVolume()
      Returns the base volume of this sound source.
      Returns:
      volume in the range of 0.0 - 1.0 with 0 being silent and 1 being the maximum volume

    • setPitch

      public void setPitch(float pitch)
      Sets the pitch of this sound source.
      Parameters:
      pitch - The pitch value, which must be >= 0. Values less than 1 result in slower playback and a deeper tone, while values > 1 make it faster and produce a higher tone.

    • getPitch

      public float getPitch()
      Returns the pitch of this sound source.
      Returns:
      pitch in the range of 0.5 - 2.0 with values < 1 making the sound slower and values > 1 making it faster

    • play

      public void play()
      Starts the playback of this sound source.

    • setRelative

      public void setRelative(boolean relative)
      Sets whether the position attribute of this sound source should be handled as relative or absolute values to the listener's position.
      If set to false, the position is the absolute position in the 3D world.
      If set to true, the position is relative to the listener's position, meaning a position of x=0,y=0,z=0 is always identical to the listener's position.
      Parameters:
      relative - true = relative, false = absolute

    • isRelative

      public boolean isRelative()
      Returns whether this sound source handles the position attribute as relative to the listeners position.
      Returns:
      relative

    • setPosition

      public void setPosition(com.badlogic.gdx.math.Vector3 position)
      Sets the positions of this sound source in the virtual world.
      Parameters:
      position - the position in 3D space

    • setPosition

      public void setPosition(float x, float y, float z)
      Sets the positions of this sound source in the virtual world.
      Parameters:
      x - x
      y - y
      z - z

    • getPosition

      public com.badlogic.gdx.math.Vector3 getPosition(com.badlogic.gdx.math.Vector3 saveTo)
      Retrieves the position of this sound source.
      Parameters:
      saveTo - the vector the result should be saved to
      Returns:
      returns the saveTo parameter vector that contains the result

    • setRadius

      public void setRadius(float radius)
      Changes the source to a "large" source with a radius. The source has a raised cosine shape. A radius of 0 is the default (point-source).
      The OpenAL documentation about this is very thin. I don't know nor have the resources to test how this really works with attenuation and directionality. If you happen to know, please PR a fix for this javadoc.
      Parameters:
      radius - the radius

    • getRadius

      public float getRadius()
      Returns the radius of the source.
      Returns:
      the radius

    • setSpeed

      public void setSpeed(com.badlogic.gdx.math.Vector3 speed)
      Sets the speed of this sound source. The speed is not automatically determined by changes to the position, you need to call setSpeed manually.
      The speed is only used for calculating a Doppler effect. Note that you need to call set speed on the sound listener as well in order to get a proper Doppler effect.
      Parameters:
      speed - the speed

    • setSpeed

      public void setSpeed(float x, float y, float z)
      Sets the speed of this sound source. The speed is not automatically determined by changes to the position, you need to call setSpeed manually.
      The speed is only used for calculating a Doppler effect. Note that you need to call set speed on the sound listener as well in order to get a proper Doppler effect.
      Parameters:
      x - the speed on the x-axis
      y - the speed on the y-axis
      z - the speed on the z-axis

    • makeDirectional

      public void makeDirectional(com.badlogic.gdx.math.Vector3 direction, float coneInnerAngle, float coneOuterAngle, float outOfConeVolume)
      Makes this sound source emit sound in a cone shape facing a direction. Inside the inner cone angle, the listener hears the sound at full volume. Outside the outer cone angle the sound is even on the level specified by outOfConeVolume. The volume is faded in between both angles (inside the cone). Call makeOmniDirectional() to make the source non-directional again.
      Parameters:
      direction - the direction the source is facing
      coneInnerAngle - the inner cone angle
      coneOuterAngle - the outer cone angle
      outOfConeVolume - the volume of the sound source when outside of the cone

    • setDirection

      public void setDirection(com.badlogic.gdx.math.Vector3 direction)
      Sets the direction of this sound source. You need to call makeDirectional(Vector3, float, float, float) first, otherwise the direction will be ignored.
      Parameters:
      direction - the direction

    • makeOmniDirectional

      public void makeOmniDirectional()
      Makes this sound source omni-directional. This is the default, so you only need to call it if you have made the source directional earlier.

    • isDirectional

      public boolean isDirectional()
      Returns true if this sound source is directional.
      Returns:
      directional = true, omni-directional = false

    • enableAttenuation

      public void enableAttenuation()
      Enables the distance attenuation of this sound source.

    • disableAttenuation

      public void disableAttenuation()
      Disables the distance attenuation of this sound source.

    • setAttenuationFactor

      public void setAttenuationFactor(float rolloff)
      This factor determines how slowly or how quickly the sound source loses volume as the listener moves away from the source. A factor of 0.5 reduces the volume loss by half. With a factor of 2, the source loses volume twice as fast.
      Parameters:
      rolloff - (default depends on the attenuation model)

    • setAttenuationMinDistance

      public void setAttenuationMinDistance(float minDistance)
      Sets the distance the listener must be from the sound source at which the attenuation should begin. The attenuation itself is controlled by the attenuation model and the attenuation factor of the source.
      Parameters:
      minDistance - (default depends on the attenuation model)

    • setAttenuationMaxDistance

      public void setAttenuationMaxDistance(float maxDistance)
      Sets the distance the listener must be from the sound source at which the attenuation should stop. The attenuation itself is controlled by the attenuation model and the attenuation factor of the source.
      Parameters:
      maxDistance - (default depends on the attenuation model)

    • getAttenuationFactor

      public float getAttenuationFactor()
      Returns the attenuation factor of this source. See setAttenuationFactor(float) for more information.
      Returns:
      the attenuation factor (default depends on the attenuation model)

    • getAttenuationMinDistance

      public float getAttenuationMinDistance()
      Returns the minimum distance for the attenuation to start. See setAttenuationMinDistance(float) for more information.
      Returns:
      the attenuation min distance (default depends on the attenuation model)

    • getAttenuationMaxDistance

      public float getAttenuationMaxDistance()
      Returns the distance at which the attenuation will stop. See setAttenuationMaxDistance(float) for more information.
      Returns:
      the attenuation max distance (default depends on the attenuation model)

    • setVirtualization

      public void setVirtualization(AudioConfig.Virtualization virtualization)
      Sets the virtualization enabled state for this sound source.
      OpenAL requires input channels to be down-mixed to the output channel configuration, possibly using HRTF or other virtualization techniques to give a sense of speakers that may not be physically present. This leads to sometimes unexpected and unwanted audio output, so you can disable it.

      Check AudioConfig.Virtualization for the different methods available.

      Recommended settings:
      Parameters:
      virtualization - null is a legal NOP

    • getVirtualization

      public AudioConfig.Virtualization getVirtualization()
      Retrieves the virtualization mode.
      Returns:
      the virtualization mode

    • setSpatialization

      public void setSpatialization(AudioConfig.Spatialization spatialization)
      Sets the spatialization mode for this sound source.
      Parameters:
      spatialization - null is a legal NOP

    • getSpatialization

      public AudioConfig.Spatialization getSpatialization()
      Retrieves the spatialization mode.
      Returns:
      the spatialization mode

    • setLooping

      public void setLooping(boolean looping)
      Sets wether this sound source should loop. When looping is enabled, the source will immediately play the sound again when it's finished playing.
      Parameters:
      looping - true for looped playback

    • isPlaying

      public boolean isPlaying()
      Returns whether this sound source is currently playing.
      Returns:
      true when this sound source is playing, false otherwise.

    • isPaused

      public boolean isPaused()
      Returns whether this sound source is paused.
      Returns:
      true when this sound source is paused, false otherwise.

    • pause

      public void pause()
      Pauses the sound playback.

    • stop

      public void stop()
      Stops the sound playback and rewinds it.

    • setFilter

      public void setFilter(float lowFreqVolume, float highFreqVolume)
      Enables the given filter as direct filter (dry signal) on this sound source.
      Parameters:
      lowFreqVolume - range: 0 - 1, 0 means completely silent, 1 means full loudness
      highFreqVolume - range: 0 - 1, 0 means completely silent, 1 means full loudness

    • hasFilter

      public boolean hasFilter()
      Returns true if a direct filter is active on this sound source.
      Returns:
      result

    • attachEffect

      public SoundEffect attachEffect(SoundEffect effect)
      Attaches a sound effect to this sound source. If you attach more effects than effect slots are available, the oldest attached effect will be kicked out. Attaching an effect that is already attached to this source is a legal NOP.

      AudioDeviceConfig.setEffectSlots(int) to change the number of available effect slots.
      Call AudioDevice.getNumberOfEffectSlots() to retrieve the number of available effect slots.
      Parameters:
      effect - the sound effect
      Returns:
      the effect that was kicked out or null otherwise

    • attachEffect

      public SoundEffect attachEffect(SoundEffect effect, float lowFreqVolume, float highFreqVolume)
      Attaches a sound effect to this sound source. If you attach more effects than effect slots are available, the oldest attached effect will be kicked out. Attaching an effect that is already attached to this source is a legal NOP. Optionally you can set a filter that is only used for this effect, or null if you don't want to apply a filter.

      AudioDeviceConfig.setEffectSlots(int) to change the number of available effect slots.
      Call AudioDevice.getNumberOfEffectSlots() to retrieve the number of available effect slots.
      Parameters:
      effect - the sound effect
      lowFreqVolume - range: 0 - 1, 0 means completely silent, 1 means full loudness
      highFreqVolume - range: 0 - 1, 0 means completely silent, 1 means full loudness
      Returns:
      the effect that was kicked out or null otherwise

    • detachEffect

      public boolean detachEffect(SoundEffect effect)
      Detaches the given SoundEffect from this sound source.
      Parameters:
      effect - the effect
      Returns:
      true if the effect was successfully detached, false if the effect isn't attached to this source (anymore)

    • detachAllEffects

      public void detachAllEffects()
      Detaches all currently attached sound effects from this sound source.

    • setResamplerByIndex

      protected void setResamplerByIndex(int index)

    • setResampler

      public boolean setResampler(String resampler)
      Sets the resampler for this sound source.

      Check AudioDevice.getAvailableResamplers() for a list of available resamplers.
      Parameters:
      resampler - the resampler name
      Returns:
      true if successful, false if the desired resampler is not available

    • getResampler

      public String getResampler()
      Returns the name of the resampler currently in use.
      Returns:
      name of the resampler

    • dispose

      protected void dispose()