JOAL v2.6.0-rc-20250712
JOAL, OpenAL® API Binding for Java™ (public API).
com.jogamp.openal.sound3d.AudioSystem3D Class Reference

The AudioSystem3D class provides a set of methods for creating and manipulating a 3D audio environment. More...

Collaboration diagram for com.jogamp.openal.sound3d.AudioSystem3D:

Static Public Member Functions

static void init () throws ALException
 Initialize the Sound3D environment. More...
 
static boolean isAvailable ()
 Returns the available state of this instance. More...
 
static final AL getAL ()
 Return OpenAL global AL. More...
 
static final ALC getALC ()
 Return OpenAL global ALC. More...
 
static final ALExt getALExt ()
 Return OpenAL global ALExt. More...
 
static int getALError ()
 
static boolean checkError (final Device device, final String prefix, final boolean verbose, final boolean throwException)
 Returns true if an OpenAL ALC or AL error occurred, otherwise false. More...
 
static boolean checkALError (final String prefix, final boolean verbose, final boolean throwException)
 Returns true if an OpenAL AL error occurred, otherwise false. More...
 
static boolean checkALCError (final Device device, final String prefix, final boolean verbose, final boolean throwException)
 Returns true if an OpenAL ALC error occurred, otherwise false. More...
 
static Context createContext (final Device device)
 Creates a new Sound3D Context for a specified device including native ALCcontext creation. More...
 
static Context createContext (final Device device, final int[] attributes)
 Creates a new Sound3D Context for a specified device including native ALCcontext creation. More...
 
static Context getCurrentContext ()
 Returns this thread current context. More...
 
static boolean makeContextCurrent (final Context context, final boolean throwException)
 Makes the audio context current on the calling thread. More...
 
static boolean releaseContext (final Context context, final boolean throwException)
 Releases control of this audio context from the current thread, if implementation utilizes context locking. More...
 
static Device openDevice (final String deviceName)
 Opens the named audio device. More...
 
static Buffer[] generateBuffers (final int numBuffers)
 Generate an array of Sound3D buffers. More...
 
static Buffer loadBuffer (final String filename) throws IOException, UnsupportedAudioFileException
 Loads a Sound3D buffer with the specified audio file. More...
 
static Buffer loadBuffer (InputStream stream) throws IOException, UnsupportedAudioFileException
 Loads a Sound3D buffer with the specified audio file. More...
 
static Source loadSource (final String filename) throws IOException, UnsupportedAudioFileException
 Loads a Sound3D Source with the specified audio file. More...
 
static Source loadSource (final InputStream stream) throws IOException, UnsupportedAudioFileException
 Loads a Sound3D Source with the specified audio stream. More...
 
static Source[] generateSources (final int numSources)
 Generates a set of uninitialized Source3D sources. More...
 
static Source generateSource (final Buffer buff)
 Generate a Sound3D source from an initialized Buffer. More...
 
static Listener getListener ()
 Get the listener object associated with this Sound3D environment. More...
 

Detailed Description

The AudioSystem3D class provides a set of methods for creating and manipulating a 3D audio environment.

Author
Athomas Goldberg, Sven Gothel, et al.

Definition at line 62 of file AudioSystem3D.java.

Member Function Documentation

◆ checkALCError()

static boolean com.jogamp.openal.sound3d.AudioSystem3D.checkALCError ( final Device  device,
final String  prefix,
final boolean  verbose,
final boolean  throwException 
)
static

Returns true if an OpenAL ALC error occurred, otherwise false.

Parameters
devicereferencing an ALCdevice, may be null
prefixprefix to print on error and if verbose
verbosepass true to show errors
throwExceptiontrue to throw an ALException on error
Returns
true if an error occurred, otherwise false

Definition at line 161 of file AudioSystem3D.java.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ checkALError()

static boolean com.jogamp.openal.sound3d.AudioSystem3D.checkALError ( final String  prefix,
final boolean  verbose,
final boolean  throwException 
)
static

Returns true if an OpenAL AL error occurred, otherwise false.

