com.threerings.openal
Class Sound

java.lang.Object
  com.threerings.openal.Sound

Direct Known Subclasses:

BlankSound

public class Sound
extends Object

Represents an instance of a sound clip which can be positioned in 3D space, gain and pitch adjusted and played or looped.

Nested Class Summary

static interface

Sound.StartObserver Used to await notification of the starting of a sound which may be delayed in loading.

Field Summary

protected ClipBuffer	_buffer The OpenAL buffer from which we get our sound data.
protected float	_coneInnerAngle The inside angle of the sound cone.
protected float	_coneOuterAngle The outside angle of the sound cone.
protected float	_coneOuterGain The gain outside the sound cone.
protected float	_dx The direction of the sound.
protected float	_dy The direction of the sound.
protected float	_dz The direction of the sound.
protected float	_gain The gain of the sound.
protected SoundGroup	_group The sound group with which we are associated.
protected boolean	_loopDesired Whether or not looping is desired after resolution.
protected float	_maxDistance The maximum distance for attenuation.
protected float	_maxGain The maximum gain.
protected float	_minGain The minimum gain.
protected float	_pitch The pitch multiplier.
protected float	_px The position of the sound.
protected float	_py The position of the sound.
protected float	_pz The position of the sound.
protected float	_referenceDistance The reference distance for attenuation.
protected float	_rolloffFactor The attenuation rolloff factor.
protected Source	_source The source via which we are playing our sound currently.
protected boolean	_sourceRelative Whether or not the sound's position, velocity, etc. are relative to the listener.
protected int	_stateDesired The desired state of the sound (stopped, playing, paused) after resolution.
protected float	_vx The velocity of the sound.
protected float	_vy The velocity of the sound.
protected float	_vz The velocity of the sound.

Constructor Summary

protected

Sound(SoundGroup group, ClipBuffer buffer)

Method Summary

ClipBuffer	getBuffer() Returns the buffer of audio data associated with this sound.
SoundGroup	getGroup() Returns a reference to the group to which the sound belongs.
boolean	isPending() Called to check if this sound wants to start playing.
boolean	isPlaying() Called to check if this sound is currently playing.
boolean	loop(boolean allowDefer) Loops this sound, starting from the beginning of the audio data.
void	pause() Pauses this sound.
boolean	play(boolean allowDefer) Plays this sound from the beginning.
protected boolean	play(boolean allowDefer, boolean loop, Sound.StartObserver obs)
boolean	play(Sound.StartObserver obs, boolean loop) Plays this sound from the beginning, notifying the supplied observer when the audio starts.
protected boolean	reclaim() Called by the SoundGroup when it wants to reclaim our source.
void	setConeInnerAngle(float angle) Sets the inside angle of the sound cone.
void	setConeOuterAngle(float angle) Sets the outside angle of the sound cone.
void	setConeOuterGain(float gain) Sets the gain outside of the sound cone.
void	setDirection(float x, float y, float z) Sets the direction of the sound.
void	setGain(float gain) Sets the gain of the sound (which will be multiplied by the base gain).
void	setMaxDistance(float distance) Sets the maximum distance for attenuation.
void	setMaxGain(float gain) Sets the maximum gain.
void	setMinGain(float gain) Sets the minimum gain.
void	setPitch(float pitch) Sets the pitch multiplier.
void	setPosition(float x, float y, float z) Sets the position of the sound.
void	setReferenceDistance(float distance) Sets the reference distance for attenuation.
void	setRolloffFactor(float rolloff) Sets the rolloff factor for attenuation.
void	setSourceRelative(boolean relative) Sets whether or not the position, velocity, etc., of the sound are relative to the listener.
void	setVelocity(float x, float y, float z) Sets the velocity of the sound.
void	stop() Stops this sound and rewinds to its beginning.
protected void	updateSourceGain() Updates the source gain according to our configured gain and the base gain.

Methods inherited from class java.lang.Object

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

Field Detail

_group

protected SoundGroup _group

The sound group with which we are associated.

_buffer

protected ClipBuffer _buffer

The OpenAL buffer from which we get our sound data.

_source

protected Source _source

The source via which we are playing our sound currently.

_stateDesired

protected int _stateDesired

The desired state of the sound (stopped, playing, paused) after resolution.

_loopDesired

protected boolean _loopDesired

Whether or not looping is desired after resolution.

_px

protected float _px

The position of the sound.

_py

protected float _py

The position of the sound.

_pz

protected float _pz

The position of the sound.

_vx

protected float _vx

The velocity of the sound.

