Package com.jogamp.openal.sound3d
Class AudioSystem3D
- java.lang.Object
-
- com.jogamp.openal.sound3d.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 Summary
Constructors Constructor Description AudioSystem3D()
-
Method Summary
All Methods Static Methods Concrete Methods Deprecated Methods Modifier and Type Method Description static booleancheckALCError(Device device, String prefix, boolean verbose, boolean throwException)Returns true if an OpenAL ALC error occurred, otherwise falsestatic booleancheckALError(String prefix, boolean verbose, boolean throwException)Returns true if an OpenAL AL error occurred, otherwise falsestatic booleancheckError(Device device, String prefix, boolean verbose, boolean throwException)Returns true if an OpenAL ALC or AL error occurred, otherwise falsestatic ContextcreateContext(Device device)Creates a new Sound3D Context for a specified device including nativeALCcontextcreation.static ContextcreateContext(Device device, int[] attributes)Creates a new Sound3D Context for a specified device including nativeALCcontextcreation.static Buffer[]generateBuffers(int numBuffers)Generate an array of Sound3D buffers.static SourcegenerateSource(Buffer buff)Generate a Sound3D source from an initialized Buffer.static Source[]generateSources(int numSources)Generates a set of uninitialized Source3D sourcesstatic ALgetAL()Return OpenAL globalAL.static ALCgetALC()Return OpenAL globalALC.static intgetALError()static ALExtgetALExt()Return OpenAL globalALExt.static ContextgetCurrentContext()Returns this thread current context.static ListenergetListener()Get the listener object associated with this Sound3D environment.static voidinit()Deprecated.Not required to be called due to static initializationstatic booleanisAvailable()Returns theavailable stateof this instance.static BufferloadBuffer(InputStream stream)Loads a Sound3D buffer with the specified audio file.static BufferloadBuffer(String filename)Loads a Sound3D buffer with the specified audio file.static SourceloadSource(InputStream stream)Loads a Sound3D Source with the specified audio stream.static SourceloadSource(String filename)Loads a Sound3D Source with the specified audio file.static booleanmakeContextCurrent(Context context, boolean throwException)Makes the audio context current on the calling thread.static DeviceopenDevice(String deviceName)Opens the named audio device.static booleanreleaseContext(Context context, boolean throwException)Releases control of this audio context from the current thread, if implementation utilizes context locking.
-
-
-
Method Detail
-
init
@Deprecated public static void init() throws ALException
Deprecated.Not required to be called due to static initializationInitialize the Sound3D environment.- Throws:
ALException
-
isAvailable
public static boolean isAvailable()
Returns theavailable stateof this instance.The
available stateis affected by this instance overall availability, i.e. after instantiation.
-
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 anALCdevice, may be nullprefix- prefix to print on error and if `verbose`verbose- pass true to show errorsthrowException- 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 errorsthrowException- 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 anALCdevice, may be nullprefix- prefix to print on error and if `verbose`verbose- pass true to show errorsthrowException- 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 nativeALCcontextcreation.- 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 nativeALCcontextcreation.- Parameters:
device- The device the Context is being created for, must be valid.attributes- list ofALCcontextattributes 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.
-
-