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

This class is used to represent sound-producing objects in the Sound3D environment. More...

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

Public Member Functions

 Source ()
 Create a new instance with an invalid OpenAL source ID. More...
 
 Source (final int sourceID)
 Create a new instance with a given OpenAL source ID. More...
 
boolean create ()
 Creates a new OpenAL source ID if isValid() == false. More...
 
int getID ()
 Return the OpenAL source ID, -1 if invalid. More...
 
boolean isValid ()
 Returns whether getID() is valid, i.e. More...
 
void delete ()
 Delete this source, freeing its resources. More...
 
void play ()
 Beginning playing the audio in this source. More...
 
void pause ()
 pauses the audio in this Source. More...
 
void stop ()
 Stops the audio in this Source. More...
 
void rewind ()
 Rewinds the audio in this source. More...
 
boolean isPlaying ()
 Determines whether or not this source is playing. More...
 
void setPitch (final float pitch)
 Sets the pitch of the audio on this source. More...
 
float getPitch ()
 Gets the pitch of the audio on this source. More...
 
void setGain (final float gain)
 Sets the gain of the audio on this source. More...
 
float getGain ()
 Gets the gain of the audio on this source. More...
 
void setMaxDistance (final float maxDistance)
 Sets the max distance where there will no longer be any attenuation of the source. More...
 
float getMaxDistance ()
 Gets the max distance where there will no longer be any attenuation of the source. More...
 
void setRolloffFactor (final float rolloffFactor)
 Sets the rolloff rate of the source. More...
 
float getRolloffFactor ()
 Gets the rolloff rate of the source. More...
 
void setReferenceDistance (final float referenceDistance)
 Sets the distance under which the volume for the source would normally drop by half, before being influenced by rolloff factor or max distance. More...
 
float getReferenceDistance ()
 Gets the distance under which the volume for the source would normally drop by half, before being influenced by rolloff factor or max distance. More...
 
void setMinGain (final float minGain)
 Sets the minimum gain for this source. More...
 
float getMinGain ()
 Gets the minimum gain for this source. More...
 
void setMaxGain (final float maxGain)
 Sets the maximum gain for this source. More...
 
float getMaxGain ()
 SGets the maximum gain for this source. More...
 
void setConeOuterGain (final float coneOuterGain)
 Sets the gain when outside the oriented cone. More...
 
float getConeOuterGain ()
 Gets the gain when outside the oriented cone. More...
 
void setPosition (final Vec3f position)
 Sets the x,y,z position of the source. More...
 
void setPosition (final float x, final float y, final float z)
 Sets the x,y,z position of the source. More...
 
Vec3f getPosition ()
 Gets the x,y,z position of the source. More...
 
void setVelocity (final Vec3f velocity)
 Sets the velocity vector of the source. More...
 
void setVelocity (final float x, final float y, final float z)
 Sets the velocity vector of the source. More...
 
Vec3f getVelocity ()
 Gets the velocity vector of the source. More...
 
void setDirection (final Vec3f direction)
 Sets the direction vector of the source. More...
 
void setDirection (final float x, final float y, final float z)
 Sets the direction vector of the source. More...
 
Vec3f getDirection ()
 Gets the direction vector of the source. More...
 
void setSourceRelative (final boolean isRelative)
 Determines if the position of the source is relative to the listener. More...
 
boolean isSourceRelative ()
 Determines if the position of the source is relative to the listener. More...
 
void setLooping (final boolean isLooping)
 turns looping on or off. More...
 
boolean getLooping ()
 indicates whether looping is turned on or off. More...
 
int getBuffersQueued () throws ALException
 Gets the number of buffers currently queued on this source. More...
 
int getBuffersProcessed () throws ALException
 Gets the number of buffers already processed on this source. More...
 
void setBuffer (final Buffer buffer)
 Associates the buffer with this source if buffer is not null, otherwise disassociates the previously associated buffer from this source. More...
 
Buffer getBuffer ()
 Gets the buffer associated with this source. More...
 
void queueBuffers (final Buffer[] buffers) throws ALException
 Queues one or more buffers on a source. More...
 
void queueBuffers (final int[] bufferIDs) throws ALException
 Queues bufferIDs.length OpenAL buffers on a source. More...
 
void unqueueBuffers (final Buffer[] buffers) throws ALException
 Unqueues one or more buffers on a source. More...
 
void unqueueBuffers (final int[] bufferIDs) throws ALException
 Unqueues bufferIDs.length OpenAL buffers on a source. More...
 
String toString ()
 

Detailed Description

This class is used to represent sound-producing objects in the Sound3D environment.