Parameters
prefixprefix to print on error and if verbose
verbosepass true to show errors
throwExceptiontrue to throw an ALException on error
Returns
true if an error occurred, otherwise false

Definition at line 139 of file AudioSystem3D.java.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ checkError()

static boolean com.jogamp.openal.sound3d.AudioSystem3D.checkError ( final Device  device,
final String  prefix,
final boolean  verbose,
final boolean  throwException 
)
static

Returns true if an OpenAL ALC or AL error occurred, otherwise false.

Parameters
devicereferencing an ALCdevice, may be null
prefixprefix to print on error and if verbose
verbosepass true to show errors
throwExceptiontrue to throw an ALException on error
Returns
true if an error occurred, otherwise false

Definition at line 125 of file AudioSystem3D.java.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ createContext() [1/2]

static Context com.jogamp.openal.sound3d.AudioSystem3D.createContext ( final Device  device)
static

Creates a new Sound3D Context for a specified device including native ALCcontext creation.

Parameters
deviceThe device the Context is being created for, must be valid
Returns
The new Sound3D context.

Definition at line 183 of file AudioSystem3D.java.

◆ createContext() [2/2]

static Context com.jogamp.openal.sound3d.AudioSystem3D.createContext ( final Device  device,
final int[]  attributes 
)
static

Creates a new Sound3D Context for a specified device including native ALCcontext creation.

Parameters
deviceThe device the Context is being created for, must be valid.
attributeslist of ALCcontext attributes for context creation, maybe empty or null
Returns
The new Sound3D context.

Definition at line 194 of file AudioSystem3D.java.

◆ generateBuffers()

static Buffer[] com.jogamp.openal.sound3d.AudioSystem3D.generateBuffers ( final int  numBuffers)
static

Generate an array of Sound3D buffers.

Parameters
numBuffersThe number of Sound3D buffers to generate.
Returns
an array of (initially enpty) Sound3D buffers.

Definition at line 264 of file AudioSystem3D.java.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ generateSource()

static Source com.jogamp.openal.sound3d.AudioSystem3D.generateSource ( final Buffer  buff)
static

Generate a Sound3D source from an initialized Buffer.

Parameters
buffThe buffer to be associate with the source.
Returns
the newly generated Source.

Definition at line 398 of file AudioSystem3D.java.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ generateSources()

static Source[] com.jogamp.openal.sound3d.AudioSystem3D.generateSources ( final int  numSources)
static

Generates a set of uninitialized Source3D sources.

Parameters
numSourcesthe number of Sound3D sources to generate.
Returns
an array of uninitialized sources.

Definition at line 379 of file AudioSystem3D.java.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ getAL()

static final AL com.jogamp.openal.sound3d.AudioSystem3D.getAL ( )
static

Return OpenAL global AL.

Definition at line 107 of file AudioSystem3D.java.

◆ getALC()

static final ALC com.jogamp.openal.sound3d.AudioSystem3D.getALC ( )
static

Return OpenAL global ALC.

Definition at line 109 of file AudioSystem3D.java.

◆ getALError()

static int com.jogamp.openal.sound3d.AudioSystem3D.getALError ( )
static

Definition at line 113 of file AudioSystem3D.java.

Here is the call graph for this function:

◆ getALExt()

static final ALExt com.jogamp.openal.sound3d.AudioSystem3D.getALExt ( )
static

Return OpenAL global ALExt.

Definition at line 111 of file AudioSystem3D.java.

Here is the caller graph for this function:

◆ getCurrentContext()

static Context com.jogamp.openal.sound3d.AudioSystem3D.getCurrentContext ( )
static

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)

Definition at line 207 of file AudioSystem3D.java.

Here is the call graph for this function:

◆ getListener()

static Listener com.jogamp.openal.sound3d.AudioSystem3D.getListener ( )
static

Get the listener object associated with this Sound3D environment.

Returns
The listener object.

Definition at line 412 of file AudioSystem3D.java.

Here is the caller graph for this function:

◆ init()

static void com.jogamp.openal.sound3d.AudioSystem3D.init ( ) throws ALException
static

