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 boolean
checkALCError(Device device, String prefix, boolean verbose, boolean throwException)
Returns true if an OpenAL ALC error occurred, otherwise falsestatic boolean
checkALError(String prefix, boolean verbose, boolean throwException)
Returns true if an OpenAL AL error occurred, otherwise falsestatic boolean
checkError(Device device, String prefix, boolean verbose, boolean throwException)
Returns true if an OpenAL ALC or AL error occurred, otherwise falsestatic Context
createContext(Device device)
Creates a new Sound3D Context for a specified device including nativeALCcontext
creation.static Context
createContext(Device device, int[] attributes)
Creates a new Sound3D Context for a specified device including nativeALCcontext
creation.static Buffer[]
generateBuffers(int numBuffers)
Generate an array of Sound3D buffers.static Source
generateSource(Buffer buff)
Generate a Sound3D source from an initialized Buffer.static Source[]
generateSources(int numSources)
Generates a set of uninitialized Source3D sourcesstatic AL
getAL()
Return OpenAL globalAL
.static ALC
getALC()
Return OpenAL globalALC
.static int
getALError()
static ALExt
getALExt()
Return OpenAL globalALExt
.static Context
getCurrentContext()
Returns this thread current context.static Listener
getListener()
Get the listener object associated with this Sound3D environment.static void
init()
Deprecated.Not required to be called due to static initializationstatic boolean
isAvailable()
Returns theavailable state
of this instance.static Buffer
loadBuffer(InputStream stream)
Loads a Sound3D buffer with the specified audio file.static Buffer
loadBuffer(String filename)
Loads a Sound3D buffer with the specified audio file.static Source
loadSource(InputStream stream)
Loads a Sound3D Source with the specified audio stream.static Source
loadSource(String filename)
Loads a Sound3D Source with the specified audio file.static boolean
makeContextCurrent(Context context, boolean throwException)
Makes the audio context current on the calling thread.static Device
openDevice(String deviceName)
Opens the named audio device.static boolean
releaseContext(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 state
of this instance.The
available state
is 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 nativeALCcontext
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 nativeALCcontext
creation.- Parameters:
device
- The device the Context is being created for, must be valid.attributes
- list ofALCcontext
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.
-
-