summaryrefslogtreecommitdiffstats
path: root/src/java/net
diff options
context:
space:
mode:
authorathomas <athomas@dev.java.net>2003-06-08 18:10:40 +0000
committerathomas <athomas@dev.java.net>2003-06-08 18:10:40 +0000
commit72cfd64b3dc677b397b1e53ea906d5b3fb688449 (patch)
tree9e380c83e2c50d72d7db5a06bbbe45bd88a46760 /src/java/net
parent82697159695d6e28f6807cb386419cf6f4181f6e (diff)
added missing javadoc comments
git-svn-id: file:///home/mbien/NetBeansProjects/JOGAMP/joal-sync/git-svn/../svn-server-sync/joal/trunk@26 03bf7f67-59de-4072-a415-9a990d468a3f
Diffstat (limited to 'src/java/net')
-rw-r--r--src/java/net/java/games/sound3d/AudioSystem3D.java74
-rw-r--r--src/java/net/java/games/sound3d/Buffer.java114
-rw-r--r--src/java/net/java/games/sound3d/Context.java47
-rw-r--r--src/java/net/java/games/sound3d/Device.java29
-rw-r--r--src/java/net/java/games/sound3d/Listener.java66
-rw-r--r--src/java/net/java/games/sound3d/Source.java6
-rw-r--r--src/java/net/java/games/sound3d/Vec3f.java14
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;