net.jinx.audio
Class Source

java.lang.Object
  net.jinx.audio.Source

Direct Known Subclasses:

StreamSource, SynthesizedSource

public class Source
extends java.lang.Object

The Source class is intended to make the job of implementing the Audible interface a little easier. Source represents any individual sound source.

Source objects should have their delete() method called when they are no longer needed and should then be discarded. They should always be deleted and discarded when an Audible object's deinit() method is called. They should NEVER be used after that.

This is designed to loosely mimic the Source class of the Sound3D toolkit, while still allowing low-level access to the OpenAL APIs.

API Stability: Alpha; this is subject to change at any time.

Constructor Summary

Source(net.java.games.joal.AL al, net.java.games.joal.ALC alc)
Constructor; allows the construction of an unconfigured Source.

Method Summary

int	buffersProcessed() Provides the number of Buffers already processed on this Source.
int	buffersQueued() Provides the number of Buffers currently queued on this Source.
void	delete() Frees the resources that this Source consumes.
protected net.java.games.joal.AL	getAL() Provides the AL object that was used to construct this Source.
protected net.java.games.joal.ALC	getALC() Provides the ALC object that was used to construct this Source.
protected boolean	getBooleanInt(int pname) Utility method to use getInt to get a boolean value.
Buffer	getBuffer() Provides the Buffer associated with this Source.
float	getConeOuterGain() Provides the gain outside the oriented cone.
float[]	getDirection() Provides the direction of this Source.
protected float	getFloat(int pname) Utility method to use alGetSourcef().
float	getGain() Provides the gain for this source.
protected int	getInt(int pname) Utility method to use alGetSourcei().
float	getMaxDistance() Provides the maximum distance after which there will be no more attenuation of this source.
float	getMaxGain() Provides the maximum gain for this Source.
float	getMinGain() Provides the minimum gain for this Source.
float	getPitch() Provides the current pitch value of this Source.
float[]	getPosition() Provides the position of this Source.
float	getReferenceDistance() Provides the value of the reference distance for this Source.
float	getRolloffFactor() Provides the rolloff factor.
int	getSourceID() Provides the OpenAL name of this Source.
float[]	getVelocity() Provides the velocity of this Source.
boolean	isInitialized() Indicates if this Source is in an initialized state, in which it will function.
boolean	isLooping() Indicates if this Source will loop.
boolean	isSourceRelative() Indicates if this Source is relative to the position the Listener.
void	pause() Pauses this source.
void	play() Begins playing this Source.
void	queueBuffer(Buffer buffer) Queues a Buffer object on this Source.
void	queueBuffers(Buffer[] buffers) Queues an array of Buffer objects on this Source.
void	rewind() Rewinds this source.
protected void	setBooleanInt(int pname, boolean value) Utility method to use setInt to set a boolean value.
void	setBuffer(Buffer buffer) Sets the Buffer associated with this Source.
void	setConeOuterGain(float cog) Sets the gain outside the oriented cone.
void	setDirection(float[] d) Sets the direction of this Source.
void	setDirection(float x, float y, float z) Sets the direction of this Source.
protected void	setFloat(int pname, float value) Utility method to use alSourcef().
void	setGain(float gain) Sets the gain for this Source.
protected void	setInt(int pname, int value) Utility method to use alSourcei().
void	setLooping(boolean loop) Sets wether or not this Source loops back to the beginning when it finishes.
void	setMaxDistance(float max) Sets the maximum distance after which there will be no more attenuation of this Source.
void	setMaxGain(float mg) Sets the maximum gain for this Source.
void	setMinGain(float mg) Sets the minimum gain for this Source.
void	setPitch(float pitch) Sets the pitch of this Source without affecting the speed of playback.
void	setPosition(float[] pos) Sets the position of this Source.
void	setPosition(float x, float y, float z) Sets the position of this Source.
void	setReferenceDistance(float rd) Sets the reference distance; this is the distance where the volume of this Source would normally drop by half before being affected by rolloff factor or maximum distance.
void	setRolloffFactor(float rolloff) Sets the rolloff factor.
void	setSourceRelative(boolean sr) Sets whether or not this Source is relative to the position of the Listener.
void	setVelocity(float[] v) Sets the velocity of this Source.
void	setVelocity(float x, float y, float z) Sets the velocity of this Source.
void	stop() Stops this Source.
void	unqueueBuffer(Buffer buffer) Unqueues a Buffer object from this Source.
void	unqueueBuffers(Buffer[] buffers) Unqueues an array of Buffer objects from this Source.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Source

