j3dcore: flatten the directory structure a bit

Signed-off-by: Harvey Harrison <[email protected]>

1 files changed, 533 insertions, 0 deletions

diff --git a/src/javax/media/j3d/AudioDevice3D.java b/src/javax/media/j3d/AudioDevice3D.java
new file mode 100644
index 0000000..7f152e4
--- /dev/null
+++ b/src/javax/media/j3d/AudioDevice3D.java
@@ -0,0 +1,533 @@
+/*
+ * Copyright 1998-2008 Sun Microsystems, Inc.  All Rights Reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Sun designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Sun in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
+ * CA 95054 USA or visit www.sun.com if you need additional information or
+ * have any questions.
+ *
+ */
+
+package javax.media.j3d;
+
+import javax.vecmath.Point2f;
+import javax.vecmath.Point3d;
+import javax.vecmath.Point3f;
+import javax.vecmath.Vector3d;
+import javax.vecmath.Vector3f;
+
+
+/**
+ * The AudioDevice3D class defines a 3D audio device that is used to set
+ * sound and aural attributes.
+ *<P>
+ * After the application chooses the AudioDevice3D that Java3D sound
+ * is to be rendered on, the Java 3D Sound Scheduler will call these
+ * methods for all active sounds to render them on the audio device.
+ *<P>
+ * The intent is for this interface to be implemented by AudioDevice Driver
+ * developers using a software or hardware sound engine of their choice.
+ *<P>
+ * Methods in this interface provide the Java3D Core a generic way to
+ * set and query the audio device the application has chosen audio rendering
+ * to be performed on.  Methods in this interface include:
+ * <UL>
+ *    Set up and clear the sound as a sample on the device.
+ * <P>
+ *    Start, stop, pause, unpause, mute, and unmute of sample on the device.
+ * <P>
+ *    Set parameters for each sample corresponding to the fields in the
+ *    Sound node.
+ * <P>
+ *    Set the current active aural parameters that affect all positional samples.
+ * </UL>
+ * <P>
+ * Sound Types
+ * <P>
+ * Sound types match the Sound node classes defined for Java 3D core
+ * for BackgroundSound, PointSound, and ConeSound.  The type of sound
+ * a sample is loaded as determines which methods affect it.
+ *
+ * <P>
+ * Sound Data Types
+ * <P>
+ * Samples can be processed as streaming or buffered data.
+ * Fully spatializing sound sources may require data to be buffered.
+ *
+ */
+
+public interface AudioDevice3D extends AudioDevice {
+
+     /**
+      *  Specifies the sound type as background sound.
+      */
+     public static final int BACKGROUND_SOUND = 1;
+
+     /**
+      *  Specifies the sound type as point sound.
+      */
+     public static final int POINT_SOUND      = 2;
+
+     /**
+      *  Specifies the sound type as cone sound.
+      */
+
+     public static final int CONE_SOUND       = 3;
+
+     /**
+      *  Sound data specified as Streaming is not copied by the AudioDevice
+      *  driver implementation.  It is up to the application to ensure that
+      *  this data is continuously accessible during sound rendering.
+      *  Furthermore, full sound spatialization may not be possible, for
+      *  all AudioDevice3D implementations on unbuffered sound data.
+      */
+     public static final int STREAMING_AUDIO_DATA = 1;
+     /**
+      *  Sound data specified as Buffered is copied by the AudioDevice
+      *  driver implementation.
+      */
+     public static final int BUFFERED_AUDIO_DATA = 2;
+
+
+    /**
+     * Accepts a reference to the current View.
+     * Passes reference to current View Object.  The PhysicalEnvironment
+     * parameters (with playback type and speaker placement), and the
+     * PhysicalBody parameters (position/orientation of ears)
+     * can be obtained from this object, and the transformations to/from
+     * ViewPlatform coordinate (space the listener's head is in) and
+     * Virtual World coordinates (space sounds are in).
+     * <P>
+     * This method should only be called by Java3D Core and NOT by any application.
+     * @param reference the current View
+     */
+    public abstract void  setView(View reference);
+
+    /**
+     * Accepts a reference to the MediaContainer
+     * which contains a reference to sound data and information about the
+     * type of data it is.  A "sound type" input parameter denotes if the
+     * Java 3D sound associated with this sample is a Background, Point, or
+     * Cone Sound node.
+     * Depending on the type of MediaContainer the sound data is and on the
+     * implementation of the AudioDevice used, sound data preparation could
+     * consist of opening, attaching, or loading sound data into the device.
+     * Unless the cached flag is true, this sound data should NOT be copied,
+     * if possible, into host or device memory.
+     *<P>
+     * Once this preparation is complete for the sound sample, an AudioDevice
+     * specific index, used to reference the sample in future method calls,
+     * is returned.  All the rest of the methods described below require
+     * this index as a parameter.
+     * <P>
+     * This method should only be called by Java3D Core and NOT by any application.
+     * @param soundType defines the type of Sound Node: Background, Point, and
+     * Cone
+     * @param soundData reference to MediaContainer sound data and cached flag
+     * @return device specific sample index used for referencing this sound
+     */
+    public abstract int   prepareSound(int soundType, MediaContainer soundData);
+
+    /**
+     * Requests that the AudioDevice free all
+     * resources associated with sample with index id.
+     * <P>
+     * This method should only be called by Java3D Core and NOT by any application.
+     * @param index device specific reference number to device driver sample
+     */
+    public abstract void   clearSound(int index);
+
+    /**
+     * Returns the duration in milliseconds of the sound sample,
+     * if this information can be determined.
+     * For non-cached
+     * streams, this method returns Sound.DURATION_UNKNOWN.
+     * <P>
+     * This method should only be called by Java3D Core and NOT by any application.
+     * @param index device specific reference number to device driver sample
+     * @return sound duration in milliseconds if this can be determined,
+     * otherwise (for non-cached streams) Sound.DURATION_UNKNOWN is returned
+     */
+    public abstract long   getSampleDuration(int index);
+
+    /**
+     *
+     * Retrieves the number of channels (on executing audio device) that
+     * this sound is using, if it is playing, or is expected to use
+     * if it were begun to be played.  This form of this method takes the
+     * sound's current state (including whether it is muted or unmuted)
+     * into account.
+     *<P>
+     * For some AudioDevice3D implementations:
+     *<UL>
+     *     Muted sound take channels up on the systems mixer (because they're
+     *         rendered as samples playing with gain zero.
+     *<P>
+     *     A single sound could be rendered using multiple samples, each taking
+     *         up mixer channels.
+     *</UL>
+     * <P>
+     * This method should only be called by Java3D Core and NOT by any application.
+     * @param index device specific reference number to device driver sample
+     * @return number of channels used by sound if it were playing
+     */
+    public abstract int    getNumberOfChannelsUsed(int index);
+
+    /**
+     *
+     * Retrieves the number of channels (on executing audio device) that
+     * this sound is using, if it is playing, or is projected to use if
+     * it were to be started playing.  Rather than using the actual current
+     * muted/unmuted state of the sound, the muted parameter is used in
+     * making the determination.
+     * <P>
+     * This method should only be called by Java3D Core and NOT by any application.
+     * @param index device specific reference number to device driver sample
+     * @param muted flag to use as the current muted state ignoring current
+     * mute state
+     * @return number of channels used by sound if it were playing
+     */
+    public abstract int    getNumberOfChannelsUsed(int index, boolean muted);
+
+    /**
+     * Begins a sound playing on the AudioDevice.
+     * <P>
+     * This method should only be called by Java3D Core and NOT by any application.
+     * @param index device specific reference number to device driver sample
+     * @return flag denoting if sample was started; 1 if true, 0 if false
+     */
+    public abstract int    startSample(int index);
+
+    /**
+     * Returns the system time of when the sound
+     * was last "started".  Note that this start time will be as accurate
+     * as the AudioDevice implementation can make it - but that it is not
+     * guaranteed to be exact.
+     * <P>
+     * This method should only be called by Java3D Core and NOT by any application.
+     * @param index device specific reference number to device driver sample
+     * @return system time in milliseconds of the last time sound was started
+     */
+    public abstract long   getStartTime(int index);
+
+    /**
+     * Stops the sound on the AudioDevice.
+     * <P>
+     * This method should only be called by Java3D Core and NOT by any application.
+     * @param index device specific reference number to device driver sample
+     * associated with sound data to be played
+     * @return flag denoting if sample was stopped; 1 if true, 0 if false
+     */
+    public abstract int    stopSample(int index);
+
+    /**
+     * Sets the overall gain scale factor applied to data associated with this
+     * source to increase or decrease its overall amplitude.
+     * The gain scale factor value passed into this method is the combined value
+     * of the Sound node's Initial Gain and the current AuralAttribute Gain
+     * scale factors.
+     * <P>
+     * This method should only be called by Java3D Core and NOT by any application.
+     * @param index device specific reference number to device driver sample
+     * @param scaleFactor amplitude (gain) scale factor
+     */
+    public abstract void   setSampleGain(int index, float scaleFactor);
+
+    /**
+     * Sets a sound's loop count.
+     * A full description of this parameter and how it is used is in
+     * the documentation for Sound.setLoop.
+     * <P>
+     * This method should only be called by Java3D Core and NOT by any application.
+     * @param index device specific reference number to device driver sample
+     * @param count number of times sound is looped during play
+     * @see Sound#setLoop
+     */
+    public abstract void   setLoop(int index, int count);
+
+    /**
+     * Passes a reference to the concatenated transformation to be applied to
+     * local sound position and direction parameters.
+     * <P>
+     * This method should only be called by Java3D Core and NOT by any application.
+     * @param index device specific reference number to device driver sample
+     * @param trans transformation matrix applied to local coordinate parameters
+     */
+    public abstract void  setVworldXfrm(int index, Transform3D trans);
+
+
+    /**
+     * Sets this sound's location (in Local coordinates) from specified
+     * Point. The form of the position parameter matches those of the PointSound
+     * method of the same name.
+     * A full description of this parameter and how it is used is in
+     * the documentation for PointSound class.
+     * <P>
+     * This method should only be called by Java3D Core and  NOT by any application.
+     * @param index device specific reference number to device driver sample
+     * @param position location of Point or Cone Sound in Virtual World
+     * coordinates
+     * @see PointSound#setPosition(float x, float y, float z)
+     * @see PointSound#setPosition(Point3f position)
+     */
+    public abstract void   setPosition(int index, Point3d position);
+
+    /**
+     * Sets this sound's distance gain elliptical attenuation (not
+     * including filter cutoff frequency) by defining corresponding
+     * arrays containing distances from the sound's origin and gain
+     * scale factors applied to all active positional sounds.
+     * Gain scale factor is applied to sound based on the distance
+     * the listener
+     * is from sound source.
+     * These attenuation parameters are ignored for BackgroundSound nodes.
+     * The back attenuation parameter is ignored for PointSound nodes.
+     * <P>
+     * The form of the attenuation parameters match that of the ConeSound method
+     * of the same name.
+     * A full description of this parameter and how it is used is in
+     * the documentation for ConeSound class.
+     * <P>
+     * This method should only be called by Java3D Core and  NOT by any application.
+     * @param index device specific reference number to device driver sample
+     * @param frontDistance defines an array of distance along positive axis
+     * through which ellipses pass
+     * @param frontAttenuationScaleFactor gain scale factors
+     * @param backDistance defines an array of distance along the negative axis
+     * through which ellipses pass
+     * @param backAttenuationScaleFactor gain scale factors
+     * @see ConeSound#setDistanceGain(float[] frontDistance, float[] frontGain,
+     * float[] backDistance, float[] backGain)
+     * @see ConeSound#setDistanceGain(Point2f[] frontAttenuation,
+     * Point2f[] backAttenuation)
+     */
+    public abstract void setDistanceGain(int index,
+              double[] frontDistance, float[]  frontAttenuationScaleFactor,
+              double[] backDistance, float[]  backAttenuationScaleFactor);
+    /**
+     * Sets this sound's direction from the local coordinate vector provided.
+     * The form of the direction parameter matches that of the ConeSound method
+     * of the same name.
+     * A full description of this parameter and how it is used is in
+     * the documentation for the ConeSound class.
+     * <P>
+     * This method should only be called by Java3D Core and  NOT by any application.
+     * @param index device specific reference number to device driver sample
+     * @param direction the new direction vector in local coordinates
+     * @see ConeSound#setDirection(float x, float y, float z)
+     * @see ConeSound#setDirection(Vector3f direction)
+     */
+    public abstract void setDirection(int index, Vector3d direction);
+
+    /**
+     * Sets this sound's angular gain attenuation (including filter)
+     * by defining corresponding arrays containing angular offsets from
+     * the sound's axis, gain scale factors, and frequency cutoff applied
+     * to all active directional sounds.
+     * Gain scale factor is applied to sound based on the angle between the
+     * sound's axis and the ray from the sound source origin to the listener.
+     * The form of the attenuation parameter matches that of the ConeSound
+     * method of the same name.
+     * A full description of this parameter and how it is used is in
+     * the documentation for the ConeSound class.
+     * <P>
+     * This method should only be called by Java3D Core and  NOT by any application.
+     * @param index device specific reference number to device driver sample
+     * @param filterType describes type (if any) of filtering defined by attenuation
+     * @param angle array containing angular distances from sound axis
+     * @param attenuationScaleFactor array containing gain scale factor
+     * @param filterCutoff array containing filter cutoff frequencies.
+     * The filter values for each tuples can be set to Sound.NO_FILTER.
+     * @see ConeSound#setAngularAttenuation(float[] distance, float[] gain,
+     * float[] filter)
+     * @see ConeSound#setAngularAttenuation(Point3f[] attenuation)
+     * @see ConeSound#setAngularAttenuation(Point2f[] attenuation)
+     */
+    public abstract void setAngularAttenuation(int index, int filterType,
+          double[] angle, float[] attenuationScaleFactor, float[] filterCutoff);
+
+    /**
+     * Changes the speed of sound factor.
+     * A full description of this parameter and how it is used is in
+     * the documentation for the AuralAttributes class.
+     * <P>
+     * This method should only be called by Java3D Core and  NOT by any application.
+     * @param rolloff atmospheric gain scale factor (changing speed of sound)
+     * @see AuralAttributes#setRolloff
+     */
+    public abstract void setRolloff(float rolloff);
+
+    /**
+     * Sets the Reflective Coefficient scale factor applied to distinct
+     * low-order early reflections of sound off the surfaces in the region
+     * defined by the current listening region.
+     * <P>
+     * A full description of this parameter and how it is used is in
+     * the documentation for the AuralAttributes class.
+     * <P>
+     * This method should only be called by Java3D Core and  NOT by any application.
+     * @param coefficient reflection/absorption factor applied to reverb
+     * @see AuralAttributes#setReflectionCoefficient
+     */
+    public abstract void setReflectionCoefficient(float coefficient);
+
+    /**
+     * Sets the reverberation delay time.
+     * In this form,  while reverberation is being rendered, the parameter
+     * specifies the delay time between each order of late reflections
+     * explicitly given in milliseconds.
+     * A value for delay time of 0.0 disables
+     * reverberation.
+     * <P>
+     * A full description of this parameter and how it is used is in
+     * the documentation for the AuralAttributes class.
+     * <P>
+     * This method should only be called by Java3D Core and  NOT by any application.
+     * @param reverbDelay time between each order of late reflection
+     * @see AuralAttributes#setReverbDelay(float reverbDelay)
+     */
+    public abstract void setReverbDelay(float reverbDelay);
+
+    /**
+     * Sets the reverberation order of reflections.
+     * The reverbOrder parameter specifies the number of times reflections are added to
+     * reverberation being calculated. A value of -1 specifies an unbounded
+     * number of reverberations.
+     * A full description of this parameter and how it is used is in
+     * the documentation for the AuralAttributes class.
+     * <P>
+     * This method should only be called by Java3D Core and  NOT by any application.
+     * @param reverbOrder number of times reflections added to reverb signal
+     * @see AuralAttributes#setReverbOrder
+     */
+    public abstract void setReverbOrder(int reverbOrder);
+
+    /**
+     * Sets Distance Filter corresponding arrays containing distances and
+     * frequency cutoff applied to all active positional sounds.
+     * Gain scale factor is applied to sound based on the distance the listener
+     * is from the sound source.
+     * A full description of this parameter and how it is used is in
+     * the documentation for the AuralAttributes class.
+     * <P>
+     * This method should only be called by Java3D Core and  NOT by any application.
+     * @param filterType denotes the type of filtering to be applied
+     * @param distance array of offset distances from sound origin
+     * @param filterCutoff array of frequency cutoff
+     * @see AuralAttributes#setDistanceFilter(float[] distance,
+     *       float[] frequencyCutoff)
+     * @see AuralAttributes#setDistanceFilter(Point2f[] attenuation)
+     */
+    public abstract void setDistanceFilter(int filterType,
+              double[] distance, float[]  filterCutoff);
+
+    /**
+     * Specifies a scale factor applied to the frequency (or
+     * wavelength).  A value less than 1.0 will result of slowing the playback
+     * rate of the sample.  A value greater than 1.0 will increase the playback
+     * rate.
+     * This parameter is also used to expand or contract the usual
+     * frequency shift applied to the sound source due to Doppler effect
+     * calculations. Valid values are >= 0.0.
+     * A full description of this parameter and how it is used is in
+     * the documentation for the AuralAttributes class.
+     * <P>
+     * This method should only be called by Java3D Core and  NOT by any application.
+     * @param frequencyScaleFactor factor applied to change of frequency
+     * @see AuralAttributes#setFrequencyScaleFactor
+     */
+    public abstract void setFrequencyScaleFactor(float frequencyScaleFactor);
+
+    /**
+     * Sets the Velocity scale factor applied during Doppler Effect calculation.
+     * This parameter specifies a scale factor applied to the velocity of sound
+     * relative to the listener's position and movement in relation to the sound's
+     * position and movement.  This scale factor is multipled by the calculated
+     * velocity portion of the Doppler effect equation used during sound rendering.
+     * A full description of this parameter and how it is used is in
+     * the documentation for the AuralAttributes class.
+     * <P>
+     * This method should only be called by Java3D Core and  NOT by any application.
+     * @param velocityScaleFactor applied to velocity of sound in relation
+     * to listener
+     * @see AuralAttributes#setVelocityScaleFactor
+     */
+    public abstract void setVelocityScaleFactor(float velocityScaleFactor);
+
+    /**
+     * Makes the sample 'play silently'.
+     * This method implements (as efficiently as possible) the muting
+     * of a playing sound sample.  Ideally this is implemented by
+     * stopping a sample and freeing channel resources (rather than
+     * just setting the gain of the sample to zero).
+     * <P>
+     * This method should only be called by Java3D Core and  NOT by any application.
+     * @param index device specific reference number to device driver sample
+     */
+    public abstract void muteSample(int index);
+
+    /**
+     * Makes a silently playing sample audible.
+     * In the ideal, this restarts a muted sample by offset from the
+     * beginning by the number of milliseconds since the time the sample
+     * began playing (rather than setting gain to current non-zero gain).
+     * <P>
+     * This method should only be called by Java3D Core and  NOT by any application.
+     * @param index device specific reference number to device driver sample
+     */
+    public abstract void unmuteSample(int index);
+
+    /**
+     * Temporarily stops a cached sample from playing without resetting the
+     * sample's current pointer back to the beginning of the sound data so
+     * that it can be unpaused at a later time from the same location in the
+     * sample when the pause was initiated.  Pausing a streaming, non-cached
+     * sound sample will be treated as a mute.
+     * <P>
+     * This method should only be called by Java3D Core and  NOT by any application.
+     * @param index device specific reference number to device driver sample
+     */
+    public abstract void pauseSample(int index);
+
+    /**
+     * Restarts the paused sample from the location in the sample where
+     * paused.
+     * <P>
+     * This method should only be called by Java3D Core and  NOT by any application.
+     * @param index device specific reference number to device driver sample
+     */
+    public abstract void unpauseSample(int index);
+
+    /**
+     *
+     * Explicitly updates a Sample.
+     * This method is called when a Sound is to be explicitly updated.
+     * It is only called when all a sounds parameters are known to have
+     * been passed to the audio device.  In this way, an implementation
+     * can choose to perform lazy-evaluation of a sample, rather than
+     * updating the rendering state of the sample after every individual
+     * parameter changed.
+     * This method can be left as a null method if the implementor so chooses.
+     * <P>
+     * This method should only be called by Java3D Core and  NOT by any application.
+     * @param index device specific reference number to device driver sample
+     */
+    public abstract void updateSample(int index);
+
+}