paulscode.sound.libraries
Class LibraryJavaSound

java.lang.Object
  extended by paulscode.sound.Library
      extended by paulscode.sound.libraries.LibraryJavaSound

public class LibraryJavaSound
extends Library

The LibraryJavaSound class interfaces the JavaSound library. For more information about the JavaSound API, visit http://java.sun.com/products/java-media/sound/

SoundSystem LibraryJavaSound License:

You are free to use this library for any purpose, commercial or otherwise. You may modify this library or source code, and distribute it any way you like, provided the following conditions are met:
1) You may not falsely claim to be the author of this library or any unmodified portion of it.
2) You may not copyright this library or a modified version of it and then sue me for copyright infringement.
3) If you modify the source code, you must clearly document the changes made before redistributing the modified source code, so other users know it is not the original code.
4) You are not required to give me credit for this library in any derived work, but if you do, you must also mention my website: http://www.paulscode.com
5) I the author will not be responsible for any damages (physical, financial, or otherwise) caused by the use if this library or any part of it.
6) I the author do not guarantee, warrant, or make any representations, either expressed or implied, regarding the use of this library or any part of it.

Author: Paul Lamb
http://www.paulscode.com


Nested Class Summary
static class LibraryJavaSound.Exception
          The LibraryJavaSound.Exception class provides library-specific error information.
static class LibraryJavaSound.MixerRanking
          The MixerRanking class is used to determine the capabilities of a mixer, and to give it a ranking based on the priority of those capabilities.
 
Field Summary
 
Fields inherited from class paulscode.sound.Library
bufferMap, listener, normalChannels, reverseByteOrder, sourceMap, streamingChannels, streamThread
 
Constructor Summary
LibraryJavaSound()
          Constructor: Instantiates the source map, buffer map and listener information.
 
Method Summary
 void cleanup()
          Stops all sources, and removes references to all instantiated objects.
 void copySources(java.util.HashMap<java.lang.String,Source> srcMap)
          Creates sources based on the source map provided.
protected  Channel createChannel(int type)
          Creates a new channel of the specified type (normal or streaming).
 void dopplerChanged()
          The Doppler parameters have changed.
 java.lang.String getClassName()
          Returns the name of the class.
static java.lang.String getDescription()
          Returns a longer description of this library type.
static javax.sound.sampled.Mixer getMixer()
          Returns a handle to the current JavaSound mixer, or null if no mixer has been set yet.
static LibraryJavaSound.MixerRanking getMixerRanking()
           
static java.lang.String getTitle()
          Returns the short title of this library type.
 void init()
          Initializes Javasound.
static boolean libraryCompatible()
          Checks if the JavaSound library type is compatible.
 boolean loadSound(FilenameURL filenameURL)
          Pre-loads a sound into memory.
 boolean loadSound(SoundBuffer buffer, java.lang.String identifier)
          Saves the specified sample data, under the specified identifier.
 void newSource(boolean priority, boolean toStream, boolean toLoop, java.lang.String sourcename, FilenameURL filenameURL, float x, float y, float z, int attModel, float distOrRoll)
          Creates a new source and places it into the source map.
 void quickPlay(boolean priority, boolean toStream, boolean toLoop, java.lang.String sourcename, FilenameURL filenameURL, float x, float y, float z, int attModel, float distOrRoll, boolean temporary)
          Creates and immediately plays a new source.
 void rawDataStream(javax.sound.sampled.AudioFormat audioFormat, boolean priority, java.lang.String sourcename, float x, float y, float z, int attModel, float distOrRoll)
          Opens a direct line for streaming audio data.
static void setLineCount(int value)
           
 void setListenerVelocity(float x, float y, float z)
          Sets the listener's velocity, for use in Doppler effect.
 void setMasterVolume(float value)
          Sets the overall volume to the specified value, affecting all sources.
static void setMaxSampleRate(int value)
           
static void setMinSampleRate(int value)
           
static void setMixer(javax.sound.sampled.Mixer m)
          Sets the current mixer.
static void useGainControl(boolean value)
           
static void usePanControl(boolean value)
           
static void useSampleRateControl(boolean value)
           
 
Methods inherited from class paulscode.sound.Library
activate, checkFadeVolumes, cull, dequeueSound, errorCheck, errorMessage, fadeOut, fadeOutIn, feedRawAudioData, feedRawAudioData, flush, getAllLoadedFilenames, getAllSourcenames, getListenerData, getMidiChannel, getPitch, getSource, getSources, getVolume, importantMessage, listenerMoved, loadMidi, message, midiSourcename, millisecondsPlayed, moveListener, pause, play, play, printStackTrace, queueSound, removeSource, removeTemporarySources, replaySources, reverseByteOrder, rewind, setAttenuation, setDistOrRoll, setListenerAngle, setListenerData, setListenerOrientation, setListenerPosition, setLooping, setMidiChannel, setPitch, setPosition, setPriority, setTemporary, setVelocity, setVolume, stop, turnListener, unloadMidi, unloadSound
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

LibraryJavaSound

public LibraryJavaSound()
                 throws SoundSystemException
Constructor: Instantiates the source map, buffer map and listener information. Also sets the library type to SoundSystemConfig.LIBRARY_JAVASOUND

Throws:
SoundSystemException
Method Detail

init

public void init()
          throws SoundSystemException
Initializes Javasound.

Overrides:
init in class Library
Throws:
SoundSystemException

libraryCompatible

public static boolean libraryCompatible()
Checks if the JavaSound library type is compatible.

Returns:
True or false.

createChannel

