Package com.ardor3d.audio.joal
Class LibraryJOAL
java.lang.Object
com.ardor3d.audio.Library
com.ardor3d.audio.joal.LibraryJOAL
The LibraryJOAL class interfaces the JOAL binding of OpenAL.
This software is based on or using the JOAL Library available from https://jogamp.org/joal/www/
JOAL License:
Copyright (c) 2003 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 MIDROSYSTEMS, 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.
SoundSystem LibraryJOAL License:
You are free to use this library for any purpose, commercial or otherwise. You may modify this library or source code, and distribute it any way you like, provided the following conditions are met:
1) You must abide by the conditions of the aforementioned JOAL License.
2) You may not falsely claim to be the author of this library or any unmodified portion of it.
3) You may not copyright this library or a modified version of it and then sue me for copyright infringement.
4) If you modify the source code, you must clearly document the changes made before redistributing the modified source code, so other users know it is not the original code.
5) You are not required to give me credit for this library in any derived work, but if you do, you must also mention my website: http://www.paulscode.com
6) I the author will not be responsible for any damages (physical, financial, or otherwise) caused by the use if this library or any part of it.
7) I the author do not guarantee, warrant, or make any representations, either expressed or implied, regarding the use of this library or any part of it.
Author: Paul Lamb
http://www.paulscode.com
This software is based on or using the JOAL Library available from https://jogamp.org/joal/www/
JOAL License:
Copyright (c) 2003 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 MIDROSYSTEMS, 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.
SoundSystem LibraryJOAL License:
You are free to use this library for any purpose, commercial or otherwise. You may modify this library or source code, and distribute it any way you like, provided the following conditions are met:
1) You must abide by the conditions of the aforementioned JOAL License.
2) You may not falsely claim to be the author of this library or any unmodified portion of it.
3) You may not copyright this library or a modified version of it and then sue me for copyright infringement.
4) If you modify the source code, you must clearly document the changes made before redistributing the modified source code, so other users know it is not the original code.
5) You are not required to give me credit for this library in any derived work, but if you do, you must also mention my website: http://www.paulscode.com
6) I the author will not be responsible for any damages (physical, financial, or otherwise) caused by the use if this library or any part of it.
7) I the author do not guarantee, warrant, or make any representations, either expressed or implied, regarding the use of this library or any part of it.
Author: Paul Lamb
http://www.paulscode.com
-
Nested Class Summary
Modifier and TypeClassDescriptionstatic class
The LibraryJOAL.Exception class provides library-specific error information. -
Field Summary
Fields inherited from class com.ardor3d.audio.Library
bufferMap, listener, normalChannels, reverseByteOrder, sourceMap, streamingChannels, streamThread
-
Constructor Summary
ConstructorDescriptionConstructor: Instantiates the source map, buffer map and listener information.Also sets the library type to SoundSystemConfig.LIBRARY_OPENAL -
Method Summary
Modifier and TypeMethodDescriptionstatic boolean
Whether or not the AL_PITCH control is supported.void
cleanup()
Stops all sources, shuts down OpenAL, and removes references to all instantiated objects.void
copySources
(HashMap<String, Source> srcMap) Creates sources based on the source map provided.protected Channel
createChannel
(int type) Creates a new channel of the specified type (normal or streaming).void
The Doppler parameters have changed.static com.jogamp.openal.AL
getAL()
Returns a handle to OpenAL, or null if OpenAL is not initialized.Returns the name of the class.static String
Returns a longer description of this library type.static String
getTitle()
Returns the short title of this library type.void
init()
Initializes OpenAL, creates the listener, and grabs up audio channels.static boolean
Checks if the OpenAL library type is compatible.boolean
loadSound
(FilenameURL filenameURL) Pre-loads a sound into memory.boolean
loadSound
(SoundBuffer buffer, String identifier) Saves the specified sample data, under the specified identifier.void
newSource
(boolean priority, boolean toStream, boolean toLoop, String sourcename, FilenameURL filenameURL, float x, float y, float z, int attModel, float distOrRoll) Creates a new source and places it into the source map.void
quickPlay
(boolean priority, boolean toStream, boolean toLoop, String sourcename, FilenameURL filenameURL, float x, float y, float z, int attModel, float distOrRoll, boolean temporary) Creates and immediately plays a new source.void
rawDataStream
(AudioFormat audioFormat, boolean priority, String sourcename, float x, float y, float z, int attModel, float distOrRoll) Opens a direct line for streaming audio data.void
setListenerAngle
(float angle) Changes the listeners orientation to the specified 'angle' radians counterclockwise around the y-Axis.void
Changes the listeners position and orientation using the specified listener data.void
setListenerOrientation
(float lookX, float lookY, float lookZ, float upX, float upY, float upZ) Changes the listeners orientation using the specified coordinates.void
setListenerPosition
(float x, float y, float z) Changes the listener's position.void
setListenerVelocity
(float x, float y, float z) Sets the listener's velocity, for use in Doppler effect.void
setMasterVolume
(float value) Sets the overall volume to the specified value, affecting all sources.void
unloadSound
(String filename) Removes a pre-loaded sound from memory.Methods inherited from class com.ardor3d.audio.Library
activate, checkFadeVolumes, cull, dequeueSound, errorCheck, errorMessage, fadeOut, fadeOutIn, feedRawAudioData, feedRawAudioData, flush, getAllLoadedFilenames, getAllSourcenames, getListenerData, getPitch, getSource, getSources, getVolume, importantMessage, listenerMoved, loadMidi, message, midiSourcename, millisecondsPlayed, moveListener, pause, play, play, printStackTrace, queueSound, removeSource, removeTemporarySources, replaySources, reverseByteOrder, rewind, setAttenuation, setDistOrRoll, setLooping, setPitch, setPosition, setPriority, setTemporary, setVelocity, setVolume, stop, turnListener, unloadMidi
-
Constructor Details
-
LibraryJOAL
Constructor: Instantiates the source map, buffer map and listener information.Also sets the library type to SoundSystemConfig.LIBRARY_OPENAL- Throws:
SoundSystemException
- if the sound system cannot be initialized
-
-
Method Details
-
init
Initializes OpenAL, creates the listener, and grabs up audio channels.- Overrides:
init
in classLibrary
- Throws:
SoundSystemException
-
libraryCompatible
public static boolean libraryCompatible()Checks if the OpenAL library type is compatible.- Returns:
- True or false.
-
createChannel
Creates a new channel of the specified type (normal or streaming). Possible values for channel type can be found in theSoundSystemConfig
class.- Overrides:
createChannel
in classLibrary
- Parameters:
type
- Type of channel.- Returns:
- The new channel.
-
cleanup
public void cleanup()Stops all sources, shuts down OpenAL, and removes references to all instantiated objects. -
loadSound
Pre-loads a sound into memory. -
loadSound
Saves the specified sample data, under the specified identifier. This identifier can be later used in place of 'filename' parameters to reference the sample data. -
unloadSound
Removes a pre-loaded sound from memory. This is a good method to use for freeing up memory after a large sound file is no longer needed. NOTE: the source will remain in memory after this method has been called, for as long as the sound is attached to an existing source.- Overrides:
unloadSound
in classLibrary
- Parameters:
filename
- Filename/identifier of the sound file to unload.
-
setMasterVolume
public void setMasterVolume(float value) Sets the overall volume to the specified value, affecting all sources.- Overrides:
setMasterVolume
in classLibrary
- Parameters:
value
- New volume, float value ( 0.0f - 1.0f ).
-
newSource
public void newSource(boolean priority, boolean toStream, boolean toLoop, String sourcename, FilenameURL filenameURL, float x, float y, float z, int attModel, float distOrRoll) Creates a new source and places it into the source map.- Overrides:
newSource
in classLibrary
- Parameters:
priority
- Setting this to true will prevent other sounds from overriding this one.toStream
- Setting this to true will load the sound in pieces rather than all at once.toLoop
- Should this source loop, or play only once.sourcename
- A unique identifier for this source. Two sources may not use the same sourcename.filenameURL
- Filename/URL of the sound file to play at this source.x
- X position for this source.y
- Y position for this source.z
- Z position for this source.attModel
- Attenuation model to use.distOrRoll
- Either the fading distance or rolloff factor, depending on the value of "attmodel".
-
rawDataStream
public void rawDataStream(AudioFormat audioFormat, boolean priority, String sourcename, float x, float y, float z, int attModel, float distOrRoll) Opens a direct line for streaming audio data.- Overrides:
rawDataStream
in classLibrary
- Parameters:
audioFormat
- Format that the data will be in.priority
- Setting this to true will prevent other sounds from overriding this one.sourcename
- A unique identifier for this source. Two sources may not use the same sourcename.x
- X position for this source.y
- Y position for this source.z
- Z position for this source.attModel
- Attenuation model to use.distOrRoll
- Either the fading distance or rolloff factor, depending on the value of "attmodel".
-
quickPlay
public void quickPlay(boolean priority, boolean toStream, boolean toLoop, String sourcename, FilenameURL filenameURL, float x, float y, float z, int attModel, float distOrRoll, boolean temporary) Creates and immediately plays a new source.- Overrides:
quickPlay
in classLibrary
- Parameters:
priority
- Setting this to true will prevent other sounds from overriding this one.toStream
- Setting this to true will load the sound in pieces rather than all at once.toLoop
- Should this source loop, or play only once.sourcename
- A unique identifier for this source. Two sources may not use the same sourcename.filenameURL
- Filename/URL of the sound file to play at this source.x
- X position for this source.y
- Y position for this source.z
- Z position for this source.attModel
- Attenuation model to use.distOrRoll
- Either the fading distance or rolloff factor, depending on the value of "attmodel".temporary
- Whether or not this source should be removed after it finishes playing.
-
copySources
Creates sources based on the source map provided.- Overrides:
copySources
in classLibrary
- Parameters:
srcMap
- Sources to copy.
-
setListenerPosition
public void setListenerPosition(float x, float y, float z) Changes the listener's position.- Overrides:
setListenerPosition
in classLibrary
- Parameters:
x
- Destination X coordinate.y
- Destination Y coordinate.z
- Destination Z coordinate.
-
setListenerAngle
public void setListenerAngle(float angle) Changes the listeners orientation to the specified 'angle' radians counterclockwise around the y-Axis.- Overrides:
setListenerAngle
in classLibrary
- Parameters:
angle
- Radians.
-
setListenerOrientation
public void setListenerOrientation(float lookX, float lookY, float lookZ, float upX, float upY, float upZ) Changes the listeners orientation using the specified coordinates.- Overrides:
setListenerOrientation
in classLibrary
- Parameters:
lookX
- X element of the look-at direction.lookY
- Y element of the look-at direction.lookZ
- Z element of the look-at direction.upX
- X element of the up direction.upY
- Y element of the up direction.upZ
- Z element of the up direction.
-
setListenerData
Changes the listeners position and orientation using the specified listener data.- Overrides:
setListenerData
in classLibrary
- Parameters:
l
- Listener data to use.
-
setListenerVelocity
public void setListenerVelocity(float x, float y, float z) Sets the listener's velocity, for use in Doppler effect.- Overrides:
setListenerVelocity
in classLibrary
- Parameters:
x
- Velocity along world x-axis.y
- Velocity along world y-axis.z
- Velocity along world z-axis.
-
dopplerChanged
public void dopplerChanged()The Doppler parameters have changed.- Overrides:
dopplerChanged
in classLibrary
-
getAL
public static com.jogamp.openal.AL getAL()Returns a handle to OpenAL, or null if OpenAL is not initialized.- Returns:
- Used to interface with OpenAL functions.
-
alPitchSupported
public static boolean alPitchSupported()Whether or not the AL_PITCH control is supported.- Returns:
- True if AL_PITCH is supported.
-
getTitle
Returns the short title of this library type.- Returns:
- A short title.
-
getDescription
Returns a longer description of this library type.- Returns:
- A longer description.
-
getClassName
Returns the name of the class.- Overrides:
getClassName
in classLibrary
- Returns:
- "Library" + library title.
-