diff options
Diffstat (limited to 'src/java')
| -rw-r--r-- | src/java/net/java/games/sound3d/AudioSystem3D.java | 74 | ||||
| -rw-r--r-- | src/java/net/java/games/sound3d/Buffer.java | 114 | ||||
| -rw-r--r-- | src/java/net/java/games/sound3d/Context.java | 47 | ||||
| -rw-r--r-- | src/java/net/java/games/sound3d/Device.java | 29 | ||||
| -rw-r--r-- | src/java/net/java/games/sound3d/Listener.java | 66 | ||||
| -rw-r--r-- | src/java/net/java/games/sound3d/Source.java | 6 | ||||
| -rw-r--r-- | src/java/net/java/games/sound3d/Vec3f.java | 14 |
7 files changed, 198 insertions, 152 deletions
diff --git a/src/java/net/java/games/sound3d/AudioSystem3D.java b/src/java/net/java/games/sound3d/AudioSystem3D.java index 80eac7c..b356b6b 100644 --- a/src/java/net/java/games/sound3d/AudioSystem3D.java +++ b/src/java/net/java/games/sound3d/AudioSystem3D.java @@ -45,7 +45,8 @@ import javax.sound.sampled.UnsupportedAudioFileException; /** - * DOCUMENT ME! + * The AudioSystem3D class provides a set of methods for creating and + * manipulating a 3D audio environment. * * @author Athomas Goldberg */ @@ -55,7 +56,8 @@ public class AudioSystem3D { private static Listener listener; /** - * DOCUMENT ME! + * Iniitalize the Sound3D environment. This must be called before + * other methods in the class can be used. */ public static void init() { ALFactory.initialize(); @@ -64,24 +66,23 @@ public class AudioSystem3D { } /** - * DOCUMENT ME! + * Creates a new Sound3D Context for a specified device. * - * @param device DOCUMENT ME! + * @param device The device the Context is being created for. * - * @return DOCUMENT ME! + * @return The new Sound3D context. */ public static Context createContext(Device device) { Context result = null; ALC.Context realContext = alc.alcCreateContext(device.realDevice, null); result = new Context(alc, realContext, device); - return result; } /** - * DOCUMENT ME! + * Makes the specified context the current context. * - * @param context DOCUMENT ME! + * @param context the context to make current. */ public static void makeContextCurrent(Context context) { ALC.Context realContext = null; @@ -94,11 +95,13 @@ public class AudioSystem3D { } /** - * DOCUMENT ME! + * Opens the specifified audio device. * - * @param deviceName DOCUMENT ME! + * @param deviceName The specified device name, On windows this will be + * DirectSound3D. We will be automating device discovery in upcoming versions + * of this class. * - * @return DOCUMENT ME! + * @return The device described by the specifed name. */ public static Device openDevice(String deviceName) { Device result = null; @@ -109,11 +112,11 @@ public class AudioSystem3D { } /** - * DOCUMENT ME! + * Generate an array of Sound3D buffers. * - * @param numBuffers DOCUMENT ME! + * @param numBuffers The number of Sound3D buffers to generate. * - * @return DOCUMENT ME! + * @return an array of (initially enpty) Sound3D buffers. */ public static Buffer[] generateBuffers(int numBuffers) { Buffer[] result = new Buffer[numBuffers]; @@ -128,14 +131,17 @@ public class AudioSystem3D { } /** - * DOCUMENT ME! + * Loads a Sound3D buffer with the specified audio file. * - * @param filename DOCUMENT ME! + * @param filename the name of the file to load. * - * @return DOCUMENT ME! + * @return a new Sound3D buffer containing the audio data from the + * specified file. * - * @throws IOException DOCUMENT ME! - * @throws UnsupportedAudioFileException DOCUMENT ME! + * @throws IOException If the file cannot be found or some other IO error + * occurs. + * @throws UnsupportedAudioFileException If the format of the sudio data is + * not supported */ public static Buffer loadBuffer(String filename) throws IOException, UnsupportedAudioFileException { @@ -150,14 +156,18 @@ public class AudioSystem3D { } /** - * DOCUMENT ME! + * Loads a Sound3D Source with the specified audio file. This is + * functionally equivelant to generateSource(loadBuffer(fileName)); * - * @param filename DOCUMENT ME! + * @param filename the name of the file to load. * - * @return DOCUMENT ME! + * @return a new Sound3D Source containing the audio data from the + * specified file. * - * @throws IOException DOCUMENT ME! - * @throws UnsupportedAudioFileException DOCUMENT ME! + * @throws IOException If the file cannot be found or some other IO error + * occurs. + * @throws UnsupportedAudioFileException If the format of the sudio data is + * not supported */ public static Source loadSource(String filename) throws IOException, UnsupportedAudioFileException { @@ -167,11 +177,11 @@ public class AudioSystem3D { } /** - * DOCUMENT ME! + * Generates a set of uninitialized Source3D sources * - * @param numSources DOCUMENT ME! + * @param numSources the number of Sound3D sources to generate. * - * @return DOCUMENT ME! + * @return an array of uninitialized sources. */ public static Source[] generateSources(int numSources) { Source[] result = new Source[numSources]; @@ -186,11 +196,11 @@ public class AudioSystem3D { } /** - * DOCUMENT ME! + * Generate a Sound3D source from an initialized Buffer. * - * @param buff DOCUMENT ME! + * @param buff The buffer to generate the source from. * - * @return DOCUMENT ME! + * @return the newly generated Source. */ public static Source generateSource(Buffer buff) { Source result = null; @@ -202,9 +212,9 @@ public class AudioSystem3D { } /** - * DOCUMENT ME! + * Get the listener object associated with this Sound3D environment. * - * @return DOCUMENT ME! + * @return The listener object. */ public static Listener getListener() { if (listener == null) { diff --git a/src/java/net/java/games/sound3d/Buffer.java b/src/java/net/java/games/sound3d/Buffer.java index c94915b..5afbc40 100644 --- a/src/java/net/java/games/sound3d/Buffer.java +++ b/src/java/net/java/games/sound3d/Buffer.java @@ -1,139 +1,135 @@ /** -* Copyright (c) 2003 Sun Microsystems, Inc. All Rights Reserved. -* -* Redistribution and use in source and binary forms, with or without -* modification, are permitted provided that the following conditions are met: -* -* -Redistribution of source code must retain the above copyright notice, -* this list of conditions and the following disclaimer. -* -* -Redistribution in binary form must reproduce the above copyright notice, -* this list of conditions and the following disclaimer in the documentation -* and/or other materials provided with the distribution. -* -* Neither the name of Sun Microsystems, Inc. or the names of contributors may -* be used to endorse or promote products derived from this software without -* specific prior written permission. -* -* This software is provided "AS IS," without a warranty of any kind. -* ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDING -* ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR -* NON-INFRINGEMENT, ARE HEREBY EXCLUDED. SUN MIDROSYSTEMS, INC. ("SUN") AND ITS -* LICENSORS SHALL NOT BE LIABLE FOR ANY DAMAGES SUFFERED BY LICENSEE AS A -* RESULT OF USING, MODIFYING OR DISTRIBUTING THIS SOFTWARE OR ITS DERIVATIVES. -* IN NO EVENT WILL SUN OR ITS LICENSORS BE LIABLE FOR ANY LOST REVENUE, PROFIT -* OR DATA, OR FOR DIRECT, INDIRECT, SPECIAL, CONSEQUENTIAL, INCIDENTAL OR -* PUNITIVE DAMAGES, HOWEVER CAUSED AND REGARDLESS OF THE THEORY OF LIABILITY, -* ARISING OUT OF THE USE OF OR INABILITY TO USE THIS SOFTWARE, EVEN IF SUN HAS -* BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. -* -* You acknowledge that this software is not designed or intended for use in the -* design, construction, operation or maintenance of any nuclear facility. -*/ - + * Copyright (c) 2003 Sun Microsystems, Inc. All Rights Reserved. + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * -Redistribution of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. -Redistribution in + * binary form must reproduce the above copyright notice, this list of + * conditions and the following disclaimer in the documentation and/or other + * materials provided with the distribution. Neither the name of Sun + * Microsystems, Inc. or the names of contributors may be used to endorse or + * promote products derived from this software without specific prior written + * permission. This software is provided "AS IS," without a warranty of any + * kind. ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES, + * INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR + * PURPOSE OR NON-INFRINGEMENT, ARE HEREBY EXCLUDED. SUN MIDROSYSTEMS, INC. + * ("SUN") AND ITS LICENSORS SHALL NOT BE LIABLE FOR ANY DAMAGES SUFFERED BY + * LICENSEE AS A RESULT OF USING, MODIFYING OR DISTRIBUTING THIS SOFTWARE OR + * ITS DERIVATIVES. IN NO EVENT WILL SUN OR ITS LICENSORS BE LIABLE FOR ANY + * LOST REVENUE, PROFIT OR DATA, OR FOR DIRECT, INDIRECT, SPECIAL, + * CONSEQUENTIAL, INCIDENTAL OR PUNITIVE DAMAGES, HOWEVER CAUSED AND + * REGARDLESS OF THE THEORY OF LIABILITY, ARISING OUT OF THE USE OF OR + * INABILITY TO USE THIS SOFTWARE, EVEN IF SUN HAS BEEN ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGES. You acknowledge that this software is not + * designed or intended for use in the design, construction, operation or + * maintenance of any nuclear facility. + */ package net.java.games.sound3d; -import java.nio.ByteBuffer; - import net.java.games.joal.AL; +import java.nio.ByteBuffer; + /** - * DOCUMENT ME! + * The Sound3D Buffer is a container for audio data used in the Sound3D + * environment. * * @author Athomas Goldberg */ public class Buffer { - //DOCUMENT ME! - public final static int FORMAT_MONO8 = AL.AL_FORMAT_MONO8; + public final static int FORMAT_MONO8 = AL.AL_FORMAT_MONO8; - //DOCUMENT ME! public final static int FORMAT_MONO16 = AL.AL_FORMAT_MONO16; - //DOCUMENT ME! public final static int FORMAT_STEREO8 = AL.AL_FORMAT_STEREO8; - //DOCUMENT ME! public final static int FORMAT_STEREO16 = AL.AL_FORMAT_STEREO16; - final int bufferName; + final int bufferID; private ByteBuffer data; private boolean isConfigured = false; private final AL al; - Buffer(AL al, int bufferName) { - this.bufferName = bufferName; + Buffer(AL al, int bufferID) { + this.bufferID = bufferID; this.al = al; } /** - * DOCUMENT ME! + * Configure the Sound3D buffer * - * @param data DOCUMENT ME! - * @param format DOCUMENT ME! - * @param freq DOCUMENT ME! + * @param data the raw audio data + * @param format the format of the data: <code>FORMAT_MONO8, FORMAT_MONO16, + * FORMAT_STEREO8</code> and <code>FORMAT_STEREO16</code> + * @param freq the frequency of the data */ public void configure(ByteBuffer data, int format, int freq) { if (!isConfigured) { - al.alBufferData(bufferName, format, data, data.capacity(), freq); + al.alBufferData(bufferID, format, data, data.capacity(), freq); } } /** - * DOCUMENT ME! + * Delete this buffer, and free its resources. */ public void delete() { data = null; - al.alDeleteBuffers(1, new int[] { bufferName }); + al.alDeleteBuffers(1, new int[] { bufferID }); } /** - * DOCUMENT ME! + * Get the bit-depth of the data, (8 or 16) * + * @return the bit-depth of the data */ public int getBitDepth() { int[] i = new int[1]; - al.alGetBufferi(bufferName, AL.AL_BITS, i); + al.alGetBufferi(bufferID, AL.AL_BITS, i); return i[0]; } /** - * DOCUMENT ME! + * Get the number of channels of the data (1-Mono, 2-Stereo) * + * @return the number of audio channels. */ public int getNumChannels() { int[] i = new int[1]; - al.alGetBufferi(bufferName, AL.AL_CHANNELS, i); + al.alGetBufferi(bufferID, AL.AL_CHANNELS, i); return i[0]; } /** - * DOCUMENT ME! + * Gets the raw data contained in this buffer. * + * @return the raw buffer data. */ public ByteBuffer getData() { return data; } /** - * DOCUMENT ME! + * Gets the audio frequency of the data contained in this buffer. * + * @return the frequency of the data */ public int getFrequency() { int[] i = new int[1]; - al.alGetBufferi(bufferName, AL.AL_FREQUENCY, i); + al.alGetBufferi(bufferID, AL.AL_FREQUENCY, i); return i[0]; } /** - * DOCUMENT ME! + * Gets the size (in bytes) of the raw data containe in this buffer. * + * @return the size of the data. */ public int getSize() { int[] i = new int[1]; - al.alGetBufferi(bufferName, AL.AL_SIZE, i); + al.alGetBufferi(bufferID, AL.AL_SIZE, i); return i[0]; } diff --git a/src/java/net/java/games/sound3d/Context.java b/src/java/net/java/games/sound3d/Context.java index 5215810..00d7178 100644 --- a/src/java/net/java/games/sound3d/Context.java +++ b/src/java/net/java/games/sound3d/Context.java @@ -35,29 +35,42 @@ package net.java.games.sound3d; import net.java.games.joal.ALC; + /** - * @author Athomas Goldberg + * This class provides a Sound3D Context associated with a specified device. * + * @author Athomas Goldberg */ public class Context { - private final ALC alc; - final ALC.Context realContext; + private final ALC alc; + final ALC.Context realContext; final Device device; - - Context(ALC alc, ALC.Context realContext, Device device) { - this.alc = alc; - this.realContext = realContext; + + Context(ALC alc, ALC.Context realContext, Device device) { + this.alc = alc; + this.realContext = realContext; this.device = device; - } - - public void suspend() { - alc.alcSuspendContext(realContext); - } - - public void destroy() { - alc.alcDestroyContext(realContext); - } - + } + + /** + * Suspend this context + */ + public void suspend() { + alc.alcSuspendContext(realContext); + } + + /** + * destroys this conteext freeing its resources. + */ + public void destroy() { + alc.alcDestroyContext(realContext); + } + + /** + * Gets the device associated with this context. + * + * @return the device associated with this context. + */ public Device getDevice() { return device; } diff --git a/src/java/net/java/games/sound3d/Device.java b/src/java/net/java/games/sound3d/Device.java index 5973df3..44879a3 100644 --- a/src/java/net/java/games/sound3d/Device.java +++ b/src/java/net/java/games/sound3d/Device.java @@ -35,20 +35,25 @@ package net.java.games.sound3d; import net.java.games.joal.ALC; + /** - * @author Athomas Goldberg + * This class provides a handle to a specific audio device. * + * @author Athomas Goldberg */ public class Device { - private final ALC alc; - final ALC.Device realDevice; - - Device(ALC alc, ALC.Device realDevice) { - this.alc = alc; - this.realDevice = realDevice; - } - - public void close() { - alc.alcCloseDevice(realDevice); - } + private final ALC alc; + final ALC.Device realDevice; + + Device(ALC alc, ALC.Device realDevice) { + this.alc = alc; + this.realDevice = realDevice; + } + + /** + * closes the device, freeing its resources. + */ + public void close() { + alc.alcCloseDevice(realDevice); + } } diff --git a/src/java/net/java/games/sound3d/Listener.java b/src/java/net/java/games/sound3d/Listener.java index e3509dc..d80c8d0 100644 --- a/src/java/net/java/games/sound3d/Listener.java +++ b/src/java/net/java/games/sound3d/Listener.java @@ -37,7 +37,9 @@ import net.java.games.joal.AL; /** - * DOCUMENT ME! + * This class represents the human listener in the Sound3D environment. It + * provides methods for controlling the position, orientation as well as other + * properties associated with the listener. * * @author Athomas Goldberg */ @@ -49,18 +51,20 @@ public class Listener { } /** - * DOCUMENT ME! + * Sets the Gain, or volume of the audio in the environment relative to the + * listener * - * @param gain DOCUMENT ME! + * @param gain the gain, or volume */ public void setGain(float gain) { al.alListenerf(AL.AL_GAIN, gain); } /** - * DOCUMENT ME! + * Gets the value of the gain, or volume of the audio in the environment + * relative to the listener. * - * @return DOCUMENT ME! + * @return the gain value. */ public float getGain() { float[] f = new float[1]; @@ -70,29 +74,37 @@ public class Listener { } /** - * DOCUMENT ME! + * Sets the position in (x-y-z coordinates) of the Listener in the Sound3D + * environment. * - * @param x DOCUMENT ME! - * @param y DOCUMENT ME! - * @param z DOCUMENT ME! + * @param x The position of the listener along the X-axis in the Sound3D + * environment + * @param y The position of the listener along the Y-axis in the Sound3D + * environment + * @param z The position of the listener along the Z-axis in the Sound3D + * environment */ public void setPosition(float x, float y, float z) { al.alListener3f(AL.AL_POSITION, x, y, z); } /** - * DOCUMENT ME! + * Sets the position in (x-y-z coordinates) of the Listener in the Sound3D + * environment. * - * @param position DOCUMENT ME! + * @param position a Vec3f object containing the x,y and z coordinates of + * Listener. */ public void setPosition(Vec3f position) { al.alListener3f(AL.AL_POSITION, position.v1, position.v2, position.v3); } /** - * DOCUMENT ME! + * Gets the position in (x-y-z coordinates) of the Listener in the Sound3D + * environment. * - * @return DOCUMENT ME! + * @return a Vec3f object containing the x,y and z coordinates of + * Listener. */ public Vec3f getPosition() { Vec3f result = null; @@ -104,18 +116,22 @@ public class Listener { } /** - * DOCUMENT ME! + * Sets the velocity in (x-y-z coordinates) of the Listener in the Sound3D + * environment. Used in determining doppler shift. * - * @param velocity DOCUMENT ME! + * @param velocity a Vec3f object containing the velicity in + * x,y and z coordinates of Listener. */ public void setVelocity(Vec3f velocity) { al.alListener3f(AL.AL_VELOCITY, velocity.v1, velocity.v2, velocity.v3); } /** - * DOCUMENT ME! + * Gets the velocity in (x-y-z coordinates) of the Listener in the Sound3D + * environment. Used in determining doppler shift. * - * @return DOCUMENT ME! + * @return a Vec3f object containing the velicity in + * x,y and z coordinates of Listener. */ public Vec3f getVelocity() { Vec3f result = null; @@ -127,23 +143,29 @@ public class Listener { } /** - * DOCUMENT ME! + * Sets the orientation of the Listener in the Sound3D environment. + * Orientation is expressed as "up" and "at" vectors. * - * @param orientation DOCUMENT ME! + * @param orientation The first 3 elements of the array should contain + * the x,y,z up-vector, the second 3 elements should contain the x,z,z + * look-at vector. */ public void setOrientation(float[] orientation) { al.alListenerfv(AL.AL_ORIENTATION, orientation); } /** - * DOCUMENT ME! + * Gets the orientation of the Listener in the Sound3D environment. + * Orientation is expressed as "up" and "at" vectors. * - * @return DOCUMENT ME! + * @return an array containing the orientation of the listener. + * The first 3 elements of the array contain + * the x,y,z up-vector, the second 3 elements contain the x,z,z + * look-at vector. */ public float[] getOrientation() { float[] tmp = new float[6]; al.alGetListenerfv(AL.AL_ORIENTATION, tmp); - return tmp; } } diff --git a/src/java/net/java/games/sound3d/Source.java b/src/java/net/java/games/sound3d/Source.java index a6cfd04..37dfbb8 100644 --- a/src/java/net/java/games/sound3d/Source.java +++ b/src/java/net/java/games/sound3d/Source.java @@ -436,7 +436,7 @@ public final class Source { * @param buffer DOCUMENT ME! */ public void setBuffer(Buffer buffer) { - al.alSourcei(sourceName, AL.AL_BUFFER, buffer.bufferName); + al.alSourcei(sourceName, AL.AL_BUFFER, buffer.bufferID); this.buffer = buffer; } @@ -459,7 +459,7 @@ public final class Source { int[] arr = new int[numBuffers]; for (int i = 0; i < numBuffers; i++) { - arr[i] = buffers[i].bufferName; + arr[i] = buffers[i].bufferID; } al.alSourceQueueBuffers(sourceName, numBuffers, arr); @@ -475,7 +475,7 @@ public final class Source { int[] arr = new int[numBuffers]; for (int i = 0; i < numBuffers; i++) { - arr[i] = buffers[i].bufferName; + arr[i] = buffers[i].bufferID; } al.alSourceUnqueueBuffers(sourceName, numBuffers, arr); diff --git a/src/java/net/java/games/sound3d/Vec3f.java b/src/java/net/java/games/sound3d/Vec3f.java index a97c304..f6f494b 100644 --- a/src/java/net/java/games/sound3d/Vec3f.java +++ b/src/java/net/java/games/sound3d/Vec3f.java @@ -34,26 +34,26 @@ package net.java.games.sound3d; /** - * DOCUMENT ME! + * A onvenience class representing a 3-element float vector * * @author Athomas Goldberg */ public final class Vec3f { - //DOCUMENT ME! + /** the first element in the vector */ public final float v1; - //DOCUMENT ME! + /** the first element in the vector */ public final float v2; - //DOCUMENT ME! + /** the first element in the vector */ public final float v3; /** * Creates a new Vec3f object. * - * @param v1 DOCUMENT ME! - * @param v2 DOCUMENT ME! - * @param v3 DOCUMENT ME! + * @param v1 the first element in the vector + * @param v2 the second element in the vector + * @param v3 the third element in the vector */ public Vec3f(float v1, float v2, float v3) { this.v1 = v1; |