Initialize the Sound3D environment.

Deprecated:
Not required to be called due to static initialization

Definition at line 95 of file AudioSystem3D.java.

◆ isAvailable()

static boolean com.jogamp.openal.sound3d.AudioSystem3D.isAvailable ( )
static

Returns the available state of this instance.

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

Definition at line 104 of file AudioSystem3D.java.

Here is the caller graph for this function:

◆ loadBuffer() [1/2]

static Buffer com.jogamp.openal.sound3d.AudioSystem3D.loadBuffer ( final String  filename) throws IOException, UnsupportedAudioFileException
static

Loads a Sound3D buffer with the specified audio file.

Parameters
filenamethe name of the file to load.
Returns
a new Sound3D buffer containing the audio data from the specified file.
Exceptions
IOExceptionIf the file cannot be found or some other IO error occurs.
UnsupportedAudioFileExceptionIf the format of the audio data is not supported

Definition at line 289 of file AudioSystem3D.java.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ loadBuffer() [2/2]

static Buffer com.jogamp.openal.sound3d.AudioSystem3D.loadBuffer ( InputStream  stream) throws IOException, UnsupportedAudioFileException
static

Loads a Sound3D buffer with the specified audio file.

Parameters
streamcontains the stream associated with the audio file.
Returns
a new Sound3D buffer containing the audio data from the passed stream.
Exceptions
IOExceptionIf the stream cannot be read or some other IO error occurs.
UnsupportedAudioFileExceptionIf the format of the audio data is not supported

Definition at line 314 of file AudioSystem3D.java.

Here is the call graph for this function:

◆ loadSource() [1/2]

static Source com.jogamp.openal.sound3d.AudioSystem3D.loadSource ( final InputStream  stream) throws IOException, UnsupportedAudioFileException
static

Loads a Sound3D Source with the specified audio stream.

This is functionally equivalent to generateSource(loadBuffer(stream));

Parameters
streamcontains the stream associated with the audio file.
Returns
a new Sound3D Source containing the audio data from the passed stream.
Exceptions
IOExceptionIf the file cannot be found or some other IO error occurs.
UnsupportedAudioFileExceptionIf the format of the audio data is not supported

Definition at line 365 of file AudioSystem3D.java.

Here is the call graph for this function:

◆ loadSource() [2/2]

static Source com.jogamp.openal.sound3d.AudioSystem3D.loadSource ( final String  filename) throws IOException, UnsupportedAudioFileException
static

Loads a Sound3D Source with the specified audio file.

This is functionally equivalent to generateSource(loadBuffer(fileName));

Parameters
filenamethe name of the file to load.
Returns
a new Sound3D Source containing the audio data from the specified file.
Exceptions
IOExceptionIf the file cannot be found or some other IO error occurs.
UnsupportedAudioFileExceptionIf the format of the audio data is not supported

Definition at line 344 of file AudioSystem3D.java.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ makeContextCurrent()

static boolean com.jogamp.openal.sound3d.AudioSystem3D.makeContextCurrent ( final Context  context,
final boolean  throwException 
)
static

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
contextthe context to make current.
throwExceptionif 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)

Definition at line 226 of file AudioSystem3D.java.

Here is the call graph for this function:

◆ openDevice()

static Device com.jogamp.openal.sound3d.AudioSystem3D.openDevice ( final String  deviceName)
static

Opens the named audio device.

Parameters
deviceNameThe specified device name, null for default.
Returns
The device described by the specified name

Definition at line 253 of file AudioSystem3D.java.

Here is the caller graph for this function:

◆ releaseContext()

static boolean com.jogamp.openal.sound3d.AudioSystem3D.releaseContext ( final Context  context,
final boolean  throwException 
)
static

Releases control of this audio context from the current thread, if implementation utilizes context locking.

Recursive calls are supported.

Parameters
contextthe context to release.
throwExceptionif 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)

Definition at line 242 of file AudioSystem3D.java.

Here is the call graph for this function:

The documentation for this class was generated from the following file: