Package com.jogamp.openal.sound3d

Class AudioSystem3D

  • public class AudioSystem3D
extends Object
    The AudioSystem3D class provides a set of methods for creating and manipulating a 3D audio environment.
    Author:
    Athomas Goldberg, Sven Gothel, et al.

    • Constructor Detail

      • AudioSystem3D

        public AudioSystem3D()

    • Method Detail

      • init

        @Deprecated
public static void init()
                 throws ALException
        Deprecated.
        Not required to be called due to static initialization
        Initialize the Sound3D environment.
        Throws:
        ALException

      • isAvailable

        public static boolean isAvailable()
        Returns the available state of this instance.

        The available state is affected by this instance overall availability, i.e. after instantiation.

      • getAL

        public static final AL getAL()
        Return OpenAL global AL.

      • getALC

        public static final ALC getALC()
        Return OpenAL global ALC.

      • getALExt

        public static final ALExt getALExt()
        Return OpenAL global ALExt.

      • getALError

        public static int getALError()

      • checkError

        public static boolean checkError​(Device device,
                                 String prefix,
                                 boolean verbose,
                                 boolean throwException)
        Returns true if an OpenAL ALC or AL error occurred, otherwise false
        Parameters:
        device - referencing an ALCdevice, may be null
        prefix - prefix to print on error and if `verbose`
        verbose - pass true to show errors
        throwException - true to throw an ALException on error
        Returns:
        true if an error occurred, otherwise false

      • checkALError

        public static boolean checkALError​(String prefix,
                                   boolean verbose,
                                   boolean throwException)
        Returns true if an OpenAL AL error occurred, otherwise false
        Parameters:
        prefix - prefix to print on error and if `verbose`
        verbose - pass true to show errors
        throwException - true to throw an ALException on error
        Returns:
        true if an error occurred, otherwise false

      • checkALCError

        public static boolean checkALCError​(Device device,
                                    String prefix,
                                    boolean verbose,
                                    boolean throwException)
        Returns true if an OpenAL ALC error occurred, otherwise false
        Parameters:
        device - referencing an ALCdevice, may be null
        prefix - prefix to print on error and if `verbose`
        verbose - pass true to show errors
        throwException - true to throw an ALException on error
        Returns:
        true if an error occurred, otherwise false

      • createContext

        public static Context createContext​(Device device)
        Creates a new Sound3D Context for a specified device including native ALCcontext creation.
        Parameters:
        device - The device the Context is being created for, must be valid
        Returns:
        The new Sound3D context.

      • createContext

        public static Context createContext​(Device device,
                                    int[] attributes)
        Creates a new Sound3D Context for a specified device including native ALCcontext creation.
        Parameters:
        device - The device the Context is being created for, must be valid.
        attributes - list of ALCcontext attributes for context creation, maybe empty or null
        Returns:
        The new Sound3D context.

      • getCurrentContext

        public static Context getCurrentContext()
        Returns this thread current context. If no context is current, returns null.
        Returns:
        the context current on this thread, or null if no context is current.
        See Also:
        Context.getCurrentContext(), #makeContextCurrent(Context), #releaseContext(Context)

      • makeContextCurrent

        public static boolean makeContextCurrent​(Context context,
                                         boolean throwException)
        Makes the audio context current on the calling thread.

        Recursive calls are supported.

        At any point in time one context can only be current by one thread, and one thread can only have one context current.

        Parameters:
        context - the context to make current.
        throwException - if true, throws ALException if #getALContext() is null, current thread holds another context or failed to natively make current
        Returns:
        true if current thread holds no other context and context successfully made current, otherwise false
        See Also:
        Context#makeCurrent(), #releaseContext(Context)

      • releaseContext

        public static boolean releaseContext​(Context context,
                                     boolean throwException)
        Releases control of this audio context from the current thread, if implementation utilizes context locking.

        Recursive calls are supported.

        Parameters:
        context - the context to release.
        throwException - if true, throws ALException if context has not been previously made current on current thread or native release failed.
        Returns:
        true if context has previously been made current on the current thread and successfully released, otherwise false
        See Also:
        Context#release(), #makeContextCurrent(Context)

      • openDevice

        public static Device openDevice​(String deviceName)
        Opens the named audio device.
        Parameters:
        deviceName - The specified device name, null for default.
        Returns:
        The device described by the specified name

      • generateBuffers

        public static Buffer[] generateBuffers​(int numBuffers)
        Generate an array of Sound3D buffers.
        Parameters:
        numBuffers - The number of Sound3D buffers to generate.
        Returns:
        an array of (initially enpty) Sound3D buffers.

      • loadBuffer

        public static Buffer loadBuffer​(String filename)
                         throws IOException,
                                UnsupportedAudioFileException
        Loads a Sound3D buffer with the specified audio file.
        Parameters:
        filename - the name of the file to load.
        Returns:
        a new Sound3D buffer containing the audio data from the specified file.
        Throws:
        IOException - If the file cannot be found or some other IO error occurs.
        UnsupportedAudioFileException - If the format of the audio data is not supported

      • loadBuffer

        public static Buffer loadBuffer​(InputStream stream)
                         throws IOException,
                                UnsupportedAudioFileException
        Loads a Sound3D buffer with the specified audio file.
        Parameters:
        stream - contains the stream associated with the audio file.
        Returns:
        a new Sound3D buffer containing the audio data from the passed stream.
        Throws:
        IOException - If the stream cannot be read or some other IO error occurs.
        UnsupportedAudioFileException - If the format of the audio data is not supported

      • loadSource

        public static Source loadSource​(String filename)
                         throws IOException,
                                UnsupportedAudioFileException
        Loads a Sound3D Source with the specified audio file. This is functionally equivalent to generateSource(loadBuffer(fileName));
        Parameters:
        filename - the name of the file to load.
        Returns:
        a new Sound3D Source containing the audio data from the specified file.
        Throws:
        IOException - If the file cannot be found or some other IO error occurs.
        UnsupportedAudioFileException - If the format of the audio data is not supported

      • loadSource

        public static Source loadSource​(InputStream stream)
                         throws IOException,
                                UnsupportedAudioFileException
        Loads a Sound3D Source with the specified audio stream. This is functionally equivalent to generateSource(loadBuffer(stream));
        Parameters:
        stream - contains the stream associated with the audio file.
        Returns:
        a new Sound3D Source containing the audio data from the passed stream.
        Throws:
        IOException - If the file cannot be found or some other IO error occurs.
        UnsupportedAudioFileException - If the format of the audio data is not supported

      • generateSources

        public static Source[] generateSources​(int numSources)
        Generates a set of uninitialized Source3D sources
        Parameters:
        numSources - the number of Sound3D sources to generate.
        Returns:
        an array of uninitialized sources.

      • generateSource

        public static Source generateSource​(Buffer buff)
        Generate a Sound3D source from an initialized Buffer.
        Parameters:
        buff - The buffer to be associate with the source.
        Returns:
        the newly generated Source.

      • getListener

        public static Listener getListener()
        Get the listener object associated with this Sound3D environment.
        Returns:
        The listener object.