It contains methods for setting the position, direction, pitch, gain and other properties along with methods for starting, pausing, rewinding and stopping sudio projecting from a source.

Author
Athomas Goldberg, Sven Gothel, et al.

Definition at line 48 of file Source.java.

Constructor & Destructor Documentation

◆ Source() [1/2]

com.jogamp.openal.sound3d.Source.Source ( )

Create a new instance with an invalid OpenAL source ID.

Definition at line 53 of file Source.java.

◆ Source() [2/2]

com.jogamp.openal.sound3d.Source.Source ( final int  sourceID)

Create a new instance with a given OpenAL source ID.

Parameters
sourceIDan OpenAL source ID, pass -1 for an invalid value for lazy creation

Definition at line 61 of file Source.java.

Member Function Documentation

◆ create()

boolean com.jogamp.openal.sound3d.Source.create ( )

Creates a new OpenAL source ID if isValid() == false.

Returns
true if a new ID has been successfully created, otherwise false

Definition at line 69 of file Source.java.

Here is the call graph for this function:

◆ delete()

void com.jogamp.openal.sound3d.Source.delete ( )

Delete this source, freeing its resources.

Definition at line 95 of file Source.java.

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

◆ getBuffer()

Buffer com.jogamp.openal.sound3d.Source.getBuffer ( )

Gets the buffer associated with this source.

Returns
the buffer associated with this source

Definition at line 540 of file Source.java.

◆ getBuffersProcessed()

int com.jogamp.openal.sound3d.Source.getBuffersProcessed ( ) throws ALException

Gets the number of buffers already processed on this source.

Returns
the number of buffers already processed on this source.
Exceptions
ALExceptionon AL error

Definition at line 512 of file Source.java.

Here is the call graph for this function:

◆ getBuffersQueued()

int com.jogamp.openal.sound3d.Source.getBuffersQueued ( ) throws ALException

Gets the number of buffers currently queued on this source.

Returns
the number of buffers currently queued on this source.
Exceptions
ALExceptionon AL error

Definition at line 500 of file Source.java.

Here is the call graph for this function:

◆ getConeOuterGain()

float com.jogamp.openal.sound3d.Source.getConeOuterGain ( )

Gets the gain when outside the oriented cone.

Returns
the gain when outside the oriented cone.

Definition at line 321 of file Source.java.

Here is the call graph for this function:

◆ getDirection()

Vec3f com.jogamp.openal.sound3d.Source.getDirection ( )

Gets the direction vector of the source.

Returns
the direction vector of the source.

Definition at line 438 of file Source.java.

Here is the call graph for this function:

◆ getGain()

float com.jogamp.openal.sound3d.Source.getGain ( )

Gets the gain of the audio on this source.

This can be used to contro the volume of the source.

Returns
the gain of the audio on this source

Definition at line 191 of file Source.java.

Here is the call graph for this function:

◆ getID()

int com.jogamp.openal.sound3d.Source.getID ( )

Return the OpenAL source ID, -1 if invalid.

Definition at line 85 of file Source.java.

Here is the caller graph for this function:

◆ getLooping()

boolean com.jogamp.openal.sound3d.Source.getLooping ( )

indicates whether looping is turned on or off.

Returns
true-looping is on, false-looping is off

Definition at line 488 of file Source.java.

Here is the call graph for this function:

◆ getMaxDistance()

float com.jogamp.openal.sound3d.Source.getMaxDistance ( )

Gets the max distance where there will no longer be any attenuation of the source.

Returns
the max ditance for source attentuation.

Definition at line 214 of file Source.java.

Here is the call graph for this function:

◆ getMaxGain()

float com.jogamp.openal.sound3d.Source.getMaxGain ( )

SGets the maximum gain for this source.

Returns
the maximum gain for this source

Definition at line 300 of file Source.java.

Here is the call graph for this function:

◆ getMinGain()

float com.jogamp.openal.sound3d.Source.getMinGain ( )

Gets the minimum gain for this source.

Returns
the minimum gain for this source.

Definition at line 279 of file Source.java.

Here is the call graph for this function:

◆ getPitch()

float com.jogamp.openal.sound3d.Source.getPitch ( )

Gets the pitch of the audio on this source.

The pitch may be modified without altering the playback speed of the audio.

Returns
the pitch value of this source.

Definition at line 168 of file Source.java.

Here is the call graph for this function:

◆ getPosition()

Vec3f com.jogamp.openal.sound3d.Source.getPosition ( )

Gets the x,y,z position of the source.

Returns
a Vec3f object containing the x,y,z position of the source.

Definition at line 360 of file Source.java.

Here is the call graph for this function:

◆ getReferenceDistance()

