Class JoalAudioFactory

  • All Implemented Interfaces:
    AudioFactory

    public class JoalAudioFactory
    extends AbstractAudioFactory
    This is the JOAL audio system specific AudioFactory.

    The JOAL sound system supports, where available, full surround-sound with 3D positioning capabilities.

    When only stereo capable hardware is available, it will automatically create an approximation of the desired sound-scape.

    This factory initialises JOAL, provides new Joal-specific Audio objects and deals with clean-up operations.



    This software is based on or using the JOAL Library available from http://jogamp.org/joal/www/

    JOAL is released under the BSD license. The full license terms follow:
    Copyright (c) 2003-2006 Sun Microsystems, Inc. All Rights Reserved.
    Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
    - Redistribution of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
    - Redistribution in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
    Neither the name of Sun Microsystems, Inc. or the names of contributors may be used to endorse or promote products derived from this software without specific prior written permission.
    This software is provided "AS IS," without a warranty of any kind. ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE HEREBY EXCLUDED. SUN MICROSYSTEMS, INC. ("SUN") AND ITS LICENSORS SHALL NOT BE LIABLE FOR ANY DAMAGES SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR DISTRIBUTING THIS SOFTWARE OR ITS DERIVATIVES. IN NO EVENT WILL SUN OR ITS LICENSORS BE LIABLE FOR ANY LOST REVENUE, PROFIT OR DATA, OR FOR DIRECT, INDIRECT, SPECIAL, CONSEQUENTIAL, INCIDENTAL OR PUNITIVE DAMAGES, HOWEVER CAUSED AND REGARDLESS OF THE THEORY OF LIABILITY, ARISING OUT OF THE USE OF OR INABILITY TO USE THIS SOFTWARE, EVEN IF SUN HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
    You acknowledge that this software is not designed or intended for use in the design, construction, operation or maintenance of any nuclear facility.



    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.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      (package private) static int AL_FORMAT_51CHN16
      Definition of 16-bit 5.1 multi-channel audio format.
      (package private) static int AL_FORMAT_51CHN8
      Definition of 8-bit 5.1 multi-channel audio format.
      (package private) static int AL_FORMAT_61CHN16
      Definition of 16-bit 6.1 multi-channel audio format.
      (package private) static int AL_FORMAT_61CHN8
      Definition of 8-bit 6.1 multi-channel audio format.
      (package private) static int AL_FORMAT_71CHN16
      Definition of 16-bit 7.1 multi-channel audio format.
      (package private) static int AL_FORMAT_71CHN8
      Definition of 8-bit 7.1 multi-channel audio format.
      (package private) static int AL_FORMAT_QUAD16
      Definition of 16-bit quad multi-channel audio format.
      (package private) static int AL_FORMAT_QUAD8
      Definition of 8-bit quad multi-channel audio format.
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      static boolean checkALCError​(com.jogamp.openal.ALCdevice alcDevice)
      Method to check if any error has occurred in the OpenAL sub-system.
      static boolean checkALCError​(com.jogamp.openal.ALCdevice alcDevice, java.lang.String msg)
      Method to check if any error has occurred in the OpenAL context sub-system.
      static boolean checkALError()
      Method to check if any error has occurred in the OpenAL sub-system.
      static boolean checkALError​(java.lang.String msg)
      Method to check if any error has occurred in the OpenAL sub-system.
      void cleanup()
      Perform any implementation specific clean-up operations.
      AudioBuffer createNewBuffer​(java.lang.String systemName, java.lang.String userName)
      Provide a specific new AudioBuffer object.
      AudioListener createNewListener​(java.lang.String systemName, java.lang.String userName)
      Provide a specific new AudioListener object.
      AudioSource createNewSource​(java.lang.String systemName, java.lang.String userName)
      Provide a specific new AudioSource object.
      AudioListener getActiveAudioListener()
      Get the currently active Listener object.
      static com.jogamp.openal.AL getAL()
      Return a reference to the active AL object for use by other Joal objects
      boolean init()
      Initialise this JoalAudioFactory and check for multi-channel support.
      boolean isInitialised()
      Determine if this AudioFactory is initialised
      void setDistanceAttenuated​(boolean attenuated)
      Set if this AudioFactory should attenuate sources based on their distance from the listener.
      java.lang.String toString()  
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
    • Field Detail

      • AL_FORMAT_QUAD8

        static int AL_FORMAT_QUAD8
        Definition of 8-bit quad multi-channel audio format.

        These formats are only supported by certain OpenAL implementations and support is determined at runtime.

        Initially set format to unknown.

      • AL_FORMAT_QUAD16

        static int AL_FORMAT_QUAD16
        Definition of 16-bit quad multi-channel audio format.

        These formats are only supported by certain OpenAL implementations and support is determined at runtime.

        Initially set format to unknown.

      • AL_FORMAT_51CHN8

        static int AL_FORMAT_51CHN8
        Definition of 8-bit 5.1 multi-channel audio format.

        These formats are only supported by certain OpenAL implementations and support is determined at runtime.

        Initially set format to unknown.

      • AL_FORMAT_51CHN16

        static int AL_FORMAT_51CHN16
        Definition of 16-bit 5.1 multi-channel audio format.

        These formats are only supported by certain OpenAL implementations and support is determined at runtime.

        Initially set format to unknown.

      • AL_FORMAT_61CHN8

        static int AL_FORMAT_61CHN8
        Definition of 8-bit 6.1 multi-channel audio format.

        These formats are only supported by certain OpenAL implementations and support is determined at runtime.

        Initially set format to unknown.

      • AL_FORMAT_61CHN16

        static int AL_FORMAT_61CHN16
        Definition of 16-bit 6.1 multi-channel audio format.

        These formats are only supported by certain OpenAL implementations and support is determined at runtime.

        Initially set format to unknown.

      • AL_FORMAT_71CHN8

        static int AL_FORMAT_71CHN8
        Definition of 8-bit 7.1 multi-channel audio format.

        These formats are only supported by certain OpenAL implementations and support is determined at runtime.

        Initially set format to unknown.

      • AL_FORMAT_71CHN16

        static int AL_FORMAT_71CHN16
        Definition of 16-bit 7.1 multi-channel audio format.

        These formats are only supported by certain OpenAL implementations and support is determined at runtime.

        Initially set format to unknown.

    • Method Detail

      • init

        public boolean init()
        Initialise this JoalAudioFactory and check for multi-channel support.

        Initial values for multi-channel formats are set to unknown as OpenAL implementations are only guaranteed to support MONO and STEREO Buffers.

        On initialisation, we need to check if this implementation supports multi-channel formats.

        This is done by making alGetEnumValue calls to request the value of the Buffer Format Tag Enum (that will be passed to an alBufferData call). Enum Values are retrieved by string names. The following names are defined for multi-channel wave formats ...

        • "AL_FORMAT_QUAD8" : 4 Channel, 8 bit data
        • "AL_FORMAT_QUAD16" : 4 Channel, 16 bit data
        • "AL_FORMAT_51CHN8" : 5.1 Channel, 8 bit data
        • "AL_FORMAT_51CHN16" : 5.1 Channel, 16 bit data
        • "AL_FORMAT_61CHN8" : 6.1 Channel, 8 bit data
        • "AL_FORMAT_61CHN16" : 6.1 Channel, 16 bit data
        • "AL_FORMAT_71CHN8" : 7.1 Channel, 8 bit data
        • "AL_FORMAT_71CHN16" : 7.1 Channel, 16 bit data
        Specified by:
        init in interface AudioFactory
        Overrides:
        init in class AbstractAudioFactory
        Returns:
        true, if initialisation successful
      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object
      • isInitialised

        public boolean isInitialised()
        Description copied from interface: AudioFactory
        Determine if this AudioFactory is initialised
        Returns:
        true if initialised
      • createNewBuffer

        public AudioBuffer createNewBuffer​(java.lang.String systemName,
                                           java.lang.String userName)
        Description copied from interface: AudioFactory
        Provide a specific new AudioBuffer object.
        Parameters:
        systemName - for this object instance
        userName - for this object instance
        Returns:
        a new specific AudioBuffer
      • createNewListener

        public AudioListener createNewListener​(java.lang.String systemName,
                                               java.lang.String userName)
        Description copied from interface: AudioFactory
        Provide a specific new AudioListener object.
        Parameters:
        systemName - for this object instance
        userName - for this object instance
        Returns:
        a new specific AudioListener
      • createNewSource

        public AudioSource createNewSource​(java.lang.String systemName,
                                           java.lang.String userName)
        Description copied from interface: AudioFactory
        Provide a specific new AudioSource object.
        Parameters:
        systemName - for this object instance
        userName - for this object instance
        Returns:
        a new specific AudioSource
      • getAL

        public static com.jogamp.openal.AL getAL()
        Return a reference to the active AL object for use by other Joal objects
        Returns:
        active AL object
      • checkALError

        public static boolean checkALError()
        Method to check if any error has occurred in the OpenAL sub-system.

        If an error has occurred, log the error as a warning message and return True.

        If no error has occurred, return False.

        Returns:
        True if an error has occurred
      • checkALError

        public static boolean checkALError​(java.lang.String msg)
        Method to check if any error has occurred in the OpenAL sub-system.

        If an error has occurred, log the error as a warning message with the defined message pre-pended and return True.

        If no error has occurred, return False.

        Parameters:
        msg - additional message prepended to the log
        Returns:
        True if an error has occurred
      • checkALCError

        public static boolean checkALCError​(com.jogamp.openal.ALCdevice alcDevice)
        Method to check if any error has occurred in the OpenAL sub-system.

        If an error has occurred, log the error as a warning message and return True.

        If no error has occurred, return False.

        Parameters:
        alcDevice - OpenAL context device to check
        Returns:
        True if an error has occurred
      • checkALCError

        public static boolean checkALCError​(com.jogamp.openal.ALCdevice alcDevice,
                                            java.lang.String msg)
        Method to check if any error has occurred in the OpenAL context sub-system.

        If an error has occurred, log the error as a warning message with the defined message pre-pended and return True.

        If no error has occurred, return False.

        Parameters:
        alcDevice - OpenAL context device to check
        msg - additional message prepended to the log
        Returns:
        True if an error has occurred