protected Channel createChannel(int type)
Creates a new channel of the specified type (normal or streaming). Possible values for channel type can be found in the SoundSystemConfig class.

Overrides:
createChannel in class Library
Parameters:
type - Type of channel.
Returns:
The new channel.

cleanup

public void cleanup()
Stops all sources, and removes references to all instantiated objects.

Overrides:
cleanup in class Library

loadSound

public boolean loadSound(FilenameURL filenameURL)
Pre-loads a sound into memory.

Overrides:
loadSound in class Library
Parameters:
filenameURL - Filename/URL of a sound file to load.
Returns:
True if the sound loaded properly.

loadSound

public boolean loadSound(SoundBuffer buffer,
                         java.lang.String identifier)
Saves the specified sample data, under the specified identifier. This identifier can be later used in place of 'filename' parameters to reference the sample data.

Overrides:
loadSound in class Library
Parameters:
buffer - the sample data and audio format to save.
identifier - What to call the sample.
Returns:
True if there weren't any problems.

setMasterVolume

public void setMasterVolume(float value)
Sets the overall volume to the specified value, affecting all sources.

Overrides:
setMasterVolume in class Library
Parameters:
value - New volume, float value ( 0.0f - 1.0f ).

newSource

public void newSource(boolean priority,
                      boolean toStream,
                      boolean toLoop,
                      java.lang.String sourcename,
                      FilenameURL filenameURL,
                      float x,
                      float y,
                      float z,
                      int attModel,
                      float distOrRoll)
Creates a new source and places it into the source map.

Overrides:
newSource in class Library
Parameters:
priority - Setting this to true will prevent other sounds from overriding this one.
toStream - Setting this to true will load the sound in pieces rather than all at once.
toLoop - Should this source loop, or play only once.
sourcename - A unique identifier for this source. Two sources may not use the same sourcename.
filenameURL - Filename/URL of the sound file to play at this source.
x - X position for this source.
y - Y position for this source.
z - Z position for this source.
attModel - Attenuation model to use.
distOrRoll - Either the fading distance or rolloff factor, depending on the value of "attmodel".

rawDataStream

public void rawDataStream(javax.sound.sampled.AudioFormat audioFormat,
                          boolean priority,
                          java.lang.String sourcename,
                          float x,
                          float y,
                          float z,
                          int attModel,
                          float distOrRoll)
Opens a direct line for streaming audio data.

Overrides:
rawDataStream in class Library
Parameters:
audioFormat - Format that the data will be in.
priority - Setting this to true will prevent other sounds from overriding this one.
sourcename - A unique identifier for this source. Two sources may not use the same sourcename.
x - X position for this source.
y - Y position for this source.
z - Z position for this source.
attModel - Attenuation model to use.
distOrRoll - Either the fading distance or rolloff factor, depending on the value of "attmodel".

quickPlay

public void quickPlay(boolean priority,
                      boolean toStream,
                      boolean toLoop,
                      java.lang.String sourcename,
                      FilenameURL filenameURL,
                      float x,
                      float y,
                      float z,
                      int attModel,
                      float distOrRoll,
                      boolean temporary)
Creates and immediately plays a new source.

Overrides:
quickPlay in class Library
Parameters:
priority - Setting this to true will prevent other sounds from overriding this one.
toStream - Setting this to true will load the sound in pieces rather than all at once.
toLoop - Should this source loop, or play only once.
sourcename - A unique identifier for this source. Two sources may not use the same sourcename.
filenameURL - Filename/URL of the sound file to play at this source.
x - X position for this source.
y - Y position for this source.
z - Z position for this source.
attModel - Attenuation model to use.
distOrRoll - Either the fading distance or rolloff factor, depending on the value of "attmodel".
temporary - Whether or not this source should be removed after it finishes playing.

copySources

public void copySources(java.util.HashMap<java.lang.String,Source> srcMap)
Creates sources based on the source map provided.

Overrides:
copySources in class Library
Parameters:
srcMap - Sources to copy.

setListenerVelocity

public void setListenerVelocity(float x,
                                float y,
                                float z)
Sets the listener's velocity, for use in Doppler effect.

Overrides:
setListenerVelocity in class Library
Parameters:
x - Velocity along world x-axis.
y - Velocity along world y-axis.
z - Velocity along world z-axis.

dopplerChanged

public void dopplerChanged()
The Doppler parameters have changed.

Overrides:
dopplerChanged in class Library

getMixer

public static javax.sound.sampled.Mixer getMixer()
Returns a handle to the current JavaSound mixer, or null if no mixer has been set yet.

Returns:
Handle to the mixer or null.

setMixer

public static void setMixer(javax.sound.sampled.Mixer m)
                     throws SoundSystemException
Sets the current mixer. If this method is not called, the "Java Sound Audio Engine" mixer will be used by default.

Parameters:
m - New mixer.
Throws:
SoundSystemException

getMixerRanking

public static LibraryJavaSound.MixerRanking getMixerRanking()

setMinSampleRate

public static void setMinSampleRate(int value)

setMaxSampleRate

public static void setMaxSampleRate(int value)

setLineCount

public static void setLineCount(int value)

useGainControl

public static void useGainControl(boolean value)

usePanControl

public static void usePanControl(boolean value)

useSampleRateControl

public static void useSampleRateControl(boolean value)

getTitle

public static java.lang.String getTitle()
Returns the short title of this library type.

Returns:
A short title.

getDescription

public static java.lang.String getDescription()
Returns a longer description of this library type.

Returns:
A longer description.

getClassName

public java.lang.String getClassName()
Returns the name of the class.

Overrides:
getClassName in class Library
Returns:
"Library" + library title.