float com.jogamp.openal.sound3d.Source.getReferenceDistance ( )

Gets the distance under which the volume for the source would normally drop by half, before being influenced by rolloff factor or max distance.

Returns
the reference distance for the source.

Definition at line 258 of file Source.java.

Here is the call graph for this function:

◆ getRolloffFactor()

float com.jogamp.openal.sound3d.Source.getRolloffFactor ( )

Gets the rolloff rate of the source.

The default value is 1.0

Returns
the rolloff rate of the source.

Definition at line 235 of file Source.java.

Here is the call graph for this function:

◆ getVelocity()

Vec3f com.jogamp.openal.sound3d.Source.getVelocity ( )

Gets the velocity vector of the source.

Returns
the velocity vector of the source

Definition at line 399 of file Source.java.

Here is the call graph for this function:

◆ isPlaying()

boolean com.jogamp.openal.sound3d.Source.isPlaying ( )

Determines whether or not this source is playing.

Returns
true if this source is playing.

Definition at line 146 of file Source.java.

Here is the call graph for this function:

◆ isSourceRelative()

boolean com.jogamp.openal.sound3d.Source.isSourceRelative ( )

Determines if the position of the source is relative to the listener.

The default is false.

Returns
true if the position of the source is relative to the listener, false if the position of the source is relative to the world.

Definition at line 466 of file Source.java.

Here is the call graph for this function:

◆ isValid()

boolean com.jogamp.openal.sound3d.Source.isValid ( )

Returns whether getID() is valid, i.e.

not delete()'ed

Definition at line 88 of file Source.java.

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

◆ pause()

void com.jogamp.openal.sound3d.Source.pause ( )

pauses the audio in this Source.

Definition at line 123 of file Source.java.

Here is the call graph for this function:

◆ play()

void com.jogamp.openal.sound3d.Source.play ( )

Beginning playing the audio in this source.

Definition at line 116 of file Source.java.

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

◆ queueBuffers() [1/2]

void com.jogamp.openal.sound3d.Source.queueBuffers ( final Buffer[]  buffers) throws ALException

Queues one or more buffers on a source.

Useful for streaming audio, buffers will be played in the order they are queued.

Parameters
buffersa set of initialized (loaded) buffers.
Exceptions
ALExceptionon AL error

Definition at line 551 of file Source.java.

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

◆ queueBuffers() [2/2]

void com.jogamp.openal.sound3d.Source.queueBuffers ( final int[]  bufferIDs) throws ALException

Queues bufferIDs.length OpenAL buffers on a source.

Parameters
bufferIDsarray of to be queued OpenAL buffer IDs
Exceptions
ALExceptionon AL error

Definition at line 568 of file Source.java.

Here is the call graph for this function:

◆ rewind()

void com.jogamp.openal.sound3d.Source.rewind ( )

Rewinds the audio in this source.

Definition at line 137 of file Source.java.

Here is the call graph for this function:

◆ setBuffer()

void com.jogamp.openal.sound3d.Source.setBuffer ( final Buffer  buffer)

Associates the buffer with this source if buffer is not null, otherwise disassociates the previously associated buffer from this source.

Parameters
bufferthe buffer to be associated with this source if not null. If null, disassociates the current buffer from this source.

Definition at line 526 of file Source.java.

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

◆ setConeOuterGain()

void com.jogamp.openal.sound3d.Source.setConeOuterGain ( final float  coneOuterGain)

Sets the gain when outside the oriented cone.

Parameters
coneOuterGainthe gain when outside the oriented cone.

Definition at line 312 of file Source.java.

Here is the call graph for this function:

◆ setDirection() [1/2]

void com.jogamp.openal.sound3d.Source.setDirection ( final float  x,
final float  y,
final float  z 
)

Sets the direction vector of the source.

Parameters
xthe x direction of the source.
ythe y direction of the source.
zthe z direction of the source.

Definition at line 429 of file Source.java.

Here is the call graph for this function:

◆ setDirection() [2/2]

void com.jogamp.openal.sound3d.Source.setDirection ( final Vec3f  direction)

Sets the direction vector of the source.

Parameters
directionthe direction vector of the source.

Definition at line 413 of file Source.java.

Here is the call graph for this function:

◆ setGain()

void com.jogamp.openal.sound3d.Source.setGain ( final float  gain)

Sets the gain of the audio on this source.

This can be used to contro the volume of the source.

Parameters
gainthe gain of the audio on this source

Definition at line 181 of file Source.java.

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

◆ setLooping()

void com.jogamp.openal.sound3d.Source.setLooping ( final boolean  isLooping)

turns looping on or off.

Parameters
isLoopingtrue-looping is on, false-looping is off