_vy

protected float _vy

The velocity of the sound.

_vz

protected float _vz

The velocity of the sound.

_gain

protected float _gain

The gain of the sound.

_sourceRelative

protected boolean _sourceRelative

Whether or not the sound's position, velocity, etc. are relative to the listener.

_minGain

protected float _minGain

The minimum gain.

_maxGain

protected float _maxGain

The maximum gain.

_referenceDistance

protected float _referenceDistance

The reference distance for attenuation.

_rolloffFactor

protected float _rolloffFactor

The attenuation rolloff factor.

_maxDistance

protected float _maxDistance

The maximum distance for attenuation.

_pitch

protected float _pitch

The pitch multiplier.

_dx

protected float _dx

The direction of the sound.

_dy

protected float _dy

The direction of the sound.

_dz

protected float _dz

The direction of the sound.

_coneInnerAngle

protected float _coneInnerAngle

The inside angle of the sound cone.

_coneOuterAngle

protected float _coneOuterAngle

The outside angle of the sound cone.

_coneOuterGain

protected float _coneOuterGain

The gain outside the sound cone.

Constructor Detail

Sound

protected Sound(SoundGroup group,
                ClipBuffer buffer)

Method Detail

getGroup

public SoundGroup getGroup()

Returns a reference to the group to which the sound belongs.

getBuffer

public ClipBuffer getBuffer()

Returns the buffer of audio data associated with this sound.

setPosition

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

Sets the position of the sound.

setVelocity

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

Sets the velocity of the sound.

setGain

public void setGain(float gain)

Sets the gain of the sound (which will be multiplied by the base gain).

setSourceRelative

public void setSourceRelative(boolean relative)

Sets whether or not the position, velocity, etc., of the sound are relative to the listener.

setMinGain

public void setMinGain(float gain)

Sets the minimum gain.

setMaxGain

public void setMaxGain(float gain)

Sets the maximum gain.

setReferenceDistance

public void setReferenceDistance(float distance)

Sets the reference distance for attenuation.

setRolloffFactor

public void setRolloffFactor(float rolloff)

Sets the rolloff factor for attenuation.

setMaxDistance

public void setMaxDistance(float distance)

Sets the maximum distance for attenuation.

setPitch

public void setPitch(float pitch)

Sets the pitch multiplier.

setDirection

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

Sets the direction of the sound.

setConeInnerAngle

public void setConeInnerAngle(float angle)

Sets the inside angle of the sound cone.

setConeOuterAngle

public void setConeOuterAngle(float angle)

Sets the outside angle of the sound cone.

setConeOuterGain

public void setConeOuterGain(float gain)

Sets the gain outside of the sound cone.

play

public boolean play(boolean allowDefer)

Plays this sound from the beginning. While the sound is playing, an audio channel will be locked and then freed when the sound completes.

Parameters:

allowDefer - if false, the sound will be played immediately or not at all. If true, the sound will be queued up for loading if it is currently flushed from the cache and played once loaded.

Returns:

true if the sound could be played and was started (or queued up to be loaded and played ASAP if it was specified as deferrable) or false if the sound could not be played either because it was not ready and deferral was not allowed or because too many other sounds were playing concurrently.

loop

public boolean loop(boolean allowDefer)

Loops this sound, starting from the beginning of the audio data. It will continue to loop until pause()d or stop()ped. While the sound is playing an audio channel will be locked.

Returns:

true if a channel could be obtained to play the sound (and the sound was thus started) or false if no channels were available.

play

public boolean play(Sound.StartObserver obs,
                    boolean loop)

Plays this sound from the beginning, notifying the supplied observer when the audio starts.

Parameters:

loop - whether or not to loop the sampe until stop()ped.

pause

public void pause()

Pauses this sound. A subsequent call to play(boolean) will resume the sound from the precise position that it left off. While the sound is paused, its audio channel will remain locked.

stop

public void stop()

Stops this sound and rewinds to its beginning. The audio channel being used to play the sound will be released.

isPlaying

public boolean isPlaying()

Called to check if this sound is currently playing.

isPending

public boolean isPending()

Called to check if this sound wants to start playing.

play

protected boolean play(boolean allowDefer,
                       boolean loop,
                       Sound.StartObserver obs)

updateSourceGain

protected void updateSourceGain()

Updates the source gain according to our configured gain and the base gain.

reclaim

protected boolean reclaim()

Called by the SoundGroup when it wants to reclaim our source.

Returns:

false if we have no source to reclaim or if we're still busy playing our sound, true if we gave up our source.