org.jrabbit.standard.game.sound
Class Sound

java.lang.Object
  extended by org.jrabbit.standard.game.sound.Sound
All Implemented Interfaces:
ControllableAudio

public class Sound
extends java.lang.Object
implements ControllableAudio

A Sound is a lightweight object that utilizes SoundData in the Cache to play audio. A Sound also has controllable pitch and volume settings.

Author:
Chris Molini

Field Summary
protected  Channel channel
          This is a reference to the Channel this Sound is categorized under.
protected  float pitch
          The pitch setting.
protected  SoundPointer soundPointer
          This is used to access the SoundCache and retrieve the desired SoundData for playback.
protected  float volume
          The volume setting.
 
Constructor Summary
Sound(java.lang.String reference)
          Creates a Sound that attempts to play the SoundData indicated by the supplied reference.
Sound(java.lang.String reference, java.lang.String channel)
          Creates a Sound that attempts to play the SoundData indicated by the supplied reference, and that categorizes itself under the indicated Channel.
 
Method Summary
 SoundData data()
          Accesses the SoundData this Sound uses to play audio.
 void loop()
          Begins continuously looping the sound, using the in-place sound and pitch settings.
 void loop(float pitch, float volume)
          Begins continuously looping the sound, overriding the current pitch and volume settings.
 float pitch()
          Accesses this Sound's audio settings.
 void playOnce()
          Plays the sound once, using the in-place sound and pitch settings.
 void playOnce(float pitch, float volume)
          Plays the sound once, overriding the current pitch and volume settings.
 void playSound(float pitch, float volume, boolean loop)
          Plays the sound with the indicated settings.
 boolean setChannel(Channel channel)
          Changes the Channel this Sound is categorized under.
 boolean setChannel(java.lang.String reference)
          Changes the Channel this Sound is categorized under.
 void setPitch(float pitch)
          Redefines this Sound's pitch setting.
 void setVolume(float volume)
          Redefines this Sound's volume setting.
 float volume()
          Accesses this Sound's audio settings.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

soundPointer

protected SoundPointer soundPointer
This is used to access the SoundCache and retrieve the desired SoundData for playback.


channel

protected Channel channel
This is a reference to the Channel this Sound is categorized under. The volume and pitch settings of this Channel affect playback.


volume

protected float volume
The volume setting.


pitch

protected float pitch
The pitch setting.

Constructor Detail

Sound

public Sound(java.lang.String reference)
Creates a Sound that attempts to play the SoundData indicated by the supplied reference. NOTE: This constructor sets the Channel to the default (represented by an empty String).

Parameters:
reference - The identifier matching the target SoundData.

Sound

public Sound(java.lang.String reference,
             java.lang.String channel)
Creates a Sound that attempts to play the SoundData indicated by the supplied reference, and that categorizes itself under the indicated Channel.

Parameters:
reference - The identifier matching the target SoundData.
channel - The identifier of the channel to use.
Method Detail

volume

public float volume()
Accesses this Sound's audio settings.

Specified by:
volume in interface ControllableAudio
Returns:
The current volume setting.

setVolume

public void setVolume(float volume)
Redefines this Sound's volume setting. NOTE: This method only takes effect if the supplied value isn't negative.

Specified by:
setVolume in interface ControllableAudio
Parameters:
volume - The new setting for volume.

pitch

public float pitch()
Accesses this Sound's audio settings.

Specified by:
pitch in interface ControllableAudio
Returns:
The current pitch setting.

setPitch

public void setPitch(float pitch)
Redefines this Sound's pitch setting. NOTE: This method only takes effect if the supplied value isn't negative.

Specified by:
setPitch in interface ControllableAudio
Parameters:
pitch - The new setting for pitch.

setChannel

public boolean setChannel(java.lang.String reference)
Changes the Channel this Sound is categorized under. This operation will only succeed if (A) the indicated Channel exists / is not null, and (B) the indicated Channel is not the same as the one currently active.

Parameters:
reference - The identifier of the Channel in the SoundBoard to use.
Returns:
True if the operation succeeded, false if not.

setChannel

public boolean setChannel(Channel channel)
Changes the Channel this Sound is categorized under. This operation will only succeed if (A) the indicated Channel exists / is not null, and (B) the indicated Channel is not the same as the one currently active.

Parameters:
channel - The new Channel.
Returns:
True if the operation succeeded, false if not.

data

public SoundData data()
Accesses the SoundData this Sound uses to play audio.

Returns:
The SoundData retrieved from the Cache.

playOnce

public void playOnce()
Plays the sound once, using the in-place sound and pitch settings.


playOnce

public void playOnce(float pitch,
                     float volume)
Plays the sound once, overriding the current pitch and volume settings.

Parameters:
pitch - The pitch setting to play the sound at.
volume - The volume setting to play the sound at.

loop

public void loop()
Begins continuously looping the sound, using the in-place sound and pitch settings.


loop

public void loop(float pitch,
                 float volume)
Begins continuously looping the sound, overriding the current pitch and volume settings.

Parameters:
pitch - The pitch setting to loop the sound at.
volume - The volume setting to loop the sound at.

playSound

public void playSound(float pitch,
                      float volume,
                      boolean loop)
Plays the sound with the indicated settings.

Parameters:
pitch - The pitch setting to play the sound at.
volume - The volume setting to play the sound at.
loop - Whether or not the sound should loop continuously.