Definition at line 478 of file Source.java.

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

◆ setMaxDistance()

void com.jogamp.openal.sound3d.Source.setMaxDistance ( final float  maxDistance)

Sets the max distance where there will no longer be any attenuation of the source.

Parameters
maxDistancethe max ditance for source attentuation.

Definition at line 204 of file Source.java.

Here is the call graph for this function:

◆ setMaxGain()

void com.jogamp.openal.sound3d.Source.setMaxGain ( final float  maxGain)

Sets the maximum gain for this source.

Parameters
maxGainthe maximum gain for this source

Definition at line 291 of file Source.java.

Here is the call graph for this function:

◆ setMinGain()

void com.jogamp.openal.sound3d.Source.setMinGain ( final float  minGain)

Sets the minimum gain for this source.

Parameters
minGainthe minimum gain for this source.

Definition at line 270 of file Source.java.

Here is the call graph for this function:

◆ setPitch()

void com.jogamp.openal.sound3d.Source.setPitch ( final float  pitch)

Sets the pitch of the audio on this source.

The pitch may be modified without altering the playback speed of the audio.

Parameters
pitchthe pitch value of this source.

Definition at line 158 of file Source.java.

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

◆ setPosition() [1/2]

void com.jogamp.openal.sound3d.Source.setPosition ( final float  x,
final float  y,
final float  z 
)

Sets the x,y,z position of the source.

Parameters
xthe x position of the source.
ythe y position of the source.
zthe z position of the source.

Definition at line 350 of file Source.java.

Here is the call graph for this function:

◆ setPosition() [2/2]

void com.jogamp.openal.sound3d.Source.setPosition ( final Vec3f  position)

Sets the x,y,z position of the source.

Parameters
positiona Vec3f object containing the x,y,z position of the source.

Definition at line 334 of file Source.java.

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

◆ setReferenceDistance()

void com.jogamp.openal.sound3d.Source.setReferenceDistance ( final float  referenceDistance)

Sets the distance under which the volume for the source would normally drop by half, before being influenced by rolloff factor or max distance.

Parameters
referenceDistancethe reference distance for the source.

Definition at line 248 of file Source.java.

Here is the call graph for this function:

◆ setRolloffFactor()

void com.jogamp.openal.sound3d.Source.setRolloffFactor ( final float  rolloffFactor)

Sets the rolloff rate of the source.

The default value is 1.0

Parameters
rolloffFactorthe rolloff rate of the source.

Definition at line 226 of file Source.java.

Here is the call graph for this function:

◆ setSourceRelative()

void com.jogamp.openal.sound3d.Source.setSourceRelative ( final boolean  isRelative)

Determines if the position of the source is relative to the listener.

The default is false.

Parameters
isRelativetrue if the position of the source is relative to the listener, false if the position of the source is relative to the world.

Definition at line 454 of file Source.java.

Here is the call graph for this function:

◆ setVelocity() [1/2]

void com.jogamp.openal.sound3d.Source.setVelocity ( final float  x,
final float  y,
final float  z 
)

Sets the velocity vector of the source.

Parameters
xthe x velocity of the source.
ythe y velocity of the source.
zthe z velocity of the source.

Definition at line 390 of file Source.java.

Here is the call graph for this function:

◆ setVelocity() [2/2]

void com.jogamp.openal.sound3d.Source.setVelocity ( final Vec3f  velocity)

Sets the velocity vector of the source.

Parameters
velocitythe velocity vector of the source

Definition at line 374 of file Source.java.

Here is the call graph for this function:

◆ stop()

void com.jogamp.openal.sound3d.Source.stop ( )

Stops the audio in this Source.

Definition at line 130 of file Source.java.

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

◆ toString()

String com.jogamp.openal.sound3d.Source.toString ( )

Definition at line 602 of file Source.java.

◆ unqueueBuffers() [1/2]

void com.jogamp.openal.sound3d.Source.unqueueBuffers ( final Buffer[]  buffers) throws ALException

Unqueues one or more buffers on a source.

Parameters
buffersa set of previously queued buffers.
Exceptions
ALExceptionon AL error

Definition at line 579 of file Source.java.

Here is the call graph for this function:

◆ unqueueBuffers() [2/2]

void com.jogamp.openal.sound3d.Source.unqueueBuffers ( final int[]  bufferIDs) throws ALException

Unqueues bufferIDs.length OpenAL buffers on a source.

Parameters
bufferIDsarray of resulting unqueued OpenAL buffer IDs of previously queued buffers.
Exceptions
ALExceptionon AL error

Definition at line 596 of file Source.java.

Here is the call graph for this function:

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