public Source(net.java.games.joal.AL al,
              net.java.games.joal.ALC alc)

Constructor; allows the construction of an unconfigured Source.

Parameters:

al - the AL object to use for audio rendering.

alc - the ALC object to use for audio rendering.

Throws:

java.lang.NullPointerException - will be thrown if either al or alc are null.

Method Detail

getSourceID

public int getSourceID()

Provides the OpenAL name of this Source. This can be used to configure the source using regular OpenAL commands.

Returns:

the source ID.

isInitialized

public boolean isInitialized()

Indicates if this Source is in an initialized state, in which it will function.

Returns:

true if this Source will function properly. False if it's delete() method has been called.

getAL

protected net.java.games.joal.AL getAL()

Provides the AL object that was used to construct this Source.

Returns:

the AL object.

getALC

protected net.java.games.joal.ALC getALC()

Provides the ALC object that was used to construct this Source.

Returns:

the ALC object.

play

public void play()

Begins playing this Source.

pause

public void pause()

Pauses this source.

stop

public void stop()

Stops this Source.

rewind

public void rewind()

Rewinds this source.

getInt

protected int getInt(int pname)

Utility method to use alGetSourcei().

Parameters:

pname - the parameter name.

setInt

protected void setInt(int pname,
                      int value)

Utility method to use alSourcei().

Parameters:

pname - the parameter name.

value - the value to use to set the parameter.

setBooleanInt

protected void setBooleanInt(int pname,
                             boolean value)

Utility method to use setInt to set a boolean value.

Parameters:

pname - the parameter name.

value - the value to use to set the parameter.

getBooleanInt

protected boolean getBooleanInt(int pname)

Utility method to use getInt to get a boolean value.

Parameters:

pname - the parameter name.

setFloat

protected void setFloat(int pname,
                        float value)

Utility method to use alSourcef().

Parameters:

pname - the parameter name.

value - the value to use to set the parameter.

getFloat

protected float getFloat(int pname)

Utility method to use alGetSourcef().

Parameters:

pname - the parameter name.

setPitch

public void setPitch(float pitch)

Sets the pitch of this Source without affecting the speed of playback.

Parameters:

pitch - the new pitch value.

getPitch

public float getPitch()

Provides the current pitch value of this Source.

Returns:

the pitch value.

setGain

public void setGain(float gain)

Sets the gain for this Source. This controls the volume of this Source.

Parameters:

gain - the new gain value.

getGain

public float getGain()

Provides the gain for this source. This is the volume for this Source.

Returns:

the gain value.

setMaxDistance

public void setMaxDistance(float max)

Sets the maximum distance after which there will be no more attenuation of this Source.

Parameters:

max - the new maximum distance.

getMaxDistance

public float getMaxDistance()

Provides the maximum distance after which there will be no more attenuation of this source.

Returns:

the max distance value.

setRolloffFactor

public void setRolloffFactor(float rolloff)

Sets the rolloff factor.

Parameters:

rolloff - the rolloff value.

getRolloffFactor

public float getRolloffFactor()

Provides the rolloff factor.

Returns:

the rolloff factor.

setReferenceDistance

public void setReferenceDistance(float rd)

Sets the reference distance; this is the distance where the volume of this Source would normally drop by half before being affected by rolloff factor or maximum distance.

Parameters:

rd - the reference distance.

getReferenceDistance

public float getReferenceDistance()

