Package com.jogamp.openal.sound3d

Class Source

  • public final class Source
extends Object
    This class is used to represent sound-producing objects in the Sound3D environment. It contains methods for setting the position, direction, pitch, gain and other properties along with methods for starting, pausing, rewinding and stopping sudio projecting from a source.
    Author:
    Athomas Goldberg, Sven Gothel, et al.

    • Constructor Summary

      Constructors 
      Constructor Description
      Source()
      Create a new instance with an invalid OpenAL source ID
      Source​(int sourceID)
      Create a new instance with a given OpenAL source ID

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      boolean create()
      Creates a new OpenAL source ID if isValid() == false.
      void delete()
      Delete this source, freeing its resources.
      Buffer getBuffer()
      Gets the buffer associated with this source.
      int getBuffersProcessed()
      Gets the number of buffers already processed on this source.
      int getBuffersQueued()
      Gets the number of buffers currently queued on this source.
      float getConeOuterGain()
      Gets the gain when outside the oriented cone.
      Vec3f getDirection()
      Gets the direction vector of the source.
      float getGain()
      Gets the gain of the audio on this source.
      int getID()
      Return the OpenAL source ID, -1 if invalid.
      boolean getLooping()
      indicates whether looping is turned on or off.
      float getMaxDistance()
      Gets the max distance where there will no longer be any attenuation of the source.
      float getMaxGain()
      SGets the maximum gain for this source.
      float getMinGain()
      Gets the minimum gain for this source.
      float getPitch()
      Gets the pitch of the audio on this source.
      Vec3f getPosition()
      Gets the x,y,z position of the source.
      float getReferenceDistance()
      Gets the distance under which the volume for the source would normally drop by half, before being influenced by rolloff factor or max distance.
      float getRolloffFactor()
      Gets the rolloff rate of the source.
      Vec3f getVelocity()
      Gets the velocity vector of the source.
      boolean isPlaying()
      Determines whether or not this source is playing.
      boolean isSourceRelative()
      Determines if the position of the source is relative to the listener.
      boolean isValid()
      Returns whether getID() is valid, i.e.
      void pause()
      pauses the audio in this Source.
      void play()
      Beginning playing the audio in this source.
      void queueBuffers​(int[] bufferIDs)
      Queues `bufferIDs.length` OpenAL buffers on a source.
      void queueBuffers​(Buffer[] buffers)
      Queues one or more buffers on a source.
      void rewind()
      Rewinds the audio in this source
      void setBuffer​(Buffer buffer)
      Associates the buffer with this source if buffer is not null, otherwise disassociates the previously associated buffer from this source.
      void setConeOuterGain​(float coneOuterGain)
      Sets the gain when outside the oriented cone.
      void setDirection​(float x, float y, float z)
      Sets the direction vector of the source.
      void setDirection​(Vec3f direction)
      Sets the direction vector of the source.
      void setGain​(float gain)
      Sets the gain of the audio on this source.
      void setLooping​(boolean isLooping)
      turns looping on or off.
      void setMaxDistance​(float maxDistance)
      Sets the max distance where there will no longer be any attenuation of the source.
      void setMaxGain​(float maxGain)
      Sets the maximum gain for this source.
      void setMinGain​(float minGain)
      Sets the minimum gain for this source.
      void setPitch​(float pitch)
      Sets the pitch of the audio on this source.
      void setPosition​(float x, float y, float z)
      Sets the x,y,z position of the source.
      void setPosition​(Vec3f position)
      Sets the x,y,z position of the source.
      void setReferenceDistance​(float referenceDistance)
      Sets the distance under which the volume for the source would normally drop by half, before being influenced by rolloff factor or max distance.
      void setRolloffFactor​(float rolloffFactor)
      Sets the rolloff rate of the source.
      void setSourceRelative​(boolean isRelative)
      Determines if the position of the source is relative to the listener.
      void setVelocity​(float x, float y, float z)
      Sets the velocity vector of the source.
      void setVelocity​(Vec3f velocity)
      Sets the velocity vector of the source.
      void stop()
      Stops the audio in this Source
      String toString()  
      void unqueueBuffers​(int[] bufferIDs)
      Unqueues `bufferIDs.length` OpenAL buffers on a source.
      void unqueueBuffers​(Buffer[] buffers)
      Unqueues one or more buffers on a source.

    • Constructor Detail

      • Source

        public Source()
        Create a new instance with an invalid OpenAL source ID

      • Source

        public Source​(int sourceID)
        Create a new instance with a given OpenAL source ID
        Parameters:
        sourceID - an OpenAL source ID, pass -1 for an invalid value for lazy creation

    • Method Detail

      • create

        public boolean create()
        Creates a new OpenAL source ID if isValid() == false.
        Returns:
        true if a new ID has been successfully created, otherwise false

      • getID

        public int getID()
        Return the OpenAL source ID, -1 if invalid.

      • isValid

        public boolean isValid()
        Returns whether getID() is valid, i.e. not delete()'ed

      • delete

        public void delete()
        Delete this source, freeing its resources.

      • play

        public void play()
        Beginning playing the audio in this source.

      • pause

        public void pause()
        pauses the audio in this Source.

      • stop

        public void stop()
        Stops the audio in this Source

      • rewind

        public void rewind()
        Rewinds the audio in this source

      • isPlaying

        public boolean isPlaying()
        Determines whether or not this source is playing.
        Returns:
        true if this source is playing.

      • setPitch

        public void setPitch​(float pitch)
        Sets the pitch of the audio on this source. The pitch may be modified without altering the playback speed of the audio.
        Parameters:
        pitch - the pitch value of this source.

      • getPitch

        public float getPitch()
        Gets the pitch of the audio on this source. The pitch may be modified without altering the playback speed of the audio.
        Returns:
        the pitch value of this source.

      • setGain

        public void setGain​(float gain)
        Sets the gain of the audio on this source. This can be used to contro the volume of the source.
        Parameters:
        gain - the gain of the audio on this source

      • getGain

        public float getGain()
        Gets the gain of the audio on this source. This can be used to contro the volume of the source.
        Returns:
        the gain of the audio on this source

      • setMaxDistance

        public void setMaxDistance​(float maxDistance)
        Sets the max distance where there will no longer be any attenuation of the source.
        Parameters:
        maxDistance - the max ditance for source attentuation.

      • getMaxDistance

        public float getMaxDistance()
        Gets the max distance where there will no longer be any attenuation of the source.
        Returns:
        the max ditance for source attentuation.

      • setRolloffFactor

        public void setRolloffFactor​(float rolloffFactor)
        Sets the rolloff rate of the source. The default value is 1.0
        Parameters:
        rolloffFactor - the rolloff rate of the source.

      • getRolloffFactor

        public float getRolloffFactor()
        Gets the rolloff rate of the source. The default value is 1.0
        Returns:
        the rolloff rate of the source.

      • setReferenceDistance

        public void setReferenceDistance​(float referenceDistance)
        Sets the distance under which the volume for the source would normally drop by half, before being influenced by rolloff factor or max distance.
        Parameters:
        referenceDistance - the reference distance for the source.

      • getReferenceDistance

        public float getReferenceDistance()
        Gets the distance under which the volume for the source would normally drop by half, before being influenced by rolloff factor or max distance.
        Returns:
        the reference distance for the source.

      • setMinGain

        public void setMinGain​(float minGain)
        Sets the minimum gain for this source.
        Parameters:
        minGain - the minimum gain for this source.

      • getMinGain

        public float getMinGain()
        Gets the minimum gain for this source.
        Returns:
        the minimum gain for this source.

      • setMaxGain

        public void setMaxGain​(float maxGain)
        Sets the maximum gain for this source.
        Parameters:
        maxGain - the maximum gain for this source

      • getMaxGain

        public float getMaxGain()
        SGets the maximum gain for this source.
        Returns:
        the maximum gain for this source

      • setConeOuterGain

        public void setConeOuterGain​(float coneOuterGain)
        Sets the gain when outside the oriented cone.
        Parameters:
        coneOuterGain - the gain when outside the oriented cone.

      • getConeOuterGain

        public float getConeOuterGain()
        Gets the gain when outside the oriented cone.
        Returns:
        the gain when outside the oriented cone.

      • setPosition

        public void setPosition​(Vec3f position)
        Sets the x,y,z position of the source.
        Parameters:
        position - a Vec3f object containing the x,y,z position of the source.

      • setPosition

        public void setPosition​(float x,
                        float y,
                        float z)
        Sets the x,y,z position of the source.
        Parameters:
        x - the x position of the source.
        y - the y position of the source.
        z - the z position of the source.

      • getPosition

        public Vec3f getPosition()
        Gets the x,y,z position of the source.
        Returns:
        a Vec3f object containing the x,y,z position of the source.

      • setVelocity

        public void setVelocity​(Vec3f velocity)
        Sets the velocity vector of the source.
        Parameters:
        velocity - the velocity vector of the source

      • setVelocity

        public void setVelocity​(float x,
                        float y,
                        float z)
        Sets the velocity vector of the source.
        Parameters:
        x - the x velocity of the source.
        y - the y velocity of the source.
        z - the z velocity of the source.

      • getVelocity

        public Vec3f getVelocity()
        Gets the velocity vector of the source.
        Returns:
        the velocity vector of the source

      • setDirection

        public void setDirection​(Vec3f direction)
        Sets the direction vector of the source.
        Parameters:
        direction - the direction vector of the source.

      • setDirection

        public void setDirection​(float x,
                         float y,
                         float z)
        Sets the direction vector of the source.
        Parameters:
        x - the x direction of the source.
        y - the y direction of the source.
        z - the z direction of the source.

      • getDirection

        public Vec3f getDirection()
        Gets the direction vector of the source.
        Returns:
        the direction vector of the source.

      • setSourceRelative

        public void setSourceRelative​(boolean isRelative)
        Determines if the position of the source is relative to the listener. The default is false.
        Parameters:
        isRelative - true if the position of the source is relative to the listener, false if the position of the source is relative to the world.

      • isSourceRelative

        public boolean isSourceRelative()
        Determines if the position of the source is relative to the listener. The default is false.
        Returns:
        true if the position of the source is relative to the listener, false if the position of the source is relative to the world.

      • setLooping

        public void setLooping​(boolean isLooping)
        turns looping on or off.
        Parameters:
        isLooping - true-looping is on, false-looping is off

      • getLooping

        public boolean getLooping()
        indicates whether looping is turned on or off.
        Returns:
        true-looping is on, false-looping is off

      • getBuffersQueued

        public int getBuffersQueued()
                     throws ALException
        Gets the number of buffers currently queued on this source.
        Returns:
        the number of buffers currently queued on this source.
        Throws:
        ALException - on AL error

      • getBuffersProcessed

        public int getBuffersProcessed()
                        throws ALException
        Gets the number of buffers already processed on this source.
        Returns:
        the number of buffers already processed on this source.
        Throws:
        ALException - on AL error

      • setBuffer

        public void setBuffer​(Buffer buffer)
        Associates the buffer with this source if buffer is not null, otherwise disassociates the previously associated buffer from this source.
        Parameters:
        buffer - the buffer to be associated with this source if not null. If null, disassociates the current buffer from this source.

      • getBuffer

        public Buffer getBuffer()
        Gets the buffer associated with this source.
        Returns:
        the buffer associated with this source

      • queueBuffers

        public void queueBuffers​(Buffer[] buffers)
                  throws ALException
        Queues one or more buffers on a source. Useful for streaming audio, buffers will be played in the order they are queued.
        Parameters:
        buffers - a set of initialized (loaded) buffers.
        Throws:
        ALException - on AL error

      • queueBuffers

        public void queueBuffers​(int[] bufferIDs)
                  throws ALException
        Queues `bufferIDs.length` OpenAL buffers on a source.
        Parameters:
        bufferIDs - array of to be queued OpenAL buffer IDs
        Throws:
        ALException - on AL error

      • unqueueBuffers

        public void unqueueBuffers​(Buffer[] buffers)
                    throws ALException
        Unqueues one or more buffers on a source.
        Parameters:
        buffers - a set of previously queued buffers.
        Throws:
        ALException - on AL error

      • unqueueBuffers

        public void unqueueBuffers​(int[] bufferIDs)
                    throws ALException
        Unqueues `bufferIDs.length` OpenAL buffers on a source.
        Parameters:
        bufferIDs - array of resulting unqueued OpenAL buffer IDs of previously queued buffers.
        Throws:
        ALException - on AL error