Provides the value of the reference distance for this Source.

Returns:

the reference distance.

setMinGain

public void setMinGain(float mg)

Sets the minimum gain for this Source.

Parameters:

mg - the mimimum gain.

getMinGain

public float getMinGain()

Provides the minimum gain for this Source.

Returns:

the minimum gain.

setMaxGain

public void setMaxGain(float mg)

Sets the maximum gain for this Source.

Parameters:

mg - the maximum gain.

getMaxGain

public float getMaxGain()

Provides the maximum gain for this Source.

Returns:

the maximum gain.

setConeOuterGain

public void setConeOuterGain(float cog)

Sets the gain outside the oriented cone.

Parameters:

cog - the value.

getConeOuterGain

public float getConeOuterGain()

Provides the gain outside the oriented cone.

Returns:

the value.

setPosition

public void setPosition(float x,
                        float y,
                        float z)

Sets the position of this Source.

Parameters:

x - the x value.

y - the y value.

z - the z value.

setPosition

public void setPosition(float[] pos)

Sets the position of this Source.

Parameters:

pos - the position as a float array. This must be at least three elements.

getPosition

public float[] getPosition()

Provides the position of this Source.

Returns:

the position as a length three float array.

setVelocity

public void setVelocity(float x,
                        float y,
                        float z)

Sets the velocity of this Source.

Parameters:

x - the x value.

y - the y value.

z - the z value.

setVelocity

public void setVelocity(float[] v)

Sets the velocity of this Source.

Parameters:

v - the velocity as a float array. This must be at least three elements.

getVelocity

public float[] getVelocity()

Provides the velocity of this Source.

Returns:

the velocity as a length three float array.

setDirection

public void setDirection(float x,
                         float y,
                         float z)

Sets the direction of this Source.

Parameters:

x - the x value.

y - the y value.

z - the z value.

setDirection

public void setDirection(float[] d)

Sets the direction of this Source.

Parameters:

d - the direction as a float array. This must be at least three elements.

getDirection

public float[] getDirection()

Provides the direction of this Source.

Returns:

the direction as a length three float array.

setSourceRelative

public void setSourceRelative(boolean sr)

Sets whether or not this Source is relative to the position of the Listener.

Parameters:

sr - if true, then it will be source relative, false means it isn't.

isSourceRelative

public boolean isSourceRelative()

Indicates if this Source is relative to the position the Listener.

Returns:

true if it is relative.

setLooping

public void setLooping(boolean loop)

Sets wether or not this Source loops back to the beginning when it finishes.

Parameters:

loop - boolean value for setting this option.

isLooping

public boolean isLooping()

Indicates if this Source will loop.

Returns:

true if this Source will loop.

buffersQueued

public int buffersQueued()

Provides the number of Buffers currently queued on this Source.

Returns:

the number of Buffers.

buffersProcessed

public int buffersProcessed()

Provides the number of Buffers already processed on this Source.

Returns:

the number of Buffers.

setBuffer

public void setBuffer(Buffer buffer)

Sets the Buffer associated with this Source.

Parameters:

buffer - the Buffer to associate with this Source.

getBuffer

public Buffer getBuffer()

Provides the Buffer associated with this Source.

Returns:

the Buffer.

delete

public void delete()

Frees the resources that this Source consumes.

queueBuffers

public void queueBuffers(Buffer[] buffers)

Queues an array of Buffer objects on this Source.

Parameters:

buffers - the Buffer objects to queue.

queueBuffer

public void queueBuffer(Buffer buffer)

Queues a Buffer object on this Source.

Parameters:

buffer - the Buffer object to queue.

unqueueBuffers

public void unqueueBuffers(Buffer[] buffers)

Unqueues an array of Buffer objects from this Source.

Parameters:

buffers - the Buffer objects to dequeue.

unqueueBuffer

public void unqueueBuffer(Buffer buffer)

Unqueues a Buffer object from this Source.

Parameters:

buffer - the Buffer object to dequeue.